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.
{
"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
| Event | Fires | Deterministic use |
|---|---|---|
| PreToolUse | Before a tool executes | Block it: destructive shell commands, writes outside an allowed path, refunds over a threshold, a missing prerequisite step. Or require approval |
| PostToolUse | After a tool returns | Normalise heterogeneous results (timestamp formats, status codes) before the model reads them; redact secrets; run a formatter or linter after an edit |
| UserPromptSubmit | On each user turn | Inject required context; screen the input |
| SessionStart / SessionEnd | Session boundaries | Load or persist state; emit an audit record |
| Stop / SubagentStop | When a turn or subagent finishes | Verify completion criteria; run tests and feed failures back |
| PreCompact | Before compaction | Extract durable facts before detail is summarised away |
| Notification | On notifications | Route 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
| Problem | Fix |
|---|---|
| The agent sometimes skips a required verification step | PreToolUse hook blocking the downstream tool until the prerequisite has run |
| The agent occasionally exceeds a business threshold | PreToolUse hook comparing the argument to the limit and denying, redirecting to escalation |
| The agent runs a destructive command | PreToolUse hook with a deny list, plus permissions.deny in settings |
| The agent picks the wrong tool among similar ones | Rewrite the tool descriptions — a hook cannot fix selection |
| The agent's tone or format is off | Prompt or schema |
| Tool results arrive in three different formats | PostToolUse hook normalising them — deterministic transformation belongs in code, not in the model's head |
| Edits land unformatted | PostToolUse hook running the formatter |
| Facts are lost to compaction | PreCompact hook extracting them to a store |
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
| Practice | Why |
|---|---|
| Fail closed | If the check cannot be evaluated, deny |
| Be fast | The 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 narrowly | A matcher that catches every tool becomes a bottleneck and a source of surprises |
| Log every decision | The audit trail for a blocked action is the point |
| Version it with the repo | A hook is code: reviewed, tested, committed |
| Never put secrets in the hook's output | It 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
- 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?