D3 · Claude Code › Cluster 6 · Hooks

6.1 · Hook Events Overview

The lifecycle events you can hook

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:

EventFires whenCan it block?
SessionStartA session begins or resumes (matchers: startup, resume, clear, compact)No — injects context
UserPromptSubmitYou submit a prompt, before Claude processes itYes — can erase the prompt
PreToolUseBefore a tool call executesYes — can deny the tool
PostToolUseAfter a tool call succeedsFeedback only — tool already ran
NotificationClaude Code sends a notification (needs input / permission)No
StopClaude finishes responding (the main agent)Yes — can force it to keep going
SubagentStopA subagent (Task) finishes respondingYes — can force it to keep going
PreCompactBefore context compaction (matchers: manual, auto)Yes
SessionEndA session terminatesNo
🔑 Two mental buckets: pre-events (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.

⚠️ Don't confuse 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

flowchart TD S["SessionStart
(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

Trap: "A PostToolUse hook can cancel the edit." → No. The tool already executed; PostToolUse can only feed back or reformat. To prevent a tool, use PreToolUse.
Trap: "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.
Trap: Mixing up Stop and SubagentStop. → Stop is the main agent; SubagentStop is a Task subagent. Distinct events, distinct hooks.
Trap: Thinking the nine events are the whole list. → Current versions add many more (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.