The Full Hook Event Lifecycle
AdvancedConfigure behavior and permissions via settings.json · Difficulty 2/5
Explanation
More Than Just PreToolUse and PostToolUse
PreToolUse and PostToolUse are the two hook events that come up most because they're the ones that sit directly on the tool-call boundary -- one gates whether a call happens, the other gates what comes back. But the agent lifecycle has several more hook events, each bound to a different moment in a session, and each configured the same way: in settings.json, as a lifecycle event plus a command that runs when it fires.
| Event | Fires | Typical use |
|---|---|---|
PreToolUse | Before a tool call executes | Block or approve the call before it runs |
PostToolUse | After a tool call completes | Format, validate, log -- side effects on a call that already happened |
UserPromptSubmit | Before the model processes a submitted prompt | Inject context, or validate the incoming prompt before any work starts |
Stop | When the model finishes responding | Notifications, cleanup, committing an audit-log entry |
Notification | On a permission request, or after 60 seconds of idle time | Forward that event to a monitoring channel, chat integration, or audit log |
SessionStart | At session init (start or resume) | Validate environment variables, confirm dependent services are reachable |
SessionEnd | At session teardown | Final audit writes, teardown tasks, close-out notifications |
Why the Full Set Matters
Each event covers a different kind of guarantee. PreToolUse/PostToolUse bracket a single tool call. UserPromptSubmit and Stop bracket a single turn. SessionStart and SessionEnd bracket the whole session. Notification is the odd one out -- it doesn't bracket anything; it fires on a specific signal (a permission request, or 60 seconds of idle time) regardless of where in the lifecycle that signal occurs. An exam item that describes "validate that a required service is reachable before the agent starts working" is describing SessionStart, not PreToolUse -- the check needs to happen once, at the very beginning of the session, not before every individual tool call.
All of these run as deterministic code, exactly like PreToolUse/PostToolUse -- they fire every time the event occurs, regardless of what the model decides. The full lifecycle is what makes it possible to enforce a hard rule (or automate a side effect) at literally any point in a session's life, not just around tool calls.
Common exam traps
- Assuming hooks only exist at the tool-call boundary.
UserPromptSubmit,Stop,Notification,SessionStart, andSessionEndare all real, distinct hook events covering the rest of the session lifecycle. - Reaching for
PreToolUseto validate environment variables or confirm a dependent service is reachable -- that's a session-level concern, which is exactly whatSessionStartexists for. - Confusing
Stop(fires when the model finishes responding, mid-session) withSessionEnd(fires at session teardown) -- they bracket different scopes.
Key Takeaways
- The full hook lifecycle is PreToolUse, PostToolUse, UserPromptSubmit, Stop, Notification, SessionStart, and SessionEnd
- UserPromptSubmit fires before the model processes a submitted prompt -- for injecting context or validating the request
- Stop fires when the model finishes responding -- for notifications, cleanup, or committing an audit-log entry
- Notification fires on a permission request or after 60 seconds of idle time
- SessionStart fires at session init -- for validating env vars or confirming dependent services are reachable; SessionEnd fires at teardown for final audit writes
- All hook events are deterministic code that fires every time the event occurs, regardless of the model's decision
Glossary Terms
Shell scripts or commands configured in .claude/settings.json that run at defined lifecycle points: PreToolUse (before tool execution), PostToolUse (after tool execution), Stop (before ending), SubagentStop (when subagent finishes). Used for code quality gates, notifications, logging, and safety checks.
An Agent SDK lifecycle hook that intercepts tool calls before execution. Can inspect, modify, or block the call. Used for access control, parameter sanitization, rate limiting, and audit logging. Runs synchronously before the tool executes.
An Agent SDK lifecycle hook that intercepts tool results before the agent processes them. Can normalize, enrich, or transform results from multiple tools into a consistent format. Works with both custom and third-party MCP tools without modifying their source code.
An Agent SDK lifecycle hook that runs when the agent reaches an end_turn stop condition. Can inspect the final response and decide whether to allow the stop or inject additional instructions to continue the loop. Used for output validation and quality gates.
Related Concepts
settings.json as the Deterministic Control Surface
settings.json (user: ~/.claude/settings.json, project: .claude/settings.json) configures tool permissions, hooks, env vars, model selection, and MCP servers
Headless, Streaming, and Auto-Mode
Session management persists conversations as resumable sessions; /clear resets context to stay focused