Deel C · Module 02

Afdwingen: hooks & permissies

Hoe garandeer je gedrag?

Zone: machine ± 15 min kern

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:

Hoe een matcher wordt geëvalueerd
MatcherBetekenisVoorbeeld
"*", "" of weggelatenallesvuurt bij elk voorkomen van het event
alleen letters, cijfers, _, -, spaties, ,, |exacte naam, of lijst van exacte namenBash; Edit|Write
bevat een ander tekenJavaScript-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:

Hook-beslissing tegenover permissieregels
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.
allowSlaat de permissieprompt over, maar omzeilt geen deny-regels uit settings en onderdrukt niet elke prompt (bv. leesacties op netwerkpaden).
askToont 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:

Uitkomst per combinatie (bv. op PreToolUse)
StdoutExit 0Exit 2Andere exitcode
Geldig JSON-objectSucces; de velden geldenBlokkade; velden worden gelezen maar kunnen die niet overrulenSucces: exitcode genegeerd, de velden beslissen
Kapotte of ongeldige JSONNiet-blokkerende foutBlokkade; stderr is de redenNiet-blokkerende fout
Gewone tekst of nietsSuccesBlokkade; stderr is de redenNiet-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):

Exit 2 op een selectie events
EventBlokkeert?Wat gebeurt er
PreToolUsejatool call geblokkeerd; Claude ziet stderr
UserPromptSubmitjaprompt bereikt Claude niet; stderr gaat naar jou
StopjaClaude mag niet stoppen en werkt door, met stderr als reden
PostToolUseneeClaude ziet stderr; de tool is al gedraaid
PermissionRequestneeexit 2 wordt niet gehonoreerd; gebruik het decision-object
SessionStartneestderr 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.

Universele velden
VeldBetekenis
continuestandaard true; false stopt Claude helemaal (blokkeert een PreToolUse-call niet; daarvoor heb je permissionDecision: "deny" nodig)
stopReasonbericht aan jou als continue false is
systemMessagewaarschuwing voor jou
terminalSequenceescape-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 voor command, http en mcp_tool; 30 voor prompt; 60 voor agent. Op UserPromptSubmit is het standaard 30 (want het blokkeert elke prompt), en alle SessionEnd-hooks delen een budget van 1,5 s. Een hook die zijn timeout haalt, wordt geannuleerd en zijn output weggegooid. Op PreToolUse blokkeert dat de call niet (tenzij onFailure: "block"); op PreModelSwitch blokkeert een timeout de wissel juist wel.
  • Async: "async": true (alleen command) draait de hook op de achtergrond; Claude wacht niet. De hook kan dan niets meer blokkeren of beslissen (decision, permissionDecision en continue hebben 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. Check stop_hook_active in de input; na acht opeenvolgende blokkades zonder tool call grijpt Claude Code zelf in.

a hook that returns permissionDecision: "deny" blocks the tool even in bypassPermissions mode 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"
          }
        ]
      }
    ]
  }
}
  1. matcher: filtert op toolnaam. Het script spawnt alleen voor Bash-calls, niet voor elke Read of Edit.
  2. command: pad via $CLAUDE_PROJECT_DIR, zodat het werkt vanuit elke map. Het script moet executable zijn (chmod +x) en een shebang hebben.
  3. timeout: 10 seconden in plaats van de standaard 600. Een hangende guardrail mag de agent niet eindeloos blokkeren.
  4. 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)
  1. stdin: de event-JSON. tool_input.command is het Bash-commando; cwd de werkmap van de sessie.
  2. 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.
  3. Logica die een regel niet kan: bij een kale git push hangt het doel af van de huidige branch. Daarvoor is een hook nodig.
  4. 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. A PreToolUse hook that blocks the edit is enforcement.

Doe-opdracht

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

  1. Maak een leeg project: mkdir hooks-oefening && cd hooks-oefening && git init, met een rommelig bestand hello.js (const a = 'x') en een map build/ met een dummy-bestand.
  2. Guardrail. Schrijf .claude/hooks/block-rm.sh: lees de stdin-JSON met jq, haal tool_input.command eruit, en sluit af met exit 2 en een bericht op stderr als het commando rm -rf bevat; anders exit 0. Maak het executable (chmod +x).
  3. Registreer het in .claude/settings.json als PreToolUse-hook met "matcher": "Bash". Test eerst los: echo '{"tool_input":{"command":"rm -rf build"}}' | .claude/hooks/block-rm.sh; echo $?.
  4. 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".
  5. Start claude in de map. Controleer met /hooks dat 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".
  6. Maak het kapot. Verander in de guardrail exit 2 naar exit 1 en herhaal de eerste vraag. Wat gebeurt er nu met build/? 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 +x en een pad met "$CLAUDE_PROJECT_DIR".
  • Verkeerde matcher. Matchers zijn hoofdlettergevoelig: bash matcht niet, Bash wel. 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 echo uit je .bashrc) en zet permissionDecision in hookSpecificOutput, niet op het hoogste niveau. Debuggen: claude --debug.
  • jq: command not found. Installeer jq of lees de JSON met Python of Node. Zonder jq faalt 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. PostToolUse op Edit|Write vuurt niet als een Bash-commando het bestand wijzigt. Daarvoor is FileChanged bedoeld.

Zelftoets