claude_hooks 1.1.0 → 1.2.0

data/docs/external/claude-hooks-reference.md

@@ -1,121 +1,76 @@
-[Skip to main content](https://code.claude.com/docs/en/hooks#content-area)
+> ## Documentation Index
+>
+> Fetch the complete documentation index at: [/docs/llms.txt](https://code.claude.com/docs/llms.txt)
+>
+> Use this file to discover all available pages before exploring further.
 
-[Claude Code Docs home page![light logo](https://mintcdn.com/claude-code/o69F7a6qoW9vboof/logo/light.svg?fit=max&auto=format&n=o69F7a6qoW9vboof&q=85&s=536eade682636e84231afce2577f9509)![dark logo](https://mintcdn.com/claude-code/o69F7a6qoW9vboof/logo/dark.svg?fit=max&auto=format&n=o69F7a6qoW9vboof&q=85&s=0766b3221061e80143e9f300733e640b)](https://code.claude.com/docs)
-
-![US](https://d3gk2c5xim1je2.cloudfront.net/flags/US.svg)
-
-English
-
-Search...
-
-Ctrl K
-
-Search...
-
-Navigation
-
-Reference
-
-Hooks reference
-
-[Getting started](https://code.claude.com/docs/en/overview) [Build with Claude Code](https://code.claude.com/docs/en/sub-agents) [Deployment](https://code.claude.com/docs/en/third-party-integrations) [Administration](https://code.claude.com/docs/en/setup) [Configuration](https://code.claude.com/docs/en/settings) [Reference](https://code.claude.com/docs/en/cli-reference) [Resources](https://code.claude.com/docs/en/legal-and-compliance)
-
-On this page
-
-- [Configuration](https://code.claude.com/docs/en/hooks#configuration)
-- [Structure](https://code.claude.com/docs/en/hooks#structure)
-- [Project-Specific Hook Scripts](https://code.claude.com/docs/en/hooks#project-specific-hook-scripts)
-- [Plugin hooks](https://code.claude.com/docs/en/hooks#plugin-hooks)
-- [Prompt-Based Hooks](https://code.claude.com/docs/en/hooks#prompt-based-hooks)
-- [How prompt-based hooks work](https://code.claude.com/docs/en/hooks#how-prompt-based-hooks-work)
-- [Configuration](https://code.claude.com/docs/en/hooks#configuration-2)
-- [Response schema](https://code.claude.com/docs/en/hooks#response-schema)
-- [Supported hook events](https://code.claude.com/docs/en/hooks#supported-hook-events)
-- [Example: Intelligent Stop hook](https://code.claude.com/docs/en/hooks#example%3A-intelligent-stop-hook)
-- [Example: SubagentStop with custom logic](https://code.claude.com/docs/en/hooks#example%3A-subagentstop-with-custom-logic)
-- [Comparison with bash command hooks](https://code.claude.com/docs/en/hooks#comparison-with-bash-command-hooks)
-- [Best practices](https://code.claude.com/docs/en/hooks#best-practices)
-- [Hook Events](https://code.claude.com/docs/en/hooks#hook-events)
-- [PreToolUse](https://code.claude.com/docs/en/hooks#pretooluse)
-- [PermissionRequest](https://code.claude.com/docs/en/hooks#permissionrequest)
-- [PostToolUse](https://code.claude.com/docs/en/hooks#posttooluse)
-- [Notification](https://code.claude.com/docs/en/hooks#notification)
-- [UserPromptSubmit](https://code.claude.com/docs/en/hooks#userpromptsubmit)
-- [Stop](https://code.claude.com/docs/en/hooks#stop)
-- [SubagentStop](https://code.claude.com/docs/en/hooks#subagentstop)
-- [PreCompact](https://code.claude.com/docs/en/hooks#precompact)
-- [SessionStart](https://code.claude.com/docs/en/hooks#sessionstart)
-- [Persisting environment variables](https://code.claude.com/docs/en/hooks#persisting-environment-variables)
-- [SessionEnd](https://code.claude.com/docs/en/hooks#sessionend)
-- [Hook Input](https://code.claude.com/docs/en/hooks#hook-input)
-- [PreToolUse Input](https://code.claude.com/docs/en/hooks#pretooluse-input)
-- [PostToolUse Input](https://code.claude.com/docs/en/hooks#posttooluse-input)
-- [Notification Input](https://code.claude.com/docs/en/hooks#notification-input)
-- [UserPromptSubmit Input](https://code.claude.com/docs/en/hooks#userpromptsubmit-input)
-- [Stop and SubagentStop Input](https://code.claude.com/docs/en/hooks#stop-and-subagentstop-input)
-- [PreCompact Input](https://code.claude.com/docs/en/hooks#precompact-input)
-- [SessionStart Input](https://code.claude.com/docs/en/hooks#sessionstart-input)
-- [SessionEnd Input](https://code.claude.com/docs/en/hooks#sessionend-input)
-- [Hook Output](https://code.claude.com/docs/en/hooks#hook-output)
-- [Simple: Exit Code](https://code.claude.com/docs/en/hooks#simple%3A-exit-code)
-- [Exit Code 2 Behavior](https://code.claude.com/docs/en/hooks#exit-code-2-behavior)
-- [Advanced: JSON Output](https://code.claude.com/docs/en/hooks#advanced%3A-json-output)
-- [Common JSON Fields](https://code.claude.com/docs/en/hooks#common-json-fields)
-- [PreToolUse Decision Control](https://code.claude.com/docs/en/hooks#pretooluse-decision-control)
-- [PermissionRequest Decision Control](https://code.claude.com/docs/en/hooks#permissionrequest-decision-control)
-- [PostToolUse Decision Control](https://code.claude.com/docs/en/hooks#posttooluse-decision-control)
-- [UserPromptSubmit Decision Control](https://code.claude.com/docs/en/hooks#userpromptsubmit-decision-control)
-- [Stop/SubagentStop Decision Control](https://code.claude.com/docs/en/hooks#stop%2Fsubagentstop-decision-control)
-- [SessionStart Decision Control](https://code.claude.com/docs/en/hooks#sessionstart-decision-control)
-- [SessionEnd Decision Control](https://code.claude.com/docs/en/hooks#sessionend-decision-control)
-- [Exit Code Example: Bash Command Validation](https://code.claude.com/docs/en/hooks#exit-code-example%3A-bash-command-validation)
-- [JSON Output Example: UserPromptSubmit to Add Context and Validation](https://code.claude.com/docs/en/hooks#json-output-example%3A-userpromptsubmit-to-add-context-and-validation)
-- [JSON Output Example: PreToolUse with Approval](https://code.claude.com/docs/en/hooks#json-output-example%3A-pretooluse-with-approval)
-- [Working with MCP Tools](https://code.claude.com/docs/en/hooks#working-with-mcp-tools)
-- [MCP Tool Naming](https://code.claude.com/docs/en/hooks#mcp-tool-naming)
-- [Configuring Hooks for MCP Tools](https://code.claude.com/docs/en/hooks#configuring-hooks-for-mcp-tools)
-- [Examples](https://code.claude.com/docs/en/hooks#examples)
-- [Security Considerations](https://code.claude.com/docs/en/hooks#security-considerations)
-- [Disclaimer](https://code.claude.com/docs/en/hooks#disclaimer)
-- [Security Best Practices](https://code.claude.com/docs/en/hooks#security-best-practices)
-- [Configuration Safety](https://code.claude.com/docs/en/hooks#configuration-safety)
-- [Hook Execution Details](https://code.claude.com/docs/en/hooks#hook-execution-details)
-- [Debugging](https://code.claude.com/docs/en/hooks#debugging)
-- [Basic Troubleshooting](https://code.claude.com/docs/en/hooks#basic-troubleshooting)
-- [Advanced Debugging](https://code.claude.com/docs/en/hooks#advanced-debugging)
-- [Debug Output Example](https://code.claude.com/docs/en/hooks#debug-output-example)
-
-For a quickstart guide with examples, see [Get started with Claude Code hooks](https://code.claude.com/docs/en/hooks-guide).
+[Skip to main content](https://code.claude.com/docs/en/hooks#content-area)
 
-## [​](https://code.claude.com/docs/en/hooks\#configuration)  Configuration
+For a quickstart guide with examples, see [Automate actions with hooks](https://code.claude.com/docs/en/hooks-guide).
 
-Claude Code hooks are configured in your [settings files](https://code.claude.com/docs/en/settings):
+Hooks are user-defined shell commands, HTTP endpoints, or LLM prompts that execute automatically at specific points in Claude Code’s lifecycle. Use this reference to look up event schemas, configuration options, JSON input/output formats, and advanced features like async hooks, HTTP hooks, and MCP tool hooks. If you’re setting up hooks for the first time, start with the [guide](https://code.claude.com/docs/en/hooks-guide) instead.
 
-- `~/.claude/settings.json` \- User settings
-- `.claude/settings.json` \- Project settings
-- `.claude/settings.local.json` \- Local project settings (not committed)
-- Enterprise managed policy settings
+## [​](https://code.claude.com/docs/en/hooks\#hook-lifecycle)  Hook lifecycle
 
-Enterprise administrators can use `allowManagedHooksOnly` to block user, project, and plugin hooks. See [Hook configuration](https://code.claude.com/docs/en/settings#hook-configuration).
+Hooks fire at specific points during a Claude Code session. When an event fires and a matcher matches, Claude Code passes JSON context about the event to your hook handler. For command hooks, input arrives on stdin. For HTTP hooks, it arrives as the POST request body. Your handler can then inspect the input, take action, and optionally return a decision.Events fall into three cadences:
 
-### [​](https://code.claude.com/docs/en/hooks\#structure)  Structure
+- once per session: `SessionStart` and `SessionEnd`
+- once per turn: `UserPromptSubmit`, `Stop`, and `StopFailure`
+- on every tool call inside the agentic loop: `PreToolUse` and `PostToolUse`
 
-Hooks are organized by matchers, where each matcher can have multiple hooks:
+![Hook lifecycle diagram showing optional Setup feeding into SessionStart, then a per-turn loop containing UserPromptSubmit, UserPromptExpansion for slash commands, the nested agentic loop (PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure, PostToolBatch, SubagentStart/Stop, TaskCreated, TaskCompleted), and Stop or StopFailure, followed by TeammateIdle, PreCompact, PostCompact, and SessionEnd, with Elicitation and ElicitationResult nested inside MCP tool execution, PermissionDenied as a side branch from PermissionRequest for auto-mode denials, WorktreeCreate, WorktreeRemove, Notification, ConfigChange, InstructionsLoaded, CwdChanged, and FileChanged as standalone async events, and MessageDisplay as a display-only event that runs while assistant message text streams](https://mintcdn.com/claude-code/uLsR38F1U_5zPppm/images/hooks-lifecycle.svg?fit=max&auto=format&n=uLsR38F1U_5zPppm&q=85&s=fbdbd78ad9f474da7d344879341341f0)
 
-Copy
+The table below summarizes when each event fires. The [Hook events](https://code.claude.com/docs/en/hooks#hook-events) section documents the full input schema and decision control options for each one.
 
-Ask AI
+| Event | When it fires |
+| --- | --- |
+| `SessionStart` | When a session begins or resumes |
+| `Setup` | When you start Claude Code with `--init-only`, or with `--init` or `--maintenance` in `-p` mode. For one-time preparation in CI or scripts |
+| `UserPromptSubmit` | When you submit a prompt, before Claude processes it |
+| `UserPromptExpansion` | When a user-typed command expands into a prompt, before it reaches Claude. Can block the expansion |
+| `PreToolUse` | Before a tool call executes. Can block it |
+| `PermissionRequest` | When a permission dialog appears |
+| `PermissionDenied` | When a tool call is denied by the auto mode classifier. Return `{retry: true}` to tell the model it may retry the denied tool call |
+| `PostToolUse` | After a tool call succeeds |
+| `PostToolUseFailure` | After a tool call fails |
+| `PostToolBatch` | After a full batch of parallel tool calls resolves, before the next model call |
+| `Notification` | When Claude Code sends a notification |
+| `MessageDisplay` | While assistant message text is displayed |
+| `SubagentStart` | When a subagent is spawned |
+| `SubagentStop` | When a subagent finishes |
+| `TaskCreated` | When a task is being created via `TaskCreate` |
+| `TaskCompleted` | When a task is being marked as completed |
+| `Stop` | When Claude finishes responding |
+| `StopFailure` | When the turn ends due to an API error. Output and exit code are ignored |
+| `TeammateIdle` | When an [agent team](https://code.claude.com/docs/en/agent-teams) teammate is about to go idle |
+| `InstructionsLoaded` | When a CLAUDE.md or `.claude/rules/*.md` file is loaded into context. Fires at session start and when files are lazily loaded during a session |
+| `ConfigChange` | When a configuration file changes during a session |
+| `CwdChanged` | When the working directory changes, for example when Claude executes a `cd` command. Useful for reactive environment management with tools like direnv |
+| `FileChanged` | When a watched file changes on disk. The `matcher` field specifies which filenames to watch |
+| `WorktreeCreate` | When a worktree is being created via `--worktree` or `isolation: "worktree"`. Replaces default git behavior |
+| `WorktreeRemove` | When a worktree is being removed, either at session exit or when a subagent finishes |
+| `PreCompact` | Before context compaction |
+| `PostCompact` | After context compaction completes |
+| `Elicitation` | When an MCP server requests user input during a tool call |
+| `ElicitationResult` | After a user responds to an MCP elicitation, before the response is sent back to the server |
+| `SessionEnd` | When a session terminates |
+
+### [​](https://code.claude.com/docs/en/hooks\#how-a-hook-resolves)  How a hook resolves
+
+To see how these pieces fit together, consider this `PreToolUse` hook that blocks destructive shell commands. The `matcher` narrows to Bash tool calls and the `if` condition narrows further to Bash subcommands matching `rm *`, so `block-rm.sh` only spawns when both filters match:
 
 ```
 {
   "hooks": {
-    "EventName": [\
+    "PreToolUse": [\
       {\
-        "matcher": "ToolPattern",\
+        "matcher": "Bash",\
         "hooks": [\
           {\
             "type": "command",\
-            "command": "your-command-here"\
+            "if": "Bash(rm *)",\
+            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh",\
+            "args": []\
           }\
         ]\
       }\
@@ -124,64 +79,159 @@ Ask AI
 }
 ```
 
-- **matcher**: Pattern to match tool names, case-sensitive (only applicable for
-`PreToolUse`, `PermissionRequest`, and `PostToolUse`)
+The script reads the JSON input from stdin, extracts the command, and returns a `permissionDecision` of `"deny"` if it contains `rm -rf`:
+
+```
+#!/bin/bash
+# .claude/hooks/block-rm.sh
+COMMAND=$(jq -r '.tool_input.command')
+
+if echo "$COMMAND" | grep -q 'rm -rf'; then
+  jq -n '{
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: "deny",
+      permissionDecisionReason: "Destructive command blocked by hook"
+    }
+  }'
+else
+  exit 0  # no decision; normal permission flow applies
+fi
+```
+
+Now suppose Claude Code decides to run `Bash "rm -rf /tmp/build"`. Here’s what happens:
+
+![Diagram of hook resolution: PreToolUse fires, the matcher checks for a Bash match, then the if condition checks for a Bash(rm *) match. If both match, the hook command runs and returns permissionDecision deny, so the tool call is blocked and Claude Code continues. If either check fails to match, the hook is skipped and the tool call is allowed to proceed.](https://mintcdn.com/claude-code/ikqp3_70mqIahteV/images/hook-resolution.svg?fit=max&auto=format&n=ikqp3_70mqIahteV&q=85&s=be0bf3053550c26de5f54cd64674c197)
+
+1
+
+[Navigate to header](https://code.claude.com/docs/en/hooks#)
+
+Event fires
+
+The `PreToolUse` event fires. Claude Code sends the tool input as JSON on stdin to the hook:
+
+```
+{ "tool_name": "Bash", "tool_input": { "command": "rm -rf /tmp/build" }, ... }
+```
+
+2
+
+[Navigate to header](https://code.claude.com/docs/en/hooks#)
+
+Matcher checks
+
+The matcher `"Bash"` matches the tool name, so this hook group activates. If you omit the matcher or use `"*"`, the group activates on every occurrence of the event.
 
-  - Simple strings match exactly: `Write` matches only the Write tool
-  - Supports regex: `Edit|Write` or `Notebook.*`
-  - Use `*` to match all tools. You can also use empty string (`""`) or leave
-    `matcher` blank.
-- **hooks**: Array of hooks to execute when the pattern matches
+3
 
-  - `type`: Hook execution type - `"command"` for bash commands or `"prompt"` for LLM-based evaluation
-  - `command`: (For `type: "command"`) The bash command to execute (can use `$CLAUDE_PROJECT_DIR` environment variable)
-  - `prompt`: (For `type: "prompt"`) The prompt to send to the LLM for evaluation
-  - `timeout`: (Optional) How long a hook should run, in seconds, before canceling that specific hook
+[Navigate to header](https://code.claude.com/docs/en/hooks#)
 
-For events like `UserPromptSubmit`, `Stop`, and `SubagentStop`
-that don’t use matchers, you can omit the matcher field:
+If condition checks
 
-Copy
+The `if` condition `"Bash(rm *)"` matches because `rm -rf /tmp/build` is a subcommand matching `rm *`, so this handler spawns. If the command had been `npm test`, the `if` check would fail and `block-rm.sh` would never run, avoiding the process spawn overhead. The `if` field is optional; without it, every handler in the matched group runs.
 
-Ask AI
+4
+
+[Navigate to header](https://code.claude.com/docs/en/hooks#)
+
+Hook handler runs
+
+The script inspects the full command and finds `rm -rf`, so it prints a decision to stdout:
 
 ```
 {
-  "hooks": {
-    "UserPromptSubmit": [\
-      {\
-        "hooks": [\
-          {\
-            "type": "command",\
-            "command": "/path/to/prompt-validator.py"\
-          }\
-        ]\
-      }\
-    ]
+  "hookSpecificOutput": {
+    "hookEventName": "PreToolUse",
+    "permissionDecision": "deny",
+    "permissionDecisionReason": "Destructive command blocked by hook"
   }
 }
 ```
 
-### [​](https://code.claude.com/docs/en/hooks\#project-specific-hook-scripts)  Project-Specific Hook Scripts
+If the command had been a safer `rm` variant like `rm file.txt`, the script would hit `exit 0` instead. Exit code 0 with no output means the hook has no decision to report, so the tool call continues through the normal [permission flow](https://code.claude.com/docs/en/permissions). The hook can deny the call, but staying silent doesn’t approve it.
+
+5
+
+[Navigate to header](https://code.claude.com/docs/en/hooks#)
+
+Claude Code acts on the result
+
+Claude Code reads the JSON decision, blocks the tool call, and shows Claude the reason.
+
+The [Configuration](https://code.claude.com/docs/en/hooks#configuration) section below documents the full schema, and each [hook event](https://code.claude.com/docs/en/hooks#hook-events) section documents what input your command receives and what output it can return.
+
+## [​](https://code.claude.com/docs/en/hooks\#configuration)  Configuration
+
+Hooks are defined in JSON settings files. The configuration has three levels of nesting:
+
+1. Choose a [hook event](https://code.claude.com/docs/en/hooks#hook-events) to respond to, like `PreToolUse` or `Stop`
+2. Add a [matcher group](https://code.claude.com/docs/en/hooks#matcher-patterns) to filter when it fires, like “only for the Bash tool”
+3. Define one or more [hook handlers](https://code.claude.com/docs/en/hooks#hook-handler-fields) to run when matched
+
+See [How a hook resolves](https://code.claude.com/docs/en/hooks#how-a-hook-resolves) above for a complete walkthrough with an annotated example.
 
-You can use the environment variable `CLAUDE_PROJECT_DIR` (only available when
-Claude Code spawns the hook command) to reference scripts stored in your project,
-ensuring they work regardless of Claude’s current directory:
+This page uses specific terms for each level: **hook event** for the lifecycle point, **matcher group** for the filter, and **hook handler** for the shell command, HTTP endpoint, MCP tool, prompt, or agent that runs. “Hook” on its own refers to the general feature.
 
-Copy
+### [​](https://code.claude.com/docs/en/hooks\#hook-locations)  Hook locations
 
-Ask AI
+Where you define a hook determines its scope:
+
+| Location | Scope | Shareable |
+| --- | --- | --- |
+| `~/.claude/settings.json` | All your projects | No, local to your machine |
+| `.claude/settings.json` | Single project | Yes, can be committed to the repo |
+| `.claude/settings.local.json` | Single project | No, gitignored when Claude Code creates it |
+| Managed policy settings | Organization-wide | Yes, admin-controlled |
+| [Plugin](https://code.claude.com/docs/en/plugins)`hooks/hooks.json` | When plugin is enabled | Yes, bundled with the plugin |
+| [Skill](https://code.claude.com/docs/en/skills) or [agent](https://code.claude.com/docs/en/sub-agents) frontmatter | While the component is active | Yes, defined in the component file |
+
+For details on settings file resolution, see [settings](https://code.claude.com/docs/en/settings).Enterprise administrators can use `allowManagedHooksOnly` to block user, project, and plugin hooks. Hooks from plugins force-enabled in managed settings `enabledPlugins` are exempt, so administrators can distribute vetted hooks through an organization marketplace. See [Hook configuration](https://code.claude.com/docs/en/settings#hook-configuration).
+
+### [​](https://code.claude.com/docs/en/hooks\#matcher-patterns)  Matcher patterns
+
+The `matcher` field filters when hooks fire. How a matcher is evaluated depends on the characters it contains:
+
+| Matcher value | Evaluated as | Example |
+| --- | --- | --- |
+| `"*"`, `""`, or omitted | Match all | fires on every occurrence of the event |
+| Only letters, digits, `_`, `-`, spaces, `,`, and `|` | Exact string, or list of exact strings separated by `|` or `,` with optional surrounding whitespace | `Bash` matches only the Bash tool; `Edit|Write` and `Edit, Write` each match either tool exactly; `code-reviewer` matches only that agent type |
+| Contains any other character | JavaScript regular expression, unanchored | `^Notebook` matches any tool whose name starts with `Notebook`; `mcp__memory__.*` matches every tool from the `memory` server |
+
+A matcher on the regular-expression path is tested with JavaScript’s `RegExp.prototype.test`, which succeeds on a match anywhere in the value. `Edit.*` matches both `Edit` and `NotebookEdit`; wrap the pattern in `^` and `$`, as in `^Edit$`, when you need a whole-string match.Comma separators and the surrounding whitespace tolerance require Claude Code v2.1.191 or later.Hyphens in the exact-match set require Claude Code v2.1.195 or later. On earlier versions a hyphenated name like `code-reviewer` is evaluated as an unanchored regular expression, so it also fires for `senior-code-reviewer`; anchor it as `^code-reviewer$` on those versions to match only that name.`FileChanged` and `StopFailure` use a narrower exact-match set of letters, digits, `_`, and `|` only. A hyphen, space, or comma in a matcher for those two events keeps it on the regular-expression path, and only `|` separates alternatives. Every other event with matcher support in the table that follows accepts `|` or `,`.The `FileChanged` event doesn’t follow these rules when building its watch list. See [FileChanged](https://code.claude.com/docs/en/hooks#filechanged).Each event type matches on a different field:
+
+| Event | What the matcher filters | Example matcher values |
+| --- | --- | --- |
+| `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`, `PermissionDenied` | tool name | `Bash`, `Edit|Write`, `mcp__.*` |
+| `SessionStart` | how the session started | `startup`, `resume`, `clear`, `compact` |
+| `Setup` | which CLI flag triggered setup | `init`, `maintenance` |
+| `SessionEnd` | why the session ended | `clear`, `resume`, `logout`, `prompt_input_exit`, `bypass_permissions_disabled`, `other` |
+| `Notification` | notification type | `permission_prompt`, `idle_prompt`, `auth_success`, `elicitation_dialog`, `elicitation_complete`, `elicitation_response`, `agent_needs_input`, `agent_completed` |
+| `SubagentStart` | agent type | `general-purpose`, `Explore`, `Plan`, custom agent names, or plugin-scoped names like `^my-plugin:reviewer$` |
+| `PreCompact`, `PostCompact` | what triggered compaction | `manual`, `auto` |
+| `SubagentStop` | agent type | same values as `SubagentStart` |
+| `ConfigChange` | configuration source | `user_settings`, `project_settings`, `local_settings`, `policy_settings`, `skills` |
+| `CwdChanged` | no matcher support | always fires on every directory change |
+| `FileChanged` | literal filenames to watch (see [FileChanged](https://code.claude.com/docs/en/hooks#filechanged)) | `.envrc|.env` |
+| `StopFailure` | error type | `rate_limit`, `overloaded`, `authentication_failed`, `oauth_org_not_allowed`, `billing_error`, `invalid_request`, `model_not_found`, `server_error`, `max_output_tokens`, `unknown` |
+| `InstructionsLoaded` | load reason | `session_start`, `nested_traversal`, `path_glob_match`, `include`, `compact` |
+| `UserPromptExpansion` | command name | your skill or command names |
+| `Elicitation` | MCP server name | your configured MCP server names |
+| `ElicitationResult` | MCP server name | same values as `Elicitation` |
+| `UserPromptSubmit`, `PostToolBatch`, `Stop`, `TeammateIdle`, `TaskCreated`, `TaskCompleted`, `WorktreeCreate`, `WorktreeRemove`, `MessageDisplay` | no matcher support | always fires on every occurrence |
+
+The matcher runs against a field from the [JSON input](https://code.claude.com/docs/en/hooks#hook-input-and-output) that Claude Code sends to your hook on stdin. For tool events, that field is `tool_name`. Each [hook event](https://code.claude.com/docs/en/hooks#hook-events) section lists the full set of matcher values and the input schema for that event.This example runs a linting script only when Claude writes or edits a file:
 
 ```
 {
   "hooks": {
     "PostToolUse": [\
       {\
-        "matcher": "Write|Edit",\
+        "matcher": "Edit|Write",\
         "hooks": [\
           {\
             "type": "command",\
-            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/check-style.sh"\
+            "command": "/path/to/lint-check.sh"\
           }\
         ]\
       }\
@@ -190,33 +240,43 @@ Ask AI
 }
 ```
 
-### [​](https://code.claude.com/docs/en/hooks\#plugin-hooks)  Plugin hooks
+`UserPromptSubmit`, `PostToolBatch`, `Stop`, `TeammateIdle`, `TaskCreated`, `TaskCompleted`, `WorktreeCreate`, `WorktreeRemove`, `MessageDisplay`, and `CwdChanged` don’t support matchers and always fire on every occurrence. If you add a `matcher` field to these events, it is silently ignored.For tool events, you can filter more narrowly by setting the [`if` field](https://code.claude.com/docs/en/hooks#common-fields) on individual hook handlers. `if` uses [permission rule syntax](https://code.claude.com/docs/en/permissions) to match against the tool name and arguments together, so `"Bash(git *)"` runs when any subcommand of the Bash input matches `git *` and `"Edit(*.ts)"` runs only for TypeScript files.
+
+#### [​](https://code.claude.com/docs/en/hooks\#match-mcp-tools)  Match MCP tools
 
-[Plugins](https://code.claude.com/docs/en/plugins) can provide hooks that integrate seamlessly with your user and project hooks. Plugin hooks are automatically merged with your configuration when plugins are enabled.**How plugin hooks work**:
+[MCP](https://code.claude.com/docs/en/mcp) server tools appear as regular tools in tool events (`PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`, `PermissionDenied`), so you can match them the same way you match any other tool name.MCP tools follow the naming pattern `mcp__<server>__<tool>`, for example:
 
-- Plugin hooks are defined in the plugin’s `hooks/hooks.json` file or in a file given by a custom path to the `hooks` field.
-- When a plugin is enabled, its hooks are merged with user and project hooks
-- Multiple hooks from different sources can respond to the same event
-- Plugin hooks use the `${CLAUDE_PLUGIN_ROOT}` environment variable to reference plugin files
+- `mcp__memory__create_entities`: Memory server’s create entities tool
+- `mcp__filesystem__read_file`: Filesystem server’s read file tool
+- `mcp__github__search_repositories`: GitHub server’s search tool
 
-**Example plugin hook configuration**:
+To match every tool from a server, append `.*` to the server prefix. The `.*` is required: a matcher like `mcp__memory` or `mcp__brave-search` contains only exact-match characters, so it is compared as an exact string and matches no tool.
 
-Copy
+- `mcp__memory__.*` matches all tools from the `memory` server
+- `mcp__brave-search__.*` matches all tools from a server whose name contains a hyphen
+- `mcp__.*__write.*` matches any tool whose name starts with `write` from any server
 
-Ask AI
+Hyphens in the exact-match set require Claude Code v2.1.195 or later. On earlier versions a bare hyphenated prefix like `mcp__brave-search` is evaluated as an unanchored regular expression and matches every tool from that server. The `mcp__brave-search__.*` form works on every version.Tools from a [plugin-bundled MCP server](https://code.claude.com/docs/en/mcp#plugin-provided-mcp-servers) use a scoped server segment that includes the plugin name: `mcp__plugin_<plugin-name>_<server-name>__<tool>`. A matcher written against the bare server key never fires for these tools. For a plugin named `my-plugin` that bundles a server under the key `db`, a `query` tool appears as `mcp__plugin_my-plugin_db__query`, so the matcher for every tool from that server is `mcp__plugin_my-plugin_db__.*`. Use the same scoped tool name in a handler’s [`if` field](https://code.claude.com/docs/en/hooks#common-fields). See [Plugin-provided MCP servers](https://code.claude.com/docs/en/mcp#plugin-provided-mcp-servers) for how the scoped name is built.This example logs all memory server operations and validates write operations from any MCP server:
 
 ```
 {
-  "description": "Automatic code formatting",
   "hooks": {
-    "PostToolUse": [\
+    "PreToolUse": [\
       {\
-        "matcher": "Write|Edit",\
+        "matcher": "mcp__memory__.*",\
         "hooks": [\
           {\
             "type": "command",\
-            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format.sh",\
-            "timeout": 30\
+            "command": "echo 'Memory operation initiated' >> ~/mcp-operations.log"\
+          }\
+        ]\
+      },\
+      {\
+        "matcher": "mcp__.*__write.*",\
+        "hooks": [\
+          {\
+            "type": "command",\
+            "command": "/home/user/scripts/validate-mcp-write.py"\
           }\
         ]\
       }\
@@ -225,114 +285,110 @@ Ask AI
 }
 ```
 
-Plugin hooks use the same format as regular hooks with an optional `description` field to explain the hook’s purpose.
-
-Plugin hooks run alongside your custom hooks. If multiple hooks match an event, they all execute in parallel.
-
-**Environment variables for plugins**:
-
-- `${CLAUDE_PLUGIN_ROOT}`: Absolute path to the plugin directory
-- `${CLAUDE_PROJECT_DIR}`: Project root directory (same as for project hooks)
-- All standard environment variables are available
+### [​](https://code.claude.com/docs/en/hooks\#hook-handler-fields)  Hook handler fields
 
-See the [plugin components reference](https://code.claude.com/docs/en/plugins-reference#hooks) for details on creating plugin hooks.
-
-## [​](https://code.claude.com/docs/en/hooks\#prompt-based-hooks)  Prompt-Based Hooks
+Each object in the inner `hooks` array is a hook handler: the shell command, HTTP endpoint, MCP tool, LLM prompt, or agent that runs when the matcher matches. There are five types:
 
-In addition to bash command hooks (`type: "command"`), Claude Code supports prompt-based hooks (`type: "prompt"`) that use an LLM to evaluate whether to allow or block an action. Prompt-based hooks are currently only supported for `Stop` and `SubagentStop` hooks, where they enable intelligent, context-aware decisions.
+- **[Command hooks](https://code.claude.com/docs/en/hooks#command-hook-fields)** (`type: "command"`): run a shell command. Your script receives the event’s [JSON input](https://code.claude.com/docs/en/hooks#hook-input-and-output) on stdin and communicates results back through exit codes and stdout.
+- **[HTTP hooks](https://code.claude.com/docs/en/hooks#http-hook-fields)** (`type: "http"`): send the event’s JSON input as an HTTP POST request to a URL. The endpoint communicates results back through the response body using the same [JSON output format](https://code.claude.com/docs/en/hooks#json-output) as command hooks.
+- **[MCP tool hooks](https://code.claude.com/docs/en/hooks#mcp-tool-hook-fields)** (`type: "mcp_tool"`): call a tool on an already-connected [MCP server](https://code.claude.com/docs/en/mcp). The tool’s text output is treated like command-hook stdout.
+- **[Prompt hooks](https://code.claude.com/docs/en/hooks#prompt-and-agent-hook-fields)** (`type: "prompt"`): send a prompt to a Claude model for single-turn evaluation. The model returns a yes/no decision as JSON. See [Prompt-based hooks](https://code.claude.com/docs/en/hooks#prompt-based-hooks).
+- **[Agent hooks](https://code.claude.com/docs/en/hooks#prompt-and-agent-hook-fields)** (`type: "agent"`): spawn a subagent that can use tools like Read, Grep, and Glob to verify conditions before returning a decision. Agent hooks are experimental and may change. See [Agent-based hooks](https://code.claude.com/docs/en/hooks#agent-based-hooks).
 
-### [​](https://code.claude.com/docs/en/hooks\#how-prompt-based-hooks-work)  How prompt-based hooks work
+All matching hooks run in parallel, and identical handlers are deduplicated automatically. Command hooks are deduplicated by command string and `args`, and HTTP hooks are deduplicated by URL.Handlers run in the current directory with Claude Code’s environment. The `$CLAUDE_CODE_REMOTE` environment variable is set to `"true"` in remote web environments and not set in the local CLI. As of v2.1.199, [`$CLAUDE_CODE_BRIDGE_SESSION_ID`](https://code.claude.com/docs/en/env-vars) is set to the [Remote Control](https://code.claude.com/docs/en/remote-control) session ID while the local session has an active Remote Control connection.
 
-Instead of executing a bash command, prompt-based hooks:
+#### [​](https://code.claude.com/docs/en/hooks\#common-fields)  Common fields
 
-1. Send the hook input and your prompt to a fast LLM (Haiku)
-2. The LLM responds with structured JSON containing a decision
-3. Claude Code processes the decision automatically
+These fields apply to all hook types:
 
-### [​](https://code.claude.com/docs/en/hooks\#configuration-2)  Configuration
+| Field | Required | Description |
+| --- | --- | --- |
+| `type` | yes | `"command"`, `"http"`, `"mcp_tool"`, `"prompt"`, or `"agent"` |
+| `if` | no | Permission rule syntax to filter when this hook runs, such as `"Bash(git *)"` or `"Edit(*.ts)"`. The hook command only runs if the tool call matches the pattern. See the [Bash matching table](https://code.claude.com/docs/en/hooks#bash-if-matching) below for how Bash patterns evaluate against subcommands, `$()`, and backticks. Only evaluated on tool events: `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`, and `PermissionDenied`. On other events, a hook with `if` set never runs. Uses the same syntax as [permission rules](https://code.claude.com/docs/en/permissions) |
+| `timeout` | no | Seconds before canceling. Defaults: 600 for `command`, `http`, and `mcp_tool`; 30 for `prompt`; 60 for `agent`. [`UserPromptSubmit`](https://code.claude.com/docs/en/hooks#userpromptsubmit) lowers the `command`, `http`, and `mcp_tool` default to 30, and [`MessageDisplay`](https://code.claude.com/docs/en/hooks#messagedisplay) lowers it to 10 |
+| `statusMessage` | no | Custom spinner message displayed while the hook runs |
+| `once` | no | If `true`, runs once per session then is removed. Only honored for hooks declared in [skill frontmatter](https://code.claude.com/docs/en/hooks#hooks-in-skills-and-agents); ignored in settings files and agent frontmatter |
 
-Copy
+The `if` field holds exactly one permission rule. There is no `&&`, `||`, or list syntax for combining rules; to apply multiple conditions, define a separate hook handler for each.For Bash patterns, whether your hook command runs depends on the shape of the pattern and the Bash command Claude is invoking. Leading `VAR=value` assignments are stripped before matching.
 
-Ask AI
+| `if` pattern | Bash command | Hook runs? | Why |
+| --- | --- | --- | --- |
+| `Bash(git *)` | `FOO=bar git push` | yes | leading assignments are stripped; `git push` matches |
+| `Bash(git *)` | `npm test && git push` | yes | each subcommand is checked; `git push` matches |
+| `Bash(rm *)` | `echo $(rm -rf /)` | yes | commands inside `$()` and backticks are checked; `rm -rf /` matches |
+| `Bash(rm *)` | `echo $(date)` | no | no subcommand matches `rm *` |
+| `Bash(git push *)` | `echo $(date)` | yes | patterns that specify more than the command name run the hook anyway on `$()`, backticks, or `$VAR` |
 
-```
-{
-  "hooks": {
-    "Stop": [\
-      {\
-        "hooks": [\
-          {\
-            "type": "prompt",\
-            "prompt": "Evaluate if Claude should stop: $ARGUMENTS. Check if all tasks are complete."\
-          }\
-        ]\
-      }\
-    ]
-  }
-}
-```
+The filter also fails open, running your hook regardless of pattern, when the Bash command can’t be parsed. Because the `if` filter is best-effort, use the [permission system](https://code.claude.com/docs/en/permissions) rather than a hook to enforce a hard allow or deny.
 
-**Fields:**
+#### [​](https://code.claude.com/docs/en/hooks\#command-hook-fields)  Command hook fields
 
-- `type`: Must be `"prompt"`
-- `prompt`: The prompt text to send to the LLM
+In addition to the [common fields](https://code.claude.com/docs/en/hooks#common-fields), command hooks accept these fields:
 
-  - Use `$ARGUMENTS` as a placeholder for the hook input JSON
-  - If `$ARGUMENTS` is not present, input JSON is appended to the prompt
-- `timeout`: (Optional) Timeout in seconds (default: 30 seconds)
+| Field | Required | Description |
+| --- | --- | --- |
+| `command` | yes | Shell command to execute. With `args`, the executable to spawn directly. See [Exec form and shell form](https://code.claude.com/docs/en/hooks#exec-form-and-shell-form) |
+| `args` | no | Argument list. When present, `command` is resolved as an executable and spawned directly with `args` as the argument vector, with no shell involved. See [Exec form and shell form](https://code.claude.com/docs/en/hooks#exec-form-and-shell-form) |
+| `async` | no | If `true`, runs in the background without blocking. See [Run hooks in the background](https://code.claude.com/docs/en/hooks#run-hooks-in-the-background) |
+| `asyncRewake` | no | If `true`, runs in the background and wakes Claude on exit code 2. Implies `async`. The hook’s stderr, or stdout if stderr is empty, is shown to Claude as a system reminder so it can react to a long-running background failure |
+| `shell` | no | Shell to use for this hook. Accepts `"bash"` or `"powershell"`. Defaults to `"bash"`, or to `"powershell"` on Windows when Git Bash isn’t installed. Setting `"powershell"` runs the command via PowerShell on Windows. Does not require `CLAUDE_CODE_USE_POWERSHELL_TOOL` since hooks spawn PowerShell directly. Ignored when `args` is set |
 
-### [​](https://code.claude.com/docs/en/hooks\#response-schema)  Response schema
+##### Exec form and shell form
 
-The LLM must respond with JSON containing:
+A command hook runs as exec form when `args` is set, and shell form when `args` is omitted. Set `args` whenever the hook references a [path placeholder](https://code.claude.com/docs/en/hooks#reference-scripts-by-path), since each element is passed as one argument with no quoting. Omit `args` when you need shell features like pipes or `&&`, or when neither concern applies.**Exec form** runs when `args` is present. Claude Code resolves `command` as an executable on `PATH` and spawns it directly with `args` as the argument vector. There is no shell, so each `args` element is one argument exactly as written, and path placeholders like `${CLAUDE_PLUGIN_ROOT}` are substituted into `command` and into each `args` element as plain strings. Special characters such as apostrophes, `$`, and backticks pass through verbatim because there is no shell to interpret them. No shell tokenization happens on any platform.**Shell form** runs when `args` is absent. The `command` string is passed to a shell: `sh -c` on macOS and Linux, Git Bash on Windows, or PowerShell when Git Bash isn’t installed. Set the `shell` field to choose explicitly. The shell tokenizes the string, expands variables, and interprets pipes, `&&`, redirects, and globs.
 
-Copy
+On Windows, exec form requires `command` to resolve to a real executable such as a `.exe`. The `.cmd` and `.bat` shims that npm, npx, eslint, and other tools install in `node_modules/.bin` are not executables and can’t be spawned without a shell. To run them in exec form, invoke the underlying script with `node` directly, for example `"command": "node", "args": ["${CLAUDE_PLUGIN_ROOT}/node_modules/eslint/bin/eslint.js"]`. The `node` plus script-path pattern works on every platform because `node.exe` is a real binary. To run a `.cmd` or `.bat` shim by name, use shell form.
 
-Ask AI
+This example runs a Node script bundled with a plugin. Exec form passes the resolved script path as one argument with no quoting:
 
 ```
 {
-  "decision": "approve" | "block",
-  "reason": "Explanation for the decision",
-  "continue": false,  // Optional: stops Claude entirely
-  "stopReason": "Message shown to user",  // Optional: custom stop message
-  "systemMessage": "Warning or context"  // Optional: shown to user
+  "type": "command",
+  "command": "node",
+  "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/format.js", "--fix"]
 }
 ```
 
-**Response fields:**
+The equivalent shell form needs quoting to handle paths with spaces or special characters:
 
-- `decision`: `"approve"` allows the action, `"block"` prevents it
-- `reason`: Explanation shown to Claude when decision is `"block"`
-- `continue`: (Optional) If `false`, stops Claude’s execution entirely
-- `stopReason`: (Optional) Message shown when `continue` is false
-- `systemMessage`: (Optional) Additional message shown to the user
+```
+{
+  "type": "command",
+  "command": "node \"${CLAUDE_PLUGIN_ROOT}\"/scripts/format.js --fix"
+}
+```
 
-### [​](https://code.claude.com/docs/en/hooks\#supported-hook-events)  Supported hook events
+Both forms support the same [path placeholders](https://code.claude.com/docs/en/hooks#reference-scripts-by-path), and both export them as the environment variables `CLAUDE_PROJECT_DIR`, `CLAUDE_PLUGIN_ROOT`, and `CLAUDE_PLUGIN_DATA` on the spawned process, so a script can read `process.env.CLAUDE_PLUGIN_ROOT` regardless of how it was launched. Plugin hooks additionally substitute `${user_config.*}` values; see [User configuration](https://code.claude.com/docs/en/plugins-reference#user-configuration).
 
-Prompt-based hooks work with any hook event, but are most useful for:
+In exec form, `command` is the executable name or path only. If `command` is a bare name with no path separator and contains whitespace alongside `args`, Claude Code logs a warning because the spawn will fail: there is no executable named `node script.js`. Move the extra tokens into `args`. Absolute paths with spaces, such as `C:\Program Files\nodejs\node.exe`, are a single valid executable and don’t trigger the warning.
 
-- **Stop**: Intelligently decide if Claude should continue working
-- **SubagentStop**: Evaluate if a subagent has completed its task
-- **UserPromptSubmit**: Validate user prompts with LLM assistance
-- **PreToolUse**: Make context-aware permission decisions
-- **PermissionRequest**: Intelligently allow or deny permission dialogs
+#### [​](https://code.claude.com/docs/en/hooks\#http-hook-fields)  HTTP hook fields
 
-### [​](https://code.claude.com/docs/en/hooks\#example:-intelligent-stop-hook)  Example: Intelligent Stop hook
+In addition to the [common fields](https://code.claude.com/docs/en/hooks#common-fields), HTTP hooks accept these fields:
 
-Copy
+| Field | Required | Description |
+| --- | --- | --- |
+| `url` | yes | URL to send the POST request to |
+| `headers` | no | Additional HTTP headers as key-value pairs. Values support environment variable interpolation using `$VAR_NAME` or `${VAR_NAME}` syntax. Only variables listed in `allowedEnvVars` are resolved |
+| `allowedEnvVars` | no | List of environment variable names that may be interpolated into header values. References to unlisted variables are replaced with empty strings. Required for any env var interpolation to work |
 
-Ask AI
+Claude Code sends the hook’s [JSON input](https://code.claude.com/docs/en/hooks#hook-input-and-output) as the POST request body with `Content-Type: application/json`. The response body uses the same [JSON output format](https://code.claude.com/docs/en/hooks#json-output) as command hooks.Error handling differs from command hooks: non-2xx responses, connection failures, and timeouts all produce non-blocking errors that allow execution to continue. To block a tool call or deny a permission, return a 2xx response with a JSON body containing `decision: "block"` or a `hookSpecificOutput` with `permissionDecision: "deny"`.This example sends `PreToolUse` events to a local validation service, authenticating with a token from the `MY_TOKEN` environment variable:
 
 ```
 {
   "hooks": {
-    "Stop": [\
+    "PreToolUse": [\
       {\
+        "matcher": "Bash",\
         "hooks": [\
           {\
-            "type": "prompt",\
-            "prompt": "You are evaluating whether Claude should stop working. Context: $ARGUMENTS\n\nAnalyze the conversation and determine if:\n1. All user-requested tasks are complete\n2. Any errors need to be addressed\n3. Follow-up work is needed\n\nRespond with JSON: {\"decision\": \"approve\" or \"block\", \"reason\": \"your explanation\"}",\
-            "timeout": 30\
+            "type": "http",\
+            "url": "http://localhost:8080/hooks/pre-tool-use",\
+            "timeout": 30,\
+            "headers": {\
+              "Authorization": "Bearer $MY_TOKEN"\
+            },\
+            "allowedEnvVars": ["MY_TOKEN"]\
           }\
         ]\
       }\
@@ -341,21 +397,30 @@ Ask AI
 }
 ```
 
-### [​](https://code.claude.com/docs/en/hooks\#example:-subagentstop-with-custom-logic)  Example: SubagentStop with custom logic
+#### [​](https://code.claude.com/docs/en/hooks\#mcp-tool-hook-fields)  MCP tool hook fields
 
-Copy
+In addition to the [common fields](https://code.claude.com/docs/en/hooks#common-fields), MCP tool hooks accept these fields:
+
+| Field | Required | Description |
+| --- | --- | --- |
+| `server` | yes | Name of a configured MCP server. For a [plugin-bundled server](https://code.claude.com/docs/en/mcp#plugin-provided-mcp-servers), this is the scoped name `plugin:<plugin-name>:<server-name>`, such as `plugin:my-plugin:db`, not the bare server key. The server must already be connected; the hook never triggers an OAuth or connection flow |
+| `tool` | yes | Name of the tool to call on that server |
+| `input` | no | Arguments passed to the tool. String values support `${path}` substitution from the hook’s [JSON input](https://code.claude.com/docs/en/hooks#hook-input-and-output), such as `"${tool_input.file_path}"` |
 
-Ask AI
+The tool’s text content is treated like command-hook stdout: if it parses as valid [JSON output](https://code.claude.com/docs/en/hooks#json-output) it is processed as a decision, otherwise it is shown as plain text. If the named server is not connected, or the tool returns `isError: true`, the hook produces a non-blocking error and execution continues.MCP tool hooks are available on every hook event once Claude Code has connected to your MCP servers. `SessionStart` and `Setup` typically fire before servers finish connecting, so hooks on those events should expect the “not connected” error on first run.This example calls the `security_scan` tool on the `my_server` MCP server after each `Write` or `Edit`, passing the edited file’s path:
 
 ```
 {
   "hooks": {
-    "SubagentStop": [\
+    "PostToolUse": [\
       {\
+        "matcher": "Write|Edit",\
         "hooks": [\
           {\
-            "type": "prompt",\
-            "prompt": "Evaluate if this subagent should stop. Input: $ARGUMENTS\n\nCheck if:\n- The subagent completed its assigned task\n- Any errors occurred that need fixing\n- Additional context gathering is needed\n\nReturn: {\"decision\": \"approve\" or \"block\", \"reason\": \"explanation\"}"\
+            "type": "mcp_tool",\
+            "server": "my_server",\
+            "tool": "security_scan",\
+            "input": { "file_path": "${tool_input.file_path}" }\
           }\
         ]\
       }\
@@ -364,87 +429,66 @@ Ask AI
 }
 ```
 
-### [​](https://code.claude.com/docs/en/hooks\#comparison-with-bash-command-hooks)  Comparison with bash command hooks
-
-| Feature | Bash Command Hooks | Prompt-Based Hooks |
-| --- | --- | --- |
-| **Execution** | Runs bash script | Queries LLM |
-| **Decision logic** | You implement in code | LLM evaluates context |
-| **Setup complexity** | Requires script file | Configure prompt |
-| **Context awareness** | Limited to script logic | Natural language understanding |
-| **Performance** | Fast (local execution) | Slower (API call) |
-| **Use case** | Deterministic rules | Context-aware decisions |
-
-### [​](https://code.claude.com/docs/en/hooks\#best-practices)  Best practices
-
-- **Be specific in prompts**: Clearly state what you want the LLM to evaluate
-- **Include decision criteria**: List the factors the LLM should consider
-- **Test your prompts**: Verify the LLM makes correct decisions for your use cases
-- **Set appropriate timeouts**: Default is 30 seconds, adjust if needed
-- **Use for complex decisions**: Bash hooks are better for simple, deterministic rules
-
-See the [plugin components reference](https://code.claude.com/docs/en/plugins-reference#hooks) for details on creating plugin hooks.
-
-## [​](https://code.claude.com/docs/en/hooks\#hook-events)  Hook Events
-
-### [​](https://code.claude.com/docs/en/hooks\#pretooluse)  PreToolUse
-
-Runs after Claude creates tool parameters and before processing the tool call.**Common matchers:**
-
-- `Task` \- Subagent tasks (see [subagents documentation](https://code.claude.com/docs/en/sub-agents))
-- `Bash` \- Shell commands
-- `Glob` \- File pattern matching
-- `Grep` \- Content search
-- `Read` \- File reading
-- `Edit` \- File editing
-- `Write` \- File writing
-- `WebFetch`, `WebSearch` \- Web operations
+#### [​](https://code.claude.com/docs/en/hooks\#prompt-and-agent-hook-fields)  Prompt and agent hook fields
 
-Use [PreToolUse decision control](https://code.claude.com/docs/en/hooks#pretooluse-decision-control) to allow, deny, or ask for permission to use the tool.
-
-### [​](https://code.claude.com/docs/en/hooks\#permissionrequest)  PermissionRequest
+In addition to the [common fields](https://code.claude.com/docs/en/hooks#common-fields), prompt and agent hooks accept these fields:
 
-Runs when the user is shown a permission dialog.
-Use [PermissionRequest decision control](https://code.claude.com/docs/en/hooks#permissionrequest-decision-control) to allow or deny on behalf of the user.Recognizes the same matcher values as PreToolUse.
+| Field | Required | Description |
+| --- | --- | --- |
+| `prompt` | yes | Prompt text to send to the model. Use `$ARGUMENTS` as a placeholder for the hook input JSON. Escape with a backslash to include literal text: `\$1.00` renders as `$1.00` |
+| `model` | no | Model to use for evaluation. Defaults to a fast model |
 
-### [​](https://code.claude.com/docs/en/hooks\#posttooluse)  PostToolUse
+### [​](https://code.claude.com/docs/en/hooks\#reference-scripts-by-path)  Reference scripts by path
 
-Runs immediately after a tool completes successfully.Recognizes the same matcher values as PreToolUse.
+Use these placeholders to reference hook scripts relative to the project or plugin root, regardless of the working directory when the hook runs:
 
-### [​](https://code.claude.com/docs/en/hooks\#notification)  Notification
+- `${CLAUDE_PROJECT_DIR}`: the project root. Claude Code also sets this variable in the environment of [stdio MCP servers](https://code.claude.com/docs/en/mcp#option-3-add-a-local-stdio-server) and plugin LSP servers.
+- `${CLAUDE_PLUGIN_ROOT}`: the plugin’s installation directory, for scripts bundled with a [plugin](https://code.claude.com/docs/en/plugins). Changes on each plugin update.
+- `${CLAUDE_PLUGIN_DATA}`: the plugin’s [persistent data directory](https://code.claude.com/docs/en/plugins-reference#persistent-data-directory), for dependencies and state that should survive plugin updates.
 
-Runs when Claude Code sends notifications. Supports matchers to filter by notification type.**Common matchers:**
+Prefer [exec form](https://code.claude.com/docs/en/hooks#exec-form-and-shell-form) for any hook that references a path placeholder. Exec form passes each `args` element as one argument with no shell tokenization, so paths with spaces or special characters need no quoting. In shell form, wrap each placeholder in double quotes.
 
-- `permission_prompt` \- Permission requests from Claude Code
-- `idle_prompt` \- When Claude is waiting for user input (after 60+ seconds of idle time)
-- `auth_success` \- Authentication success notifications
-- `elicitation_dialog` \- When Claude Code needs input for MCP tool elicitation
+- Project scripts
 
-You can use matchers to run different hooks for different notification types, or omit the matcher to run hooks for all notifications.**Example: Different notifications for different types**
+- Plugin scripts
 
-Copy
 
-Ask AI
+This example uses `${CLAUDE_PROJECT_DIR}` to run a style checker from the project’s `.claude/hooks/` directory after any `Write` or `Edit` tool call:
 
 ```
 {
   "hooks": {
-    "Notification": [\
+    "PostToolUse": [\
       {\
-        "matcher": "permission_prompt",\
+        "matcher": "Write|Edit",\
         "hooks": [\
           {\
             "type": "command",\
-            "command": "/path/to/permission-alert.sh"\
+            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/check-style.sh",\
+            "args": []\
           }\
         ]\
-      },\
+      }\
+    ]
+  }
+}
+```
+
+Define plugin hooks in `hooks/hooks.json` with an optional top-level `description` field. When a plugin is enabled, its hooks merge with your user and project hooks.This example runs a formatting script bundled with the plugin:
+
+```
+{
+  "description": "Automatic code formatting",
+  "hooks": {
+    "PostToolUse": [\
       {\
-        "matcher": "idle_prompt",\
+        "matcher": "Write|Edit",\
         "hooks": [\
           {\
             "type": "command",\
-            "command": "/path/to/idle-notification.sh"\
+            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format.sh",\
+            "args": [],\
+            "timeout": 30\
           }\
         ]\
       }\
@@ -453,851 +497,2355 @@ Ask AI
 }
 ```
 
-### [​](https://code.claude.com/docs/en/hooks\#userpromptsubmit)  UserPromptSubmit
+See the [plugin components reference](https://code.claude.com/docs/en/plugins-reference#hooks) for details on creating plugin hooks.
 
-Runs when the user submits a prompt, before Claude processes it. This allows you
-to add additional context based on the prompt/conversation, validate prompts, or
-block certain types of prompts.
+### [​](https://code.claude.com/docs/en/hooks\#hooks-in-skills-and-agents)  Hooks in skills and agents
 
-### [​](https://code.claude.com/docs/en/hooks\#stop)  Stop
+In addition to settings files and plugins, hooks can be defined directly in [skills](https://code.claude.com/docs/en/skills) and [subagents](https://code.claude.com/docs/en/sub-agents) using frontmatter. These hooks are scoped to the component’s lifecycle and only run when that component is active.All hook events are supported. For subagents, `Stop` hooks are automatically converted to `SubagentStop` since that is the event that fires when a subagent completes.Hooks use the same configuration format as settings-based hooks but are scoped to the component’s lifetime and cleaned up when it finishes.This skill defines a `PreToolUse` hook that runs a security validation script before each `Bash` command:
 
-Runs when the main Claude Code agent has finished responding. Does not run if
-the stoppage occurred due to a user interrupt.
+```
+---
+name: secure-operations
+description: Perform operations with security checks
+hooks:
+  PreToolUse:
+    - matcher: "Bash"
+      hooks:
+        - type: command
+          command: "./scripts/security-check.sh"
+---
+```
 
-### [​](https://code.claude.com/docs/en/hooks\#subagentstop)  SubagentStop
+Agents use the same format in their YAML frontmatter.
 
-Runs when a Claude Code subagent (Task tool call) has finished responding.
+### [​](https://code.claude.com/docs/en/hooks\#the-/hooks-menu)  The `/hooks` menu
 
-### [​](https://code.claude.com/docs/en/hooks\#precompact)  PreCompact
+Type `/hooks` in Claude Code to open a read-only browser for your configured hooks. The menu shows every hook event with a count of configured hooks, lets you drill into matchers, and shows the full details of each hook handler. Use it to verify configuration, check which settings file a hook came from, or inspect a hook’s command, prompt, or URL.The menu displays all five hook types: `command`, `prompt`, `agent`, `http`, and `mcp_tool`. Each hook is labeled with a `[type]` prefix and a source indicating where it was defined:
 
-Runs before Claude Code is about to run a compact operation.**Matchers:**
+- `User`: from `~/.claude/settings.json`
+- `Project`: from `.claude/settings.json`
+- `Local`: from `.claude/settings.local.json`
+- `Plugin`: from a plugin’s `hooks/hooks.json`
+- `Session`: registered in memory for the current session
+- `Built-in`: registered internally by Claude Code
 
-- `manual` \- Invoked from `/compact`
-- `auto` \- Invoked from auto-compact (due to full context window)
+Selecting a hook opens a detail view showing its event, matcher, type, source file, and the full command, prompt, or URL. The menu is read-only: to add, modify, or remove hooks, edit the settings JSON directly or ask Claude to make the change.
 
-### [​](https://code.claude.com/docs/en/hooks\#sessionstart)  SessionStart
+### [​](https://code.claude.com/docs/en/hooks\#disable-or-remove-hooks)  Disable or remove hooks
 
-Runs when Claude Code starts a new session or resumes an existing session (which
-currently does start a new session under the hood). Useful for loading in
-development context like existing issues or recent changes to your codebase, installing dependencies, or setting up environment variables.**Matchers:**
+To remove a hook, delete its entry from the settings JSON file.To temporarily disable all hooks without removing them, set `"disableAllHooks": true` in your settings file. There is no way to disable an individual hook while keeping it in the configuration.The `disableAllHooks` setting respects the managed settings hierarchy. If an administrator has configured hooks through managed policy settings, `disableAllHooks` set in user, project, or local settings can’t disable those managed hooks. Only `disableAllHooks` set at the managed settings level can disable managed hooks.Direct edits to hooks in settings files are normally picked up automatically by the file watcher.
 
-- `startup` \- Invoked from startup
-- `resume` \- Invoked from `--resume`, `--continue`, or `/resume`
-- `clear` \- Invoked from `/clear`
-- `compact` \- Invoked from auto or manual compact.
+## [​](https://code.claude.com/docs/en/hooks\#hook-input-and-output)  Hook input and output
 
-#### [​](https://code.claude.com/docs/en/hooks\#persisting-environment-variables)  Persisting environment variables
+Command hooks receive JSON data via stdin and communicate results through exit codes, stdout, and stderr. HTTP hooks receive the same JSON as the POST request body and communicate results through the HTTP response body. This section covers fields and behavior common to all events. Each event’s section under [Hook events](https://code.claude.com/docs/en/hooks#hook-events) includes its specific input schema and decision control options.On macOS and Linux, command hooks run in their own session without a controlling terminal as of v2.1.139. The hook process and any child processes can’t open `/dev/tty` or send escape sequences directly to the Claude Code interface. Windows has no `/dev/tty`. To surface a message to the user on any platform, return [`systemMessage`](https://code.claude.com/docs/en/hooks#json-output) in JSON output. To trigger a desktop notification, set a window title, or ring the bell, return [`terminalSequence`](https://code.claude.com/docs/en/hooks#emit-terminal-notifications) instead.
 
-SessionStart hooks have access to the `CLAUDE_ENV_FILE` environment variable, which provides a file path where you can persist environment variables for subsequent bash commands.**Example: Setting individual environment variables**
+### [​](https://code.claude.com/docs/en/hooks\#common-input-fields)  Common input fields
 
-Copy
+Hook events receive these fields as JSON, in addition to event-specific fields documented in each [hook event](https://code.claude.com/docs/en/hooks#hook-events) section. For command hooks, this JSON arrives via stdin. For HTTP hooks, it arrives as the POST request body.
 
-Ask AI
+| Field | Description |
+| --- | --- |
+| `session_id` | Current session identifier |
+| `prompt_id` | UUID identifying the user prompt currently being processed. Matches the [`prompt.id` attribute on OpenTelemetry events](https://code.claude.com/docs/en/monitoring-usage#event-correlation-attributes), so you can correlate hook output with telemetry for a single prompt. Absent until the first user input. Requires Claude Code v2.1.196 or later |
+| `transcript_path` | Path to conversation JSON. The transcript file is written asynchronously and may lag the in-memory conversation, so it may not yet include the current turn’s most recent messages when a hook fires. Hooks that need the final assistant text of the current turn should use `last_assistant_message` on [Stop](https://code.claude.com/docs/en/hooks#stop) and [SubagentStop](https://code.claude.com/docs/en/hooks#subagentstop) instead of reading the transcript |
+| `cwd` | Current working directory when the hook is invoked |
+| `permission_mode` | Current [permission mode](https://code.claude.com/docs/en/permissions#permission-modes): `"default"`, `"plan"`, `"acceptEdits"`, `"auto"`, `"dontAsk"`, or `"bypassPermissions"`. The mode labeled **Manual** arrives as `"default"`, never as `"manual"`, so scripts that match `"default"` keep working. Not all events receive this field. Check the JSON example in each [hook event](https://code.claude.com/docs/en/hooks#hook-events) section |
+| `effort` | Object with a `level` field holding the active [effort level](https://code.claude.com/docs/en/model-config#adjust-effort-level) for the turn: `"low"`, `"medium"`, `"high"`, `"xhigh"`, or `"max"`. If the requested model effort exceeds what the current model supports, this is the downgraded level the model actually used. Ultracode is not a distinct level and reports as `"xhigh"`. The object matches the [status line](https://code.claude.com/docs/en/statusline#available-data)`effort` field. Present for events that fire within a tool-use context, such as `PreToolUse`, `PostToolUse`, `Stop`, and `SubagentStop`, when the current model supports the effort parameter. The level is also available to hook commands and the Bash tool as the `$CLAUDE_EFFORT` environment variable. |
+| `hook_event_name` | Name of the event that fired |
 
-```
-#!/bin/bash
+When running with `--agent` or inside a subagent, two additional fields are included:
 
-if [ -n "$CLAUDE_ENV_FILE" ]; then
-  echo 'export NODE_ENV=production' >> "$CLAUDE_ENV_FILE"
-  echo 'export API_KEY=your-api-key' >> "$CLAUDE_ENV_FILE"
-  echo 'export PATH="$PATH:./node_modules/.bin"' >> "$CLAUDE_ENV_FILE"
-fi
+| Field | Description |
+| --- | --- |
+| `agent_id` | Unique identifier for the subagent. Present only when the hook fires inside a subagent call. Use this to distinguish subagent hook calls from main-thread calls. |
+| `agent_type` | Agent name (for example, `"Explore"` or `"security-reviewer"`). Present when the session uses `--agent` or the hook fires inside a subagent. For subagents, the subagent’s type takes precedence over the session’s `--agent` value. For [custom subagents](https://code.claude.com/docs/en/sub-agents), this is the `name` field from the agent’s frontmatter, not the filename. For subagents shipped by a [plugin](https://code.claude.com/docs/en/plugins), this is the plugin-scoped identifier such as `my-plugin:reviewer`, not the bare frontmatter name. See [SubagentStart](https://code.claude.com/docs/en/hooks#subagentstart) for how to write a matcher against a plugin-scoped name. |
 
-exit 0
+Only [`SessionStart`](https://code.claude.com/docs/en/hooks#sessionstart) hooks can receive a `model` field, and it is not guaranteed to be present. There is no `$CLAUDE_MODEL` environment variable. A hook process inherits the parent environment, so it can read `$ANTHROPIC_MODEL` if you set it in your shell, but that value doesn’t change when you switch models with `/model` during a session.For example, a `PreToolUse` hook for a Bash command receives this on stdin:
+
+```
+{
+  "session_id": "abc123",
+  "prompt_id": "550e8400-e29b-41d4-a716-446655440000",
+  "transcript_path": "/home/user/.claude/projects/.../transcript.jsonl",
+  "cwd": "/home/user/my-project",
+  "permission_mode": "default",
+  "hook_event_name": "PreToolUse",
+  "tool_name": "Bash",
+  "tool_input": {
+    "command": "npm test"
+  }
+}
 ```
 
-**Example: Persisting all environment changes from the hook**When your setup modifies the environment (for example, `nvm use`), capture and persist all changes by diffing the environment:
+The `tool_name` and `tool_input` fields are event-specific. Each [hook event](https://code.claude.com/docs/en/hooks#hook-events) section documents the additional fields for that event.
 
-Copy
+### [​](https://code.claude.com/docs/en/hooks\#exit-code-output)  Exit code output
 
-Ask AI
+The exit code from your hook command tells Claude Code whether the action should proceed, be blocked, or be ignored.**Exit 0** means success. Claude Code parses stdout for [JSON output fields](https://code.claude.com/docs/en/hooks#json-output). JSON output is only processed on exit 0. For most events, stdout is written to the debug log but not shown in the transcript. The exceptions are `UserPromptSubmit`, `UserPromptExpansion`, and `SessionStart`, where stdout is added as context that Claude can see and act on.**Exit 2** means a blocking error. Claude Code ignores stdout and any JSON in it. Instead, stderr text is fed back to Claude as an error message. The effect depends on the event: `PreToolUse` blocks the tool call, `UserPromptSubmit` rejects the prompt, and so on. See [exit code 2 behavior](https://code.claude.com/docs/en/hooks#exit-code-2-behavior-per-event) for the full list.**Any other exit code** is a non-blocking error for most hook events. The transcript shows a `<hook name> hook error` notice followed by the first line of stderr, so you can identify the cause without `--debug`. Execution continues and the full stderr is written to the debug log.For example, a hook command script that blocks dangerous Bash commands:
 
 ```
 #!/bin/bash
+# Reads JSON input from stdin, checks the command
+command=$(jq -r '.tool_input.command' < /dev/stdin)
 
-ENV_BEFORE=$(export -p | sort)
-
-# Run your setup commands that modify the environment
-source ~/.nvm/nvm.sh
-nvm use 20
-
-if [ -n "$CLAUDE_ENV_FILE" ]; then
-  ENV_AFTER=$(export -p | sort)
-  comm -13 <(echo "$ENV_BEFORE") <(echo "$ENV_AFTER") >> "$CLAUDE_ENV_FILE"
+if [[ "$command" == rm* ]]; then
+  echo "Blocked: rm commands are not allowed" >&2
+  exit 2  # Blocking error: tool call is prevented
 fi
 
-exit 0
+exit 0  # No decision: the normal permission flow applies
 ```
 
-Any variables written to this file will be available in all subsequent bash commands that Claude Code executes during the session.
+For most hook events, only exit code 2 blocks the action. Claude Code treats exit code 1 as a non-blocking error and proceeds with the action, even though 1 is the conventional Unix failure code. If your hook is meant to enforce a policy, use `exit 2`. The exception is `WorktreeCreate`, where any non-zero exit code aborts worktree creation.
 
-`CLAUDE_ENV_FILE` is only available for SessionStart hooks. Other hook types do not have access to this variable.
+#### [​](https://code.claude.com/docs/en/hooks\#exit-code-2-behavior-per-event)  Exit code 2 behavior per event
 
-### [​](https://code.claude.com/docs/en/hooks\#sessionend)  SessionEnd
+Exit code 2 is the way a hook signals “stop, don’t do this.” The effect depends on the event, because some events represent actions that can be blocked (like a tool call that hasn’t happened yet) and others represent things that already happened or can’t be prevented.
 
-Runs when a Claude Code session ends. Useful for cleanup tasks, logging session
-statistics, or saving session state.The `reason` field in the hook input will be one of:
+| Hook event | Can block? | What happens on exit 2 |
+| --- | --- | --- |
+| `PreToolUse` | Yes | Blocks the tool call |
+| `PermissionRequest` | Yes | Denies the permission |
+| `UserPromptSubmit` | Yes | Blocks prompt processing and erases the prompt |
+| `UserPromptExpansion` | Yes | Blocks the expansion |
+| `Stop` | Yes | Prevents Claude from stopping, continues the conversation |
+| `SubagentStop` | Yes | Prevents the subagent from stopping |
+| `TeammateIdle` | Yes | Prevents the teammate from going idle, so it continues working |
+| `TaskCreated` | Yes | Rolls back the task creation |
+| `TaskCompleted` | Yes | Prevents the task from being marked as completed |
+| `ConfigChange` | Yes | Blocks the configuration change from taking effect (except `policy_settings`) |
+| `StopFailure` | No | Output and exit code are ignored |
+| `PostToolUse` | No | Shows stderr to Claude; the tool already ran |
+| `PostToolUseFailure` | No | Shows stderr to Claude; the tool already failed |
+| `PostToolBatch` | Yes | Stops the agentic loop before the next model call |
+| `PermissionDenied` | No | Exit code and stderr are ignored because the denial already occurred. Use JSON `hookSpecificOutput.retry: true` to tell the model it may retry |
+| `Notification` | No | Shows stderr to user only |
+| `SubagentStart` | No | Shows stderr to user only |
+| `SessionStart` | No | Shows stderr to user only |
+| `Setup` | No | Shows stderr to user only |
+| `SessionEnd` | No | Shows stderr to user only |
+| `CwdChanged` | No | Shows stderr to user only |
+| `FileChanged` | No | Shows stderr to user only |
+| `PreCompact` | Yes | Blocks compaction |
+| `PostCompact` | No | Shows stderr to user only |
+| `Elicitation` | Yes | Denies the elicitation |
+| `ElicitationResult` | Yes | Blocks the response (action becomes decline) |
+| `WorktreeCreate` | Yes | Any non-zero exit code causes worktree creation to fail |
+| `WorktreeRemove` | No | Failures are logged in debug mode only |
+| `InstructionsLoaded` | No | Exit code is ignored |
+| `MessageDisplay` | No | The original text is displayed |
+
+For `SessionStart`, `Setup`, and `SubagentStart`, the exit code 2 stderr renders in the transcript as a `<hook name> hook error` notice, the same way a [non-blocking error](https://code.claude.com/docs/en/hooks#exit-code-output) does. Claude doesn’t see it, and the session or subagent proceeds. For `SubagentStart`, the notice appears in the subagent’s own transcript, not in the parent conversation.As of Claude Code v2.1.199, `SessionStart`, `Setup`, and `SubagentStart` show exit code 2 stderr in the transcript. Earlier versions wrote it to the debug log only.
+
+### [​](https://code.claude.com/docs/en/hooks\#http-response-handling)  HTTP response handling
+
+HTTP hooks use HTTP status codes and response bodies instead of exit codes and stdout:
+
+- **2xx with an empty body**: success, equivalent to exit code 0 with no output
+- **2xx with a plain text body**: success, the text is added as context
+- **2xx with a JSON body**: success, parsed using the same [JSON output](https://code.claude.com/docs/en/hooks#json-output) schema as command hooks
+- **Non-2xx status**: non-blocking error, execution continues
+- **Connection failure or timeout**: non-blocking error, execution continues
+
+Unlike command hooks, HTTP hooks can’t signal a blocking error through status codes alone. To block a tool call or deny a permission, return a 2xx response with a JSON body containing the appropriate decision fields.
+
+### [​](https://code.claude.com/docs/en/hooks\#json-output)  JSON output
+
+Exit codes only let you block or stay silent, but JSON output gives you finer-grained control. Instead of exiting with code 2 to block, exit 0 and print a JSON object to stdout. Claude Code reads specific fields from that JSON to control behavior, including [decision control](https://code.claude.com/docs/en/hooks#decision-control) for blocking, allowing, or escalating to the user.
+
+You must choose one approach per hook, not both: either use exit codes alone for signaling, or exit 0 and print JSON for structured control. Claude Code only processes JSON on exit 0. If you exit 2, any JSON is ignored.
+
+Your hook’s stdout must contain only the JSON object. If your shell profile prints text on startup, it can interfere with JSON parsing. See [JSON validation failed](https://code.claude.com/docs/en/hooks-guide#json-validation-failed) in the troubleshooting guide.Hook output strings, including `additionalContext`, `systemMessage`, and plain stdout, are capped at 10,000 characters. Output that exceeds this limit is saved to a file and replaced with a preview and file path, the same way large tool results are handled.The JSON object supports three kinds of fields:
+
+- **Universal fields** like `continue` work across all events. These are listed in the table below.
+- **Top-level `decision` and `reason`** are used by some events to block or provide feedback.
+- **`hookSpecificOutput`** is a nested object for events that need richer control. It requires a `hookEventName` field set to the event name.
+
+| Field | Default | Description |
+| --- | --- | --- |
+| `continue` | `true` | If `false`, Claude stops processing entirely after the hook runs. Takes precedence over any event-specific decision fields |
+| `stopReason` | none | Message shown to the user when `continue` is `false`. Not shown to Claude |
+| `suppressOutput` | `false` | If `true`, hides the hook’s stdout from the transcript. Stdout still appears in the debug log |
+| `systemMessage` | none | Warning message shown to the user |
+| `terminalSequence` | none | A terminal escape sequence for Claude Code to emit on your behalf, such as a desktop notification, window title, or bell. Restricted to OSC `0`/`1`/`2`/`9`/`99`/`777` and BEL. If the value contains anything outside the allowlist, the field is ignored. Use this instead of writing to `/dev/tty`, which is unavailable to hooks |
 
-- `clear` \- Session cleared with /clear command
-- `logout` \- User logged out
-- `prompt_input_exit` \- User exited while prompt input was visible
-- `other` \- Other exit reasons
+To stop Claude entirely regardless of event type:
+
+```
+{ "continue": false, "stopReason": "Build failed, fix errors before continuing" }
+```
 
-## [​](https://code.claude.com/docs/en/hooks\#hook-input)  Hook Input
+#### [​](https://code.claude.com/docs/en/hooks\#emit-terminal-notifications)  Emit terminal notifications
 
-Hooks receive JSON data via stdin containing session information and
-event-specific data:
+The `terminalSequence` field requires Claude Code v2.1.141 or later.Hooks run without a controlling terminal, so writing escape sequences directly to `/dev/tty` fails. Instead, return the escape sequence in the `terminalSequence` field and Claude Code emits it for you through its own terminal write path. This is race-free, works inside tmux and GNU screen, and works on Windows where there is no `/dev/tty`.The field accepts a string of one or more allowlisted escape sequences:
 
-Copy
+- OSC `0`, `1`, `2`: window and icon titles
+- OSC `9`: iTerm2, ConEmu, Windows Terminal, and WezTerm notifications, including `9;4` taskbar progress
+- OSC `99`: Kitty notifications
+- OSC `777`: urxvt, Ghostty, and Warp notifications
+- Bare BEL
 
-Ask AI
+Sequences may be terminated with BEL or with ST. Anything outside the allowlist, including CSI cursor and color sequences, OSC palette sequences, OSC 8 hyperlinks, OSC 52 clipboard writes, and OSC 1337, is rejected and the field is ignored.The example below fires a desktop notification from a `Notification` hook. The escape sequence is built with `printf` octal escapes so the control bytes never appear on the shell command line, and `jq -n --arg` builds the JSON output so quotes, backslashes, and newlines in the notification message are escaped correctly:
 
 ```
-{
-  // Common fields
-  session_id: string
-  transcript_path: string  // Path to conversation JSON
-  cwd: string              // The current working directory when the hook is invoked
-  permission_mode: string  // Current permission mode: "default", "plan", "acceptEdits", "dontAsk", or "bypassPermissions"
-
-  // Event-specific fields
-  hook_event_name: string
-  ...
-}
+#!/bin/bash
+# Notification hook: ping the desktop when Claude Code needs attention.
+input=$(cat)
+title="Claude Code"
+body=$(jq -r '.message // "Needs your attention"' <<<"$input")
+seq=$(printf '\033]777;notify;%s;%s\007' "$title" "$body")
+jq -nc --arg seq "$seq" '{terminalSequence: $seq}'
 ```
 
-### [​](https://code.claude.com/docs/en/hooks\#pretooluse-input)  PreToolUse Input
+The `{ "terminalSequence": "..." }` shape is the same from any shell or language. On Windows, build the escape string in PowerShell or a script and emit the same JSON object.
 
-The exact schema for `tool_input` depends on the tool.
+`terminalSequence` is the supported replacement for hooks that previously wrote escape sequences directly to `/dev/tty`. The allowlist is restricted to sequences that can’t move the cursor or alter colors, so a hook can never corrupt an on-screen prompt.
 
-Copy
+#### [​](https://code.claude.com/docs/en/hooks\#add-context-for-claude)  Add context for Claude
 
-Ask AI
+The `additionalContext` field passes a string from your hook into Claude’s context window. Claude Code wraps the string in a system reminder and inserts it into the conversation at the point where the hook fired. Claude reads the reminder on the next model request, but it doesn’t appear as a chat message in the interface.Return `additionalContext` inside `hookSpecificOutput` alongside the event name:
 
 ```
 {
-  "session_id": "abc123",
-  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
-  "cwd": "/Users/...",
-  "permission_mode": "default",
-  "hook_event_name": "PreToolUse",
-  "tool_name": "Write",
-  "tool_input": {
-    "file_path": "/path/to/file.txt",
-    "content": "file content"
-  },
-  "tool_use_id": "toolu_01ABC123..."
+  "hookSpecificOutput": {
+    "hookEventName": "PostToolUse",
+    "additionalContext": "This file is generated. Edit src/schema.ts and run `bun generate` instead."
+  }
 }
 ```
 
-### [​](https://code.claude.com/docs/en/hooks\#posttooluse-input)  PostToolUse Input
+Where the reminder appears depends on the event:
 
-The exact schema for `tool_input` and `tool_response` depends on the tool.
+- [SessionStart](https://code.claude.com/docs/en/hooks#sessionstart), [Setup](https://code.claude.com/docs/en/hooks#setup), and [SubagentStart](https://code.claude.com/docs/en/hooks#subagentstart): at the start of the conversation, before the first prompt
+- [UserPromptSubmit](https://code.claude.com/docs/en/hooks#userpromptsubmit) and [UserPromptExpansion](https://code.claude.com/docs/en/hooks#userpromptexpansion): alongside the submitted prompt
+- [PreToolUse](https://code.claude.com/docs/en/hooks#pretooluse), [PostToolUse](https://code.claude.com/docs/en/hooks#posttooluse), [PostToolUseFailure](https://code.claude.com/docs/en/hooks#posttoolusefailure), and [PostToolBatch](https://code.claude.com/docs/en/hooks#posttoolbatch): next to the tool result
+- [Stop](https://code.claude.com/docs/en/hooks#stop) and [SubagentStop](https://code.claude.com/docs/en/hooks#subagentstop): at the end of the turn. The conversation continues so Claude can act on the feedback. See [Stop decision control](https://code.claude.com/docs/en/hooks#stop-decision-control)
 
-Copy
+When several hooks return `additionalContext` for the same event, Claude receives all of the values. If a value exceeds 10,000 characters, Claude Code writes the full text to a file in the session directory and passes Claude the file path with a short preview instead.Use `additionalContext` for information Claude should know about the current state of your environment or the operation that just ran:
 
-Ask AI
+- **Environment state**: the current branch, deployment target, or active feature flags
+- **Conditional project rules**: which test command applies to the file just edited, which directories are read-only in this worktree
+- **External data**: open issues assigned to you, recent CI results, content fetched from an internal service
 
-```
-{
-  "session_id": "abc123",
-  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
-  "cwd": "/Users/...",
-  "permission_mode": "default",
-  "hook_event_name": "PostToolUse",
-  "tool_name": "Write",
-  "tool_input": {
-    "file_path": "/path/to/file.txt",
-    "content": "file content"
-  },
-  "tool_response": {
-    "filePath": "/path/to/file.txt",
-    "success": true
-  },
-  "tool_use_id": "toolu_01ABC123..."
-}
-```
+For instructions that never change, prefer [CLAUDE.md](https://code.claude.com/docs/en/memory). It loads without running a script and is the standard place for static project conventions.Write the text as factual statements rather than imperative system instructions. Phrasing such as “The deployment target is production” or “This repo uses `bun test`” reads as project information. Text framed as out-of-band system commands can trigger Claude’s prompt-injection defenses, which causes Claude to surface the text to you instead of treating it as context.Once injected, the text is saved in the session transcript. For mid-session events like `PostToolUse` or `UserPromptSubmit`, resuming with `--continue` or `--resume` replays the saved text rather than re-running the hook for past turns, so values like timestamps or commit SHAs become stale on resume. `SessionStart` hooks run again on resume with `source` set to `"resume"`, so they can refresh their context.
 
-### [​](https://code.claude.com/docs/en/hooks\#notification-input)  Notification Input
+#### [​](https://code.claude.com/docs/en/hooks\#decision-control)  Decision control
 
-Copy
+Not every event supports blocking or controlling behavior through JSON. The events that do each use a different set of fields to express that decision. Use this table as a quick reference before writing a hook:
 
-Ask AI
+| Events | Decision pattern | Key fields |
+| --- | --- | --- |
+| UserPromptSubmit, UserPromptExpansion, PostToolUse, PostToolUseFailure, PostToolBatch, Stop, SubagentStop, ConfigChange, PreCompact | Top-level `decision` | `decision: "block"`, `reason`. Stop and SubagentStop also accept `hookSpecificOutput.additionalContext` for [non-error feedback that continues the conversation](https://code.claude.com/docs/en/hooks#stop-decision-control) |
+| TeammateIdle, TaskCreated, TaskCompleted | Exit code or `continue: false` | Exit code 2 blocks the action with stderr feedback. JSON `{"continue": false, "stopReason": "..."}` also stops the teammate entirely, matching `Stop` hook behavior |
+| PreToolUse | `hookSpecificOutput` | `permissionDecision` (allow/deny/ask/defer), `permissionDecisionReason` |
+| PermissionRequest | `hookSpecificOutput` | `decision.behavior` (allow/deny) |
+| PermissionDenied | `hookSpecificOutput` | `retry: true` tells the model it may retry the denied tool call |
+| WorktreeCreate | path return | Command hook prints path on stdout; HTTP hook returns `hookSpecificOutput.worktreePath`. Hook failure or missing path fails creation |
+| Elicitation | `hookSpecificOutput` | `action` (accept/decline/cancel), `content` (form field values for accept) |
+| ElicitationResult | `hookSpecificOutput` | `action` (accept/decline/cancel), `content` (form field values override) |
+| MessageDisplay | `hookSpecificOutput` | `displayContent` replaces the displayed text on screen. Display-only: the transcript and what Claude sees keep the original |
+| SessionStart, Setup, SubagentStart | Context only | `hookSpecificOutput.additionalContext` adds context for Claude. SessionStart also accepts [`initialUserMessage`, `watchPaths`, `sessionTitle`, and `reloadSkills`](https://code.claude.com/docs/en/hooks#sessionstart-decision-control). No blocking or decision control |
+| WorktreeRemove, Notification, SessionEnd, PostCompact, InstructionsLoaded, StopFailure, CwdChanged, FileChanged | None | No decision control. Used for side effects like logging or cleanup |
 
-```
-{
-  "session_id": "abc123",
-  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
-  "cwd": "/Users/...",
-  "permission_mode": "default",
-  "hook_event_name": "Notification",
-  "message": "Claude needs your permission to use Bash",
-  "notification_type": "permission_prompt"
-}
-```
+A few events can also rewrite content rather than only allow or block it:
+
+- `PreToolUse`: `updatedInput` directly under `hookSpecificOutput` replaces a tool’s arguments before it runs. See [PreToolUse decision control](https://code.claude.com/docs/en/hooks#pretooluse-decision-control)
+- `PermissionRequest`: `updatedInput` inside the `decision` object. See [PermissionRequest decision control](https://code.claude.com/docs/en/hooks#permissionrequest-decision-control)
+- `PostToolUse`: `updatedToolOutput` replaces the tool’s result. See [PostToolUse decision control](https://code.claude.com/docs/en/hooks#posttooluse-decision-control)
+- `UserPromptSubmit`: can’t replace the prompt; it only injects `additionalContext` alongside it
 
-### [​](https://code.claude.com/docs/en/hooks\#userpromptsubmit-input)  UserPromptSubmit Input
+For redaction or transformation use cases, intercept at `PreToolUse` for outbound tool inputs and `PostToolUse` for inbound tool results.Here are examples of each pattern in action:
 
-Copy
+- Top-level decision
 
-Ask AI
+- PreToolUse
+
+- PermissionRequest
+
+
+Used by `UserPromptSubmit`, `UserPromptExpansion`, `PostToolUse`, `PostToolUseFailure`, `PostToolBatch`, `Stop`, `SubagentStop`, `ConfigChange`, and `PreCompact`. The only value is `"block"`. To allow the action to proceed, omit `decision` from your JSON, or exit 0 without any JSON at all:
 
 ```
 {
-  "session_id": "abc123",
-  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
-  "cwd": "/Users/...",
-  "permission_mode": "default",
-  "hook_event_name": "UserPromptSubmit",
-  "prompt": "Write a function to calculate the factorial of a number"
+  "decision": "block",
+  "reason": "Test suite must pass before proceeding"
 }
 ```
 
-### [​](https://code.claude.com/docs/en/hooks\#stop-and-subagentstop-input)  Stop and SubagentStop Input
-
-`stop_hook_active` is true when Claude Code is already continuing as a result of
-a stop hook. Check this value or process the transcript to prevent Claude Code
-from running indefinitely.
+Uses `hookSpecificOutput` for richer control: allow, deny, or escalate to the user. You can also modify tool input before it runs or inject additional context for Claude. See [PreToolUse decision control](https://code.claude.com/docs/en/hooks#pretooluse-decision-control) for the full set of options.
 
-Copy
+```
+{
+  "hookSpecificOutput": {
+    "hookEventName": "PreToolUse",
+    "permissionDecision": "deny",
+    "permissionDecisionReason": "Database writes are not allowed"
+  }
+}
+```
 
-Ask AI
+Uses `hookSpecificOutput` to allow or deny a permission request on behalf of the user. When allowing, you can also modify the tool’s input or apply permission rules so the user isn’t prompted again. See [PermissionRequest decision control](https://code.claude.com/docs/en/hooks#permissionrequest-decision-control) for the full set of options.
 
 ```
 {
-  "session_id": "abc123",
-  "transcript_path": "~/.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
-  "permission_mode": "default",
-  "hook_event_name": "Stop",
-  "stop_hook_active": true
+  "hookSpecificOutput": {
+    "hookEventName": "PermissionRequest",
+    "decision": {
+      "behavior": "allow",
+      "updatedInput": {
+        "command": "npm run lint"
+      }
+    }
+  }
 }
 ```
 
-### [​](https://code.claude.com/docs/en/hooks\#precompact-input)  PreCompact Input
+For extended examples including Bash command validation, prompt filtering, and auto-approval scripts, see [What you can automate](https://code.claude.com/docs/en/hooks-guide#what-you-can-automate) in the guide and the [Bash command validator reference implementation](https://github.com/anthropics/claude-code/blob/main/examples/hooks/bash_command_validator_example.py).
+
+## [​](https://code.claude.com/docs/en/hooks\#hook-events)  Hook events
+
+Each event corresponds to a point in Claude Code’s lifecycle where hooks can run. The sections below are ordered to match the lifecycle: from session setup through the agentic loop to session end. Each section describes when the event fires, what matchers it supports, the JSON input it receives, and how to control behavior through output.
+
+### [​](https://code.claude.com/docs/en/hooks\#sessionstart)  SessionStart
+
+Runs when Claude Code starts a new session or resumes an existing session. Useful for loading development context like existing issues or recent changes to your codebase, or setting up environment variables. For static context that doesn’t require a script, use [CLAUDE.md](https://code.claude.com/docs/en/memory) instead.SessionStart runs on every session, so keep these hooks fast. Only `type: "command"` and `type: "mcp_tool"` hooks are supported.The matcher value corresponds to how the session was initiated:
+
+| Matcher | When it fires |
+| --- | --- |
+| `startup` | New session |
+| `resume` | `--resume`, `--continue`, or `/resume` |
+| `clear` | `/clear` |
+| `compact` | Auto or manual compaction |
 
-For `manual`, `custom_instructions` comes from what the user passes into
-`/compact`. For `auto`, `custom_instructions` is empty.
+#### [​](https://code.claude.com/docs/en/hooks\#sessionstart-input)  SessionStart input
 
-Copy
+In addition to the [common input fields](https://code.claude.com/docs/en/hooks#common-input-fields), SessionStart hooks receive `source` and optionally `model`, `agent_type`, and `session_title`:
 
-Ask AI
+| Field | Description |
+| --- | --- |
+| `source` | How the session started: `"startup"` for new sessions, `"resume"` for resumed sessions, `"clear"` after `/clear`, or `"compact"` after compaction |
+| `model` | The active model identifier. It can be omitted, for example after `/clear` or when a session is restored through conversation recovery, so check for the field before reading it |
+| `agent_type` | The agent name, present when you start Claude Code with `claude --agent <name>` |
+| `session_title` | The current session title if one is already set, for example via `--name` or `/rename`. A hook that emits `sessionTitle` can check `session_title` first to avoid overwriting a title the user set explicitly |
 
 ```
 {
   "session_id": "abc123",
-  "transcript_path": "~/.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
-  "permission_mode": "default",
-  "hook_event_name": "PreCompact",
-  "trigger": "manual",
-  "custom_instructions": ""
+  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
+  "cwd": "/Users/...",
+  "hook_event_name": "SessionStart",
+  "source": "startup",
+  "model": "claude-sonnet-5"
 }
 ```
 
-### [​](https://code.claude.com/docs/en/hooks\#sessionstart-input)  SessionStart Input
+#### [​](https://code.claude.com/docs/en/hooks\#sessionstart-decision-control)  SessionStart decision control
 
-Copy
+Any text your hook script prints to stdout is added as context for Claude. In addition to the [JSON output fields](https://code.claude.com/docs/en/hooks#json-output) available to all hooks, you can return these event-specific fields:
 
-Ask AI
+| Field | Description |
+| --- | --- |
+| `additionalContext` | String added to Claude’s context at the start of the conversation, before the first prompt. See [Add context for Claude](https://code.claude.com/docs/en/hooks#add-context-for-claude) for how the text is delivered and what to put in it |
+| `initialUserMessage` | String used as the first user message of the session. Applies in [non-interactive mode](https://code.claude.com/docs/en/headless) with the `-p` flag, where it becomes the first turn even if no prompt is provided. If a prompt is provided, it follows as the next turn. Unlike `additionalContext`, which attaches to an existing turn, this creates the turn |
+| `sessionTitle` | Sets the session title, with the same effect as `/rename`. Use to name sessions automatically from the launch folder, git branch, or worktree name. Applies only when `source` is `"startup"` or `"resume"`; ignored on `"clear"` and `"compact"` |
+| `watchPaths` | Array of absolute paths to watch for [FileChanged](https://code.claude.com/docs/en/hooks#filechanged) events during this session |
+| `reloadSkills` | Boolean. When `true`, Claude Code re-scans the [skill](https://code.claude.com/docs/en/skills) and command directories after the SessionStart hooks complete, so skills the hook installed are available in the same session, starting with the first prompt |
 
 ```
 {
-  "session_id": "abc123",
-  "transcript_path": "~/.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
-  "permission_mode": "default",
-  "hook_event_name": "SessionStart",
-  "source": "startup"
+  "hookSpecificOutput": {
+    "hookEventName": "SessionStart",
+    "additionalContext": "Current branch: feat/auth-refactor\nUncommitted changes: src/auth.ts, src/login.tsx\nActive issue: #4211 Migrate to OAuth2",
+    "sessionTitle": "auth-refactor"
+  }
 }
 ```
 
-### [​](https://code.claude.com/docs/en/hooks\#sessionend-input)  SessionEnd Input
+Since plain stdout already reaches Claude for this event, a hook that only loads context can print to stdout directly without building JSON. Use the JSON form when you need to combine context with other fields such as `suppressOutput` or `sessionTitle`.Use `reloadSkills` when a SessionStart hook installs or updates skills. Skill discovery normally runs before SessionStart hooks finish, so files the hook writes into `~/.claude/skills/` or `.claude/skills/` would otherwise only appear in the next session. This example syncs a shared skills repository and requests the re-scan:
 
-Copy
+```
+#!/bin/bash
 
-Ask AI
+git -C ~/.claude/skills/team-skills pull --quiet 2>/dev/null || \
+  git clone --quiet https://git.example.com/your-org/team-skills.git ~/.claude/skills/team-skills
 
+echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "reloadSkills": true}}'
 ```
-{
-  "session_id": "abc123",
-  "transcript_path": "~/.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
-  "cwd": "/Users/...",
-  "permission_mode": "default",
-  "hook_event_name": "SessionEnd",
-  "reason": "exit"
-}
+
+#### [​](https://code.claude.com/docs/en/hooks\#persist-environment-variables)  Persist environment variables
+
+SessionStart hooks have access to the `CLAUDE_ENV_FILE` environment variable, which provides a file path where you can persist environment variables for subsequent Bash commands.To set individual environment variables, write `export` statements to `CLAUDE_ENV_FILE`. Use append (`>>`) to preserve variables set by other hooks:
+
 ```
+#!/bin/bash
+
+if [ -n "$CLAUDE_ENV_FILE" ]; then
+  echo 'export NODE_ENV=production' >> "$CLAUDE_ENV_FILE"
+  echo 'export DEBUG_LOG=true' >> "$CLAUDE_ENV_FILE"
+  echo 'export PATH="$PATH:./node_modules/.bin"' >> "$CLAUDE_ENV_FILE"
+fi
 
-## [​](https://code.claude.com/docs/en/hooks\#hook-output)  Hook Output
+exit 0
+```
 
-There are two mutually exclusive ways for hooks to return output back to Claude Code. The output
-communicates whether to block and any feedback that should be shown to Claude
-and the user.
+To capture all environment changes from setup commands, compare the exported variables before and after:
 
-### [​](https://code.claude.com/docs/en/hooks\#simple:-exit-code)  Simple: Exit Code
+```
+#!/bin/bash
 
-Hooks communicate status through exit codes, stdout, and stderr:
+ENV_BEFORE=$(export -p | sort)
 
-- **Exit code 0**: Success. `stdout` is shown to the user in verbose mode
-(ctrl+o), except for `UserPromptSubmit` and `SessionStart`, where stdout is
-added to the context. JSON output in `stdout` is parsed for structured control
-(see [Advanced: JSON Output](https://code.claude.com/docs/en/hooks#advanced-json-output)).
-- **Exit code 2**: Blocking error. Only `stderr` is used as the error message
-and fed back to Claude. The format is `[command]: {stderr}`. JSON in `stdout`
-is **not** processed for exit code 2. See per-hook-event behavior below.
-- **Other exit codes**: Non-blocking error. `stderr` is shown to the user in verbose mode (ctrl+o) with
-format `Failed with non-blocking status code: {stderr}`. If `stderr` is empty,
-it shows `No stderr output`. Execution continues.
+# Run your setup commands that modify the environment
+source ~/.nvm/nvm.sh
+nvm use 20
 
-Reminder: Claude Code does not see stdout if the exit code is 0, except for
-the `UserPromptSubmit` hook where stdout is injected as context.
+if [ -n "$CLAUDE_ENV_FILE" ]; then
+  ENV_AFTER=$(export -p | sort)
+  comm -13 <(echo "$ENV_BEFORE") <(echo "$ENV_AFTER") >> "$CLAUDE_ENV_FILE"
+fi
 
-#### [​](https://code.claude.com/docs/en/hooks\#exit-code-2-behavior)  Exit Code 2 Behavior
+exit 0
+```
 
-| Hook Event | Behavior |
-| --- | --- |
-| `PreToolUse` | Blocks the tool call, shows stderr to Claude |
-| `PermissionRequest` | Denies the permission, shows stderr to Claude |
-| `PostToolUse` | Shows stderr to Claude (tool already ran) |
-| `Notification` | N/A, shows stderr to user only |
-| `UserPromptSubmit` | Blocks prompt processing, erases prompt, shows stderr to user only |
-| `Stop` | Blocks stoppage, shows stderr to Claude |
-| `SubagentStop` | Blocks stoppage, shows stderr to Claude subagent |
-| `PreCompact` | N/A, shows stderr to user only |
-| `SessionStart` | N/A, shows stderr to user only |
-| `SessionEnd` | N/A, shows stderr to user only |
+Any variables written to this file will be available in all subsequent Bash commands that Claude Code executes during the session.
 
-### [​](https://code.claude.com/docs/en/hooks\#advanced:-json-output)  Advanced: JSON Output
+`CLAUDE_ENV_FILE` is available for SessionStart, [Setup](https://code.claude.com/docs/en/hooks#setup), [CwdChanged](https://code.claude.com/docs/en/hooks#cwdchanged), and [FileChanged](https://code.claude.com/docs/en/hooks#filechanged) hooks. Other hook types don’t have access to this variable.
 
-Hooks can return structured JSON in `stdout` for more sophisticated control.
+### [​](https://code.claude.com/docs/en/hooks\#setup)  Setup
 
-JSON output is only processed when the hook exits with code 0. If your hook
-exits with code 2 (blocking error), `stderr` text is used directly—any JSON in `stdout`
-is ignored. For other non-zero exit codes, only `stderr` is shown to the user in verbose mode (ctrl+o).
+Fires only when you launch Claude Code with `--init-only`, or with `--init` or `--maintenance` in [non-interactive mode](https://code.claude.com/docs/en/headless) with the `-p` flag. It doesn’t fire on normal startup. Use it for one-time dependency installation or scheduled cleanup that you trigger explicitly from CI or scripts, separate from normal session startup. For per-session initialization, use [SessionStart](https://code.claude.com/docs/en/hooks#sessionstart) instead.The matcher value corresponds to the CLI flag that triggered the hook:
 
-#### [​](https://code.claude.com/docs/en/hooks\#common-json-fields)  Common JSON Fields
+| Matcher | When it fires |
+| --- | --- |
+| `init` | `claude --init-only` or `claude -p --init` |
+| `maintenance` | `claude -p --maintenance` |
 
-All hook types can include these optional fields:
+`--init-only` runs Setup hooks and `SessionStart` hooks with the `startup` matcher, then exits without starting a conversation. `--init` and `--maintenance` fire Setup hooks only when combined with `-p`; in an interactive session those two flags don’t currently fire Setup hooks.Because Setup doesn’t fire on every launch, a plugin that needs a dependency installed can’t rely on Setup alone. The practical pattern is to check for the dependency on first use and install on miss, for example a hook or skill that tests for `${CLAUDE_PLUGIN_DATA}/node_modules` and runs `npm install` if absent. See the [persistent data directory](https://code.claude.com/docs/en/plugins-reference#persistent-data-directory) for where to store installed dependencies.
 
-Copy
+#### [​](https://code.claude.com/docs/en/hooks\#setup-input)  Setup input
 
-Ask AI
+In addition to the [common input fields](https://code.claude.com/docs/en/hooks#common-input-fields), Setup hooks receive a `trigger` field set to either `"init"` or `"maintenance"`:
 
 ```
 {
-  "continue": true, // Whether Claude should continue after hook execution (default: true)
-  "stopReason": "string", // Message shown when continue is false
-
-  "suppressOutput": true, // Hide stdout from transcript mode (default: false)
-  "systemMessage": "string" // Optional warning message shown to the user
+  "session_id": "abc123",
+  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
+  "cwd": "/Users/...",
+  "hook_event_name": "Setup",
+  "trigger": "init"
 }
 ```
 
-If `continue` is false, Claude stops processing after the hooks run.
+#### [​](https://code.claude.com/docs/en/hooks\#setup-decision-control)  Setup decision control
 
-- For `PreToolUse`, this is different from `"permissionDecision": "deny"`, which
-only blocks a specific tool call and provides automatic feedback to Claude.
-- For `PostToolUse`, this is different from `"decision": "block"`, which
-provides automated feedback to Claude.
-- For `UserPromptSubmit`, this prevents the prompt from being processed.
-- For `Stop` and `SubagentStop`, this takes precedence over any
-`"decision": "block"` output.
-- In all cases, `"continue" = false` takes precedence over any
-`"decision": "block"` output.
+Setup hooks can’t block. Any non-zero exit code, including 2, surfaces stderr to the user as a `<hook name> hook error` notice, and execution continues. In [non-interactive mode](https://code.claude.com/docs/en/headless), hook output appears only when you launch with `--verbose`.To pass information into Claude’s context, return `additionalContext` in JSON output; plain stdout is written to the debug log only. In addition to the [JSON output fields](https://code.claude.com/docs/en/hooks#json-output) available to all hooks, you can return these event-specific fields:
 
-`stopReason` accompanies `continue` with a reason shown to the user, not shown
-to Claude.
+| Field | Description |
+| --- | --- |
+| `additionalContext` | String added to Claude’s context. Multiple hooks’ values are concatenated |
 
-#### [​](https://code.claude.com/docs/en/hooks\#pretooluse-decision-control)  `PreToolUse` Decision Control
+```
+{
+  "hookSpecificOutput": {
+    "hookEventName": "Setup",
+    "additionalContext": "Dependencies installed: node_modules, .venv"
+  }
+}
+```
 
-`PreToolUse` hooks can control whether a tool call proceeds.
+Setup hooks have access to `CLAUDE_ENV_FILE`. Variables written to that file persist into subsequent Bash commands for the session, just as in [SessionStart hooks](https://code.claude.com/docs/en/hooks#persist-environment-variables). Only `type: "command"` and `type: "mcp_tool"` hooks are supported.
 
-- `"allow"` bypasses the permission system. `permissionDecisionReason` is shown
-to the user but not to Claude.
-- `"deny"` prevents the tool call from executing. `permissionDecisionReason` is
-shown to Claude.
-- `"ask"` asks the user to confirm the tool call in the UI.
-`permissionDecisionReason` is shown to the user but not to Claude.
+### [​](https://code.claude.com/docs/en/hooks\#instructionsloaded)  InstructionsLoaded
 
-Additionally, hooks can modify tool inputs before execution using `updatedInput`:
+Fires when a `CLAUDE.md` or `.claude/rules/*.md` file is loaded into context. This event fires at session start for eagerly-loaded files and again later when files are lazily loaded, for example when Claude accesses a subdirectory that contains a nested `CLAUDE.md` or when conditional rules with `paths:` frontmatter match. The hook doesn’t support blocking or decision control. It runs asynchronously for observability purposes.The matcher runs against `load_reason`. For example, use `"matcher": "session_start"` to fire only for files loaded at session start, or `"matcher": "path_glob_match|nested_traversal"` to fire only for lazy loads.
 
-- `updatedInput` allows you to modify the tool’s input parameters before the tool executes.
-- This is most useful with `"permissionDecision": "allow"` to modify and approve tool calls.
+#### [​](https://code.claude.com/docs/en/hooks\#instructionsloaded-input)  InstructionsLoaded input
 
-Copy
+In addition to the [common input fields](https://code.claude.com/docs/en/hooks#common-input-fields), InstructionsLoaded hooks receive these fields:
 
-Ask AI
+| Field | Description |
+| --- | --- |
+| `file_path` | Absolute path to the instruction file that was loaded |
+| `memory_type` | Scope of the file: `"User"`, `"Project"`, `"Local"`, or `"Managed"` |
+| `load_reason` | Why the file was loaded: `"session_start"`, `"nested_traversal"`, `"path_glob_match"`, `"include"`, or `"compact"`. The `"compact"` value fires when instruction files are re-loaded after a compaction event |
+| `globs` | Path glob patterns from the file’s `paths:` frontmatter, if any. Present only for `path_glob_match` loads |
+| `trigger_file_path` | Path to the file whose access triggered this load, for lazy loads |
+| `parent_file_path` | Path to the parent instruction file that included this one, for `include` loads |
 
 ```
 {
-  "hookSpecificOutput": {
-    "hookEventName": "PreToolUse",
-    "permissionDecision": "allow"
-    "permissionDecisionReason": "My reason here",
-    "updatedInput": {
-      "field_to_modify": "new value"
-    }
-  }
+  "session_id": "abc123",
+  "transcript_path": "/Users/.../.claude/projects/.../transcript.jsonl",
+  "cwd": "/Users/my-project",
+  "hook_event_name": "InstructionsLoaded",
+  "file_path": "/Users/my-project/CLAUDE.md",
+  "memory_type": "Project",
+  "load_reason": "session_start"
 }
 ```
 
-The `decision` and `reason` fields are deprecated for PreToolUse hooks.
-Use `hookSpecificOutput.permissionDecision` and
-`hookSpecificOutput.permissionDecisionReason` instead. The deprecated fields
-`"approve"` and `"block"` map to `"allow"` and `"deny"` respectively.
+#### [​](https://code.claude.com/docs/en/hooks\#instructionsloaded-decision-control)  InstructionsLoaded decision control
 
-#### [​](https://code.claude.com/docs/en/hooks\#permissionrequest-decision-control)  `PermissionRequest` Decision Control
+InstructionsLoaded hooks have no decision control. They can’t block or modify instruction loading. Use this event for audit logging, compliance tracking, or observability.
 
-`PermissionRequest` hooks can allow or deny permission requests shown to the user.
+### [​](https://code.claude.com/docs/en/hooks\#userpromptsubmit)  UserPromptSubmit
 
-- For `"behavior": "allow"` you can also optionally pass in an `"updatedInput"` that modifies the tool’s input parameters before the tool executes.
-- For `"behavior": "deny"` you can also optionally pass in a `"message"` string that tells the model why the permission was denied, and a boolean `"interrupt"` which will stop Claude.
+Runs when the user submits a prompt, before Claude processes it. This allows you
+to add additional context based on the prompt/conversation, validate prompts, or
+block certain types of prompts.`UserPromptSubmit` hooks have a default timeout of 30 seconds for `command`, `http`, and `mcp_tool` types, shorter than the 600-second default for those types on most other events. Because this hook runs before every prompt and blocks model processing until it completes, a stuck hook stalls the session. If your hook needs more time, set the `timeout` field in the hook entry.A `UserPromptSubmit` hook that reaches its timeout is canceled and its output, including any `additionalContext`, is discarded. The prompt still reaches Claude without that context. As of v2.1.196, the transcript shows a notice naming the hook, the timeout that fired, and that the output was discarded. Earlier versions cancel the hook with no notice.
 
-Copy
+#### [​](https://code.claude.com/docs/en/hooks\#userpromptsubmit-input)  UserPromptSubmit input
 
-Ask AI
+In addition to the [common input fields](https://code.claude.com/docs/en/hooks#common-input-fields), UserPromptSubmit hooks receive the `prompt` field containing the text the user submitted.
 
 ```
 {
-  "hookSpecificOutput": {
-    "hookEventName": "PermissionRequest",
-    "decision": {
-      "behavior": "allow",
-      "updatedInput": {
-        "command": "npm run lint"
-      }
-    }
-  }
+  "session_id": "abc123",
+  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
+  "cwd": "/Users/...",
+  "permission_mode": "default",
+  "hook_event_name": "UserPromptSubmit",
+  "prompt": "Write a function to calculate the factorial of a number"
 }
 ```
 
-#### [​](https://code.claude.com/docs/en/hooks\#posttooluse-decision-control)  `PostToolUse` Decision Control
+#### [​](https://code.claude.com/docs/en/hooks\#userpromptsubmit-decision-control)  UserPromptSubmit decision control
 
-`PostToolUse` hooks can provide feedback to Claude after tool execution.
+`UserPromptSubmit` hooks can control whether a user prompt is processed and add context. All [JSON output fields](https://code.claude.com/docs/en/hooks#json-output) are available.There are two ways to add context to the conversation on exit code 0:
 
-- `"block"` automatically prompts Claude with `reason`.
-- `undefined` does nothing. `reason` is ignored.
-- `"hookSpecificOutput.additionalContext"` adds context for Claude to consider.
+- **Plain text stdout**: any non-JSON text written to stdout is added as context
+- **JSON with `additionalContext`**: use the JSON format below for more control. The `additionalContext` field is added as context
 
-Copy
+Plain stdout is shown as hook output in the transcript. The `additionalContext` value is injected as a system reminder that Claude reads without a visible transcript entry.To block a prompt, return a JSON object with `decision` set to `"block"`:
 
-Ask AI
+| Field | Description |
+| --- | --- |
+| `decision` | `"block"` prevents the prompt from being processed and erases it from context. Omit to allow the prompt to proceed |
+| `reason` | Shown to the user when `decision` is `"block"`. Not added to context |
+| `additionalContext` | String added to Claude’s context alongside the submitted prompt. See [Add context for Claude](https://code.claude.com/docs/en/hooks#add-context-for-claude) |
+| `sessionTitle` | Sets the session title. Use to name sessions automatically based on the prompt content |
+| `suppressOriginalPrompt` | If `true` when `decision` is `"block"`, omits the original prompt text from the block message shown to the user |
 
 ```
 {
-  "decision": "block" | undefined,
+  "decision": "block",
   "reason": "Explanation for decision",
   "hookSpecificOutput": {
-    "hookEventName": "PostToolUse",
-    "additionalContext": "Additional information for Claude"
+    "hookEventName": "UserPromptSubmit",
+    "additionalContext": "My additional context here",
+    "sessionTitle": "My session title"
   }
 }
 ```
 
-#### [​](https://code.claude.com/docs/en/hooks\#userpromptsubmit-decision-control)  `UserPromptSubmit` Decision Control
+### [​](https://code.claude.com/docs/en/hooks\#userpromptexpansion)  UserPromptExpansion
+
+Runs when a user-typed command expands into a prompt before reaching Claude. Use this to block specific commands from direct invocation, inject context for a particular skill, or log which commands users invoke. For example, a hook matching `deploy` can block `/deploy` unless an approval file is present, or a hook matching a review skill can append the team’s review checklist as `additionalContext`.This event covers the path `PreToolUse` doesn’t: a `PreToolUse` hook matching the `Skill` tool fires only when Claude calls the tool, but typing `/skillname` directly bypasses `PreToolUse`. `UserPromptExpansion` fires on that direct path.Matches on `command_name`. Leave the matcher empty to fire on every prompt-type command.
 
-`UserPromptSubmit` hooks can control whether a user prompt is processed and add context.**Adding context (exit code 0):**
-There are two ways to add context to the conversation:
+#### [​](https://code.claude.com/docs/en/hooks\#userpromptexpansion-input)  UserPromptExpansion input
 
-1. **Plain text stdout** (simpler): Any non-JSON text written to stdout is added
-as context. This is the easiest way to inject information.
-2. **JSON with `additionalContext`** (structured): Use the JSON format below for
-more control. The `additionalContext` field is added as context.
+In addition to the [common input fields](https://code.claude.com/docs/en/hooks#common-input-fields), UserPromptExpansion hooks receive `expansion_type`, `command_name`, `command_args`, `command_source`, and the original `prompt` string. The `expansion_type` field is `slash_command` for skill and custom commands, or `mcp_prompt` for MCP server prompts.
 
-Both methods work with exit code 0. Plain stdout is shown as hook output in
-the transcript; `additionalContext` is added more discretely.**Blocking prompts:**
+```
+{
+  "session_id": "abc123",
+  "transcript_path": "/Users/.../00893aaf.jsonl",
+  "cwd": "/Users/...",
+  "permission_mode": "default",
+  "hook_event_name": "UserPromptExpansion",
+  "expansion_type": "slash_command",
+  "command_name": "example-skill",
+  "command_args": "arg1 arg2",
+  "command_source": "plugin",
+  "prompt": "/example-skill arg1 arg2"
+}
+```
 
-- `"decision": "block"` prevents the prompt from being processed. The submitted
-prompt is erased from context. `"reason"` is shown to the user but not added
-to context.
-- `"decision": undefined` (or omitted) allows the prompt to proceed normally.
+#### [​](https://code.claude.com/docs/en/hooks\#userpromptexpansion-decision-control)  UserPromptExpansion decision control
 
-Copy
+`UserPromptExpansion` hooks can block the expansion or add context. All [JSON output fields](https://code.claude.com/docs/en/hooks#json-output) are available.
 
-Ask AI
+| Field | Description |
+| --- | --- |
+| `decision` | `"block"` prevents the command from expanding. Omit to allow it to proceed |
+| `reason` | Shown to the user when `decision` is `"block"` |
+| `additionalContext` | String added to Claude’s context alongside the expanded prompt. See [Add context for Claude](https://code.claude.com/docs/en/hooks#add-context-for-claude) |
 
 ```
 {
-  "decision": "block" | undefined,
-  "reason": "Explanation for decision",
+  "decision": "block",
+  "reason": "This slash command is not available",
   "hookSpecificOutput": {
-    "hookEventName": "UserPromptSubmit",
-    "additionalContext": "My additional context here"
+    "hookEventName": "UserPromptExpansion",
+    "additionalContext": "Additional context for this expansion"
   }
 }
 ```
 
-The JSON format isn’t required for simple use cases. To add context, you can print plain text to stdout with exit code 0. Use JSON when you need to
-block prompts or want more structured control.
+### [​](https://code.claude.com/docs/en/hooks\#messagedisplay)  MessageDisplay
 
-#### [​](https://code.claude.com/docs/en/hooks\#stop/subagentstop-decision-control)  `Stop`/`SubagentStop` Decision Control
+Runs while an assistant message streams to the screen. Claude Code displays the message in increments: each time a batch of newly completed lines is ready to render, the hook runs once with those lines and Claude Code renders the hook’s replacement text in their place. A long message produces several calls; a short message may produce only one.Use MessageDisplay to:
 
-`Stop` and `SubagentStop` hooks can control whether Claude must continue.
+- strip markdown for a minimal display
+- transform the text an Agent SDK application shows its users
+- redact API keys or internal hostnames from Claude’s responses
 
-- `"block"` prevents Claude from stopping. You must populate `reason` for Claude
-to know how to proceed.
-- `undefined` allows Claude to stop. `reason` is ignored.
+Claude Code holds each batch until your hook returns, so keep the hook fast. If the hook fails or times out, Claude Code displays the original text. The default timeout for this event is 10 seconds; if your hook needs more time, set the `timeout` field in the hook entry.MessageDisplay is display-only: the replacement text changes only what is rendered on screen. The transcript and what Claude sees keep the original text, so Claude never sees the replacement, and verbose mode shows the original. The hook receives assistant message text only, so tool results and the text you type render unchanged.MessageDisplay doesn’t support matchers and fires for every assistant message that streams text; messages with no text, such as tool-call-only responses, don’t trigger it.In non-interactive runs, including Agent SDK queries and `claude -p`, MessageDisplay runs once per assistant message instead of once per batch of lines. The single call arrives after the message completes and carries the full message text: `index` is `0`, `final` is `true`, and `delta` holds the entire message. A hook that collects the `delta` text for each message receives the same total text in both modes.
 
-Copy
+#### [​](https://code.claude.com/docs/en/hooks\#messagedisplay-input)  MessageDisplay input
 
-Ask AI
+In addition to the [common input fields](https://code.claude.com/docs/en/hooks#common-input-fields), MessageDisplay hooks receive identifiers for the turn and message, the position of this call within the message, and the new text in `delta`. Batch boundaries depend on how the text streams, so use `index` and `final` to track progress through a message rather than expecting lines to be grouped a particular way.
+
+| Field | Description |
+| --- | --- |
+| `turn_id` | UUID of the current turn |
+| `message_id` | UUID of the assistant message being displayed. Stable across every batch of the same message. This is not the API `msg_…` id, so it can’t be correlated with transcript message ids |
+| `index` | Zero-based index of this batch within the message |
+| `final` | `true` on the message’s last batch. Each message has exactly one final batch |
+| `delta` | The newly completed lines since the prior batch, terminating newlines included. Always whole lines, except the final batch which may end mid-line. In interactive runs, the final batch’s delta is empty when the message ends on a newline, so treat `final`, not a non-empty delta, as the end-of-message signal. In Agent SDK and `claude -p` runs, the single call carries the entire message |
 
 ```
 {
-  "decision": "block" | undefined,
-  "reason": "Must be provided when Claude is blocked from stopping"
+  "session_id": "abc123",
+  "transcript_path": "/Users/.../.claude/projects/.../transcript.jsonl",
+  "cwd": "/Users/my-project",
+  "hook_event_name": "MessageDisplay",
+  "turn_id": "0c9e6a2f-7d41-4f4e-9a15-3f4f7c2b8d10",
+  "message_id": "5b2a9c8e-1f63-4d8a-b7c4-9e0d2a6f1c3b",
+  "index": 0,
+  "final": false,
+  "delta": "Here is the plan:\n"
 }
 ```
 
-#### [​](https://code.claude.com/docs/en/hooks\#sessionstart-decision-control)  `SessionStart` Decision Control
+#### [​](https://code.claude.com/docs/en/hooks\#messagedisplay-output)  MessageDisplay output
+
+In addition to the [JSON output fields](https://code.claude.com/docs/en/hooks#json-output) available to all hooks, MessageDisplay hooks can return `displayContent` to replace the delta on screen:
+
+| Field | Description |
+| --- | --- |
+| `displayContent` | Text displayed in place of the delta. Omit it to display the original |
+
+MessageDisplay hooks have no decision control. They can’t block the message or change what is stored in the transcript or sent to Claude.This example strips markdown formatting from Claude’s responses for a plain-text display. The script reads each batch from stdin, removes bold markers and inline code backticks from `delta`, and returns the result as `displayContent`.
 
-`SessionStart` hooks allow you to load in context at the start of a session.
+- macOS/Linux
 
-- `"hookSpecificOutput.additionalContext"` adds the string to the context.
-- Multiple hooks’ `additionalContext` values are concatenated.
+- Windows (PowerShell)
 
-Copy
 
-Ask AI
+Register a command hook for the event in your settings file:
 
 ```
 {
-  "hookSpecificOutput": {
-    "hookEventName": "SessionStart",
-    "additionalContext": "My additional context here"
+  "hooks": {
+    "MessageDisplay": [\
+      {\
+        "hooks": [\
+          {\
+            "type": "command",\
+            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/plain-display.sh",\
+            "args": []\
+          }\
+        ]\
+      }\
+    ]
   }
 }
 ```
 
-#### [​](https://code.claude.com/docs/en/hooks\#sessionend-decision-control)  `SessionEnd` Decision Control
-
-`SessionEnd` hooks run when a session ends. They cannot block session termination
-but can perform cleanup tasks.
+Save this script to `.claude/hooks/plain-display.sh` in your project and make it executable with `chmod +x`:
 
-#### [​](https://code.claude.com/docs/en/hooks\#exit-code-example:-bash-command-validation)  Exit Code Example: Bash Command Validation
+```
+#!/bin/bash
+jq '{hookSpecificOutput: {hookEventName: "MessageDisplay", displayContent: (.delta | gsub("\\*\\*"; "") | gsub("`"; ""))}}'
+```
 
-Copy
+The script needs `jq` on your `PATH`.
 
-Ask AI
+Register a command hook that runs the script through PowerShell:
 
 ```
-#!/usr/bin/env python3
-import json
-import re
-import sys
+{
+  "hooks": {
+    "MessageDisplay": [\
+      {\
+        "hooks": [\
+          {\
+            "type": "command",\
+            "command": "powershell.exe",\
+            "args": [\
+              "-NoProfile",\
+              "-ExecutionPolicy",\
+              "Bypass",\
+              "-File",\
+              "${CLAUDE_PROJECT_DIR}/.claude/hooks/plain-display.ps1"\
+            ]\
+          }\
+        ]\
+      }\
+    ]
+  }
+}
+```
 
-# Define validation rules as a list of (regex pattern, message) tuples
-VALIDATION_RULES = [\
-    (\
-        r"\bgrep\b(?!.*\|)",\
-        "Use 'rg' (ripgrep) instead of 'grep' for better performance and features",\
-    ),\
-    (\
-        r"\bfind\s+\S+\s+-name\b",\
-        "Use 'rg --files | rg pattern' or 'rg --files -g pattern' instead of 'find -name' for better performance",\
-    ),\
-]
+The `-NoProfile` flag skips loading your PowerShell profile so the hook starts fast, and `-ExecutionPolicy Bypass` lets PowerShell run the local script file.Save this script to `.claude/hooks/plain-display.ps1` in your project:
 
-def validate_command(command: str) -> list[str]:
-    issues = []
-    for pattern, message in VALIDATION_RULES:
-        if re.search(pattern, command):
-            issues.append(message)
-    return issues
+```
+$batch = [Console]::In.ReadToEnd() | ConvertFrom-Json
+$text = $batch.delta -replace '\*\*', '' -replace '`', ''
+@{
+  hookSpecificOutput = @{
+    hookEventName = "MessageDisplay"
+    displayContent = $text
+  }
+} | ConvertTo-Json
+```
 
-try:
-    input_data = json.load(sys.stdin)
-except json.JSONDecodeError as e:
-    print(f"Error: Invalid JSON input: {e}", file=sys.stderr)
-    sys.exit(1)
+Batches with no markdown pass through unchanged. If the script fails, for example because `jq` is missing, Claude Code displays the original text and notes the failure only in [debug output](https://code.claude.com/docs/en/hooks#debug-hooks), not in the session.
 
-tool_name = input_data.get("tool_name", "")
-tool_input = input_data.get("tool_input", {})
-command = tool_input.get("command", "")
+### [​](https://code.claude.com/docs/en/hooks\#pretooluse)  PreToolUse
 
-if tool_name != "Bash" or not command:
-    sys.exit(1)
+Runs after Claude creates tool parameters and before processing the tool call. Matches on tool name: `Bash`, `Edit`, `Write`, `Read`, `Glob`, `Grep`, `Agent`, `WebFetch`, `WebSearch`, `AskUserQuestion`, `ExitPlanMode`, and any [MCP tool names](https://code.claude.com/docs/en/hooks#match-mcp-tools).
 
-# Validate the command
-issues = validate_command(command)
+PreToolUse runs only when Claude calls a tool. Files you [reference with `@` in your prompt](https://code.claude.com/docs/en/common-workflows#reference-files-and-directories) are added without any tool call: Claude Code inserts their contents while building the prompt, so no PreToolUse hook fires for them, including hooks matching `Read`. To block specific paths from `@` references, use a [`Read` deny rule](https://code.claude.com/docs/en/permissions#read-and-edit) instead.
 
-if issues:
-    for message in issues:
-        print(f"• {message}", file=sys.stderr)
-    # Exit code 2 blocks tool call and shows stderr to Claude
-    sys.exit(2)
-```
+Use [PreToolUse decision control](https://code.claude.com/docs/en/hooks#pretooluse-decision-control) to allow, deny, ask, or defer the tool call.
 
-#### [​](https://code.claude.com/docs/en/hooks\#json-output-example:-userpromptsubmit-to-add-context-and-validation)  JSON Output Example: UserPromptSubmit to Add Context and Validation
+#### [​](https://code.claude.com/docs/en/hooks\#pretooluse-input)  PreToolUse input
 
-For `UserPromptSubmit` hooks, you can inject context using either method:
+In addition to the [common input fields](https://code.claude.com/docs/en/hooks#common-input-fields), PreToolUse hooks receive `tool_name`, `tool_input`, and `tool_use_id`. The `tool_input` fields depend on the tool:
 
-- **Plain text stdout** with exit code 0: Simplest approach, prints text
-- **JSON output** with exit code 0: Use `"decision": "block"` to reject prompts,
-or `additionalContext` for structured context injection
+##### Bash
 
-Remember: Exit code 2 only uses `stderr` for the error message. To block using
-JSON (with a custom reason), use `"decision": "block"` with exit code 0.
+Executes shell commands.
 
-Copy
+| Field | Type | Example | Description |
+| --- | --- | --- | --- |
+| `command` | string | `"npm test"` | The shell command to execute |
+| `description` | string | `"Run test suite"` | Optional description of what the command does |
+| `timeout` | number | `120000` | Optional timeout in milliseconds |
+| `run_in_background` | boolean | `false` | Whether to run the command in background |
 
-Ask AI
+##### Write
 
-```
-#!/usr/bin/env python3
-import json
-import sys
-import re
-import datetime
+Creates or overwrites a file.
 
-# Load input from stdin
-try:
-    input_data = json.load(sys.stdin)
-except json.JSONDecodeError as e:
-    print(f"Error: Invalid JSON input: {e}", file=sys.stderr)
-    sys.exit(1)
+| Field | Type | Example | Description |
+| --- | --- | --- | --- |
+| `file_path` | string | `"/path/to/file.txt"` | Absolute path to the file to write |
+| `content` | string | `"file content"` | Content to write to the file |
 
-prompt = input_data.get("prompt", "")
+##### Edit
 
-# Check for sensitive patterns
-sensitive_patterns = [\
-    (r"(?i)\b(password|secret|key|token)\s*[:=]", "Prompt contains potential secrets"),\
-]
+Replaces a string in an existing file.
 
-for pattern, message in sensitive_patterns:
-    if re.search(pattern, prompt):
-        # Use JSON output to block with a specific reason
-        output = {
-            "decision": "block",
-            "reason": f"Security policy violation: {message}. Please rephrase your request without sensitive information."
-        }
-        print(json.dumps(output))
-        sys.exit(0)
+| Field | Type | Example | Description |
+| --- | --- | --- | --- |
+| `file_path` | string | `"/path/to/file.txt"` | Absolute path to the file to edit |
+| `old_string` | string | `"original text"` | Text to find and replace |
+| `new_string` | string | `"replacement text"` | Replacement text |
+| `replace_all` | boolean | `false` | Whether to replace all occurrences |
 
-# Add current time to context
-context = f"Current time: {datetime.datetime.now()}"
-print(context)
-
-"""
-The following is also equivalent:
-print(json.dumps({
-  "hookSpecificOutput": {
-    "hookEventName": "UserPromptSubmit",
-    "additionalContext": context,
-  },
-}))
-"""
+##### Read
 
-# Allow the prompt to proceed with the additional context
-sys.exit(0)
-```
+Reads file contents.
 
-#### [​](https://code.claude.com/docs/en/hooks\#json-output-example:-pretooluse-with-approval)  JSON Output Example: PreToolUse with Approval
+| Field | Type | Example | Description |
+| --- | --- | --- | --- |
+| `file_path` | string | `"/path/to/file.txt"` | Absolute path to the file to read |
+| `offset` | number | `10` | Optional line number to start reading from |
+| `limit` | number | `50` | Optional number of lines to read |
 
-Copy
+##### Glob
 
-Ask AI
+Finds files matching a glob pattern.
 
-```
-#!/usr/bin/env python3
-import json
-import sys
+| Field | Type | Example | Description |
+| --- | --- | --- | --- |
+| `pattern` | string | `"**/*.ts"` | Glob pattern to match files against |
+| `path` | string | `"/path/to/dir"` | Optional directory to search in. Defaults to current working directory |
 
-# Load input from stdin
-try:
-    input_data = json.load(sys.stdin)
-except json.JSONDecodeError as e:
-    print(f"Error: Invalid JSON input: {e}", file=sys.stderr)
-    sys.exit(1)
+##### Grep
 
-tool_name = input_data.get("tool_name", "")
-tool_input = input_data.get("tool_input", {})
+Searches file contents with regular expressions.
 
-# Example: Auto-approve file reads for documentation files
-if tool_name == "Read":
-    file_path = tool_input.get("file_path", "")
-    if file_path.endswith((".md", ".mdx", ".txt", ".json")):
-        # Use JSON output to auto-approve the tool call
-        output = {
-            "decision": "approve",
-            "reason": "Documentation file auto-approved",
-            "suppressOutput": True  # Don't show in verbose mode
-        }
-        print(json.dumps(output))
-        sys.exit(0)
+| Field | Type | Example | Description |
+| --- | --- | --- | --- |
+| `pattern` | string | `"TODO.*fix"` | Regular expression pattern to search for |
+| `path` | string | `"/path/to/dir"` | Optional file or directory to search in |
+| `glob` | string | `"*.ts"` | Optional glob pattern to filter files |
+| `output_mode` | string | `"content"` | `"content"`, `"files_with_matches"`, or `"count"`. Defaults to `"files_with_matches"` |
+| `-i` | boolean | `true` | Case insensitive search |
+| `multiline` | boolean | `false` | Enable multiline matching |
 
-# For other cases, let the normal permission flow proceed
-sys.exit(0)
-```
+##### WebFetch
 
-## [​](https://code.claude.com/docs/en/hooks\#working-with-mcp-tools)  Working with MCP Tools
+Fetches and processes web content.
 
-Claude Code hooks work seamlessly with
-[Model Context Protocol (MCP) tools](https://code.claude.com/docs/en/mcp). When MCP servers
-provide tools, they appear with a special naming pattern that you can match in
-your hooks.
+| Field | Type | Example | Description |
+| --- | --- | --- | --- |
+| `url` | string | `"https://example.com/api"` | URL to fetch content from |
+| `prompt` | string | `"Extract the API endpoints"` | Prompt to run on the fetched content |
 
-### [​](https://code.claude.com/docs/en/hooks\#mcp-tool-naming)  MCP Tool Naming
+##### WebSearch
 
-MCP tools follow the pattern `mcp__<server>__<tool>`, for example:
+Searches the web.
 
-- `mcp__memory__create_entities` \- Memory server’s create entities tool
-- `mcp__filesystem__read_file` \- Filesystem server’s read file tool
-- `mcp__github__search_repositories` \- GitHub server’s search tool
+| Field | Type | Example | Description |
+| --- | --- | --- | --- |
+| `query` | string | `"react hooks best practices"` | Search query |
+| `allowed_domains` | array | `["docs.example.com"]` | Optional: only include results from these domains |
+| `blocked_domains` | array | `["spam.example.com"]` | Optional: exclude results from these domains |
 
-### [​](https://code.claude.com/docs/en/hooks\#configuring-hooks-for-mcp-tools)  Configuring Hooks for MCP Tools
+##### Agent
 
-You can target specific MCP tools or entire MCP servers:
+Spawns a [subagent](https://code.claude.com/docs/en/sub-agents).
 
-Copy
+| Field | Type | Example | Description |
+| --- | --- | --- | --- |
+| `prompt` | string | `"Find all API endpoints"` | The task for the agent to perform |
+| `description` | string | `"Find API endpoints"` | Short description of the task |
+| `subagent_type` | string | `"Explore"` | Type of specialized agent to use |
+| `model` | string | `"sonnet"` | Optional model alias to override the default |
 
-Ask AI
+In `PostToolUse`, `tool_response` for a completed Agent call carries the subagent’s final text along with usage telemetry. Read these fields to record per-subagent cost from a hook:
 
-```
-{
-  "hooks": {
-    "PreToolUse": [\
-      {\
-        "matcher": "mcp__memory__.*",\
-        "hooks": [\
-          {\
-            "type": "command",\
-            "command": "echo 'Memory operation initiated' >> ~/mcp-operations.log"\
-          }\
-        ]\
-      },\
-      {\
-        "matcher": "mcp__.*__write.*",\
-        "hooks": [\
-          {\
-            "type": "command",\
-            "command": "/home/user/scripts/validate-mcp-write.py"\
-          }\
-        ]\
-      }\
-    ]
-  }
-}
-```
+| Field | Type | Example | Description |
+| --- | --- | --- | --- |
+| `status` | string | `"completed"` | `"completed"` for foreground subagents, `"async_launched"` for background subagents. As of v2.1.198, subagents run in the background by default, so an omitted `run_in_background` also produces `"async_launched"` |
+| `agentId` | string | `"a4d2c8f1e0b3a297"` | Identifier for the subagent run |
+| `content` | array | `[{"type": "text", "text": "Found 12 endpoints..."}]` | The subagent’s final text blocks |
+| `resolvedModel` | string | `"claude-sonnet-4-5"` | Model the subagent ran on, which may differ from the requested model. Requires Claude Code v2.1.174 or later |
+| `totalTokens` | number | `12450` | Total tokens billed across the subagent’s turns |
+| `totalDurationMs` | number | `48211` | Wall-clock duration of the subagent run |
+| `totalToolUseCount` | number | `7` | Count of tool calls the subagent made |
+| `usage` | object | `{"input_tokens": 8320, ...}` | Per-type token breakdown: `input_tokens`, `output_tokens`, `cache_creation_input_tokens`, `cache_read_input_tokens` |
 
-## [​](https://code.claude.com/docs/en/hooks\#examples)  Examples
+For background subagents, the tool returns immediately after launching, so `tool_response` carries no usage fields. It has `status: "async_launched"`, `agentId`, `description`, `prompt`, `outputFile`, and `resolvedModel`.The `resolvedModel` field names the model the subagent actually runs on, which can differ from the `model` value in `tool_input`, such as when `availableModels` or another override applies. It requires Claude Code v2.1.174 or later.
 
-For practical examples including code formatting, notifications, and file protection, see [More Examples](https://code.claude.com/docs/en/hooks-guide#more-examples) in the get started guide.
+##### AskUserQuestion
 
-## [​](https://code.claude.com/docs/en/hooks\#security-considerations)  Security Considerations
+Asks the user one to four multiple-choice questions.
 
-### [​](https://code.claude.com/docs/en/hooks\#disclaimer)  Disclaimer
+| Field | Type | Example | Description |
+| --- | --- | --- | --- |
+| `questions` | array | `[{"question": "Which framework?", "header": "Framework", "options": [{"label": "React"}], "multiSelect": false}]` | Questions to present, each with a `question` string, short `header`, `options` array, and optional `multiSelect` flag |
+| `answers` | object | `{"Which framework?": "React"}` | Optional. Maps question text to the selected option label. Multi-select answers join labels with commas. Claude doesn’t set this field; supply it via `updatedInput` to answer programmatically |
 
-**USE AT YOUR OWN RISK**: Claude Code hooks execute arbitrary shell commands on
-your system automatically. By using hooks, you acknowledge that:
+##### ExitPlanMode
 
-- You are solely responsible for the commands you configure
-- Hooks can modify, delete, or access any files your user account can access
-- Malicious or poorly written hooks can cause data loss or system damage
-- Anthropic provides no warranty and assumes no liability for any damages
-resulting from hook usage
-- You should thoroughly test hooks in a safe environment before production use
+Presents a plan and asks the user to approve it before Claude leaves [plan mode](https://code.claude.com/docs/en/permission-modes#analyze-before-you-edit-with-plan-mode). Claude writes the plan to a file on disk before calling the tool, so the literal `tool_input` from the model is typically empty. Claude Code injects the plan content and file path before passing the input to hooks.
 
-Always review and understand any hook commands before adding them to your
-configuration.
+| Field | Type | Example | Description |
+| --- | --- | --- | --- |
+| `plan` | string | `"## Refactor auth\n1. Extract..."` | Plan content in Markdown. Injected from the plan file on disk |
+| `planFilePath` | string | `"/Users/.../plans/refactor-auth.md"` | Path to the plan file. Injected |
+| `allowedPrompts` | array | `[{"tool": "Bash", "prompt": "run tests"}]` | Deprecated. Claude Code accepts the field but ignores it. Before v2.1.205, it carried prompt-based permissions Claude requested to implement the plan |
 
-### [​](https://code.claude.com/docs/en/hooks\#security-best-practices)  Security Best Practices
+In `PostToolUse`, `tool_response` is an object with `plan` and `filePath` fields holding the approved plan, plus internal status flags. Read `tool_response.plan` for the plan content rather than re-reading the file from disk.
 
-Here are some key practices for writing more secure hooks:
+#### [​](https://code.claude.com/docs/en/hooks\#pretooluse-decision-control)  PreToolUse decision control
 
-1. **Validate and sanitize inputs** \- Never trust input data blindly
-2. **Always quote shell variables** \- Use `"$VAR"` not `$VAR`
-3. **Block path traversal** \- Check for `..` in file paths
-4. **Use absolute paths** \- Specify full paths for scripts (use
-“$CLAUDE\_PROJECT\_DIR” for the project path)
-5. **Skip sensitive files** \- Avoid `.env`, `.git/`, keys, etc.
+`PreToolUse` hooks can control whether a tool call proceeds. Unlike other hooks that use a top-level `decision` field, PreToolUse returns its decision inside a `hookSpecificOutput` object. This gives it richer control: four outcomes (allow, deny, ask, or defer) plus the ability to modify tool input before execution.
 
-### [​](https://code.claude.com/docs/en/hooks\#configuration-safety)  Configuration Safety
+| Field | Description |
+| --- | --- |
+| `permissionDecision` | `"allow"` skips the permission prompt, except for [tools that require user interaction](https://code.claude.com/docs/en/hooks#pretooluse-decision-control). `"deny"` prevents the tool call. `"ask"` prompts the user to confirm. `"defer"` exits gracefully so the tool can be resumed later. [Deny and ask rules](https://code.claude.com/docs/en/permissions#manage-permissions) are still evaluated regardless of what the hook returns |
+| `permissionDecisionReason` | For `"allow"` and `"ask"`, shown to the user but not Claude. For `"deny"`, shown to Claude. For `"defer"`, ignored |
+| `updatedInput` | Modifies the tool’s input parameters before execution. Replaces the entire input object, so include unchanged fields alongside modified ones. Combine with `"allow"` to auto-approve, or `"ask"` to show the modified input to the user. For `"defer"`, ignored |
+| `additionalContext` | String added to Claude’s context alongside the tool result. Ignored when `permissionDecision` is `"defer"`. See [Add context for Claude](https://code.claude.com/docs/en/hooks#add-context-for-claude) |
 
-Direct edits to hooks in settings files don’t take effect immediately. Claude
-Code:
+When multiple PreToolUse hooks return different decisions, precedence is `deny` \> `defer` \> `ask` \> `allow`.When a hook returns `"ask"`, the permission prompt displayed to the user includes a label identifying where the hook came from: for example, `[User]`, `[Project]`, `[Plugin]`, or `[Local]`. This helps users understand which configuration source is requesting confirmation.
 
-1. Captures a snapshot of hooks at startup
-2. Uses this snapshot throughout the session
-3. Warns if hooks are modified externally
-4. Requires review in `/hooks` menu for changes to apply
+```
+{
+  "hookSpecificOutput": {
+    "hookEventName": "PreToolUse",
+    "permissionDecision": "allow",
+    "permissionDecisionReason": "My reason here",
+    "updatedInput": {
+      "field_to_modify": "new value"
+    },
+    "additionalContext": "Current environment: production. Proceed with caution."
+  }
+}
+```
 
-This prevents malicious hook modifications from affecting your current session.
+`AskUserQuestion` and `ExitPlanMode` require user interaction and normally block in [non-interactive mode](https://code.claude.com/docs/en/headless) with the `-p` flag. Returning `permissionDecision: "allow"` together with `updatedInput` satisfies that requirement: the hook reads the tool’s input from stdin, collects the answer through your own UI, and returns it in `updatedInput` so the tool runs without prompting. Returning `"allow"` alone is not sufficient for these tools. For `AskUserQuestion`, echo back the original `questions` array and add an [`answers`](https://code.claude.com/docs/en/hooks#askuserquestion) object mapping each question’s text to the chosen answer.As of v2.1.199, an MCP tool whose server marks it with [`_meta["anthropic/requiresUserInteraction"]`](https://code.claude.com/docs/en/mcp#require-approval-for-a-specific-tool) is stricter: a hook can’t skip its approval prompt with `"allow"`, with or without `updatedInput`, because Claude Code can’t confirm the hook collected the interaction the tool needs.
 
-## [​](https://code.claude.com/docs/en/hooks\#hook-execution-details)  Hook Execution Details
+PreToolUse previously used top-level `decision` and `reason` fields, but these are deprecated for this event. Use `hookSpecificOutput.permissionDecision` and `hookSpecificOutput.permissionDecisionReason` instead. The deprecated values `"approve"` and `"block"` map to `"allow"` and `"deny"` respectively. Other events like PostToolUse and Stop continue to use top-level `decision` and `reason` as their current format.
 
-- **Timeout**: 60-second execution limit by default, configurable per command.
+#### [​](https://code.claude.com/docs/en/hooks\#defer-a-tool-call-for-later)  Defer a tool call for later
 
-  - A timeout for an individual command does not affect the other commands.
-- **Parallelization**: All matching hooks run in parallel
-- **Deduplication**: Multiple identical hook commands are deduplicated automatically
-- **Environment**: Runs in current directory with Claude Code’s environment
+`"defer"` is for integrations that run `claude -p` as a subprocess and read its JSON output, such as an Agent SDK app or a custom UI built on top of Claude Code. It lets that calling process pause Claude at a tool call, collect input through its own interface, and resume where it left off. Claude Code honors this value only in [non-interactive mode](https://code.claude.com/docs/en/headless) with the `-p` flag. In interactive sessions it logs a warning and ignores the hook result.
 
-  - The `CLAUDE_PROJECT_DIR` environment variable is available and contains the
-    absolute path to the project root directory (where Claude Code was started)
-  - The `CLAUDE_CODE_REMOTE` environment variable indicates whether the hook is running in a remote (web) environment (`"true"`) or local CLI environment (not set or empty). Use this to run different logic based on execution context.
-- **Input**: JSON via stdin
-- **Output**:
+The `defer` value requires Claude Code v2.1.89 or later. Earlier versions don’t recognize it and the tool proceeds through the normal permission flow.
 
-  - PreToolUse/PermissionRequest/PostToolUse/Stop/SubagentStop: Progress shown in verbose mode (ctrl+o)
-  - Notification/SessionEnd: Logged to debug only (`--debug`)
-  - UserPromptSubmit/SessionStart: stdout added as context for Claude
+The `AskUserQuestion` tool is the typical case: Claude wants to ask the user something, but there is no terminal to answer in. The round trip works like this:
 
-## [​](https://code.claude.com/docs/en/hooks\#debugging)  Debugging
+1. Claude calls `AskUserQuestion`. The `PreToolUse` hook fires.
+2. The hook returns `permissionDecision: "defer"`. The tool doesn’t execute. The process exits with `stop_reason: "tool_deferred"` and the pending tool call preserved in the transcript.
+3. The calling process reads `deferred_tool_use` from the SDK result, surfaces the question in its own UI, and waits for an answer.
+4. The calling process runs `claude -p --resume <session-id>`. The same tool call fires `PreToolUse` again.
+5. The hook returns `permissionDecision: "allow"` with the answer in `updatedInput`. The tool executes and Claude continues.
 
-### [​](https://code.claude.com/docs/en/hooks\#basic-troubleshooting)  Basic Troubleshooting
+The `deferred_tool_use` field carries the tool’s `id`, `name`, and `input`. The `input` is the parameters Claude generated for the tool call, captured before execution:
 
-If your hooks aren’t working:
+```
+{
+  "type": "result",
+  "subtype": "success",
+  "stop_reason": "tool_deferred",
+  "session_id": "abc123",
+  "deferred_tool_use": {
+    "id": "toolu_01abc",
+    "name": "AskUserQuestion",
+    "input": { "questions": [{ "question": "Which framework?", "header": "Framework", "options": [{"label": "React"}, {"label": "Vue"}], "multiSelect": false }] }
+  }
+}
+```
 
-1. **Check configuration** \- Run `/hooks` to see if your hook is registered
-2. **Verify syntax** \- Ensure your JSON settings are valid
-3. **Test commands** \- Run hook commands manually first
-4. **Check permissions** \- Make sure scripts are executable
-5. **Review logs** \- Use `claude --debug` to see hook execution details
+There is no timeout or retry limit. The session remains on disk until you resume it, subject to the [`cleanupPeriodDays`](https://code.claude.com/docs/en/settings#available-settings) retention sweep that deletes session files after 30 days by default. If the answer is not ready when you resume, the hook can return `"defer"` again and the process exits the same way. The calling process controls when to break the loop by eventually returning `"allow"` or `"deny"` from the hook.`"defer"` only works when Claude makes a single tool call in the turn. If Claude makes several tool calls at once, `"defer"` is ignored with a warning and the tool proceeds through the normal permission flow. The constraint exists because resume can only re-run one tool: there is no way to defer one call from a batch without leaving the others unresolved.If the deferred tool is no longer available when you resume, the process exits with `stop_reason: "tool_deferred_unavailable"` and `is_error: true` before the hook fires. This happens when an MCP server that provided the tool is not connected for the resumed session. The `deferred_tool_use` payload is still included so you can identify which tool went missing.
 
-Common issues:
+`--resume` restores the permission mode that was active when the tool was deferred, so you don’t need to pass `--permission-mode` again. The exceptions are `plan` and `bypassPermissions`, which are never carried over. Passing `--permission-mode` explicitly on resume overrides the restored value.
 
-- **Quotes not escaped** \- Use `\"` inside JSON strings
-- **Wrong matcher** \- Check tool names match exactly (case-sensitive)
-- **Command not found** \- Use full paths for scripts
+### [​](https://code.claude.com/docs/en/hooks\#permissionrequest)  PermissionRequest
 
-### [​](https://code.claude.com/docs/en/hooks\#advanced-debugging)  Advanced Debugging
+Runs when the user is shown a permission dialog.
+Use [PermissionRequest decision control](https://code.claude.com/docs/en/hooks#permissionrequest-decision-control) to allow or deny on behalf of the user.Matches on tool name, same values as PreToolUse.
 
-For complex hook issues:
+#### [​](https://code.claude.com/docs/en/hooks\#permissionrequest-input)  PermissionRequest input
 
-1. **Inspect hook execution** \- Use `claude --debug` to see detailed hook
-execution
-2. **Validate JSON schemas** \- Test hook input/output with external tools
-3. **Check environment variables** \- Verify Claude Code’s environment is correct
-4. **Test edge cases** \- Try hooks with unusual file paths or inputs
-5. **Monitor system resources** \- Check for resource exhaustion during hook
-execution
-6. **Use structured logging** \- Implement logging in your hook scripts
+PermissionRequest hooks receive `tool_name` and `tool_input` fields like PreToolUse hooks, but without `tool_use_id`. An optional `permission_suggestions` array contains the “always allow” options the user would normally see in the permission dialog. The difference is when the hook fires: PermissionRequest hooks run when a permission dialog is about to be shown to the user, while PreToolUse hooks run before tool execution regardless of permission status.
 
-### [​](https://code.claude.com/docs/en/hooks\#debug-output-example)  Debug Output Example
+```
+{
+  "session_id": "abc123",
+  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
+  "cwd": "/Users/...",
+  "permission_mode": "default",
+  "hook_event_name": "PermissionRequest",
+  "tool_name": "Bash",
+  "tool_input": {
+    "command": "rm -rf node_modules",
+    "description": "Remove node_modules directory"
+  },
+  "permission_suggestions": [\
+    {\
+      "type": "addRules",\
+      "rules": [{ "toolName": "Bash", "ruleContent": "rm -rf node_modules" }],\
+      "behavior": "allow",\
+      "destination": "localSettings"\
+    }\
+  ]
+}
+```
 
-Use `claude --debug` to see hook execution details:
+#### [​](https://code.claude.com/docs/en/hooks\#permissionrequest-decision-control)  PermissionRequest decision control
 
-Copy
+`PermissionRequest` hooks can allow or deny permission requests. In addition to the [JSON output fields](https://code.claude.com/docs/en/hooks#json-output) available to all hooks, your hook script can return a `decision` object with these event-specific fields:
 
-Ask AI
+| Field | Description |
+| --- | --- |
+| `behavior` | `"allow"` grants the permission, `"deny"` denies it. [Deny and ask rules](https://code.claude.com/docs/en/permissions#manage-permissions) are still evaluated, so a hook returning `"allow"` doesn’t override a matching deny rule |
+| `updatedInput` | For `"allow"` only: modifies the tool’s input parameters before execution. Replaces the entire input object, so include unchanged fields alongside modified ones. The modified input is re-evaluated against deny and ask rules |
+| `updatedPermissions` | For `"allow"` only: array of [permission update entries](https://code.claude.com/docs/en/hooks#permission-update-entries) to apply, such as adding an allow rule or changing the session permission mode |
+| `message` | For `"deny"` only: tells Claude why the permission was denied |
+| `interrupt` | For `"deny"` only: if `true`, stops Claude |
 
 ```
-[DEBUG] Executing hooks for PostToolUse:Write
-[DEBUG] Getting matching hook commands for PostToolUse with query: Write
-[DEBUG] Found 1 hook matchers in settings
-[DEBUG] Matched 1 hooks for query "Write"
-[DEBUG] Found 1 hook commands to execute
-[DEBUG] Executing hook command: <Your command> with timeout 60000ms
-[DEBUG] Hook command completed with status 0: <Your stdout>
+{
+  "hookSpecificOutput": {
+    "hookEventName": "PermissionRequest",
+    "decision": {
+      "behavior": "allow",
+      "updatedInput": {
+        "command": "npm run lint"
+      }
+    }
+  }
+}
 ```
 
-Progress messages appear in verbose mode (ctrl+o) showing:
+#### [​](https://code.claude.com/docs/en/hooks\#permission-update-entries)  Permission update entries
 
-- Which hook is running
-- Command being executed
-- Success/failure status
-- Output or error messages
+The `updatedPermissions` output field and the [`permission_suggestions` input field](https://code.claude.com/docs/en/hooks#permissionrequest-input) both use the same array of entry objects. Each entry has a `type` that determines its other fields, and a `destination` that controls where the change is written.
 
-Was this page helpful?
+| `type` | Fields | Effect |
+| --- | --- | --- |
+| `addRules` | `rules`, `behavior`, `destination` | Adds permission rules. `rules` is an array of `{toolName, ruleContent?}` objects. Omit `ruleContent` to match the whole tool. `behavior` is `"allow"`, `"deny"`, or `"ask"` |
+| `replaceRules` | `rules`, `behavior`, `destination` | Replaces all rules of the given `behavior` at the `destination` with the provided `rules` |
+| `removeRules` | `rules`, `behavior`, `destination` | Removes matching rules of the given `behavior` |
+| `setMode` | `mode`, `destination` | Changes the permission mode. Valid modes are `default`, `auto`, `acceptEdits`, `dontAsk`, `bypassPermissions`, `plan`, and `manual` as an alias for `default`. The `manual` alias requires Claude Code v2.1.200 or later |
+| `addDirectories` | `directories`, `destination` | Adds working directories. `directories` is an array of path strings |
+| `removeDirectories` | `directories`, `destination` | Removes working directories |
+
+`setMode` with `bypassPermissions` only takes effect if the session was launched with bypass mode already available: `--dangerously-skip-permissions`, `--permission-mode bypassPermissions`, `--allow-dangerously-skip-permissions`, or `permissions.defaultMode: "bypassPermissions"` in settings, and the mode is not disabled by [`permissions.disableBypassPermissionsMode`](https://code.claude.com/docs/en/permissions#managed-settings). Otherwise the update is a no-op. `bypassPermissions` is never persisted as `defaultMode` regardless of `destination`.
+
+The `destination` field on every entry determines whether the change stays in memory or persists to a settings file.
+
+| `destination` | Writes to |
+| --- | --- |
+| `session` | in-memory only, discarded when the session ends |
+| `localSettings` | `.claude/settings.local.json` |
+| `projectSettings` | `.claude/settings.json` |
+| `userSettings` | `~/.claude/settings.json` |
+
+A hook can echo one of the `permission_suggestions` it received as its own `updatedPermissions` output, which is equivalent to the user selecting that “always allow” option in the dialog.
+
+### [​](https://code.claude.com/docs/en/hooks\#posttooluse)  PostToolUse
+
+Runs immediately after a tool completes successfully.Matches on tool name, same values as PreToolUse.
+
+#### [​](https://code.claude.com/docs/en/hooks\#posttooluse-input)  PostToolUse input
+
+`PostToolUse` hooks fire after a tool has already executed successfully. The input includes both `tool_input`, the arguments sent to the tool, and `tool_response`, the result it returned. The exact schema for both depends on the tool.
+
+```
+{
+  "session_id": "abc123",
+  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
+  "cwd": "/Users/...",
+  "permission_mode": "default",
+  "hook_event_name": "PostToolUse",
+  "tool_name": "Write",
+  "tool_input": {
+    "file_path": "/path/to/file.txt",
+    "content": "file content"
+  },
+  "tool_response": {
+    "filePath": "/path/to/file.txt",
+    "success": true
+  },
+  "tool_use_id": "toolu_01ABC123...",
+  "duration_ms": 12
+}
+```
+
+| Field | Description |
+| --- | --- |
+| `duration_ms` | Optional. Tool execution time in milliseconds. Excludes time spent in permission prompts and PreToolUse hooks |
+
+#### [​](https://code.claude.com/docs/en/hooks\#posttooluse-decision-control)  PostToolUse decision control
+
+`PostToolUse` hooks can provide feedback to Claude after tool execution. In addition to the [JSON output fields](https://code.claude.com/docs/en/hooks#json-output) available to all hooks, your hook script can return these event-specific fields:
+
+| Field | Description |
+| --- | --- |
+| `decision` | `"block"` adds the `reason` next to the tool result. Claude still sees the original output; to replace it, use `updatedToolOutput` |
+| `reason` | Explanation shown to Claude when `decision` is `"block"` |
+| `additionalContext` | String added to Claude’s context alongside the tool result. See [Add context for Claude](https://code.claude.com/docs/en/hooks#add-context-for-claude) |
+| `updatedToolOutput` | Replaces the tool’s output with the provided value before it is sent to Claude. The value must match the tool’s output shape |
+| `updatedMCPToolOutput` | Replaces the output for [MCP tools](https://code.claude.com/docs/en/hooks#match-mcp-tools) only. Prefer `updatedToolOutput`, which works for all tools |
+
+The example below replaces the output of a `Bash` call. The replacement value matches the `Bash` tool’s output shape:
+
+```
+{
+  "hookSpecificOutput": {
+    "hookEventName": "PostToolUse",
+    "additionalContext": "Additional information for Claude",
+    "updatedToolOutput": {
+      "stdout": "[redacted]",
+      "stderr": "",
+      "interrupted": false,
+      "isImage": false
+    }
+  }
+}
+```
+
+`updatedToolOutput` only changes what Claude sees. The tool has already run by the time the hook fires, so any files written, commands executed, or network requests sent have already taken effect. Telemetry such as OpenTelemetry tool spans and analytics events also captures the original output before the hook runs. To prevent or modify a tool call before it runs, use a [PreToolUse](https://code.claude.com/docs/en/hooks#pretooluse) hook instead.The replacement value must match the tool’s output shape. Built-in tools return structured objects rather than plain strings. For example, `Bash` returns an object with `stdout`, `stderr`, `interrupted`, and `isImage` fields. For built-in tools, a value that doesn’t match the tool’s output schema is ignored and the original output is used. MCP tool output is passed through without schema validation. Stripping error details that Claude needs can cause it to proceed on a false assumption.
+
+### [​](https://code.claude.com/docs/en/hooks\#posttoolusefailure)  PostToolUseFailure
+
+Runs when a tool execution fails. This event fires for tool calls that throw errors or return failure results. Use this to log failures, send alerts, or provide corrective feedback to Claude.Matches on tool name, same values as PreToolUse.
+
+#### [​](https://code.claude.com/docs/en/hooks\#posttoolusefailure-input)  PostToolUseFailure input
+
+PostToolUseFailure hooks receive the same `tool_name` and `tool_input` fields as PostToolUse, along with error information as top-level fields:
+
+```
+{
+  "session_id": "abc123",
+  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
+  "cwd": "/Users/...",
+  "permission_mode": "default",
+  "hook_event_name": "PostToolUseFailure",
+  "tool_name": "Bash",
+  "tool_input": {
+    "command": "npm test",
+    "description": "Run test suite"
+  },
+  "tool_use_id": "toolu_01ABC123...",
+  "error": "Command exited with non-zero status code 1",
+  "is_interrupt": false,
+  "duration_ms": 4187
+}
+```
+
+| Field | Description |
+| --- | --- |
+| `error` | String describing what went wrong |
+| `is_interrupt` | Optional boolean indicating whether the failure was caused by user interruption |
+| `duration_ms` | Optional. Tool execution time in milliseconds. Excludes time spent in permission prompts and PreToolUse hooks |
+
+#### [​](https://code.claude.com/docs/en/hooks\#posttoolusefailure-decision-control)  PostToolUseFailure decision control
+
+`PostToolUseFailure` hooks can provide context to Claude after a tool failure. In addition to the [JSON output fields](https://code.claude.com/docs/en/hooks#json-output) available to all hooks, your hook script can return these event-specific fields:
+
+| Field | Description |
+| --- | --- |
+| `additionalContext` | String added to Claude’s context alongside the error. See [Add context for Claude](https://code.claude.com/docs/en/hooks#add-context-for-claude) |
+
+```
+{
+  "hookSpecificOutput": {
+    "hookEventName": "PostToolUseFailure",
+    "additionalContext": "Additional information about the failure for Claude"
+  }
+}
+```
+
+### [​](https://code.claude.com/docs/en/hooks\#posttoolbatch)  PostToolBatch
+
+Runs once after every tool call in a batch has resolved, before Claude Code sends the next request to the model. `PostToolUse` fires once per tool, which means it fires concurrently when Claude makes parallel tool calls. `PostToolBatch` fires exactly once with the full batch, so it is the right place to inject context that depends on the set of tools that ran rather than on any single tool. There is no matcher for this event.
+
+#### [​](https://code.claude.com/docs/en/hooks\#posttoolbatch-input)  PostToolBatch input
+
+In addition to the [common input fields](https://code.claude.com/docs/en/hooks#common-input-fields), PostToolBatch hooks receive `tool_calls`, an array describing every tool call in the batch:
+
+```
+{
+  "session_id": "abc123",
+  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
+  "cwd": "/Users/...",
+  "permission_mode": "default",
+  "hook_event_name": "PostToolBatch",
+  "tool_calls": [\
+    {\
+      "tool_name": "Read",\
+      "tool_input": {"file_path": "/.../ledger/accounts.py"},\
+      "tool_use_id": "toolu_01...",\
+      "tool_response": "     1\tfrom __future__ import annotations\n     2\t..."\
+    },\
+    {\
+      "tool_name": "Read",\
+      "tool_input": {"file_path": "/.../ledger/transactions.py"},\
+      "tool_use_id": "toolu_02...",\
+      "tool_response": "     1\tfrom __future__ import annotations\n     2\t..."\
+    }\
+  ]
+}
+```
+
+`tool_response` contains the same content the model receives in the corresponding `tool_result` block. The value is a serialized string or content-block array, exactly as the tool emitted it. For `Read`, that means line-number-prefixed text rather than raw file contents. Responses can be large, so parse only the fields you need.
+
+The `tool_response` shape differs from `PostToolUse`’s. `PostToolUse` passes the tool’s structured `Output` object, such as `{filePath: "...", success: true}` for `Write`; `PostToolBatch` passes the serialized `tool_result` content the model sees.
+
+#### [​](https://code.claude.com/docs/en/hooks\#posttoolbatch-decision-control)  PostToolBatch decision control
+
+`PostToolBatch` hooks can inject context for Claude. In addition to the [JSON output fields](https://code.claude.com/docs/en/hooks#json-output) available to all hooks, your hook script can return these event-specific fields:
+
+| Field | Description |
+| --- | --- |
+| `additionalContext` | Context string injected once before the next model call. See [Add context for Claude](https://code.claude.com/docs/en/hooks#add-context-for-claude) for delivery details, what to put in it, and how resumed sessions handle past values |
+
+```
+{
+  "hookSpecificOutput": {
+    "hookEventName": "PostToolBatch",
+    "additionalContext": "These files are part of the ledger module. Run pytest before marking the task complete."
+  }
+}
+```
+
+Returning `decision: "block"` or `continue: false` stops the agentic loop before the next model call.
+
+### [​](https://code.claude.com/docs/en/hooks\#permissiondenied)  PermissionDenied
+
+Runs when the [auto mode](https://code.claude.com/docs/en/permission-modes#eliminate-prompts-with-auto-mode) classifier denies a tool call. This hook only fires in auto mode: it doesn’t run when you manually deny a permission dialog, when a `PreToolUse` hook blocks a call, or when a `deny` rule matches. Use it to log classifier denials, adjust configuration, or tell the model it may retry the tool call.Matches on tool name, same values as PreToolUse.
+
+#### [​](https://code.claude.com/docs/en/hooks\#permissiondenied-input)  PermissionDenied input
+
+In addition to the [common input fields](https://code.claude.com/docs/en/hooks#common-input-fields), PermissionDenied hooks receive `tool_name`, `tool_input`, `tool_use_id`, and `reason`.
+
+```
+{
+  "session_id": "abc123",
+  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
+  "cwd": "/Users/...",
+  "permission_mode": "auto",
+  "hook_event_name": "PermissionDenied",
+  "tool_name": "Bash",
+  "tool_input": {
+    "command": "rm -rf /tmp/build",
+    "description": "Clean build directory"
+  },
+  "tool_use_id": "toolu_01ABC123...",
+  "reason": "Auto mode denied: command targets a path outside the project"
+}
+```
+
+| Field | Description |
+| --- | --- |
+| `reason` | The classifier’s explanation for why the tool call was denied |
+
+#### [​](https://code.claude.com/docs/en/hooks\#permissiondenied-decision-control)  PermissionDenied decision control
+
+PermissionDenied hooks can tell the model it may retry the denied tool call. Return a JSON object with `hookSpecificOutput.retry` set to `true`:
+
+```
+{
+  "hookSpecificOutput": {
+    "hookEventName": "PermissionDenied",
+    "retry": true
+  }
+}
+```
+
+When `retry` is `true`, Claude Code adds a message to the conversation telling the model it may retry the tool call. The denial itself is not reversed. If your hook doesn’t return JSON, or returns `retry: false`, the denial stands and the model receives the original rejection message.
+
+### [​](https://code.claude.com/docs/en/hooks\#notification)  Notification
+
+Runs when Claude Code sends notifications. Matches on notification type. Omit the matcher to run hooks for all notification types.
+
+| Matcher | When it fires |
+| --- | --- |
+| `permission_prompt` | Claude needs you to approve a tool use |
+| `idle_prompt` | Claude is done and waiting for your next prompt |
+| `auth_success` | Authentication completes |
+| `elicitation_dialog` | An MCP server opens an elicitation form |
+| `elicitation_complete` | An MCP elicitation form is submitted or dismissed |
+| `elicitation_response` | An MCP elicitation response is sent back to the server |
+| `agent_needs_input` | A background session starts waiting on your input. Fires only while [agent view](https://code.claude.com/docs/en/agent-view) is open in a terminal |
+| `agent_completed` | A background session finishes or fails. Fires only while [agent view](https://code.claude.com/docs/en/agent-view) is open in a terminal |
+
+The `agent_needs_input` and `agent_completed` types require Claude Code v2.1.198 or later.Use separate matchers to run different handlers depending on the notification type. This configuration triggers a permission-specific alert script when Claude needs permission approval and a different notification when Claude has been idle:
+
+```
+{
+  "hooks": {
+    "Notification": [\
+      {\
+        "matcher": "permission_prompt",\
+        "hooks": [\
+          {\
+            "type": "command",\
+            "command": "/path/to/permission-alert.sh"\
+          }\
+        ]\
+      },\
+      {\
+        "matcher": "idle_prompt",\
+        "hooks": [\
+          {\
+            "type": "command",\
+            "command": "/path/to/idle-notification.sh"\
+          }\
+        ]\
+      }\
+    ]
+  }
+}
+```
+
+#### [​](https://code.claude.com/docs/en/hooks\#notification-input)  Notification input
+
+In addition to the [common input fields](https://code.claude.com/docs/en/hooks#common-input-fields), Notification hooks receive `message` with the notification text, an optional `title`, and `notification_type` indicating which type fired.
+
+```
+{
+  "session_id": "abc123",
+  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
+  "cwd": "/Users/...",
+  "hook_event_name": "Notification",
+  "message": "Claude needs your permission",
+  "title": "Permission needed",
+  "notification_type": "permission_prompt"
+}
+```
+
+Notification hooks can’t block or modify notifications. They are intended for side effects such as forwarding the notification to an external service. The [common JSON output fields](https://code.claude.com/docs/en/hooks#json-output) such as `systemMessage` apply.
+
+### [​](https://code.claude.com/docs/en/hooks\#subagentstart)  SubagentStart
+
+Runs when a Claude Code subagent is spawned via the Agent tool. Supports matchers to filter by agent type name. For built-in agents, this is the agent name like `general-purpose`, `Explore`, or `Plan`. For [custom subagents](https://code.claude.com/docs/en/sub-agents), this is the `name` field from the agent’s frontmatter, not the filename.For subagents shipped by a [plugin](https://code.claude.com/docs/en/plugins), the agent type is the plugin-scoped identifier such as `my-plugin:reviewer`, not the bare frontmatter name. The colon places a plugin-scoped name on the regular-expression path, so anchor the matcher with `^` and `$` for an exact match: `^my-plugin:reviewer$`.
+
+#### [​](https://code.claude.com/docs/en/hooks\#subagentstart-input)  SubagentStart input
+
+In addition to the [common input fields](https://code.claude.com/docs/en/hooks#common-input-fields), SubagentStart hooks receive `agent_id` with the unique identifier for the subagent and `agent_type` with the agent name that the matcher filters on.
+
+```
+{
+  "session_id": "abc123",
+  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
+  "cwd": "/Users/...",
+  "hook_event_name": "SubagentStart",
+  "agent_id": "agent-abc123",
+  "agent_type": "Explore"
+}
+```
+
+SubagentStart hooks can’t block subagent creation, but they can inject context into the subagent. In addition to the [JSON output fields](https://code.claude.com/docs/en/hooks#json-output) available to all hooks, you can return:
+
+| Field | Description |
+| --- | --- |
+| `additionalContext` | String added to the subagent’s context at the start of its conversation, before its first prompt. See [Add context for Claude](https://code.claude.com/docs/en/hooks#add-context-for-claude) |
+
+```
+{
+  "hookSpecificOutput": {
+    "hookEventName": "SubagentStart",
+    "additionalContext": "Follow security guidelines for this task"
+  }
+}
+```
+
+### [​](https://code.claude.com/docs/en/hooks\#subagentstop)  SubagentStop
+
+Runs when a Claude Code subagent has finished responding. Matches on agent type, same values as SubagentStart.
+
+#### [​](https://code.claude.com/docs/en/hooks\#subagentstop-input)  SubagentStop input
+
+In addition to the [common input fields](https://code.claude.com/docs/en/hooks#common-input-fields), SubagentStop hooks receive `stop_hook_active`, `agent_id`, `agent_type`, `agent_transcript_path`, and `last_assistant_message`. The `agent_type` field is the value used for matcher filtering. The `transcript_path` is the main session’s transcript, while `agent_transcript_path` is the subagent’s own transcript stored in a nested `subagents/` folder. The `last_assistant_message` field contains the text content of the subagent’s final response, so hooks can access it without parsing the transcript file.SubagentStop hooks also receive the `background_tasks` and `session_crons` arrays described under [Stop input](https://code.claude.com/docs/en/hooks#stop-input), available in Claude Code v2.1.145 or later. Both arrays are scoped to the parent session, not the subagent.
+
+```
+{
+  "session_id": "abc123",
+  "transcript_path": "~/.claude/projects/.../abc123.jsonl",
+  "cwd": "/Users/...",
+  "permission_mode": "default",
+  "hook_event_name": "SubagentStop",
+  "stop_hook_active": false,
+  "agent_id": "def456",
+  "agent_type": "Explore",
+  "agent_transcript_path": "~/.claude/projects/.../abc123/subagents/agent-def456.jsonl",
+  "last_assistant_message": "Analysis complete. Found 3 potential issues...",
+  "background_tasks": [],
+  "session_crons": []
+}
+```
+
+SubagentStop hooks use the same decision control format as [Stop hooks](https://code.claude.com/docs/en/hooks#stop-decision-control), including `hookSpecificOutput.additionalContext` with `hookEventName` set to `"SubagentStop"`, for non-error feedback that keeps the subagent running. Returning `decision: "block"` with a `reason` keeps the subagent running and delivers `reason` to the subagent as its next instruction. To inject context into the parent session after a subagent returns, use a [`PostToolUse`](https://code.claude.com/docs/en/hooks#posttooluse) hook on the `Agent` tool instead.
+
+### [​](https://code.claude.com/docs/en/hooks\#taskcreated)  TaskCreated
+
+Runs when a task is being created via the `TaskCreate` tool. Use this to enforce naming conventions, require task descriptions, or prevent certain tasks from being created.When a `TaskCreated` hook exits with code 2, the task is not created and the stderr message is fed back to the model as feedback. To stop the teammate entirely instead of re-running it, return JSON with `{"continue": false, "stopReason": "..."}`. TaskCreated hooks don’t support matchers and fire on every occurrence.
+
+#### [​](https://code.claude.com/docs/en/hooks\#taskcreated-input)  TaskCreated input
+
+In addition to the [common input fields](https://code.claude.com/docs/en/hooks#common-input-fields), TaskCreated hooks receive `task_id`, `task_subject`, and optionally `task_description`, `teammate_name`, and `team_name`.
+
+```
+{
+  "session_id": "abc123",
+  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
+  "cwd": "/Users/...",
+  "permission_mode": "default",
+  "hook_event_name": "TaskCreated",
+  "task_id": "task-001",
+  "task_subject": "Implement user authentication",
+  "task_description": "Add login and signup endpoints",
+  "teammate_name": "implementer",
+  "team_name": "session-a1b2c3d4"
+}
+```
+
+| Field | Description |
+| --- | --- |
+| `task_id` | Identifier of the task being created |
+| `task_subject` | Title of the task |
+| `task_description` | Detailed description of the task. May be absent |
+| `teammate_name` | Name of the teammate creating the task. May be absent |
+| `team_name` | Deprecated. Session-derived team name; will be removed in a future release |
+
+#### [​](https://code.claude.com/docs/en/hooks\#taskcreated-decision-control)  TaskCreated decision control
+
+TaskCreated hooks support two ways to control task creation:
+
+- **Exit code 2**: the task is not created and the stderr message is fed back to the model as feedback.
+- **JSON `{"continue": false, "stopReason": "..."}`**: stops the teammate entirely, matching `Stop` hook behavior. The `stopReason` is shown to the user.
+
+This example blocks tasks whose subjects don’t follow the required format:
+
+```
+#!/bin/bash
+INPUT=$(cat)
+TASK_SUBJECT=$(echo "$INPUT" | jq -r '.task_subject')
+
+if [[ ! "$TASK_SUBJECT" =~ ^\[TICKET-[0-9]+\] ]]; then
+  echo "Task subject must start with a ticket number, e.g. '[TICKET-123] Add feature'" >&2
+  exit 2
+fi
+
+exit 0
+```
+
+### [​](https://code.claude.com/docs/en/hooks\#taskcompleted)  TaskCompleted
+
+Runs when a task is being marked as completed. This fires in two situations: when any agent explicitly marks a task as completed through the TaskUpdate tool, or when an [agent team](https://code.claude.com/docs/en/agent-teams) teammate finishes its turn with in-progress tasks. Use this to enforce completion criteria like passing tests or lint checks before a task can close.When a `TaskCompleted` hook exits with code 2, the task is not marked as completed and the stderr message is fed back to the model as feedback. To stop the teammate entirely instead of re-running it, return JSON with `{"continue": false, "stopReason": "..."}`. TaskCompleted hooks don’t support matchers and fire on every occurrence.
+
+#### [​](https://code.claude.com/docs/en/hooks\#taskcompleted-input)  TaskCompleted input
+
+In addition to the [common input fields](https://code.claude.com/docs/en/hooks#common-input-fields), TaskCompleted hooks receive `task_id`, `task_subject`, and optionally `task_description`, `teammate_name`, and `team_name`.
+
+```
+{
+  "session_id": "abc123",
+  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
+  "cwd": "/Users/...",
+  "permission_mode": "default",
+  "hook_event_name": "TaskCompleted",
+  "task_id": "task-001",
+  "task_subject": "Implement user authentication",
+  "task_description": "Add login and signup endpoints",
+  "teammate_name": "implementer",
+  "team_name": "session-a1b2c3d4"
+}
+```
+
+| Field | Description |
+| --- | --- |
+| `task_id` | Identifier of the task being completed |
+| `task_subject` | Title of the task |
+| `task_description` | Detailed description of the task. May be absent |
+| `teammate_name` | Name of the teammate completing the task. May be absent |
+| `team_name` | Deprecated. Session-derived team name; will be removed in a future release |
+
+#### [​](https://code.claude.com/docs/en/hooks\#taskcompleted-decision-control)  TaskCompleted decision control
+
+TaskCompleted hooks support two ways to control task completion:
+
+- **Exit code 2**: the task is not marked as completed and the stderr message is fed back to the model as feedback.
+- **JSON `{"continue": false, "stopReason": "..."}`**: stops the teammate entirely, matching `Stop` hook behavior. The `stopReason` is shown to the user.
+
+This example runs tests and blocks task completion if they fail:
+
+```
+#!/bin/bash
+INPUT=$(cat)
+TASK_SUBJECT=$(echo "$INPUT" | jq -r '.task_subject')
+
+# Run the test suite
+if ! npm test 2>&1; then
+  echo "Tests not passing. Fix failing tests before completing: $TASK_SUBJECT" >&2
+  exit 2
+fi
+
+exit 0
+```
+
+### [​](https://code.claude.com/docs/en/hooks\#stop)  Stop
+
+Runs when the main Claude Code agent has finished responding. Does not run if
+the stoppage occurred due to a user interrupt. API errors fire
+[StopFailure](https://code.claude.com/docs/en/hooks#stopfailure) instead.
+
+The [`/goal`](https://code.claude.com/docs/en/goal) command is a built-in shortcut for a session-scoped prompt-based Stop hook. Use it when you want Claude to keep working until a condition holds without writing hook configuration.
+
+#### [​](https://code.claude.com/docs/en/hooks\#stop-input)  Stop input
+
+In addition to the [common input fields](https://code.claude.com/docs/en/hooks#common-input-fields), Stop hooks receive `stop_hook_active`, `last_assistant_message`, `background_tasks`, and `session_crons`. The `stop_hook_active` field is `true` when Claude Code is already continuing as a result of a stop hook. Check this value or process the transcript to avoid blocking on a condition that will never resolve. Claude Code overrides the hook and ends the turn after 8 consecutive blocks.The `last_assistant_message` field contains the text content of Claude’s final response, so hooks can access it without parsing the transcript file. For hooks that act on the just-completed turn, such as read-aloud or notification hooks, use this field rather than reading `transcript_path`: the transcript file isn’t guaranteed to include the final message at Stop time on all versions.The `background_tasks` and `session_crons` arrays, available in Claude Code v2.1.145 or later, let hooks distinguish “session is done” from “session is paused waiting for background work to wake it back up”. Both arrays are present when the task registry is reachable and are empty when nothing is in flight or scheduled.Each entry in `background_tasks` describes one in-flight task and uses these fields:
+
+| Field | Description |
+| --- | --- |
+| `id` | Task identifier |
+| `type` | Friendly task-type label such as `shell`, `subagent`, `monitor`, `workflow`, `teammate`, `cloud session`, or `MCP task`. Each label identifies which Claude Code feature created the task. Falls back to the raw discriminant for unrecognized types |
+| `status` | Current task status |
+| `description` | Free-text description, capped at 1000 characters with an in-string `… [+N chars]` marker when clipped |
+| `command` | Shell command line, capped at 1000 characters. Present only for `shell` tasks |
+| `agent_type` | Subagent type name. Present only for `subagent` tasks |
+| `server` | MCP server name. Present only for `monitor` and `MCP task` tasks |
+| `tool` | MCP tool name. Present only for `monitor` and `MCP task` tasks |
+| `name` | Workflow name. Present only for `workflow` tasks |
+
+Each entry in `session_crons` describes one session-scoped scheduled wakeup, sourced from `CronCreate`, `ScheduleWakeup`, and `/loop`:
+
+| Field | Description |
+| --- | --- |
+| `id` | Cron task identifier |
+| `schedule` | Cron expression, for example `0 9 * * 1-5` |
+| `recurring` | `false` for one-shot wakeups whose schedule encodes a single fire time, `true` for tasks that re-fire on every match |
+| `prompt` | Prompt submitted when the cron fires, capped at 1000 characters with the same `… [+N chars]` marker |
+
+This example shows a Stop input with one in-flight shell task and one recurring cron:
+
+```
+{
+  "session_id": "abc123",
+  "transcript_path": "~/.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
+  "cwd": "/Users/...",
+  "permission_mode": "default",
+  "hook_event_name": "Stop",
+  "stop_hook_active": true,
+  "last_assistant_message": "I've completed the refactoring. Here's a summary...",
+  "background_tasks": [\
+    {\
+      "id": "task-001",\
+      "type": "shell",\
+      "status": "running",\
+      "description": "tail logs",\
+      "command": "tail -f /var/log/syslog"\
+    }\
+  ],
+  "session_crons": [\
+    {\
+      "id": "cron-001",\
+      "schedule": "0 9 * * 1-5",\
+      "recurring": true,\
+      "prompt": "check the build"\
+    }\
+  ]
+}
+```
+
+#### [​](https://code.claude.com/docs/en/hooks\#stop-decision-control)  Stop decision control
+
+`Stop` and `SubagentStop` hooks can control whether Claude continues. In addition to the [JSON output fields](https://code.claude.com/docs/en/hooks#json-output) available to all hooks, your hook script can return these event-specific fields:
+
+| Field | Description |
+| --- | --- |
+| `decision` | `"block"` prevents Claude from stopping. Omit to allow Claude to stop |
+| `reason` | Required when `decision` is `"block"`. Tells Claude why it should continue |
+| `hookSpecificOutput.additionalContext` | Non-error feedback for Claude. The conversation continues so Claude can act on it, but unlike `decision: "block"` it is shown in the transcript as hook feedback rather than a hook error |
+
+```
+{
+  "decision": "block",
+  "reason": "Must be provided when Claude is blocked from stopping"
+}
+```
+
+Use `additionalContext` when the hook is working as designed and giving Claude guidance, such as “run the test suite before finishing”. It keeps the conversation going through the same loop protections as `decision: "block"`, namely the `stop_hook_active` input and the 8-consecutive-continuation cap, but the transcript labels it `Stop hook feedback` and no hook error notification is shown:
+
+```
+{
+  "hookSpecificOutput": {
+    "hookEventName": "Stop",
+    "additionalContext": "Please run the test suite before finishing"
+  }
+}
+```
+
+### [​](https://code.claude.com/docs/en/hooks\#stopfailure)  StopFailure
+
+Runs instead of [Stop](https://code.claude.com/docs/en/hooks#stop) when the turn ends due to an API error. Output and exit code are ignored. Use this to log failures, send alerts, or take recovery actions when Claude can’t complete a response due to rate limits, authentication problems, or other API errors.
+
+#### [​](https://code.claude.com/docs/en/hooks\#stopfailure-input)  StopFailure input
+
+In addition to the [common input fields](https://code.claude.com/docs/en/hooks#common-input-fields), StopFailure hooks receive `error`, optional `error_details`, and optional `last_assistant_message`. The `error` field identifies the error type and is used for matcher filtering.
+
+| Field | Description |
+| --- | --- |
+| `error` | Error type: `rate_limit`, `overloaded`, `authentication_failed`, `oauth_org_not_allowed`, `billing_error`, `invalid_request`, `model_not_found`, `server_error`, `max_output_tokens`, or `unknown` |
+| `error_details` | Additional details about the error, when available |
+| `last_assistant_message` | The rendered error text shown in the conversation. Unlike `Stop` and `SubagentStop`, where this field holds Claude’s conversational output, for `StopFailure` it contains the API error string itself, such as `"API Error: Rate limit reached"` |
+
+```
+{
+  "session_id": "abc123",
+  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
+  "cwd": "/Users/...",
+  "hook_event_name": "StopFailure",
+  "error": "rate_limit",
+  "error_details": "429 Too Many Requests",
+  "last_assistant_message": "API Error: Rate limit reached"
+}
+```
+
+StopFailure hooks have no decision control. They run for notification and logging purposes only.
+
+### [​](https://code.claude.com/docs/en/hooks\#teammateidle)  TeammateIdle
+
+Runs when an [agent team](https://code.claude.com/docs/en/agent-teams) teammate is about to go idle after finishing its turn. Use this to enforce quality gates before a teammate stops working, such as requiring passing lint checks or verifying that output files exist.When a `TeammateIdle` hook exits with code 2, the teammate receives the stderr message as feedback and continues working instead of going idle. To stop the teammate entirely instead of re-running it, return JSON with `{"continue": false, "stopReason": "..."}`. TeammateIdle hooks don’t support matchers and fire on every occurrence.
+
+#### [​](https://code.claude.com/docs/en/hooks\#teammateidle-input)  TeammateIdle input
+
+In addition to the [common input fields](https://code.claude.com/docs/en/hooks#common-input-fields), TeammateIdle hooks receive `teammate_name` and `team_name`.
+
+```
+{
+  "session_id": "abc123",
+  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
+  "cwd": "/Users/...",
+  "permission_mode": "default",
+  "hook_event_name": "TeammateIdle",
+  "teammate_name": "researcher",
+  "team_name": "session-a1b2c3d4"
+}
+```
+
+| Field | Description |
+| --- | --- |
+| `teammate_name` | Name of the teammate that is about to go idle |
+| `team_name` | Deprecated. Session-derived team name; will be removed in a future release |
+
+#### [​](https://code.claude.com/docs/en/hooks\#teammateidle-decision-control)  TeammateIdle decision control
+
+TeammateIdle hooks support two ways to control teammate behavior:
+
+- **Exit code 2**: the teammate receives the stderr message as feedback and continues working instead of going idle.
+- **JSON `{"continue": false, "stopReason": "..."}`**: stops the teammate entirely, matching `Stop` hook behavior. The `stopReason` is shown to the user.
+
+This example checks that a build artifact exists before allowing a teammate to go idle:
+
+```
+#!/bin/bash
+
+if [ ! -f "./dist/output.js" ]; then
+  echo "Build artifact missing. Run the build before stopping." >&2
+  exit 2
+fi
+
+exit 0
+```
+
+### [​](https://code.claude.com/docs/en/hooks\#configchange)  ConfigChange
+
+Runs when a configuration file changes during a session. Use this to audit settings changes, enforce security policies, or block unauthorized modifications to configuration files.ConfigChange hooks fire for changes to settings files, managed policy settings, and skill files. The `source` field in the input tells you which type of configuration changed, and the optional `file_path` field provides the path to the changed file.The matcher filters on the configuration source:
+
+| Matcher | When it fires |
+| --- | --- |
+| `user_settings` | `~/.claude/settings.json` changes |
+| `project_settings` | `.claude/settings.json` changes |
+| `local_settings` | `.claude/settings.local.json` changes |
+| `policy_settings` | Managed policy settings change |
+| `skills` | A skill file in `.claude/skills/` changes |
+
+This example logs all configuration changes for security auditing:
+
+```
+{
+  "hooks": {
+    "ConfigChange": [\
+      {\
+        "hooks": [\
+          {\
+            "type": "command",\
+            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/audit-config-change.sh",\
+            "args": []\
+          }\
+        ]\
+      }\
+    ]
+  }
+}
+```
+
+#### [​](https://code.claude.com/docs/en/hooks\#configchange-input)  ConfigChange input
+
+In addition to the [common input fields](https://code.claude.com/docs/en/hooks#common-input-fields), ConfigChange hooks receive `source` and optionally `file_path`. The `source` field indicates which configuration type changed, and `file_path` provides the path to the specific file that was modified.
+
+```
+{
+  "session_id": "abc123",
+  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
+  "cwd": "/Users/...",
+  "hook_event_name": "ConfigChange",
+  "source": "project_settings",
+  "file_path": "/Users/.../my-project/.claude/settings.json"
+}
+```
+
+#### [​](https://code.claude.com/docs/en/hooks\#configchange-decision-control)  ConfigChange decision control
+
+ConfigChange hooks can block configuration changes from taking effect. Use exit code 2 or a JSON `decision` to prevent the change. When blocked, the new settings are not applied to the running session.
+
+| Field | Description |
+| --- | --- |
+| `decision` | `"block"` prevents the configuration change from being applied. Omit to allow the change |
+| `reason` | Explanation shown to the user when `decision` is `"block"` |
+
+```
+{
+  "decision": "block",
+  "reason": "Configuration changes to project settings require admin approval"
+}
+```
+
+`policy_settings` changes can’t be blocked. Hooks still fire for `policy_settings` sources, so you can use them for audit logging, but any blocking decision is ignored. This ensures enterprise-managed settings always take effect.
+
+### [​](https://code.claude.com/docs/en/hooks\#cwdchanged)  CwdChanged
+
+Runs when the working directory changes during a session, for example when Claude executes a `cd` command. Use this to react to directory changes: reload environment variables, activate project-specific toolchains, or run setup scripts automatically. Pairs with [FileChanged](https://code.claude.com/docs/en/hooks#filechanged) for tools like [direnv](https://direnv.net/) that manage per-directory environment.CwdChanged hooks have access to `CLAUDE_ENV_FILE`. Variables written to that file persist into subsequent Bash commands for the session, just as in [SessionStart hooks](https://code.claude.com/docs/en/hooks#persist-environment-variables).CwdChanged doesn’t support matchers and fires on every directory change.
+
+#### [​](https://code.claude.com/docs/en/hooks\#cwdchanged-input)  CwdChanged input
+
+In addition to the [common input fields](https://code.claude.com/docs/en/hooks#common-input-fields), CwdChanged hooks receive `old_cwd` and `new_cwd`.
+
+```
+{
+  "session_id": "abc123",
+  "transcript_path": "/Users/.../.claude/projects/.../transcript.jsonl",
+  "cwd": "/Users/my-project/src",
+  "hook_event_name": "CwdChanged",
+  "old_cwd": "/Users/my-project",
+  "new_cwd": "/Users/my-project/src"
+}
+```
+
+#### [​](https://code.claude.com/docs/en/hooks\#cwdchanged-output)  CwdChanged output
+
+In addition to the [JSON output fields](https://code.claude.com/docs/en/hooks#json-output) available to all hooks, CwdChanged hooks can return `watchPaths` to dynamically set which file paths [FileChanged](https://code.claude.com/docs/en/hooks#filechanged) watches:
+
+| Field | Description |
+| --- | --- |
+| `watchPaths` | Array of absolute paths. Replaces the current dynamic watch list. Paths from your `matcher` configuration are always watched. Returning an empty array clears the dynamic list, which is typical when entering a new directory |
+
+CwdChanged hooks have no decision control. They can’t block the directory change.
+
+### [​](https://code.claude.com/docs/en/hooks\#filechanged)  FileChanged
+
+Runs when a watched file changes on disk. Useful for reloading environment variables when project configuration files are modified.The `matcher` for this event serves two roles:
+
+- **Build the watch list**: the value is split on `|` and each segment is registered as a literal filename in the working directory, so `".envrc|.env"` watches exactly those two files. Regex patterns are not useful here: a value like `^\.env` would watch a file literally named `^\.env`.
+- **Filter which hooks run**: when a watched file changes, the same value filters which hook groups run using the standard [matcher rules](https://code.claude.com/docs/en/hooks#matcher-patterns) against the changed file’s basename.
+
+FileChanged hooks have access to `CLAUDE_ENV_FILE`. Variables written to that file persist into subsequent Bash commands for the session, just as in [SessionStart hooks](https://code.claude.com/docs/en/hooks#persist-environment-variables).
+
+#### [​](https://code.claude.com/docs/en/hooks\#filechanged-input)  FileChanged input
+
+In addition to the [common input fields](https://code.claude.com/docs/en/hooks#common-input-fields), FileChanged hooks receive `file_path` and `event`.
+
+| Field | Description |
+| --- | --- |
+| `file_path` | Absolute path to the file that changed |
+| `event` | What happened: `"change"` for a modified file, `"add"` for a created file, or `"unlink"` for a deleted file |
+
+```
+{
+  "session_id": "abc123",
+  "transcript_path": "/Users/.../.claude/projects/.../transcript.jsonl",
+  "cwd": "/Users/my-project",
+  "hook_event_name": "FileChanged",
+  "file_path": "/Users/my-project/.envrc",
+  "event": "change"
+}
+```
+
+#### [​](https://code.claude.com/docs/en/hooks\#filechanged-output)  FileChanged output
+
+In addition to the [JSON output fields](https://code.claude.com/docs/en/hooks#json-output) available to all hooks, FileChanged hooks can return `watchPaths` to dynamically update which file paths are watched:
+
+| Field | Description |
+| --- | --- |
+| `watchPaths` | Array of absolute paths. Replaces the current dynamic watch list. Paths from your `matcher` configuration are always watched. Use this when your hook script discovers additional files to watch based on the changed file |
+
+FileChanged hooks have no decision control. They can’t block the file change from occurring.
+
+### [​](https://code.claude.com/docs/en/hooks\#worktreecreate)  WorktreeCreate
+
+Runs when a worktree is being created, either from `claude --worktree` or from a [subagent using `isolation: "worktree"`](https://code.claude.com/docs/en/sub-agents#choose-the-subagent-scope). By default Claude Code creates the isolated working copy with `git worktree`. Configuring a WorktreeCreate hook replaces that default git behavior, letting you use a different version control system like SVN, Perforce, or Mercurial.Because the hook replaces the default behavior entirely, [`.worktreeinclude`](https://code.claude.com/docs/en/worktrees#copy-gitignored-files-into-worktrees) is not processed. If you need to copy local configuration files like `.env` into the new worktree, do it inside your hook script.The hook must return the path to the created worktree directory. Claude Code uses this path as the working directory for the isolated session. See [WorktreeCreate output](https://code.claude.com/docs/en/hooks#worktreecreate-output) for how each hook type returns the path.This example creates an SVN working copy and prints the path for Claude Code to use. Replace the repository URL with your own:
+
+```
+{
+  "hooks": {
+    "WorktreeCreate": [\
+      {\
+        "hooks": [\
+          {\
+            "type": "command",\
+            "command": "bash -c 'NAME=$(jq -r .name); DIR=\"$HOME/.claude/worktrees/$NAME\"; svn checkout https://svn.example.com/repo/trunk \"$DIR\" >&2 && echo \"$DIR\"'"\
+          }\
+        ]\
+      }\
+    ]
+  }
+}
+```
+
+The hook reads the worktree `name` from the JSON input on stdin, checks out a fresh copy into a new directory, and prints the directory path. The `echo` on the last line is what Claude Code reads as the worktree path. Redirect any other output to stderr so it doesn’t interfere with the path.
+
+#### [​](https://code.claude.com/docs/en/hooks\#worktreecreate-input)  WorktreeCreate input
+
+In addition to the [common input fields](https://code.claude.com/docs/en/hooks#common-input-fields), WorktreeCreate hooks receive the `name` field. This is a slug identifier for the new worktree, either specified by the user or auto-generated, for example `bold-oak-a3f2`.
+
+```
+{
+  "session_id": "abc123",
+  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
+  "cwd": "/Users/...",
+  "hook_event_name": "WorktreeCreate",
+  "name": "feature-auth"
+}
+```
+
+#### [​](https://code.claude.com/docs/en/hooks\#worktreecreate-output)  WorktreeCreate output
+
+WorktreeCreate hooks don’t use the standard allow/block decision model. Instead, the hook’s success or failure determines the outcome. The hook must return the path to the created worktree directory:
+
+- **Command hooks** (`type: "command"`): print the path as the last non-empty line of stdout. Claude Code strips ANSI escape codes before reading that line, so shell startup banners printed before your `echo` are ignored. Redirect any other hook output to stderr.
+- **HTTP hooks** (`type: "http"`): return `{ "hookSpecificOutput": { "hookEventName": "WorktreeCreate", "worktreePath": "/absolute/path" } }` in the response body.
+
+If the hook fails or produces no path, worktree creation fails with an error.Claude Code resolves a relative path against the directory the hook ran in. If the resulting path isn’t a directory Claude Code can enter, the session prints an error naming the path and exits with code 1. Before v2.1.205, a relative path or a path that didn’t exist on disk crashed the session at startup, and with `-p` it stalled for about 30 seconds before exiting with code 0.
+
+### [​](https://code.claude.com/docs/en/hooks\#worktreeremove)  WorktreeRemove
+
+Runs when a worktree is being removed, either when you exit a `--worktree` session and choose to remove it, or when a subagent with `isolation: "worktree"` finishes. This is the cleanup counterpart to [WorktreeCreate](https://code.claude.com/docs/en/hooks#worktreecreate).For git-based worktrees, Claude Code handles cleanup automatically with `git worktree remove`. If you configured a WorktreeCreate hook for a non-git version control system, pair it with a WorktreeRemove hook to handle cleanup. Without one, the worktree directory is left on disk.Claude Code passes the path returned by WorktreeCreate as `worktree_path` in the hook input. This example reads that path and removes the directory:
+
+```
+{
+  "hooks": {
+    "WorktreeRemove": [\
+      {\
+        "hooks": [\
+          {\
+            "type": "command",\
+            "command": "bash -c 'jq -r .worktree_path | xargs rm -rf'"\
+          }\
+        ]\
+      }\
+    ]
+  }
+}
+```
+
+#### [​](https://code.claude.com/docs/en/hooks\#worktreeremove-input)  WorktreeRemove input
+
+In addition to the [common input fields](https://code.claude.com/docs/en/hooks#common-input-fields), WorktreeRemove hooks receive the `worktree_path` field, which is the absolute path to the worktree being removed.
+
+```
+{
+  "session_id": "abc123",
+  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
+  "cwd": "/Users/...",
+  "hook_event_name": "WorktreeRemove",
+  "worktree_path": "/Users/.../my-project/.claude/worktrees/feature-auth"
+}
+```
+
+WorktreeRemove hooks have no decision control. They can’t block worktree removal but can perform cleanup tasks like removing version control state or archiving changes. Hook failures are logged in debug mode only.
+
+### [​](https://code.claude.com/docs/en/hooks\#precompact)  PreCompact
+
+Runs before Claude Code is about to run a compact operation.The matcher value indicates whether compaction was triggered manually or automatically:
+
+| Matcher | When it fires |
+| --- | --- |
+| `manual` | `/compact` |
+| `auto` | Auto-compact when the context window is full |
+
+Exit with code 2 to block compaction. For a manual `/compact`, the stderr message is shown to the user. You can also block by returning JSON with `"decision": "block"`.Blocking automatic compaction has different effects depending on when it fires. If compaction was triggered proactively before the context limit, Claude Code skips it and the conversation continues uncompacted. If compaction was triggered to recover from a context-limit error already returned by the API, the underlying error surfaces and the current request fails.
+
+#### [​](https://code.claude.com/docs/en/hooks\#precompact-input)  PreCompact input
+
+In addition to the [common input fields](https://code.claude.com/docs/en/hooks#common-input-fields), PreCompact hooks receive `trigger` and `custom_instructions`. For `manual`, `custom_instructions` contains what the user passes into `/compact`. For `auto`, `custom_instructions` is empty.
+
+```
+{
+  "session_id": "abc123",
+  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
+  "cwd": "/Users/...",
+  "hook_event_name": "PreCompact",
+  "trigger": "manual",
+  "custom_instructions": ""
+}
+```
+
+### [​](https://code.claude.com/docs/en/hooks\#postcompact)  PostCompact
+
+Runs after Claude Code completes a compact operation. Use this event to react to the new compacted state, for example to log the generated summary or update external state.The same matcher values apply as for `PreCompact`:
+
+| Matcher | When it fires |
+| --- | --- |
+| `manual` | After `/compact` |
+| `auto` | After auto-compact when the context window is full |
+
+#### [​](https://code.claude.com/docs/en/hooks\#postcompact-input)  PostCompact input
+
+In addition to the [common input fields](https://code.claude.com/docs/en/hooks#common-input-fields), PostCompact hooks receive `trigger` and `compact_summary`. The `compact_summary` field contains the conversation summary generated by the compact operation.
+
+```
+{
+  "session_id": "abc123",
+  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
+  "cwd": "/Users/...",
+  "hook_event_name": "PostCompact",
+  "trigger": "manual",
+  "compact_summary": "Summary of the compacted conversation..."
+}
+```
+
+PostCompact hooks have no decision control. They can’t affect the compaction result but can perform follow-up tasks.
+
+### [​](https://code.claude.com/docs/en/hooks\#sessionend)  SessionEnd
+
+Runs when a Claude Code session ends. Useful for cleanup tasks, logging session
+statistics, or saving session state. Supports matchers to filter by exit reason.The `reason` field in the hook input indicates why the session ended:
+
+| Reason | Description |
+| --- | --- |
+| `clear` | Session cleared with `/clear` command |
+| `resume` | Session switched via interactive `/resume` |
+| `logout` | User logged out |
+| `prompt_input_exit` | User exited while prompt input was visible |
+| `bypass_permissions_disabled` | Bypass permissions mode was disabled |
+| `other` | Other exit reasons |
+
+#### [​](https://code.claude.com/docs/en/hooks\#sessionend-input)  SessionEnd input
+
+In addition to the [common input fields](https://code.claude.com/docs/en/hooks#common-input-fields), SessionEnd hooks receive a `reason` field indicating why the session ended. See the [reason table](https://code.claude.com/docs/en/hooks#sessionend) above for all values.
+
+```
+{
+  "session_id": "abc123",
+  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
+  "cwd": "/Users/...",
+  "hook_event_name": "SessionEnd",
+  "reason": "other"
+}
+```
+
+SessionEnd hooks have no decision control. They can’t block session termination but can perform cleanup tasks.SessionEnd hooks have a default timeout of 1.5 seconds. This applies to session exit, `/clear`, and switching sessions via interactive `/resume`. If a hook needs more time, set a per-hook `timeout` in the hook configuration. The overall budget is automatically raised to the highest per-hook timeout configured in settings files, up to 60 seconds. Timeouts set on plugin-provided hooks don’t raise the budget. To override the budget explicitly, set the `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` environment variable in milliseconds.
+
+```
+CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS=5000 claude
+```
+
+### [​](https://code.claude.com/docs/en/hooks\#elicitation)  Elicitation
+
+Runs when an MCP server requests user input mid-task. By default, Claude Code shows an interactive dialog for the user to respond. Hooks can intercept this request and respond programmatically, skipping the dialog entirely.The matcher field matches against the MCP server name.
+
+#### [​](https://code.claude.com/docs/en/hooks\#elicitation-input)  Elicitation input
+
+In addition to the [common input fields](https://code.claude.com/docs/en/hooks#common-input-fields), Elicitation hooks receive `mcp_server_name`, `message`, and optional `mode`, `url`, `elicitation_id`, and `requested_schema` fields.For form-mode elicitation, the most common case:
+
+```
+{
+  "session_id": "abc123",
+  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
+  "cwd": "/Users/...",
+  "permission_mode": "default",
+  "hook_event_name": "Elicitation",
+  "mcp_server_name": "my-mcp-server",
+  "message": "Please provide your credentials",
+  "mode": "form",
+  "requested_schema": {
+    "type": "object",
+    "properties": {
+      "username": { "type": "string", "title": "Username" }
+    }
+  }
+}
+```
+
+For URL-mode elicitation, used for browser-based authentication:
+
+```
+{
+  "session_id": "abc123",
+  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
+  "cwd": "/Users/...",
+  "permission_mode": "default",
+  "hook_event_name": "Elicitation",
+  "mcp_server_name": "my-mcp-server",
+  "message": "Please authenticate",
+  "mode": "url",
+  "url": "https://auth.example.com/login"
+}
+```
+
+#### [​](https://code.claude.com/docs/en/hooks\#elicitation-output)  Elicitation output
+
+To respond programmatically without showing the dialog, return a JSON object with `hookSpecificOutput`:
+
+```
+{
+  "hookSpecificOutput": {
+    "hookEventName": "Elicitation",
+    "action": "accept",
+    "content": {
+      "username": "alice"
+    }
+  }
+}
+```
+
+| Field | Values | Description |
+| --- | --- | --- |
+| `action` | `accept`, `decline`, `cancel` | Whether to accept, decline, or cancel the request |
+| `content` | object | Form field values to submit. Only used when `action` is `accept` |
+
+Exit code 2 denies the elicitation and shows stderr to the user.
+
+### [​](https://code.claude.com/docs/en/hooks\#elicitationresult)  ElicitationResult
+
+Runs after a user responds to an MCP elicitation. Hooks can observe, modify, or block the response before it is sent back to the MCP server.The matcher field matches against the MCP server name.
+
+#### [​](https://code.claude.com/docs/en/hooks\#elicitationresult-input)  ElicitationResult input
+
+In addition to the [common input fields](https://code.claude.com/docs/en/hooks#common-input-fields), ElicitationResult hooks receive `mcp_server_name`, `action`, and optional `mode`, `elicitation_id`, and `content` fields.
+
+```
+{
+  "session_id": "abc123",
+  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
+  "cwd": "/Users/...",
+  "permission_mode": "default",
+  "hook_event_name": "ElicitationResult",
+  "mcp_server_name": "my-mcp-server",
+  "action": "accept",
+  "content": { "username": "alice" },
+  "mode": "form",
+  "elicitation_id": "elicit-123"
+}
+```
+
+#### [​](https://code.claude.com/docs/en/hooks\#elicitationresult-output)  ElicitationResult output
+
+To override the user’s response, return a JSON object with `hookSpecificOutput`:
+
+```
+{
+  "hookSpecificOutput": {
+    "hookEventName": "ElicitationResult",
+    "action": "decline",
+    "content": {}
+  }
+}
+```
+
+| Field | Values | Description |
+| --- | --- | --- |
+| `action` | `accept`, `decline`, `cancel` | Overrides the user’s action |
+| `content` | object | Overrides form field values. Only meaningful when `action` is `accept` |
+
+Exit code 2 blocks the response, changing the effective action to `decline`.
+
+## [​](https://code.claude.com/docs/en/hooks\#prompt-based-hooks)  Prompt-based hooks
+
+In addition to command, HTTP, and MCP tool hooks, Claude Code supports prompt-based hooks (`type: "prompt"`) that use an LLM to evaluate whether to allow or block an action, and agent hooks (`type: "agent"`) that spawn an agentic verifier with tool access. Not all events support every hook type.Events that support all five hook types (`command`, `http`, `mcp_tool`, `prompt`, and `agent`):
+
+- `PermissionDenied`
+- `PermissionRequest`
+- `PostToolBatch`
+- `PostToolUse`
+- `PostToolUseFailure`
+- `PreToolUse`
+- `Stop`
+- `SubagentStop`
+- `TaskCompleted`
+- `TaskCreated`
+- `TeammateIdle`
+- `UserPromptExpansion`
+- `UserPromptSubmit`
+
+Events that support `command`, `http`, and `mcp_tool` hooks but not `prompt` or `agent`:
+
+- `ConfigChange`
+- `CwdChanged`
+- `Elicitation`
+- `ElicitationResult`
+- `FileChanged`
+- `InstructionsLoaded`
+- `Notification`
+- `PostCompact`
+- `PreCompact`
+- `SessionEnd`
+- `StopFailure`
+- `SubagentStart`
+- `WorktreeCreate`
+- `WorktreeRemove`
+
+`SessionStart` and `Setup` support `command` and `mcp_tool` hooks. They don’t support `http`, `prompt`, or `agent` hooks.
+
+### [​](https://code.claude.com/docs/en/hooks\#how-prompt-based-hooks-work)  How prompt-based hooks work
+
+Instead of executing a Bash command, prompt-based hooks:
+
+1. Send the hook input and your prompt to a Claude model, Haiku by default
+2. The LLM responds with structured JSON containing a decision
+3. Claude Code processes the decision automatically
+
+### [​](https://code.claude.com/docs/en/hooks\#prompt-hook-configuration)  Prompt hook configuration
+
+Set `type` to `"prompt"` and provide a `prompt` string instead of a `command`. Use the `$ARGUMENTS` placeholder to inject the hook’s JSON input data into your prompt text. Claude Code sends the combined prompt and input to a fast Claude model, which returns a JSON decision.This `Stop` hook asks the LLM to evaluate whether all tasks are complete before allowing Claude to finish:
+
+```
+{
+  "hooks": {
+    "Stop": [\
+      {\
+        "hooks": [\
+          {\
+            "type": "prompt",\
+            "prompt": "Evaluate if Claude should stop: $ARGUMENTS. Check if all tasks are complete."\
+          }\
+        ]\
+      }\
+    ]
+  }
+}
+```
+
+| Field | Required | Description |
+| --- | --- | --- |
+| `type` | yes | Must be `"prompt"` |
+| `prompt` | yes | The prompt text to send to the LLM. Use `$ARGUMENTS` as a placeholder for the hook input JSON. If `$ARGUMENTS` is not present, input JSON is appended to the prompt |
+| `model` | no | Model to use for evaluation. Defaults to a fast model |
+| `timeout` | no | Timeout in seconds. Default: 30 |
+| `continueOnBlock` | no | When the prompt returns `ok: false`, feed the reason back to Claude and continue the turn instead of stopping. Default: `false`. Implemented as `continue: true` on the resulting `decision: "block"`. See [Response schema](https://code.claude.com/docs/en/hooks#response-schema) for per-event behavior |
+
+### [​](https://code.claude.com/docs/en/hooks\#response-schema)  Response schema
+
+The LLM must respond with JSON containing:
+
+```
+{
+  "ok": true | false,
+  "reason": "Explanation for the decision"
+}
+```
+
+| Field | Description |
+| --- | --- |
+| `ok` | `true` to allow. `false` produces a `decision: "block"`. See the per-event behavior below |
+| `reason` | Required when `ok` is `false`. Used as the block reason |
+
+What happens on `ok: false` depends on the event:
+
+- `Stop` and `SubagentStop`: the reason is fed back to Claude as its next instruction and the turn continues
+- `PreToolUse`: the tool call is denied and the reason is returned to Claude as the tool error, equivalent to a command hook’s `permissionDecision: "deny"`
+- `PostToolUse`: by default the turn ends and the reason appears in the chat as a warning line. Set `continueOnBlock: true` to feed the reason back to Claude and continue the turn instead
+- `PostToolBatch`, `UserPromptSubmit`, and `UserPromptExpansion`: the turn ends and the reason appears as a warning line. These events end the turn on `decision: "block"` regardless of `continue`
+- `PostToolUseFailure`, `TaskCreated`, and `TaskCompleted`: the reason is returned to Claude as a tool error, similar to `PreToolUse`
+- `TeammateIdle`: by default the teammate stops and the reason appears as a warning line. Set `continueOnBlock: true` to feed the reason back to the teammate and keep it working instead
+- `PermissionRequest`: `ok: false` has no effect. To deny an approval from a hook, use a [command hook](https://code.claude.com/docs/en/hooks#command-hook-fields) returning `hookSpecificOutput.decision.behavior: "deny"`
+- `PermissionDenied`: `ok: false` has no effect because the denial already happened. The only output this event reads is `hookSpecificOutput.retry`, which prompt and agent hooks can’t set. They run on this event, but their output is discarded. Use a [command hook](https://code.claude.com/docs/en/hooks#command-hook-fields) to return `retry`
+
+If you need finer control on any event, use a [command hook](https://code.claude.com/docs/en/hooks#command-hook-fields) with the per-event fields described in [Decision control](https://code.claude.com/docs/en/hooks#decision-control).
+
+### [​](https://code.claude.com/docs/en/hooks\#check-multiple-conditions-before-stopping)  Check multiple conditions before stopping
+
+This `Stop` hook uses a detailed prompt to check three conditions before allowing Claude to stop. `SubagentStop` hooks use the same format to evaluate whether a [subagent](https://code.claude.com/docs/en/sub-agents) should stop. If `"ok"` is `false`, Claude continues working with the provided reason as its next instruction:
+
+```
+{
+  "hooks": {
+    "Stop": [\
+      {\
+        "hooks": [\
+          {\
+            "type": "prompt",\
+            "prompt": "You are evaluating whether Claude should stop working. Context: $ARGUMENTS\n\nAnalyze the conversation and determine if:\n1. All user-requested tasks are complete\n2. Any errors need to be addressed\n3. Follow-up work is needed\n\nRespond with JSON: {\"ok\": true} to allow stopping, or {\"ok\": false, \"reason\": \"your explanation\"} to continue working.",\
+            "timeout": 30\
+          }\
+        ]\
+      }\
+    ]
+  }
+}
+```
+
+## [​](https://code.claude.com/docs/en/hooks\#agent-based-hooks)  Agent-based hooks
+
+Agent hooks are experimental. Behavior and configuration may change in future releases. For production workflows, prefer [command hooks](https://code.claude.com/docs/en/hooks#command-hook-fields).
+
+Agent-based hooks (`type: "agent"`) are like prompt-based hooks but with multi-turn tool access. Instead of a single LLM call, an agent hook spawns a subagent that can read files, search code, and inspect the codebase to verify conditions. Agent hooks support the same events as prompt-based hooks.
+
+### [​](https://code.claude.com/docs/en/hooks\#how-agent-hooks-work)  How agent hooks work
+
+When an agent hook fires:
+
+1. Claude Code spawns a subagent with your prompt and the hook’s JSON input
+2. The subagent can use tools like Read, Grep, and Glob to investigate
+3. After up to 50 turns, the subagent returns a structured `{ "ok": true/false }` decision
+4. Claude Code processes the decision the same way as a prompt hook
+
+Agent hooks are useful when verification requires inspecting actual files or test output, not just evaluating the hook input data alone.
+
+### [​](https://code.claude.com/docs/en/hooks\#agent-hook-configuration)  Agent hook configuration
+
+Set `type` to `"agent"` and provide a `prompt` string. The configuration fields are the same as [prompt hooks](https://code.claude.com/docs/en/hooks#prompt-hook-configuration), with a longer default timeout:
+
+| Field | Required | Description |
+| --- | --- | --- |
+| `type` | yes | Must be `"agent"` |
+| `prompt` | yes | Prompt describing what to verify. Use `$ARGUMENTS` as a placeholder for the hook input JSON |
+| `model` | no | Model to use. Defaults to a fast model |
+| `timeout` | no | Timeout in seconds. Default: 60 |
+
+The response schema is the same as prompt hooks: `{ "ok": true }` to allow or `{ "ok": false, "reason": "..." }` to block.This `Stop` hook verifies that all unit tests pass before allowing Claude to finish:
+
+```
+{
+  "hooks": {
+    "Stop": [\
+      {\
+        "hooks": [\
+          {\
+            "type": "agent",\
+            "prompt": "Verify that all unit tests pass. Run the test suite and check the results. $ARGUMENTS",\
+            "timeout": 120\
+          }\
+        ]\
+      }\
+    ]
+  }
+}
+```
+
+## [​](https://code.claude.com/docs/en/hooks\#run-hooks-in-the-background)  Run hooks in the background
+
+By default, hooks block Claude’s execution until they complete. For long-running tasks like deployments, test suites, or external API calls, set `"async": true` to run the hook in the background while Claude continues working. Async hooks can’t block or control Claude’s behavior: response fields like `decision`, `permissionDecision`, and `continue` have no effect, because the action they would have controlled has already completed.
+
+### [​](https://code.claude.com/docs/en/hooks\#configure-an-async-hook)  Configure an async hook
+
+Add `"async": true` to a command hook’s configuration to run it in the background without blocking Claude. This field is only available on `type: "command"` hooks.This hook runs a test script after every `Write` tool call. Claude continues working immediately while `run-tests.sh` executes for up to 120 seconds. When the script finishes, its output is delivered on the next conversation turn:
+
+```
+{
+  "hooks": {
+    "PostToolUse": [\
+      {\
+        "matcher": "Write",\
+        "hooks": [\
+          {\
+            "type": "command",\
+            "command": "/path/to/run-tests.sh",\
+            "async": true,\
+            "timeout": 120\
+          }\
+        ]\
+      }\
+    ]
+  }
+}
+```
+
+The `timeout` field sets the maximum time in seconds for the background process. If not specified, async hooks use the same 10-minute default as sync hooks.
+
+### [​](https://code.claude.com/docs/en/hooks\#how-async-hooks-execute)  How async hooks execute
+
+When an async hook fires, Claude Code starts the hook process and immediately continues without waiting for it to finish. The hook receives the same JSON input via stdin as a synchronous hook.After the background process exits, if the hook produced a JSON response with an `additionalContext` field, that content is delivered to Claude as context on the next conversation turn. A `systemMessage` field is shown to you, not to Claude.Claude Code validates that JSON response against the same [output schema](https://code.claude.com/docs/en/hooks#json-output) as synchronous hooks, and drops any field whose value has the wrong type, such as a `systemMessage` that isn’t a string, instead of delivering it. Run with `--debug` to see a warning naming each dropped field. Before v2.1.202, malformed JSON output from an async hook could crash the session, and the crash recurred each time the session was resumed.Async hook completion notifications are suppressed by default. To see them, enable verbose mode with `Ctrl+O` or start Claude Code with `--verbose`.
+
+### [​](https://code.claude.com/docs/en/hooks\#run-tests-after-file-changes)  Run tests after file changes
+
+This hook starts a test suite in the background whenever Claude writes a file, then reports the results back to Claude when the tests finish. Save this script to `.claude/hooks/run-tests-async.sh` in your project and make it executable with `chmod +x`:
+
+```
+#!/bin/bash
+# run-tests-async.sh
+
+# Read hook input from stdin
+INPUT=$(cat)
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+
+# Only run tests for source files
+if [[ "$FILE_PATH" != *.ts && "$FILE_PATH" != *.js ]]; then
+  exit 0
+fi
+
+# Run tests and report results to Claude via additionalContext
+RESULT=$(npm test 2>&1)
+EXIT_CODE=$?
+
+if [ $EXIT_CODE -eq 0 ]; then
+  MSG="Tests passed after editing $FILE_PATH"
+else
+  MSG="Tests failed after editing $FILE_PATH: $RESULT"
+fi
+jq -nc --arg msg "$MSG" '{hookSpecificOutput: {hookEventName: "PostToolUse", additionalContext: $msg}}'
+```
+
+Then add this configuration to `.claude/settings.json` in your project root. The `async: true` flag lets Claude keep working while tests run:
+
+```
+{
+  "hooks": {
+    "PostToolUse": [\
+      {\
+        "matcher": "Write|Edit",\
+        "hooks": [\
+          {\
+            "type": "command",\
+            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/run-tests-async.sh",\
+            "args": [],\
+            "async": true,\
+            "timeout": 300\
+          }\
+        ]\
+      }\
+    ]
+  }
+}
+```
+
+### [​](https://code.claude.com/docs/en/hooks\#limitations)  Limitations
+
+Async hooks have several constraints compared to synchronous hooks:
+
+- Only `type: "command"` hooks support `async`. Prompt-based hooks can’t run asynchronously.
+- Async hooks can’t block tool calls or return decisions. By the time the hook completes, the triggering action has already proceeded.
+- Hook output is delivered on the next conversation turn. If the session is idle, the response waits until the next user interaction. Exception: an `asyncRewake` hook that exits with code 2 wakes Claude immediately even when the session is idle.
+- Each execution creates a separate background process. There is no deduplication across multiple firings of the same async hook.
+
+## [​](https://code.claude.com/docs/en/hooks\#security-considerations)  Security considerations
+
+### [​](https://code.claude.com/docs/en/hooks\#disclaimer)  Disclaimer
+
+Command hooks run with your system user’s full permissions.
+
+Command hooks execute shell commands with your full user permissions. They can modify, delete, or access any files your user account can access. Review and test all hook commands before adding them to your configuration.
+
+### [​](https://code.claude.com/docs/en/hooks\#security-best-practices)  Security best practices
+
+Keep these practices in mind when writing hooks:
+
+- **Validate and sanitize inputs**: never trust input data blindly
+- **Always quote shell variables**: use `"$VAR"` not `$VAR`
+- **Block path traversal**: check for `..` in file paths
+- **Use absolute paths**: specify full paths for scripts. In exec form, use `${CLAUDE_PROJECT_DIR}` and the path needs no quoting. In shell form, wrap it in double quotes
+- **Skip sensitive files**: avoid `.env`, `.git/`, keys, etc.
+
+## [​](https://code.claude.com/docs/en/hooks\#windows-powershell-tool)  Windows PowerShell tool
+
+On Windows, you can run individual hooks in PowerShell by setting `"shell": "powershell"` on a command hook. Hooks spawn PowerShell directly, so this works regardless of whether `CLAUDE_CODE_USE_POWERSHELL_TOOL` is set. Claude Code auto-detects `pwsh.exe`, the PowerShell 7 and later executable, and falls back to `powershell.exe` for Windows PowerShell 5.1.
+
+```
+{
+  "hooks": {
+    "PostToolUse": [\
+      {\
+        "matcher": "Write",\
+        "hooks": [\
+          {\
+            "type": "command",\
+            "shell": "powershell",\
+            "command": "Write-Host 'File written'"\
+          }\
+        ]\
+      }\
+    ]
+  }
+}
+```
+
+To reference the project root from a PowerShell shell-form command, write `${CLAUDE_PROJECT_DIR}` or `$env:CLAUDE_PROJECT_DIR`. As of v2.1.198, Claude Code rewrites the `${CLAUDE_PROJECT_DIR}`, `${CLAUDE_PLUGIN_ROOT}`, and `${CLAUDE_PLUGIN_DATA}` placeholders in a PowerShell shell-form command to PowerShell’s `${env:NAME}` form, whether the hook is defined in `settings.json`, a plugin, or a skill. PowerShell then resolves the value from the exported environment after parsing, so the placeholder works inside double-quoted strings but not inside single-quoted strings, where PowerShell never expands variables.Before v2.1.198, this rewrite applied only to plugin hooks. On earlier versions, a `settings.json` hook needs the `$env:` form or [exec form](https://code.claude.com/docs/en/hooks#exec-form-and-shell-form), where `${CLAUDE_PROJECT_DIR}` is substituted in each `args` element regardless of where the hook is defined.Don’t write the bare `$CLAUDE_PROJECT_DIR` spelling in a PowerShell hook. PowerShell parses it as an undefined local variable and resolves it to `$null`, which leaves the script path without its project-root prefix. Claude Code doesn’t rewrite that form; it logs a warning in the [debug log](https://code.claude.com/docs/en/hooks#debug-hooks) instead.The example below shows a `settings.json` hook that runs a project script with the `$env:` form, which works on every version:
+
+```
+{
+  "type": "command",
+  "shell": "powershell",
+  "command": "& \"$env:CLAUDE_PROJECT_DIR\\.claude\\hooks\\check.ps1\""
+}
+```
+
+## [​](https://code.claude.com/docs/en/hooks\#debug-hooks)  Debug hooks
+
+Hook execution details, including which hooks matched, their exit codes, and full stdout and stderr, are written to the debug log file. Start Claude Code with `claude --debug-file <path>` to write the log to a known location, or run `claude --debug` and read the log at `~/.claude/debug/<session-id>.txt`. The `--debug` flag doesn’t print to the terminal.
+
+```
+[DEBUG] Executing hooks for PostToolUse:Write
+[DEBUG] Found 1 hook commands to execute
+[DEBUG] Executing hook command: <Your command> with timeout 600000ms
+[DEBUG] Hook command completed with status 0: <Your stdout>
+```
+
+For more granular hook matching details, set `CLAUDE_CODE_DEBUG_LOG_LEVEL=verbose` to see additional log lines such as hook matcher counts and query matching.For troubleshooting common issues like hooks not firing, Stop hooks that keep blocking, or configuration errors, see [Limitations and troubleshooting](https://code.claude.com/docs/en/hooks-guide#limitations-and-troubleshooting) in the guide. For a broader diagnostic walkthrough covering `/context`, `/doctor`, and settings precedence, see [Debug your config](https://code.claude.com/docs/en/debug-your-config).
+
+Was this page helpful?
 
 YesNo
 
@@ -1307,4 +2855,8 @@ Ctrl+I
 
 Assistant
 
-Responses are generated using AI and may contain mistakes.
+Responses are generated using AI and may contain mistakes.
+
+![Hook lifecycle diagram showing optional Setup feeding into SessionStart, then a per-turn loop containing UserPromptSubmit, UserPromptExpansion for slash commands, the nested agentic loop (PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure, PostToolBatch, SubagentStart/Stop, TaskCreated, TaskCompleted), and Stop or StopFailure, followed by TeammateIdle, PreCompact, PostCompact, and SessionEnd, with Elicitation and ElicitationResult nested inside MCP tool execution, PermissionDenied as a side branch from PermissionRequest for auto-mode denials, WorktreeCreate, WorktreeRemove, Notification, ConfigChange, InstructionsLoaded, CwdChanged, and FileChanged as standalone async events, and MessageDisplay as a display-only event that runs while assistant message text streams](https://mintcdn.com/claude-code/uLsR38F1U_5zPppm/images/hooks-lifecycle.svg?w=1100&fit=max&auto=format&n=uLsR38F1U_5zPppm&q=85&s=3fab734aa1c51acc4b37a49d9019d182)
+
+![Diagram of hook resolution: PreToolUse fires, the matcher checks for a Bash match, then the if condition checks for a Bash(rm *) match. If both match, the hook command runs and returns permissionDecision deny, so the tool call is blocked and Claude Code continues. If either check fails to match, the hook is skipped and the tool call is allowed to proceed.](https://mintcdn.com/claude-code/ikqp3_70mqIahteV/images/hook-resolution.svg?w=1100&fit=max&auto=format&n=ikqp3_70mqIahteV&q=85&s=12622bb46f39fae9e28e994c0e778399)