Skip to main content

7.3 Claude hooks

The smallest skill on the exam (1.0%) and the answer to a disproportionate number of items, because hooks are the deterministic enforcement mechanism.

What a hook is​

Application code the harness executes at a defined lifecycle point. It runs every time, outside the model's discretion. That is the entire value proposition: a system prompt makes compliance likely, a hook makes it certain.

.claude/settings.json
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [{ "type": "command", "command": ".claude/hooks/guard-bash.sh" }]
}
],
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [{ "type": "command", "command": "npm run lint:fix --silent" }]
}
]
}
}

Lifecycle points and their uses​

EventFiresDeterministic use
PreToolUseBefore a tool executesBlock it: destructive shell commands, writes outside an allowed path, refunds over a threshold, a missing prerequisite step. Or require approval
PostToolUseAfter a tool returnsNormalise heterogeneous results (timestamp formats, status codes) before the model reads them; redact secrets; run a formatter or linter after an edit
UserPromptSubmitOn each user turnInject required context; screen the input
SessionStart / SessionEndSession boundariesLoad or persist state; emit an audit record
Stop / SubagentStopWhen a turn or subagent finishesVerify completion criteria; run tests and feed failures back
PreCompactBefore compactionExtract durable facts before detail is summarised away
NotificationOn notificationsRoute to a chat channel or pager

The contract that matters: a PreToolUse hook can deny the call, and the agent sees the denial with your reason — so the message is an instruction to the model, not just a log line. A non-blocking hook's output is advisory. In Claude Code this is expressed through the hook's exit status and its structured output; the exact codes are in the hooks reference.

Hook versus prompt versus tool description​

ProblemFix
The agent sometimes skips a required verification stepPreToolUse hook blocking the downstream tool until the prerequisite has run
The agent occasionally exceeds a business thresholdPreToolUse hook comparing the argument to the limit and denying, redirecting to escalation
The agent runs a destructive commandPreToolUse hook with a deny list, plus permissions.deny in settings
The agent picks the wrong tool among similar onesRewrite the tool descriptions — a hook cannot fix selection
The agent's tone or format is offPrompt or schema
Tool results arrive in three different formatsPostToolUse hook normalising them — deterministic transformation belongs in code, not in the model's head
Edits land unformattedPostToolUse hook running the formatter
Facts are lost to compactionPreCompact hook extracting them to a store
The distinction the exam tests

Selection problems (which tool, when) are fixed by descriptions. Compliance problems (ordering, thresholds, forbidden operations) are fixed by hooks. Strengthening a system prompt fixes neither reliably, because prompt compliance is probabilistic and the cases that matter are exactly the ones where it fails.

Writing hooks that hold​

PracticeWhy
Fail closedIf the check cannot be evaluated, deny
Be fastThe hook is on the critical path of every matching call
Return a reason the model can act on"Refunds above $500 require escalation; call create_escalation instead" beats "denied"
Match narrowlyA matcher that catches every tool becomes a bottleneck and a source of surprises
Log every decisionThe audit trail for a blocked action is the point
Version it with the repoA hook is code: reviewed, tested, committed
Never put secrets in the hook's outputIt goes into the model's context

The same logic belongs on the API side of a custom agent: a pre-dispatch check in your tool executor is the API-side equivalent of a PreToolUse hook, and it is where an API-based agent's invariants must live.

Quiz​

  1. Question 1

    Edits made by Claude Code sometimes land unformatted, and occasionally a shell command touches a path the team considers off-limits. Which hook configuration addresses both?