Claude Code hooks explained: config structure, matchers, and a copy-paste PreToolUse guard

Anthropic's Claude Code supports hooks—deterministic shell commands or HTTP endpoints that fire at fixed points in a session to block, allow, or reshape actions. A developer explains the configuration structure, the two modes for reporting decisions, and provides a copy-paste PreToolUse guard that blocks recursive rm commands. The hook JSON format for PreToolUse now requires a hookSpecificOutput object with a permissionDecision field, replacing the deprecated top-level decision field.

If you have only ever used Claude Code's permission prompts, hooks are the next layer down: deterministic shell commands or HTTP endpoints, MCP tools, prompts, or subagents that fire at fixed points in a session and can block, allow, or reshape what happens next. The feature is powerful, but the configuration has a few sharp edges that trip people up — especially the JSON your hook prints back, which changed and is easy to get wrong from memory. This post walks through the current config structure, the two ways a hook reports a decision, and a copy-paste PreToolUse guard that blocks recursive rm . Hooks live in a settings file .claude/settings.json for a project, ~/.claude/settings.json for your user . The shape is three levels of nesting, and naming them makes the rest of the docs click: { "hooks": { "PreToolUse": { "matcher": "Bash", "hooks": { "type": "command", "command": "${CLAUDE PROJECT DIR}/.claude/hooks/block-rm.sh", "if": "Bash rm " } } } } PreToolUse — the lifecycle point. Events fall into three cadences: once per session SessionStart , SessionEnd , once per turn UserPromptSubmit , Stop , and on every tool call PreToolUse , PostToolUse . "matcher": "Bash" — a filter for tool name . hooks array — the thing that actually runs. There are five types: command , http , mcp tool , prompt , and agent .The if field narrows further using permission-rule syntax — Bash rm here means "only spawn this handler when the Bash subcommand matches rm ," so the script never even launches for npm test . It holds exactly one rule; there is no && or || , so multiple conditions mean multiple handlers. A matcher that contains regex characters is tested with JavaScript's RegExp.prototype.test , which succeeds on a match anywhere in the value. So: Edit also matches NotebookEdit . If you mean only the Edit tool, write ^Edit$ . mcp <server <tool . A bare mcp memory is treated as an exact string and matches . suffix: mcp memory . for every tool from the memory server.If you want a handler to run on every occurrence of an event, omit the matcher or use " " . This is where most confusion lives. A command hook communicates results through exit codes and stdout , and you choose one of two modes: Exit codes alone. Exit 0 means success and no decision staying silent does not approve a call — it just lets the normal permission flow continue . Exit 2 is a blocking error: Claude Code ignores stdout and feeds your stderr back to Claude as the reason. For PreToolUse , exit 2 blocks the tool call. Exit 0 plus JSON on stdout. For finer control, exit 0 and print a JSON object. Claude Code only parses JSON on exit 0 — if you exit 2, any JSON is ignored. You must choose one approach per hook, not both. decision: "block" If you learned hooks a while ago, you probably remember a top-level {"decision": "block"} . That is deprecated for PreToolUse. This event now returns its decision inside a hookSpecificOutput object with a required hookEventName , and the field is permissionDecision with four possible values: allow , deny , ask , or defer . The old "approve" / "block" map to "allow" / "deny" . Other events like PostToolUse and Stop still use the top-level decision / reason fields — so the format genuinely differs per event, and copying a PostToolUse snippet into PreToolUse won't work.Here is the correct current shape for a PreToolUse deny: { "hookSpecificOutput": { "hookEventName": "PreToolUse", "permissionDecision": "deny", "permissionDecisionReason": "Recursive rm is blocked. Delete specific files instead." } } rm Save this as .claude/hooks/block-rm.sh and chmod +x it. It reads the event JSON on stdin, pulls the Bash command with jq , and denies anything with a recursive rm : bash /usr/bin/env bash PreToolUse hook: deny recursive rm, stay silent otherwise. Requires jq on PATH. input=$ cat command=$ printf '%s' "$input" | jq -r '.tool input.command // ""' if printf '%s' "$command" | grep -qiE ' ^| :space: rm :space: + - a-z r|--recursive '; then cat <<'JSON' { "hookSpecificOutput": { "hookEventName": "PreToolUse", "permissionDecision": "deny", "permissionDecisionReason": "Recursive rm is blocked by a project hook. Delete specific files instead." } } JSON exit 0 fi No decision: exit 0 with no output lets the normal permission flow decide. exit 0 With the settings above, the if: "Bash rm " filter means the script only spawns for rm commands saving the process launch on unrelated calls , and the matcher keeps it scoped to Bash. When Claude tries rm -rf /tmp/build , the hook prints the deny JSON, Claude Code blocks the call, and Claude sees the reason. A note on paths: ${CLAUDE PROJECT DIR} is substituted by Claude Code to your project root, so the hook resolves no matter what the working directory is at call time. If your project path contains spaces, switch the handler to exec form set args so each element is passed as one argument with no shell quoting. Hooks are the deterministic guardrail layer. Two neighbors worth knowing: if filter is best-effort. if filter fail open and run your hook anyway.Type /hooks in Claude Code to open a read-only browser of everything you have configured, including which settings file each hook came from — a fast way to confirm your matcher is actually matching. I'm Rulestack — I build and maintain drop-in rule and hook packs for Claude Code, Cursor, and Codex. There's a Claude Code Hooks Pack of production-ready guardrails if you'd rather not hand-roll each one. I post working AI-coding tips on Bluesky at @ai-shop.bsky.social — follow along if this was useful.