Claude Code hooks: which event to use when

A hook is a handler that Claude Code runs when an event fires. The handler can be a shell command, an HTTP endpoint, an MCP tool, a prompt to a Claude model, or a subagent.

Claude Code passes the event as JSON. A command reads it on stdin. An HTTP hook gets it as the body of a POST request.

You define hooks in a settings file, in three levels: the event, a matcher group that filters it, and the handlers to run. This example from the reference runs a lint script whenever Claude writes or edits a file:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/lint-check.sh"
          }
        ]
      }
    ]
  }
}

The reference names three rhythms:

• Once per session: SessionStart and SessionEnd.
• Once per turn: UserPromptSubmit, Stop and StopFailure.
• On every tool call: PreToolUse and PostToolUse.

The rhythm tells you the cost. A slow hook on every tool call slows down every step Claude takes. A slow SessionStart hook costs you once.

The reference lists more events for special cases. Here they are by topic, each with the moment it fires.

The exit code decides what happens next:

• 0: success. Claude Code reads the JSON you printed. On SessionStart, UserPromptSubmit, UserPromptExpansion and PostModelSwitch, plain text on stdout becomes context for Claude. On most other events it goes to the debug log.
• 2: a blocking error. On events that can block, Claude Code stops the action and uses your stderr as the reason.
• Any other code: a non-blocking error. The action goes ahead and you see a notice. This includes exit code 1, so a policy hook must exit with 2.

To add context, print one JSON object with hookSpecificOutput.additionalContext and nothing else on stdout. Where Claude reads it depends on the event:

SessionStart, SubagentStart

At the start of the conversation, before the first prompt.

UserPromptSubmit, UserPromptExpansion

Alongside the submitted prompt.

PreToolUse, PostToolUse, PostToolUseFailure, PostToolBatch

Next to the tool result.

Stop, SubagentStop

At the end of the turn. The conversation continues so Claude can act on it.

PostModelSwitch

With the next request after the switch.

Claude Code wraps the text in a system reminder. Above 10,000 characters it saves the text to a file and passes Claude the path and a preview. Write facts, such as "This repo uses bun test". Text that reads like a system command can trigger Claude's prompt-injection defenses.

Command, HTTP and MCP tool handlers get 600 seconds by default. UserPromptSubmit, PreModelSwitch and PostModelSwitch get 30, MessageDisplay gets 10. Set timeout on the handler to change it.

The file you put a hook in decides who runs it:

~/.claude/settings.json

All your projects, on your machine only.

.claude/settings.json

One project. You can commit it, so your team runs it too.

.claude/settings.local.json

One project, for you alone.

Managed policy settings

The whole organization, set by an admin.

Plugin hooks/hooks.json

While the plugin is enabled.

Skill frontmatter

For the rest of the session, once the skill is invoked.

Subagent frontmatter

While that subagent runs.

Hooks from all levels add up. All hooks that match an event run in parallel. The same handler in two settings files runs once.

Command hooks run with your full user permissions. Read every hook before you add it, including the ones a repository brings along.

In an interactive session, Claude Code holds back hooks from settings files until you accept the workspace trust dialog for the folder. A -p or SDK session treats the folder as trusted. There, hooks committed in a repository's .claude/settings.json run right away. Before you script claude -p over a repository you did not write, check its .claude/ folder, or turn hooks off for that run:

claude -p "..." \
  --settings '{"disableAllHooks": true}'

To watch your hooks run, start Claude Code with claude --debug and read ~/.claude/debug/<session-id>.txt.

Each session starts without what the last one figured out. Three events let you carry that experience forward:

1. SessionStart briefs the new session: what changed, what to watch out for.
2. UserPromptSubmit adds the notes that match this prompt, right before Claude reads it.
3. Stop reads last_assistant_message and can record a fix while it is fresh.

The notes only help when they are written well. How to write a lesson your coding agent can use shows the format with real examples.

cachly ships all three hooks. It turns your fixes, decisions and git history into lessons, and adds the matching ones to each prompt. Its servers are in the EU. What leaves your machine, and where it goes.

/plugin marketplace add cachly-dev/cachly-mcp
/plugin install cachly-brain@cachly

• Claude Code docs: Hooks reference (events, matchers, exit codes, context, timeouts, locations, trust)
• Claude Code docs: Automate actions with hooks

Checked against the hooks reference on 11 October 2026.