CONCEPT Hooks fire at fixed points in Claude Code's lifecycle
A hook is a user-defined command that Claude Code runs automatically at a specific lifecycle event. Hooks give you deterministic control: instead of hoping the model chooses to format a file or skip a dangerous command, you attach code to the event and it always runs. Each event fires at a well-defined moment — before a tool, after a tool, when you submit a prompt, when the model stops, when a session starts or ends.
These are the core events the exam expects you to know, in roughly the order they occur in a turn:
| Event | Fires when | Can it block? |
|---|---|---|
SessionStart | A session begins or resumes (matchers: startup, resume, clear, compact) | No — injects context |
UserPromptSubmit | You submit a prompt, before Claude processes it | Yes — can erase the prompt |
PreToolUse | Before a tool call executes | Yes — can deny the tool |
PostToolUse | After a tool call succeeds | Feedback only — tool already ran |
Notification | Claude Code sends a notification (needs input / permission) | No |
Stop | Claude finishes responding (the main agent) | Yes — can force it to keep going |
SubagentStop | A subagent (Task) finishes responding | Yes — can force it to keep going |
PreCompact | Before context compaction (matchers: manual, auto) | Yes |
SessionEnd | A session terminates | No |
PreToolUse,
UserPromptSubmit, PreCompact) run before an action and can stop it;
post-events (PostToolUse, Stop, SubagentStop) run
after and give feedback or push work to continue.CONCEPT The current set is larger — but the core nine anchor it
Recent Claude Code versions expose many more events beyond the core nine — for example
SubagentStart, PostToolUseFailure, PostToolBatch,
PermissionRequest, UserPromptExpansion, SessionEnd,
PostCompact, ConfigChange, and FileChanged. You browse the full,
version-current list any time with the /hooks menu inside Claude Code. Learn the core nine well;
they cover the vast majority of real automations, and the rest follow the same input/output contract.
Stop with SubagentStop. Stop fires when
the main agent finishes; SubagentStop fires when a Task subagent
finishes. A Stop hook fires every time Claude finishes responding — not only at "task done."DIAGRAM Where each event sits in a turn
(begin / resume)"] --> U["UserPromptSubmit
(you submit a prompt)"] U --> PRE{"PreToolUse
before each tool"} PRE -->|"allowed"| T["Tool runs"] T --> POST["PostToolUse
after tool succeeds"] POST -->|"more tools"| PRE POST -->|"done"| STOP["Stop
Claude finishes"] PRE -.->|"deny"| BLOCK["🔴 Tool blocked"] STOP --> END["SessionEnd
(terminate)"] N["Notification"] -.->|"needs input"| U classDef ok fill:#d4edda,stroke:#28a745,color:#155724; classDef gate fill:#ffe8cc,stroke:#ff9f40,color:#9a4a0a; classDef bad fill:#f8d7da,stroke:#dc3545,color:#721c24; class S ok; class POST ok; class END ok; class PRE gate; class STOP gate; class BLOCK bad;
CODE A hook keyed by its event name
In settings.json, the top-level hooks object is keyed by event name.
Here a PostToolUse hook logs the session, and a Stop hook plays a sound when Claude
finishes — two different lifecycle moments, two different keys.
{
"hooks": {
// after any tool succeeds, append a line to a log
"PostToolUse": [
{ "hooks": [
{ "type": "command",
"command": "jq -r .tool_name >> ~/.claude/tools.log" } ] }
],
// when the main agent finishes responding
"Stop": [
{ "hooks": [
{ "type": "command", "command": "afplay /System/Library/Sounds/Glass.aiff" } ] }
]
}
}
TRADE-OFFS Pre-events vs. post-events
✅ Pre-events (PreToolUse, UserPromptSubmit)
- Run before the action — can veto it
- The place to enforce guardrails and policy
- Can inject context that shapes what Claude does next
⚠️ Post-events (PostToolUse, Stop)
- Run after — the action already happened
- Can't undo; only give feedback or trigger follow-up work
- Best for formatting, logging, notifications, "keep going" checks
EXAM TRAPS
PostToolUse hook can cancel the edit." → No. The tool already
executed; PostToolUse can only feed back or reformat. To prevent a tool, use
PreToolUse.Stop only fires at task completion." → It fires every time
Claude finishes responding, not just when the whole task is done. It does not fire on user interrupts.Stop and SubagentStop. → Stop is
the main agent; SubagentStop is a Task subagent. Distinct events, distinct hooks.SubagentStart, PostToolBatch, SessionEnd, …). Use /hooks
to see the live set for your version.PRACTICE
Q1 · You want to block a dangerous command before it runs. Which event?
PreToolUse — it fires before the tool executes and can deny it. PostToolUse
runs after and cannot stop the action.
Q2 · Which event injects text into context when a session begins or resumes?
SessionStart. Its stdout is added to Claude's context, and its matchers
(startup, resume, clear, compact) let you target, e.g.,
only post-compaction re-injection.
Q3 · A Task subagent just finished. Which event fires — Stop or SubagentStop?
SubagentStop. Stop fires only for the main agent finishing its response;
a subagent finishing fires SubagentStop.