Reference · hook events

Every event, and whether it has a veto

You need one event, not the whole hooks lesson. 33 events, each with its own page: when it fires, what lands on stdin, what each exit code does on that event, and which JSON fields it honours. Module 09 teaches the mechanism; this is the directory.

Exit 2 blocks The exit code alone carries a veto.

  1. 04 UserPromptSubmit UserPromptSubmit can reject a submitted prompt or attach context before Claude processes it.
  2. 05 UserPromptExpansion UserPromptExpansion intercepts a typed command or MCP prompt before its expanded prompt reaches Claude.
  3. 07 PreToolUse PreToolUse can inspect, rewrite, approve, escalate, defer, or deny a tool call before it runs.
  4. 11 PostToolBatch PostToolBatch sees a complete parallel tool batch once, before the next model request.
  5. 12 Stop Stop checks the main agent's completed response and can keep the conversation going with feedback.
  6. 15 SubagentStop SubagentStop checks a finished subagent response and can keep that subagent working with feedback.
  7. 16 TeammateIdle TeammateIdle can return feedback to a finished teammate or stop that teammate entirely before it goes idle.
  8. 17 TaskCreated TaskCreated validates a pending TaskCreate operation and can roll the new task back.
  9. 18 TaskCompleted TaskCompleted enforces a completion gate and treats teammate-turn and TaskUpdate triggers differently.
  10. 21 PreCompact PreCompact can stop manual or automatic context compaction before it changes the conversation context.
  11. 23 ConfigChange ConfigChange audits a changed settings, policy, or skill file and can reject the live update unless it comes from managed policy.
  12. 24 Elicitation Elicitation intercepts an MCP server's input request and can answer it programmatically or deny it before a dialog appears.
  13. 25 ElicitationResult ElicitationResult inspects or replaces a user's MCP elicitation response before the server receives it.
  14. 32 PreModelSwitch PreModelSwitch is the v2.1.251 gate that can approve, reject, or confirm a requested change of session model. v2.1.251

Any non-zero exit blocks The one exception to the exit-2 rule.

  1. 26 WorktreeCreate WorktreeCreate builds an isolated working copy and returns the directory Claude Code should enter.

The exit code cannot block Whatever you return. Some decide through JSON instead; most only observe.

  1. 01 SessionStart A session-start hook loads dynamic context or setup when a session begins, resumes, clears, compacts, or forks.
  2. 02 Setup Setup runs one-time initialisation or maintenance only when an init or maintenance flag asks for it.
  3. 03 InstructionsLoaded InstructionsLoaded observes each instruction file added to context, including startup, nested, conditional, included, and post-compaction loads.
  4. 06 MessageDisplay MessageDisplay rewrites assistant text on screen while leaving Claude's context and the transcript unchanged.
  5. 08 PermissionRequest PermissionRequest answers a pending tool-permission prompt through JSON; exit code 2 alone has no effect.
  6. 09 PostToolUse PostToolUse can annotate or replace a successful tool result after the tool's real effects have already occurred.
  7. 10 PostToolUseFailure PostToolUseFailure reports a tool execution error and can add corrective context after the failure has happened.
  8. 13 StopFailure StopFailure reports an API error that ended the turn and cannot change that outcome.
  9. 14 SubagentStart SubagentStart adds context when an Agent tool spawns a subagent but cannot prevent creation.
  10. 19 Notification Notification forwards Claude Code alerts to hook side effects without changing or blocking the original notification.
  11. 20 PermissionDenied PermissionDenied observes an auto-mode denial and may tell the model to retry without reversing that denial.
  12. 22 PostCompact PostCompact observes the generated summary after manual or automatic compaction has finished.
  13. 27 WorktreeRemove WorktreeRemove performs cleanup for a hook-created isolated checkout without gaining a veto over removal.
  14. 28 CwdChanged CwdChanged reacts to a completed directory change and can update the session environment or watched paths.
  15. 29 DirectoryAdded DirectoryAdded starts background setup after a new working directory and its permissions are active in the session.
  16. 30 FileChanged FileChanged observes watched filesystem state after a file is created, modified, or deleted by any process.
  17. 31 SessionEnd SessionEnd gives cleanup hooks a bounded final window while the session terminates.
  18. 33 PostModelSwitch PostModelSwitch is the v2.1.251 observer that adds context after the session's model has changed. v2.1.251