Cursor-hooks: een complete handleiding, en waarom ze soms niet afgaan

Met Cursor-hooks kan een script meekijken met wat de agent doet of het blokkeren: elk shellcommando, elke MCP-aanroep, elke keer dat een bestand wordt gelezen of bewerkt. Ze zijn krachtig, en ze falen op stille manieren. Dit is alles wat we leerden toen we ze echt aansloten.

Wat Cursor-hooks zijn

Een hook is een commando dat Cursor op een vast punt in de agentlus uitvoert. Cursor stuurt een JSON-object dat beschrijft wat er gaat gebeuren naar de standaardinvoer van het commando, wacht, en leest een JSON-antwoord uit de standaarduitvoer. Sommige hooks kijken alleen mee (de bewerking loggen, het bestand formatteren). Andere beslissen: een beforeShellExecution-hook kan een commando laten draaien, het stoppen of het eerst aan jou vragen.

Daarmee zijn hooks het juiste gereedschap voor drie taken: vangrails (nooit rm -rf of git push --force uitvoeren zonder een mens), automatisering (formatteren of linten na elke bewerking) en zichtbaarheid (loggen of doorsturen wat de agent doet, zodat je weet wanneer hij je nodig heeft).

Waar hooks.json staat

Cursor leest hooks van vier plekken en voert ze allemaal uit. Elke overeenkomende hook uit elke bron draait, en Cursor voegt de antwoorden samen.

Als antwoorden elkaar tegenspreken, wint het strengste: een deny uit welke bron dan ook gaat boven ask, en ask gaat boven allow. Het kleinste werkende bestand ziet er zo uit (het is het voorbeeld uit de documentatie van Cursor):

version moet 1 zijn. Cursor houdt het bestand in de gaten en laadt het opnieuw als je opslaat. Wordt een wijziging niet actief, start Cursor dan opnieuw. Alleen dat al lost verrassend veel meldingen op het forum op.

De events waar je een hook aan kunt hangen

De huidige lijst uit de documentatie van Cursor, gegroepeerd naar doel:

Elk event krijgt een paar gemeenschappelijke velden (conversation_id, generation_id, model, hook_event_name, cursor_version, workspace_roots) plus eigen velden. beforeShellExecution krijgt de volledige command en de cwd; stop krijgt een status met de waarde completed, aborted of error.

Toestaan, weigeren en vragen

Een beslissende hook drukt één JSON-object af. Voor de shellhook ziet dat er zo uit:

• permission is allow, deny of ask.
• user_message is wat jij in Cursor ziet.
• agent_message is wat de agent te horen krijgt, zodat hij van koers kan veranderen in plaats van hetzelfde commando opnieuw te proberen.

Afsluitcodes zijn net zo belangrijk als de JSON. Afsluitcode 0 betekent “gebruik mijn JSON”. Afsluitcode 2 blokkeert de actie, net als deny. Elke andere afsluitcode wordt behandeld als een mislukte hook, en de actie gaat door, tenzij je failClosed instelt. Bij machtigingshooks blokkeert ongeldige JSON of JSON die niet aan het schema voldoet de actie.

failClosed en timeout

Elke hookvermelding kan naast command opties bevatten:

• failClosed: true maakt van een crash, een time-out, een afsluitcode anders dan nul of lege uitvoer een blokkade. De standaard is false: een kapotte bewaking laat stilletjes alles door. Voor een veiligheidshook wil je bijna altijd true.
• timeout is in seconden. Laat genoeg ruimte als je hook op een mens wacht: iemand die een diff leest, heeft meer dan vijf seconden nodig.
• matcher bepaalt wanneer de hook draait. Bij shellhooks wordt hij vergeleken met de volledige commandostring; bij toolhooks met het tooltype, zoals Shell, Read, Write of MCP:<tool_name>.

Er zit een afweging aan. In juli 2026 kreeg een gebruiker op macOS “MainThreadShellExec not initialized”: de eigen shellhost van Cursor was niet klaar, en omdat de hook fail-closed was, werd de shell van de agent geblokkeerd. Medewerkers van Cursor zeiden dat de oplossing was uitgebracht en raadden aan failClosed: true te houden. Zie je die fout in een oudere build, dan was “Developer: Reload Window” de workaround.

Hooks op Windows

Op Windows voert de Cursor-desktopapp hookcommando’s uit via PowerShell en geeft de JSON door via een pipe. Een PowerShell-script leest die uit $input; elk ander programma leest gewoon de standaardinvoer. Drie dingen gaan vaak mis:

1. Bash-scripts draaien niet zomaar. Een guard.sh van een teamgenoot op macOS mislukt onder PowerShell. Gebruik een .ps1-script, een gecompileerd programma, of roep je interpreter expliciet aan (python .cursor/hooks/guard.py). Een forumdiscussie uit januari 2026 laat een Git Bash-configuratie zien die mislukt met syntax error near unexpected token '[Convert]::FromBase64String', en dat is PowerShell-code die in bash terechtkomt.
2. Uitvoeringsbeleid. Weigert PowerShell scripts uit te voeren, start ze dan met powershell -NoProfile -ExecutionPolicy Bypass -File …, druk de JSON af en sluit af met exit 0.
3. GUI-programma’s keren te vroeg terug. Dit kostte ons een dag. Is je hook een Windows-programma dat voor het GUI-subsysteem is gebouwd, dan start PowerShell het en gaat verder zonder te wachten. Cursor leest lege uitvoer, dus de hook lijkt niets te doen (of blokkeert met failClosed alles). Bouw de hook als consoleprogramma, of verpak hem zo dat PowerShell wacht tot hij afsluit.

