Claude Code Hooks & Lifecycle Events

Unlike prompt instructions Claude might forget, a PreToolUse hook is technically guaranteed to execute before every matched tool call. Hooks are deterministic enforcement, not model-dependent suggestions.

Code 2 blocks the action and sends your stderr as context to Claude. Code 1 is a hook execution failure — different from a deliberate block. Most developers conflate 1 and 2.

An async hook fires and Claude immediately continues. The hook's output arrives as context one turn later. Design async hooks so their output is still actionable one turn later.

Beyond shell commands, hooks support type: "prompt" which runs a lightweight Claude evaluation. Perfect for nuanced Stop hooks: evaluate whether this task is genuinely complete. Not in the /hooks UI — JSON only.

The matcher is a regex on the tool name. "Edit|Write" uses alternation. It is case-sensitive. Spaces around | break it silently. Wrong casing causes hooks to silently never fire.

Matchers only filter by tool name, never by file path. To block writes to .env, parse tool_input.file_path from stdin JSON inside your hook command and exit 2 if it matches.

To hook a specific MCP tool, use the full prefix format. Add a no-matcher PostToolUse hook that logs .tool_name to discover all tool names during a real session before building matchers.

A hook on UserPromptSubmit fires before the model sees your prompt. Return additionalContext JSON to automatically inject live context — Jira status, git diff, sprint priorities — on every single message.

You can match only compact to run context-recovery logic specifically during compaction — not on every session start. Most hook guides only show generic SessionStart.

Claude posts the event JSON to your endpoint and reads the block/allow decision from the HTTP response. Build one central policy server to enforce the same rules across every developer's Claude Code session.

If an admin configures hooks via managed policy settings, a user's disableAllHooks: true cannot override them. Only a disableAllHooks at the managed policy level can disable managed hooks.

When an async hook completes, its notification is hidden unless you launched with --verbose or toggled via Ctrl+O. If an async hook appears to do nothing, enable verbose mode first.

The PreCompact event fires before the compaction algorithm runs. A hook here writes a structured backup of current state and open decisions — a precise recovery artifact beyond the fuzzy prose summary.

A skill's YAML frontmatter can declare hooks: that only fire when that skill is active. A database-migration skill can have its own PreToolUse hook validating read-only queries — zero global pollution.

A hook that spawns subagents risks infinite recursion if those subagents also trigger UserPromptSubmit. Fix: check the hook input JSON for a subagent indicator. Always scope to top-level agent sessions only.

The interactive /hooks menu only supports type: "command". The more powerful type: "prompt" and type: "http" variants must be added by editing settings JSON directly.

Unless you set timeout in hook config, hooks can run for 10 minutes. A slow external API call in a sync PreToolUse hook stalls every matched tool operation for up to 10 minutes.

A recent optimization deferred SessionStart hook execution, reducing time-to-interactive by ~500ms. If your workflow assumed the hook completes before Claude can respond, that assumption is now incorrect.