Claude Code Guide: Hook Lifecycle Automation and Boundaries

InYourLeague Research · 2026-08-29

Answer in brief

Claude Code hooks automate lifecycle actions by pairing an event with a matcher and a command, HTTP, MCP tool, prompt, or agent handler. Permission decisions remain explicit lifecycle boundaries, while /hooks, direct handler tests, failure events, exit-code handling, and timeout documentation provide the core debugging path.

Key facts at a glance

Failure modes and verification

FAQ

Does Claude Code publish a selectable model ID for hooks?

No. The official source does not publish a selectable model ID for this product. Prompt-based and agent-based hooks may use a Claude model, but the supplied official documentation specifies no selectable model ID.

Where are Claude Code hooks configured?

Hooks are added under the single hooks object in a Claude Code settings file, such as ~/.claude/settings.json. The /hooks menu displays configuration details but is read-only. See the automation guide.

How do matchers limit hook execution?

A matcher filters occurrences of an event before handlers run. Official examples match tool names such as Edit|Write or Bash, and an if field can further filter tool arguments.

Can a hook control tool permissions?

PreToolUse can block a tool before execution, PermissionRequest handles a required permission decision, and PermissionDenied reports an auto-mode denial. The supplied source supports no general claim that hooks bypass permission boundaries.

How should hook failures be investigated?

Confirm the event and matcher in /hooks, test external commands directly, and distinguish PostToolUseFailure from StopFailure. Then consult the Hooks reference for event-specific JSON, exit-code, timeout, HTTP-response, and async-hook behavior.

Sources and freshness

• Official source
• Official source
• Last verified: 2026-08-29

Extended guide

Direct answer

Claude Code hooks provide deterministic lifecycle automation: when a configured event fires and its matcher succeeds, Claude Code sends JSON context to the selected handler. Use hooks for repeatable rules such as formatting edited files, validating commands, sending notifications, injecting context, and blocking protected operations. Use prompt-based or agent-based hooks only when a decision requires model judgment. This entry was verified against the official documentation on 2026-08-29.

The official source does not publish a selectable model ID for this product. Prompt and agent handlers may use a Claude model, but the supplied official material names no model ID that users can select.

Lifecycle and execution boundaries

EndConversation calls skip PreToolUse and PostToolUse. Other documented events cover notifications, subagents, tasks, configuration changes, working-directory changes, compaction, worktrees, file watching, MCP elicitation, and session termination. Consult the Hooks reference for each event’s complete input schema and available decision controls.

Configuration procedure

1. Choose the event. Add one event key inside the single hooks object in a Claude Code settings file. For example, Notification runs when Claude Code issues a notification, while PreToolUse is the control point before a tool executes.

2. Apply the matcher. A matcher limits which occurrences reach handlers. The official examples use Edit|Write to select those tool names. A PreToolUse example first matches Bash, then uses the if field to narrow matching arguments to commands shaped like rm *. For FileChanged, the matcher identifies filenames to watch.

3. Select a handler. Claude Code supports user-defined shell commands, HTTP endpoints, MCP tool calls, LLM prompts, and subagents. Command handlers receive event JSON on stdin; HTTP handlers receive the same context as a POST request body. A handler may inspect that input, perform an action, and optionally return a decision when the event supports decision control.

4. Respect permission boundaries. Use PreToolUse when an operation must be blocked before execution. Use PermissionRequest for calls awaiting a permission decision and PermissionDenied to observe auto-mode denial. The supplied source does not establish any broader permission bypass, so no such bypass should be assumed.

5. Verify and debug. Open /hooks to confirm the event, matcher, type, source file, and handler command. The menu is read-only; edit settings JSON to change configuration. If a hook does not fire, confirm that the event occurs and both matcher layers succeed. Test an operating-system command directly when notifications fail, because desktop permissions, missing notification daemons, headless sessions, or unavailable commands can prevent visible output.

Failure-handling checklist

• Handle successful tool calls with PostToolUse and failed calls with PostToolUseFailure.
• Distinguish normal Stop from API-error StopFailure.
• Inspect hook error output instead of treating silence as success.
• Check the official event-specific rules for structured JSON, exit-code output, other exit codes, and timeouts.
• Use the automation guide for setup examples and the reference for schemas, async hooks, and advanced handler behavior.

Model availability note: The official source does not specify a selectable model ID.