Hooks op projectniveau hebben ook een vertrouwde workspace nodig. Een medewerker van Cursor somde op wat je moet controleren als ze niets doen: de logregel “Hook N produced no output” in Hooks, of Settings → Hooks de workspace als vertrouwd toont, en fouten zoals spawn, ENOENT, EPERM of ExecutionPolicy in de console.

Hooks in de Cursor CLI

De Cursor CLI (cursor-agent) leest dezelfde ~/.cursor/hooks.json en .cursor/hooks.json, maar heeft nooit elk event verstuurd dat de editor verstuurt. In januari 2026 gingen alleen de twee shellhooks af. In april bevestigden medewerkers van Cursor dat beforeShellExecution, afterShellExecution, afterFileEdit, postToolUse, stop en sessionStart werkten in de CLI, terwijl afterAgentResponse en afterAgentThought dat nog steeds niet deden (in mei opnieuw bevestigd). Voor elk event dat niet op die lijst staat geldt: test het voordat je erop vertrouwt.

Cloud agents zijn nog strenger: hooks op gebruikersniveau uit ~/.cursor/hooks.json draaien daar helemaal niet.

Als een hook niet afgaat: een checklist

1. Open het uitvoerkanaal Hooks (View → Output → Hooks) of het tabblad Hooks in Customize. Daar zie je welke hooks zijn geladen, elke uitvoering en fouten.
2. Controleer het JSON-bestand zelf. "version": 1 aanwezig, eventnamen exact gespeld (ze zijn hoofdlettergevoelig), geldige JSON.
3. Controleer het pad. Relatieve commando’s worden voor projecthooks opgelost vanuit de projectroot en voor gebruikershooks vanuit ~/.cursor/.
4. Vertrouw de workspace. Projecthooks draaien niet in een niet-vertrouwde map.
5. Voer de hook met de hand uit. Stuur er voorbeeld-JSON naartoe via een pipe en bekijk stdout. Alles behalve één JSON-object (een verdwaalde echo, een waarschuwing) breekt het parsen.
6. Start Cursor opnieuw. Opslaan laadt het bestand opnieuw, maar meerdere forummeldingen werden pas opgelost met een volledige herstart.
7. Ken de beperkingen. ask en allow werden gemeld als genegeerd naast de allowlist en de sandbox; subagentStart/subagentStop gingen volgens meldingen in sommige versies niet af; de CLI slaat sommige events over. Commits vanuit het ingebouwde paneel Source Control worden niet onderschept: er is geen hookevent voor pre-commit.

Hooks, auto-run en Auto-review

Hooks staan los van de eigen goedkeuringsinstellingen van Cursor (Settings → Agents → Approvals & Execution). Auto-run en Auto-review bepalen of Cursor het je in zijn paneel vraagt; je hook voegt daar zijn eigen beslissing aan toe. Daarom is “mijn hook zei ask, maar het commando draaide gewoon” zo’n veelvoorkomende melding: een ander machtigingspad had het al toegestaan.

Nog iets wat we op de harde manier leerden: met Auto-review kan Cursor over sommige commando’s vragen in zijn eigen venster. Een hook ziet die vraag nooit. Die gebeurt in Cursor, niet in de hookpipeline.

Waar Pet Island in beeld komt

Wil je van hooks vooral “laat me elk riskant commando zien en laat me beslissen zonder van venster te wisselen”, dan is dat wat Pet Island met Cursor doet. Het installeert de hooks voor je (beforeShellExecution en beforeMCPExecution, met failClosed aan zodat een vastgelopen helper nooit een commando doorlaat) en zet elk verzoek met het volledige commando op een klein eiland bovenaan je scherm. Daar sta je het toe of weiger je het; de agent van Cursor wacht.

Commando’s en bestandsbewerkingen uit de Cursor-editor werken vanaf het eiland. Vragen en plannen verschijnen op het eiland, en je beantwoordt ze in Cursor. In de Cursor CLI werken commando’s vanaf het eiland; andere events hangen af van wat de CLI verstuurt. Bij het verwijderen worden alleen de vermeldingen verwijderd die Pet Island heeft toegevoegd; je eigen hooks blijven staan.

VEELGESTELDE VRAGEN

Bronnen

Elke instelling en elk gedrag op deze pagina is op 26 oktober 2026 gecontroleerd aan de hand van deze pagina’s. Agents veranderen snel; klopt er iets niet meer, dan geldt de officiële pagina.

• Cursor-documentatie: Hooks
• Cursor-forum: The cursor hooks did not execute as expected (medewerker: alleen deny wordt afgedwongen)
• Cursor-forum: beforeShellExecution allow/ask ignored, allow-list takes precedence
• Cursor-forum: Fail-closed hook and MainThreadShellExec not initialized
• Cursor-forum: Malformed JSON from a hook silently allowed the command (opgelost)
• Cursor-forum: Cursor CLI doesn’t send all hook events
• Cursor-forum: Project-level hooks fail to execute on Windows
• Cursor-forum: Project hooks fail on Windows with Git Bash
• Cursor-forum: subagentStart and subagentStop never fire

VERDER LEZEN