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
:
#!/usr/bin/env bash
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
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.