What it is

A lifecycle hook is user code that Claude Code runs at fixed points in its own lifecycle — the source describes hooks as "user-defined shell commands that can be executed at various points in Claude Code's lifecycle" (claude-code/src/utils/hooks.ts:1-4). They are not part of the model's reasoning; they are out-of-band commands the user registers ahead of time (conventionally in .claude/settings.json) that the harness invokes when it reaches a named moment. Those moments span the whole arc of a session: SessionStart as the session opens (claude-code/src/utils/sessionStart.ts:35-175), UserPromptSubmit as the user's text enters the loop (claude-code/src/utils/processUserInput/processUserInput.ts:182-187), PreToolUse just before a tool runs and PostToolUse just after it returns (claude-code/src/services/tools/toolHooks.ts:435-650, claude-code/src/services/tools/toolHooks.ts:39-191), Stop at the end of a turn (claude-code/src/query/stopHooks.ts:65-189), and SessionEnd as the session closes (claude-code/src/utils/hooks.ts:175-182). Whatever the event, each hook receives a common envelope built by createBaseHookInput — session_id, transcript_path, cwd, permission_mode, agent_id, agent_type (claude-code/src/utils/hooks.ts:301-328) — with event-specific fields layered on top.

How it works

When a lifecycle event fires, getMatchingHooks filters the registered hooks by event type and matcher pattern, deduplicating by command/prompt/url/if-condition and validating if-conditions for tool-specific events (claude-code/src/utils/hooks.ts:1603-1874). The surviving set is handed to executeHooks, an async generator that spawns every matched hook in parallel and yields progress messages plus aggregated results as they arrive (claude-code/src/utils/hooks.ts:1952-1977). A command hook is run by execCommandHook, which spawns bash or PowerShell depending on the hook's shell config and rewrites Windows paths to POSIX form for bash (claude-code/src/utils/hooks.ts:747-1335). The harness hands the hook its input as JSON on stdin — jsonStringify(hookInput) with a trailing newline (claude-code/src/utils/hooks.ts:1006, claude-code/src/utils/hooks.ts:1210) — and reads the hook's verdict from stdout, validated against hookJSONOutputSchema (claude-code/src/utils/hooks.ts:382-397), with exit codes carrying their own signal: 2 means a blocking error, 0 is success, 1-3 are non-blocking (claude-code/src/utils/hooks.ts:2647-2668). The parsed output flows through ProcessHookJSONOutput, which extracts the permission decision (allow/deny/ask), any updatedInput, a blockingError, additionalContext, and event-specific outputs (claude-code/src/utils/hooks.ts:489-737). A hook can opt out of blocking entirely: if its first stdout line is {"async":true,...} or its config sets async, the process is backgrounded via executeInBackground and the turn continues without waiting (claude-code/src/utils/hooks.ts:995-1030, claude-code/src/utils/hooks.ts:1112-1164). The caller drains the generator with a for-await-of loop that aggregates every hook's contribution — blockingError, message, preventContinuation, updatedInput, permissionBehavior (claude-code/src/utils/hooks.ts:2743-2929).

Why it matters

This is the one place where user code gets to intercept and rewrite the loop's decisions. Because all matching hooks for one event run in parallel, their verdicts must be reconciled — and the reconciliation is not "last wins" but a fixed precedence, deny > ask > allow: no hook can override a deny, and an ask overrides an allow (claude-code/src/utils/hooks.ts:2820-2847). That ordering is what turns a single denying hook into a hard gate rather than one vote among many. The interception is also generative, not just a veto: a PreToolUse hook can hand back hook-modified input that replaces what the model proposed before the tool ever runs (claude-code/src/services/tools/toolHooks.ts:435-650), and a PostToolUse hook can rewrite an MCP tool's output after the fact (claude-code/src/services/tools/toolHooks.ts:39-191). Because hooks are arbitrary code, the harness refuses to run them until the workspace is trusted: shouldSkipHookDueToTrust gates every hook in interactive mode, closing the window where an untrusted repo's settings could execute before the trust dialog is even answered (claude-code/src/utils/hooks.ts:286-296, claude-code/src/utils/hooks.ts:1993-1999, claude-code/src/utils/hooks.ts:3031-3036). The lifecycle framing forces other tradeoffs too: SessionEnd hooks get an aggressive 1500ms timeout (overridable via CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS) so a slow hook can't hold shutdown hostage (claude-code/src/utils/hooks.ts:175-182), and HTTP hooks are forbidden for SessionStart/Setup because the network round-trip would deadlock the sandbox in --print mode (claude-code/src/utils/hooks.ts:1850-1864). Plugin-supplied hooks are folded in before SessionStart/Setup via a memoized loadPluginHooks call, and a plugin that fails to load is logged and skipped rather than crashing the session (claude-code/src/utils/sessionStart.ts:56-127).

Read the source

• The definition and the lifecycle envelope: claude-code/src/utils/hooks.ts:1-4; createBaseHookInput claude-code/src/utils/hooks.ts:301-328.
• Dispatch: getMatchingHooks claude-code/src/utils/hooks.ts:1603-1874; the executeHooks generator claude-code/src/utils/hooks.ts:1952-1977; the aggregation loop claude-code/src/utils/hooks.ts:2743-2929.
• Execution and I/O: execCommandHook claude-code/src/utils/hooks.ts:747-1335; stdin JSON claude-code/src/utils/hooks.ts:1006, claude-code/src/utils/hooks.ts:1210; output schema claude-code/src/utils/hooks.ts:382-397; exit-code handling claude-code/src/utils/hooks.ts:2647-2668; ProcessHookJSONOutput claude-code/src/utils/hooks.ts:489-737; async backgrounding claude-code/src/utils/hooks.ts:995-1030, claude-code/src/utils/hooks.ts:1112-1164.
• Interception semantics: permission precedence (deny > ask > allow) claude-code/src/utils/hooks.ts:2820-2847; PreToolUse input rewrite claude-code/src/services/tools/toolHooks.ts:435-650; PostToolUse output rewrite claude-code/src/services/tools/toolHooks.ts:39-191.
• Guards and per-event quirks: trust gate claude-code/src/utils/hooks.ts:286-296, claude-code/src/utils/hooks.ts:1993-1999, claude-code/src/utils/hooks.ts:3031-3036; SessionEnd timeout claude-code/src/utils/hooks.ts:175-182; HTTP forbidden for SessionStart/Setup claude-code/src/utils/hooks.ts:1850-1864; plugin loading claude-code/src/utils/sessionStart.ts:56-127; SessionStart firing claude-code/src/utils/sessionStart.ts:35-175; UserPromptSubmit claude-code/src/utils/processUserInput/processUserInput.ts:182-187; Stop hooks claude-code/src/query/stopHooks.ts:65-189.