Deel C · Module 02
Afdwingen: hooks & permissies
Hoe garandeer je gedrag?
Leerdoelen
Na deze module kun je:
- aanwijzen op welk moment in de agentic loop een hook-event vuurt, en voorspellen of exit 2 daar de actie blokkeert (
PreToolUse) of alleen feedback geeft (PostToolUse); - voorspellen wat de harness doet bij exit 0, exit 2, een andere exitcode en JSON-output met een decision, en wat het model en jij daarvan zien;
- kiezen tussen een instructie (CLAUDE.md, skill), een permissieregel en een hook voor een gewenste garantie, en een guardrail-hook schrijven en debuggen.
Voorkennis-check
Twee vragen over de agentic loop. Fout? Lees B3 De agentic loop eerst terug.
Waar zitten we?
Hooks horen bij laag 4, de harness: de code om de agent-loop heen. Het model kent ze niet; de harness vuurt ze af op vaste punten van de loop (laag 3) en kan daar ingrijpen.
De stof in drie lagen
Kern ± 5 min lezen, daarna spelen met de visual
In de vorige module stuurde je het model: CLAUDE.md, rules en skills zijn tekst in de context. Het model leest ze en volgt ze meestal, maar het mag ook anders. Dat is probabilistisch gedrag: een kans, geen garantie.
Soms heb je een garantie nodig: nooit naar main pushen, nooit .env aanpassen, altijd formatteren na een edit. Daarvoor gebruik je mechanismen die buiten het model draaien. De harness voert ze uit, ongeacht wat het model denkt:
Het model mag (probabilistisch)
- CLAUDE.md, rules, skills
- Staan als tekst in de context
- Het model beslist of het ze volgt
- Kosten context (altijd of bij gebruik)
De harness dwingt af (deterministisch)
- Hooks en permissieregels
- Draaien als code buiten het gesprek
- Het model heeft er geen zeggenschap over
- Hooks kosten geen context, tenzij ze output teruggeven
Een hook is een stukje code (meestal een shell-script) dat de harness aanroept op een vast punt in de levenscyclus: voordat een tool draait, nadat hij klaar is, als je een prompt indient, als Claude wil stoppen. De hook krijgt een JSON-beschrijving van wat er gebeurt en antwoordt met een exitcode (of JSON): doorgaan, of stoppen.
Onderstaande visual heeft twee delen. Eerst de lifecycle: waar in de loop vuurt welk event, en wat kan het doen? Daarna de simulator: wat doet de harness als je hook exit 0, exit 2 of iets anders teruggeeft? Probeer vooral PreToolUse met exit 1 en met exit 2. Dat verschil is de meest gemaakte fout.
Samengevat: exit 0 = geen bezwaar. Exit 2 = blokkeren, voor zover het event dat kan; stderr is de reden. Elke andere exitcode = een foutmelding voor jou, maar de actie gaat door.
Verdieping cadansen, matchers, types, permissies, context
Drie cadansen (plus een restgroep)
De docs delen de events in naar hoe vaak ze vuren: per sessie (SessionStart, SessionEnd), per beurt (UserPromptSubmit, Stop, StopFailure) en bij elke tool call in de agentic loop (PreToolUse, PostToolUse). Daarnaast staat een groep losse events naast de hoofdflow (o.a. Notification, FileChanged, PreCompact). De visual hanteert dezelfde indeling; de ordening binnen "Overig" is onze eigen groepering. Alle events zijn in data/hooks-events.json vastgelegd, afgeleid uit de hooks-referentie.
Het beslissende verschil zit in wat een event kan doen. Een event dat vóór een actie vuurt (PreToolUse, UserPromptSubmit) kan hem tegenhouden. Een event dat erna vuurt (PostToolUse) kan alleen feedback geven: de tool is al gedraaid.
Matchers en de if-filter
Een hook-config heeft drie niveaus: event, dan een matcher group (filter) en daarbinnen een of meer handlers. De matcher filtert op een veld dat per event verschilt: bij tool-events de toolnaam, bij SessionStart de manier van starten (startup, resume, ...). Hoe de matcher wordt gelezen hangt af van de tekens:
| Matcher | Betekenis | Voorbeeld |
|---|---|---|
"*", "" of weggelaten | alles | vuurt bij elk voorkomen van het event |
alleen letters, cijfers, _, -, spaties, ,, | | exacte naam, of lijst van exacte namen | Bash; Edit|Write |
| bevat een ander teken | JavaScript-regex, niet verankerd | ^Notebook; mcp__memory__.* |
Let op: Edit.* matcht ook NotebookEdit; gebruik ^Edit$ voor een exacte match. Matchers zijn hoofdlettergevoelig. Events zonder matcher-ondersteuning (zoals UserPromptSubmit en Stop) negeren een matcher-veld stilzwijgend.
Met het optionele veld if filter je verder op de aanroep zelf, in permissieregel-syntaxis, bv. "Bash(git push *)" of "Edit(*.ts)". Dan spawnt je script alleen als ook die regel past. Het if-veld bevat precies één regel (geen && of lijst), en werkt alleen op tool-events. De docs noemen de if-filter bij Bash best-effort: kan Claude Code het commando niet in subcommando's splitsen, dan draait je hook gewoon. Laat het script zelf dus altijd de definitieve controle doen.
Vijf hook-types
Een handler is meestal een shell-commando (type: "command"), maar er zijn er vijf: command, http (POST van de event-JSON naar een URL), mcp_tool (een tool op een MCP-server), prompt (een enkele modelbeoordeling) en agent (een subagent die met Read, Grep en Glob iets verifieert; experimenteel). De eerste drie voeren jouw logica uit. Bij prompt en agent beslist weer een model: handig voor oordelen die je niet in code kunt vatten, maar het is geen harde garantie meer.
Permissies: de andere helft van het afdwingen
Naast hooks kent Claude Code permissieregels in settings.json: allow-, ask- en deny-regels in de vorm Tool(patroon), bijvoorbeeld Edit(/.env) onder permissions.deny. Daarbovenop komen permission modes die bepalen hoeveel er zonder prompt mag. De waarden die een hook in permission_mode ontvangt zijn default (in de UI "Manual"), plan, acceptEdits, auto, dontAsk en bypassPermissions.
Hoe verhouden die twee zich? De regels uit de hooks-docs:
Een PreToolUse-hook geeft ... | Gevolg |
|---|---|
deny (of exit 2) | De tool wordt geblokkeerd, in elke permission mode, ook bypassPermissions en --dangerously-skip-permissions: PreToolUse vuurt vóór de mode-check. |
allow | Slaat de permissieprompt over, maar omzeilt geen deny-regels uit settings en onderdrukt niet elke prompt (bv. leesacties op netwerkpaden). |
ask | Toont de gewone permissieprompt, met de reden van de hook. |
| geen beslissing (exit 0, geen output) | De normale permissieflow bepaalt het. Een hook kan weigeren, maar zwijgen is geen goedkeuring. |
Een hook kan dus aanscherpen, maar nooit verder loslaten dan je regels toestaan. Bij meerdere hooks op hetzelfde event wint de strengste beslissing (deny > defer > ask > allow), en alle hooks draaien tot het einde: een deny van de ene hook voorkomt niet dat de andere zijn bijeffecten uitvoert.
Wanneer wat? Een vast patroon (dit pad, dit commando-prefix) leg je als deny-regel vast: eenvoudig, declaratief, geen script om te onderhouden. Heeft de beslissing logica nodig (inhoud, branch, tijdstip, een extern systeem), wil je loggen, of invoer herschrijven (updatedInput), dan is het een hook. In de praktijk gebruik je ze samen; de hooks-guide adviseert bij een hook die Edit|Write bewaakt ook een Edit-deny-regel, want Claude kan bestanden ook via shell-commando's wijzigen.
Er is ook een event PermissionRequest: dat vuurt als Claude Code op het punt staat om om toestemming te vragen. Een hook kan dan namens jou toestaan of weigeren (decision.behavior). Let op: exit 2 wordt op dit event niet gehonoreerd, je moet het decision-object teruggeven (probeer het in de simulator).
Wat kosten hooks aan context?
Zero, unless the hook returns output that gets added as messages to your conversation.
De hook draait als los proces; het model weet niet dat hij bestaat. Context kost alleen wat je teruggeeft: additionalContext, plain-text stdout op UserPromptSubmit, UserPromptExpansion, SessionStart en PostModelSwitch, of stderr bij exit 2. Elke zo'n string is begrensd op 10.000 tekens. Dat maakt hooks geschikt voor bijeffecten (formatteren, loggen), terwijl CLAUDE.md en skill-descriptions elke sessie of elke keer context kosten.
Waar leef je hooks?
Hooks staan in JSON-settings: ~/.claude/settings.json (al je projecten), .claude/settings.json (project, deelbaar via git), .claude/settings.local.json (project, niet gedeeld), beheerde organisatie-instellingen, de hooks/hooks.json van een plugin, of frontmatter van een skill of subagent. Hooks van verschillende niveaus mergen: ze vuren allemaal. Beheerders kunnen met allowManagedHooksOnly alle andere hooks uitschakelen. Dat maakt hooks een natuurlijk instrument voor organisatiebeleid (zie later D4).
Hooks are user-defined shell commands, HTTP endpoints, MCP tool calls, LLM prompts, or subagents that execute automatically at specific points in Claude Code's lifecycle.
Onder de motorkap stdin-payload, exitcodes, JSON-schema, timeouts, async
Wat je hook ontvangt: de stdin-payload
Een command-hook krijgt de event-informatie als JSON op stdin (een HTTP-hook als POST-body). Dit is wat een PreToolUse-hook op Bash krijgt:
stdin van een PreToolUse-hook (Bash)
{
"session_id": "abc123",
"prompt_id": "550e8400-e29b-41d4-a716-446655440000",
"transcript_path": "/home/user/.claude/projects/.../transcript.jsonl",
"cwd": "/home/user/my-project",
"permission_mode": "default",
"hook_event_name": "PreToolUse",
"tool_name": "Bash",
"tool_input": {
"command": "npm test",
"description": "Run test suite",
"timeout": 120000,
"run_in_background": false
},
"tool_use_id": "toolu_01ABC123..."
}
De velden tool_name, tool_input en tool_use_id zijn event-specifiek; de rest (session_id, cwd, permission_mode, hook_event_name, ...) krijgt elk event. Bij PostToolUse komt er een tool_response bij. Voor Write, Edit en Read is tool_input.file_path altijd absoluut (~ en relatieve paden zijn al uitgeschreven, dus je kunt een padcheck niet omzeilen met een andere schrijfwijze). Op Windows zijn de scheidingstekens backslashes: normaliseer vóór je vergelijkt.
Exitcodes en stdout samen
Wat de harness doet hangt af van de combinatie van exitcode en wat je op stdout print. Dit is de tabel uit de referentie, vertaald:
| Stdout | Exit 0 | Exit 2 | Andere exitcode |
|---|---|---|---|
| Geldig JSON-object | Succes; de velden gelden | Blokkade; velden worden gelezen maar kunnen die niet overrulen | Succes: exitcode genegeerd, de velden beslissen |
| Kapotte of ongeldige JSON | Niet-blokkerende fout | Blokkade; stderr is de reden | Niet-blokkerende fout |
| Gewone tekst of niets | Succes | Blokkade; stderr is de reden | Niet-blokkerende fout (eerste regel stderr in de melding) |
Drie dingen springen eruit. (1) Exit 2 blokkeert altijd, ook als je JSON allow zegt. (2) Exit 1 blokkeert nooit, tenzij hij gepaard gaat met geldige JSON die blokkeert. (3) Claude ziet stderr nooit bij exit 0. Mengen kan, maar de docs raden het af:
Choose one approach per hook: either use exit codes alone for signaling, or exit 0 and print JSON for structured control.
Exit 2 per event
Waar exit 2 op slaat, hangt af van het event. Een greep (de volledige tabel zit in de visual en in hooks-events.json):
| Event | Blokkeert? | Wat gebeurt er |
|---|---|---|
PreToolUse | ja | tool call geblokkeerd; Claude ziet stderr |
UserPromptSubmit | ja | prompt bereikt Claude niet; stderr gaat naar jou |
Stop | ja | Claude mag niet stoppen en werkt door, met stderr als reden |
PostToolUse | nee | Claude ziet stderr; de tool is al gedraaid |
PermissionRequest | nee | exit 2 wordt niet gehonoreerd; gebruik het decision-object |
SessionStart | nee | stderr alleen voor jou; sessie gaat door |
JSON-output: het schema
Wil je meer dan "ja/nee", dan sluit je af met exit 0 en print je één JSON-object (en niets anders) op stdout. Er zijn drie soorten velden: universele velden voor elk event, top-level decision/reason voor sommige events, en een genest hookSpecificOutput met verplichte hookEventName.
| Veld | Betekenis |
|---|---|
continue | standaard true; false stopt Claude helemaal (blokkeert een PreToolUse-call niet; daarvoor heb je permissionDecision: "deny" nodig) |
stopReason | bericht aan jou als continue false is |
systemMessage | waarschuwing voor jou |
terminalSequence | escape-sequentie voor Claude Code om uit te sturen (melding, titel, bel) |
Per event verschilt het besliskanaal. PreToolUse gebruikt hookSpecificOutput:
PreToolUse: allow, deny, ask of defer
{
"hookSpecificOutput": {
"hookEventName": "PreToolUse",
"permissionDecision": "deny",
"permissionDecisionReason": "Database writes are not allowed"
}
}
Optioneel in hetzelfde object: updatedInput (vervangt de hele tool-input vóór uitvoering), additionalContext. Events als UserPromptSubmit, PostToolUse, Stop en PreCompact gebruiken top-level decision: "block" met reason, en PostToolUse kan met updatedToolOutput herschrijven wat Claude ziet. Veelgemaakte fout: permissionDecision op het hoogste niveau zetten in plaats van in hookSpecificOutput: de JSON parset, het veld wordt zonder foutmelding genegeerd.
Fail-open of fail-closed
Een hook die niet start (pad klopt niet, script niet executable, jq ontbreekt) of een timeout haalt, is een niet-blokkerende fout: de actie gaat gewoon door. Een beleidshook met een typfout in het pad doet dus niets. Wil je fail-closed, zet dan "onFailure": "block" op een command- of http-hook (vereist Claude Code v2.1.295 of nieuwer). Het heeft geen effect op Stop, SubagentStop, TaskCompleted en TeammateIdle, noch op background-hooks.
Timeouts, async en parallel
- Timeouts (seconden,
timeout-veld): standaard 600 voorcommand,httpenmcp_tool; 30 voorprompt; 60 vooragent. OpUserPromptSubmitis het standaard 30 (want het blokkeert elke prompt), en alleSessionEnd-hooks delen een budget van 1,5 s. Een hook die zijn timeout haalt, wordt geannuleerd en zijn output weggegooid. OpPreToolUseblokkeert dat de call niet (tenzijonFailure: "block"); opPreModelSwitchblokkeert een timeout de wissel juist wel. - Async:
"async": true(alleencommand) draait de hook op de achtergrond; Claude wacht niet. De hook kan dan niets meer blokkeren of beslissen (decision,permissionDecisionencontinuehebben geen effect); output komt bij de volgende beurt. Ideaal voor trage tests na een edit. - Parallel: alle matchende hooks van een event draaien tegelijk; identieke handlers uit meerdere settings-bestanden draaien één keer.
- Lussen: een
Stop-hook die steeds blokkeert, bouwt een oneindige lus. Checkstop_hook_activein de input; na acht opeenvolgende blokkades zonder tool call grijpt Claude Code zelf in.
a hook that returns
permissionDecision: "deny"blocks the tool even inbypassPermissionsmode or with--dangerously-skip-permissions.
Uitgewerkt voorbeeld: nooit pushen naar main
Een complete guardrail in twee bestanden: de config die de hook registreert, en het script dat beslist. Het commando git push kan op veel manieren naar main wijzen (git push origin main, HEAD:main, of kaal git push terwijl je op main staat). Zo'n beslissing past niet in een permissieregel. Het is een klein programma.
.claude/settings.json
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/no-push-main.py",
"timeout": 10,
"onFailure": "block"
}
]
}
]
}
}
- matcher: filtert op toolnaam. Het script spawnt alleen voor Bash-calls, niet voor elke Read of Edit.
- command: pad via
$CLAUDE_PROJECT_DIR, zodat het werkt vanuit elke map. Het script moet executable zijn (chmod +x) en een shebang hebben. - timeout: 10 seconden in plaats van de standaard 600. Een hangende guardrail mag de agent niet eindeloos blokkeren.
- onFailure: "block": faalt het script (verkeerd pad, crash, timeout), dan wordt de call geblokkeerd in plaats van doorgelaten. Fail-closed. Vereist Claude Code v2.1.295+; laat het weg op oudere versies.
.claude/hooks/no-push-main.py
#!/usr/bin/env python3
import json, re, subprocess, sys
payload = json.load(sys.stdin)
cmd = payload.get("tool_input", {}).get("command", "")
def blokkeer(reden):
print(f"Blocked: {reden}", file=sys.stderr)
sys.exit(2)
for deel in re.split(r"&&|\|\||;|\n", cmd):
m = re.match(r"\s*git\s+push\b(.*)", deel)
if not m:
continue
posities = [a for a in m.group(1).split() if not a.startswith("-")]
if len(posities) >= 2: # git push <remote> <refspec>
doel = posities[1].split(":")[-1].removeprefix("refs/heads/")
else: # kale `git push`: huidige branch
uit = subprocess.run(["git", "branch", "--show-current"],
capture_output=True, text=True, cwd=payload.get("cwd"))
doel = uit.stdout.strip()
if doel in ("main", "master"):
blokkeer(f"directe push naar {doel} is niet toegestaan; maak een branch en open een PR")
sys.exit(0)
- stdin: de event-JSON.
tool_input.commandis het Bash-commando;cwdde werkmap van de sessie. - Blokkeren: bericht naar stderr en exit 2. Claude ontvangt de tekst als foutmelding van de tool (
PreToolUse:Bash hook error: [...]: Blocked: ...) en kan zijn aanpak bijstellen. Print je de reden naar stdout, dan ziet Claude haar niet. - Logica die een regel niet kan: bij een kale
git pushhangt het doel af van de huidige branch. Daarvoor is een hook nodig. - Exit 0 zonder output betekent "geen beslissing": voor alle andere commando's loopt de normale permissieflow. Zwijgen is geen goedkeuring: een hook kan weigeren, niet stilzwijgend toestaan.
Test het script los, zonder Claude: echo '{"tool_name":"Bash","cwd":".","tool_input":{"command":"git push origin main"}}' | .claude/hooks/no-push-main.py; echo $? geeft de melding en 2. Met git push -u origin feature/x geeft het 0.
An instruction like "never edit
.env" in CLAUDE.md or a skill is a request, not a guarantee. APreToolUsehook that blocks the edit is enforcement.
Bouw een guardrail en een formatter-hook
Je bouwt twee hooks in een wegwerp-project: een PreToolUse-hook die een gevaarlijk commando blokkeert, en een PostToolUse-hook die na elke edit een formatter draait. Je hebt Claude Code, jq en (voor de formatter) Node met npx nodig. Een andere formatter mag ook.
Opdracht
- Maak een leeg project:
mkdir hooks-oefening && cd hooks-oefening && git init, met een rommelig bestandhello.js(const a = 'x') en een mapbuild/met een dummy-bestand. - Guardrail. Schrijf
.claude/hooks/block-rm.sh: lees de stdin-JSON metjq, haaltool_input.commanderuit, en sluit af metexit 2en een bericht op stderr als het commandorm -rfbevat; andersexit 0. Maak het executable (chmod +x). - Registreer het in
.claude/settings.jsonalsPreToolUse-hook met"matcher": "Bash". Test eerst los:echo '{"tool_input":{"command":"rm -rf build"}}' | .claude/hooks/block-rm.sh; echo $?. - Formatter. Voeg een
PostToolUse-hook toe met"matcher": "Edit|Write"en dit commando:f=$(jq -r '.tool_input.file_path') && npx prettier --write --ignore-unknown "$f". - Start
claudein de map. Controleer met/hooksdat beide hooks staan. Vraag Claude: "Verwijder de map build met rm -rf". Vraag daarna: "Voeg in hello.js een regel toe met een string tussen enkele quotes". - Maak het kapot. Verander in de guardrail
exit 2naarexit 1en herhaal de eerste vraag. Wat gebeurt er nu metbuild/? Zet daarna"onFailure": "block"aan en haal het script weg (hernoem het): wat nu?
Verwacht resultaat
Guardrail: Claude probeert rm -rf build, de tool draait niet en build/ bestaat nog. Claude ziet een foutmelding als PreToolUse:Bash hook error: [...block-rm.sh]: Blocked: ... en kiest een andere aanpak of meldt het aan jou. Met Ctrl+O zie je dezelfde melding in het transcript.
Formatter: na de edit staat in hello.js een string met dubbele quotes (Prettier-standaard). In het gesprek verschijnt niets: slagen is stil. Het bewijs is het bestand zelf.
Kapot maken: met exit 1 wordt build/ wel verwijderd en zie je alleen een melding Failed with non-blocking status code: .... Met onFailure: "block" en een ontbrekend script wordt het commando geblokkeerd, met een foutmelding die failed; blocking because onFailure is "block" bevat.
Als het niet werkt, kijk naar …
- Script niet executable of verkeerd pad. Dat is een niet-blokkerende fout: het commando draait gewoon, jij ziet "No such file or directory" of "Permission denied" in de melding. Gebruik
chmod +xen een pad met"$CLAUDE_PROJECT_DIR". - Verkeerde matcher. Matchers zijn hoofdlettergevoelig:
bashmatcht niet,Bashwel. Voor meerdere tools:Edit|Write. Check/hooks: staat de hook onder het juiste event? - stderr versus stdout. De reden van een blokkade moet op stderr (
echo "..." >&2). Zet je hem op stdout, dan wordt het commando wel geblokkeerd maar ziet Claude geen reden. Bij exit 0 ziet Claude stderr nooit. - JSON werkt niet. Print alleen het JSON-object op stdout (niets ervoor, bv. een
echouit je.bashrc) en zetpermissionDecisioninhookSpecificOutput, niet op het hoogste niveau. Debuggen:claude --debug. jq: command not found. Installeerjqof lees de JSON met Python of Node. Zonderjqfaalt de hook niet-blokkerend.- Hook staat niet in
/hooks. Ongeldige JSON in settings (komma's achteraan, commentaar) zorgt ervoor dat de hooks niet laden. - Formatter doet niets na een
Bash-edit.PostToolUseopEdit|Writevuurt niet als een Bash-commando het bestand wijzigt. Daarvoor isFileChangedbedoeld.