1> ## Documentation Index
2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
3> Use this file to discover all available pages before exploring further.
4
1# Hooks reference5# Hooks reference
2 6
3> This page provides reference documentation for implementing hooks in Claude Code.7> Reference for Claude Code hook events, configuration schema, JSON input/output formats, exit codes, async hooks, HTTP hooks, prompt hooks, and MCP tool hooks.
4 8
5<Tip>9<Tip>
6 For a quickstart guide with examples, see [Get started with Claude Code hooks](/en/hooks-guide).10 For a quickstart guide with examples, see [Automate workflows with hooks](/en/hooks-guide).
7</Tip>11</Tip>
8 12
9## Configuration13Hooks 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](/en/hooks-guide) instead.
10 14
11Claude Code hooks are configured in your [settings files](/en/settings):15## Hook lifecycle
12 16
13* `~/.claude/settings.json` - User settings17Hooks 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. Some events fire once per session, while others fire repeatedly inside the agentic loop:
14* `.claude/settings.json` - Project settings18
15* `.claude/settings.local.json` - Local project settings (not committed)19<div style={{maxWidth: "500px", margin: "0 auto"}}>
16* Managed policy settings20 <Frame>
17 21 <img src="https://mintcdn.com/claude-code/WLZtXlltXc8aIoIM/images/hooks-lifecycle.svg?fit=max&auto=format&n=WLZtXlltXc8aIoIM&q=85&s=6a0bf67eeb570a96e36b564721fa2a93" alt="Hook lifecycle diagram showing the sequence of hooks from SessionStart through the agentic loop (PreToolUse, PermissionRequest, PostToolUse, SubagentStart/Stop, TaskCreated, TaskCompleted) to Stop or StopFailure, 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, and WorktreeCreate, WorktreeRemove, Notification, ConfigChange, InstructionsLoaded, CwdChanged, and FileChanged as standalone async events" width="520" height="1155" data-path="images/hooks-lifecycle.svg" />
18<Note>22 </Frame>
19 Enterprise administrators can use `allowManagedHooksOnly` to block user, project, and plugin hooks. See [Hook configuration](/en/settings#hook-configuration).23</div>
20</Note>24
21 25The table below summarizes when each event fires. The [Hook events](#hook-events) section documents the full input schema and decision control options for each one.
22### Structure26
23 27| Event | When it fires |
24Hooks are organized by matchers, where each matcher can have multiple hooks:28| :------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- |
29| `SessionStart` | When a session begins or resumes |
30| `UserPromptSubmit` | When you submit a prompt, before Claude processes it |
31| `PreToolUse` | Before a tool call executes. Can block it |
32| `PermissionRequest` | When a permission dialog appears |
33| `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 |
34| `PostToolUse` | After a tool call succeeds |
35| `PostToolUseFailure` | After a tool call fails |
36| `Notification` | When Claude Code sends a notification |
37| `SubagentStart` | When a subagent is spawned |
38| `SubagentStop` | When a subagent finishes |
39| `TaskCreated` | When a task is being created via `TaskCreate` |
40| `TaskCompleted` | When a task is being marked as completed |
41| `Stop` | When Claude finishes responding |
42| `StopFailure` | When the turn ends due to an API error. Output and exit code are ignored |
43| `TeammateIdle` | When an [agent team](/en/agent-teams) teammate is about to go idle |
44| `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 |
45| `ConfigChange` | When a configuration file changes during a session |
46| `CwdChanged` | When the working directory changes, for example when Claude executes a `cd` command. Useful for reactive environment management with tools like direnv |
47| `FileChanged` | When a watched file changes on disk. The `matcher` field specifies which filenames to watch |
48| `WorktreeCreate` | When a worktree is being created via `--worktree` or `isolation: "worktree"`. Replaces default git behavior |
49| `WorktreeRemove` | When a worktree is being removed, either at session exit or when a subagent finishes |
50| `PreCompact` | Before context compaction |
51| `PostCompact` | After context compaction completes |
52| `Elicitation` | When an MCP server requests user input during a tool call |
53| `ElicitationResult` | After a user responds to an MCP elicitation, before the response is sent back to the server |
54| `SessionEnd` | When a session terminates |
55
56### How a hook resolves
57
58To 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 commands starting with `rm`, so `block-rm.sh` only spawns when both filters match:
25 59
26```json theme={null}60```json theme={null}
27{61{
28 "hooks": {62 "hooks": {
29 "EventName": [63 "PreToolUse": [
30 {64 {
31 "matcher": "ToolPattern",65 "matcher": "Bash",
32 "hooks": [66 "hooks": [
33 {67 {
34 "type": "command",68 "type": "command",
35 "command": "your-command-here"69 "if": "Bash(rm *)",
70 "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-rm.sh"
36 }71 }
37 ]72 ]
38 }73 }
41}76}
42```77```
43 78
44* **matcher**: Pattern to match tool names, case-sensitive (only applicable for79The script reads the JSON input from stdin, extracts the command, and returns a `permissionDecision` of `"deny"` if it contains `rm -rf`:
45 `PreToolUse`, `PermissionRequest`, and `PostToolUse`)
46 * Simple strings match exactly: `Write` matches only the Write tool
47 * Supports regex: `Edit|Write` or `Notebook.*`
48 * Use `*` to match all tools. You can also use empty string (`""`) or leave
49 `matcher` blank.
50* **hooks**: Array of hooks to execute when the pattern matches
51 * `type`: Hook execution type - `"command"` for bash commands or `"prompt"` for LLM-based evaluation
52 * `command`: (For `type: "command"`) The bash command to execute (can use `$CLAUDE_PROJECT_DIR` environment variable)
53 * `prompt`: (For `type: "prompt"`) The prompt to send to the LLM for evaluation
54 * `timeout`: (Optional) How long a hook should run, in seconds, before canceling that specific hook
55 80
56For events like `UserPromptSubmit`, `Stop`, and `SubagentStop`81```bash theme={null}
57that don't use matchers, you can omit the matcher field:82#!/bin/bash
83# .claude/hooks/block-rm.sh
84COMMAND=$(jq -r '.tool_input.command')
85
86if echo "$COMMAND" | grep -q 'rm -rf'; then
87 jq -n '{
88 hookSpecificOutput: {
89 hookEventName: "PreToolUse",
90 permissionDecision: "deny",
91 permissionDecisionReason: "Destructive command blocked by hook"
92 }
93 }'
94else
95 exit 0 # allow the command
96fi
97```
58 98
59```json theme={null}99Now suppose Claude Code decides to run `Bash "rm -rf /tmp/build"`. Here's what happens:
60{100
61 "hooks": {101<Frame>
62 "UserPromptSubmit": [102 <img src="https://mintcdn.com/claude-code/-tYw1BD_DEqfyyOZ/images/hook-resolution.svg?fit=max&auto=format&n=-tYw1BD_DEqfyyOZ&q=85&s=c73ebc1eeda2037570427d7af1e0a891" alt="Hook resolution flow: PreToolUse event fires, matcher checks for Bash match, if condition checks for Bash(rm *) match, hook handler runs, result returns to Claude Code" width="930" height="290" data-path="images/hook-resolution.svg" />
63 {103</Frame>
64 "hooks": [104
105<Steps>
106 <Step title="Event fires">
107 The `PreToolUse` event fires. Claude Code sends the tool input as JSON on stdin to the hook:
108
109 ```json theme={null}
110 { "tool_name": "Bash", "tool_input": { "command": "rm -rf /tmp/build" }, ... }
111 ```
112 </Step>
113
114 <Step title="Matcher checks">
115 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.
116 </Step>
117
118 <Step title="If condition checks">
119 The `if` condition `"Bash(rm *)"` matches because the command starts with `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.
120 </Step>
121
122 <Step title="Hook handler runs">
123 The script inspects the full command and finds `rm -rf`, so it prints a decision to stdout:
124
125 ```json theme={null}
65 {126 {
66 "type": "command",127 "hookSpecificOutput": {
67 "command": "/path/to/prompt-validator.py"128 "hookEventName": "PreToolUse",
68 }129 "permissionDecision": "deny",
69 ]130 "permissionDecisionReason": "Destructive command blocked by hook"
70 }131 }
71 ]
72 }132 }
73}133 ```
74```134
135 If the command had been a safer `rm` variant like `rm file.txt`, the script would hit `exit 0` instead, which tells Claude Code to allow the tool call with no further action.
136 </Step>
137
138 <Step title="Claude Code acts on the result">
139 Claude Code reads the JSON decision, blocks the tool call, and shows Claude the reason.
140 </Step>
141</Steps>
142
143The [Configuration](#configuration) section below documents the full schema, and each [hook event](#hook-events) section documents what input your command receives and what output it can return.
144
145## Configuration
146
147Hooks are defined in JSON settings files. The configuration has three levels of nesting:
148
1491. Choose a [hook event](#hook-events) to respond to, like `PreToolUse` or `Stop`
1502. Add a [matcher group](#matcher-patterns) to filter when it fires, like "only for the Bash tool"
1513. Define one or more [hook handlers](#hook-handler-fields) to run when matched
152
153See [How a hook resolves](#how-a-hook-resolves) above for a complete walkthrough with an annotated example.
154
155<Note>
156 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, prompt, or agent that runs. "Hook" on its own refers to the general feature.
157</Note>
158
159### Hook locations
160
161Where you define a hook determines its scope:
75 162
76### Project-Specific Hook Scripts163| Location | Scope | Shareable |
164| :--------------------------------------------------------- | :---------------------------- | :--------------------------------- |
165| `~/.claude/settings.json` | All your projects | No, local to your machine |
166| `.claude/settings.json` | Single project | Yes, can be committed to the repo |
167| `.claude/settings.local.json` | Single project | No, gitignored |
168| Managed policy settings | Organization-wide | Yes, admin-controlled |
169| [Plugin](/en/plugins) `hooks/hooks.json` | When plugin is enabled | Yes, bundled with the plugin |
170| [Skill](/en/skills) or [agent](/en/sub-agents) frontmatter | While the component is active | Yes, defined in the component file |
77 171
78You can use the environment variable `CLAUDE_PROJECT_DIR` (only available when172For details on settings file resolution, see [settings](/en/settings). Enterprise administrators can use `allowManagedHooksOnly` to block user, project, and plugin hooks. See [Hook configuration](/en/settings#hook-configuration).
79Claude Code spawns the hook command) to reference scripts stored in your project,173
80ensuring they work regardless of Claude's current directory:174### Matcher patterns
175
176The `matcher` field is a regex string that filters when hooks fire. Use `"*"`, `""`, or omit `matcher` entirely to match all occurrences. Each event type matches on a different field:
177
178| Event | What the matcher filters | Example matcher values |
179| :------------------------------------------------------------------------------------------------------------- | :-------------------------------------- | :------------------------------------------------------------------------------------------------------------------------ |
180| `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`, `PermissionDenied` | tool name | `Bash`, `Edit\|Write`, `mcp__.*` |
181| `SessionStart` | how the session started | `startup`, `resume`, `clear`, `compact` |
182| `SessionEnd` | why the session ended | `clear`, `resume`, `logout`, `prompt_input_exit`, `bypass_permissions_disabled`, `other` |
183| `Notification` | notification type | `permission_prompt`, `idle_prompt`, `auth_success`, `elicitation_dialog` |
184| `SubagentStart` | agent type | `Bash`, `Explore`, `Plan`, or custom agent names |
185| `PreCompact`, `PostCompact` | what triggered compaction | `manual`, `auto` |
186| `SubagentStop` | agent type | same values as `SubagentStart` |
187| `ConfigChange` | configuration source | `user_settings`, `project_settings`, `local_settings`, `policy_settings`, `skills` |
188| `CwdChanged` | no matcher support | always fires on every directory change |
189| `FileChanged` | filename (basename of the changed file) | `.envrc`, `.env`, any filename you want to watch |
190| `StopFailure` | error type | `rate_limit`, `authentication_failed`, `billing_error`, `invalid_request`, `server_error`, `max_output_tokens`, `unknown` |
191| `InstructionsLoaded` | load reason | `session_start`, `nested_traversal`, `path_glob_match`, `include`, `compact` |
192| `Elicitation` | MCP server name | your configured MCP server names |
193| `ElicitationResult` | MCP server name | same values as `Elicitation` |
194| `UserPromptSubmit`, `Stop`, `TeammateIdle`, `TaskCreated`, `TaskCompleted`, `WorktreeCreate`, `WorktreeRemove` | no matcher support | always fires on every occurrence |
195
196The matcher is a regex, so `Edit|Write` matches either tool and `Notebook.*` matches any tool starting with Notebook. The matcher runs against a field from the [JSON input](#hook-input-and-output) that Claude Code sends to your hook on stdin. For tool events, that field is `tool_name`. Each [hook event](#hook-events) section lists the full set of matcher values and the input schema for that event.
197
198This example runs a linting script only when Claude writes or edits a file:
81 199
82```json theme={null}200```json theme={null}
83{201{
84 "hooks": {202 "hooks": {
85 "PostToolUse": [203 "PostToolUse": [
86 {204 {
87 "matcher": "Write|Edit",205 "matcher": "Edit|Write",
88 "hooks": [206 "hooks": [
89 {207 {
90 "type": "command",208 "type": "command",
91 "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/check-style.sh"209 "command": "/path/to/lint-check.sh"
92 }210 }
93 ]211 ]
94 }212 }
97}215}
98```216```
99 217
100### Plugin hooks218`UserPromptSubmit`, `Stop`, `TeammateIdle`, `TaskCreated`, `TaskCompleted`, `WorktreeCreate`, `WorktreeRemove`, 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.
219
220For tool events, you can filter more narrowly by setting the [`if` field](#common-fields) on individual hook handlers. `if` uses [permission rule syntax](/en/permissions) to match against the tool name and arguments together, so `"Bash(git *)"` runs only for `git` commands and `"Edit(*.ts)"` runs only for TypeScript files.
101 221
102[Plugins](/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.222#### Match MCP tools
103 223
104**How plugin hooks work**:224[MCP](/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.
105 225
106* 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.226MCP tools follow the naming pattern `mcp__<server>__<tool>`, for example:
107* When a plugin is enabled, its hooks are merged with user and project hooks
108* Multiple hooks from different sources can respond to the same event
109* Plugin hooks use the `${CLAUDE_PLUGIN_ROOT}` environment variable to reference plugin files
110 227
111**Example plugin hook configuration**:228* `mcp__memory__create_entities`: Memory server's create entities tool
229* `mcp__filesystem__read_file`: Filesystem server's read file tool
230* `mcp__github__search_repositories`: GitHub server's search tool
231
232Use regex patterns to target specific MCP tools or groups of tools:
233
234* `mcp__memory__.*` matches all tools from the `memory` server
235* `mcp__.*__write.*` matches any tool containing "write" from any server
236
237This example logs all memory server operations and validates write operations from any MCP server:
112 238
113```json theme={null}239```json theme={null}
114{240{
115 "description": "Automatic code formatting",
116 "hooks": {241 "hooks": {
117 "PostToolUse": [242 "PreToolUse": [
118 {243 {
119 "matcher": "Write|Edit",244 "matcher": "mcp__memory__.*",
120 "hooks": [245 "hooks": [
121 {246 {
122 "type": "command",247 "type": "command",
123 "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format.sh",248 "command": "echo 'Memory operation initiated' >> ~/mcp-operations.log"
124 "timeout": 30249 }
250 ]
251 },
252 {
253 "matcher": "mcp__.*__write.*",
254 "hooks": [
255 {
256 "type": "command",
257 "command": "/home/user/scripts/validate-mcp-write.py"
125 }258 }
126 ]259 ]
127 }260 }
130}263}
131```264```
132 265
133<Note>266### Hook handler fields
134 Plugin hooks use the same format as regular hooks with an optional `description` field to explain the hook's purpose.
135</Note>
136
137<Note>
138 Plugin hooks run alongside your custom hooks. If multiple hooks match an event, they all execute in parallel.
139</Note>
140
141**Environment variables for plugins**:
142
143* `${CLAUDE_PLUGIN_ROOT}`: Absolute path to the plugin directory
144* `${CLAUDE_PROJECT_DIR}`: Project root directory (same as for project hooks)
145* All standard environment variables are available
146
147See the [plugin components reference](/en/plugins-reference#hooks) for details on creating plugin hooks.
148 267
149### Hooks in Skills, Agents, and Slash Commands268Each object in the inner `hooks` array is a hook handler: the shell command, HTTP endpoint, LLM prompt, or agent that runs when the matcher matches. There are four types:
150 269
151In addition to settings files and plugins, hooks can be defined directly in [Skills](/en/skills), [subagents](/en/sub-agents), and [slash commands](/en/slash-commands) using frontmatter. These hooks are scoped to the component's lifecycle and only run when that component is active.270* **[Command hooks](#command-hook-fields)** (`type: "command"`): run a shell command. Your script receives the event's [JSON input](#hook-input-and-output) on stdin and communicates results back through exit codes and stdout.
271* **[HTTP 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](#json-output) as command hooks.
272* **[Prompt 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](#prompt-based-hooks).
273* **[Agent 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. See [Agent-based hooks](#agent-based-hooks).
152 274
153**Supported events**: `PreToolUse`, `PostToolUse`, and `Stop`275#### Common fields
154
155**Example in a Skill**:
156
157```yaml theme={null}
158name: secure-operations
159description: Perform operations with security checks
160hooks:
161 PreToolUse:
162 - matcher: "Bash"
163 hooks:
164 - type: command
165 command: "./scripts/security-check.sh"
166```
167 276
168**Example in an agent**:277These fields apply to all hook types:
169 278
170```yaml theme={null}279| Field | Required | Description |
171name: code-reviewer280| :-------------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
172description: Review code changes281| `type` | yes | `"command"`, `"http"`, `"prompt"`, or `"agent"` |
173hooks:282| `if` | no | Permission rule syntax to filter when this hook runs, such as `"Bash(git *)"` or `"Edit(*.ts)"`. The hook only spawns if the tool call matches the pattern. 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](/en/permissions) |
174 PostToolUse:283| `timeout` | no | Seconds before canceling. Defaults: 600 for command, 30 for prompt, 60 for agent |
175 - matcher: "Edit|Write"284| `statusMessage` | no | Custom spinner message displayed while the hook runs |
176 hooks:285| `once` | no | If `true`, runs only once per session then is removed. Skills only, not agents. See [Hooks in skills and agents](#hooks-in-skills-and-agents) |
177 - type: command
178 command: "./scripts/run-linter.sh"
179```
180 286
181Component-scoped hooks follow the same configuration format as settings-based hooks but are automatically cleaned up when the component finishes executing.287#### Command hook fields
182 288
183**Additional option for skills and slash commands:**289In addition to the [common fields](#common-fields), command hooks accept these fields:
184 290
185* `once`: Set to `true` to run the hook only once per session. After the first successful execution, the hook is removed. Note: This option is currently only supported for skills and slash commands, not for agents.291| Field | Required | Description |
292| :-------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
293| `command` | yes | Shell command to execute |
294| `async` | no | If `true`, runs in the background without blocking. See [Run hooks in the background](#run-hooks-in-the-background) |
295| `shell` | no | Shell to use for this hook. Accepts `"bash"` (default) or `"powershell"`. Setting `"powershell"` runs the command via PowerShell on Windows. Does not require `CLAUDE_CODE_USE_POWERSHELL_TOOL` since hooks spawn PowerShell directly |
186 296
187## Prompt-Based Hooks297#### HTTP hook fields
188 298
189In 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.299In addition to the [common fields](#common-fields), HTTP hooks accept these fields:
190 300
191### How prompt-based hooks work301| Field | Required | Description |
302| :--------------- | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
303| `url` | yes | URL to send the POST request to |
304| `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 |
305| `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 |
192 306
193Instead of executing a bash command, prompt-based hooks:307Claude Code sends the hook's [JSON input](#hook-input-and-output) as the POST request body with `Content-Type: application/json`. The response body uses the same [JSON output format](#json-output) as command hooks.
194 308
1951. Send the hook input and your prompt to a fast LLM (Haiku)309Error 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"`.
1962. The LLM responds with structured JSON containing a decision
1973. Claude Code processes the decision automatically
198 310
199### Configuration311This example sends `PreToolUse` events to a local validation service, authenticating with a token from the `MY_TOKEN` environment variable:
200 312
201```json theme={null}313```json theme={null}
202{314{
203 "hooks": {315 "hooks": {
204 "Stop": [316 "PreToolUse": [
205 {317 {
318 "matcher": "Bash",
206 "hooks": [319 "hooks": [
207 {320 {
208 "type": "prompt",321 "type": "http",
209 "prompt": "Evaluate if Claude should stop: $ARGUMENTS. Check if all tasks are complete."322 "url": "http://localhost:8080/hooks/pre-tool-use",
323 "timeout": 30,
324 "headers": {
325 "Authorization": "Bearer $MY_TOKEN"
326 },
327 "allowedEnvVars": ["MY_TOKEN"]
210 }328 }
211 ]329 ]
212 }330 }
219}333}
220```334```
221 335
222**Fields:**336#### Prompt and agent hook fields
223
224* `type`: Must be `"prompt"`
225* `prompt`: The prompt text to send to the LLM
226 * Use `$ARGUMENTS` as a placeholder for the hook input JSON
227 * If `$ARGUMENTS` is not present, input JSON is appended to the prompt
228* `timeout`: (Optional) Timeout in seconds (default: 30 seconds)
229
230### Response schema
231
232The LLM must respond with JSON containing:
233 337
234```json theme={null}338In addition to the [common fields](#common-fields), prompt and agent hooks accept these fields:
235{
236 "ok": true | false,
237 "reason": "Explanation for the decision"
238}
239```
240 339
241**Response fields:**340| Field | Required | Description |
341| :------- | :------- | :------------------------------------------------------------------------------------------ |
342| `prompt` | yes | Prompt text to send to the model. Use `$ARGUMENTS` as a placeholder for the hook input JSON |
343| `model` | no | Model to use for evaluation. Defaults to a fast model |
242 344
243* `ok`: `true` allows the action, `false` prevents it345All matching hooks run in parallel, and identical handlers are deduplicated automatically. Command hooks are deduplicated by command string, 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.
244* `reason`: Required when `ok` is `false`. Explanation shown to Claude
245 346
246### Supported hook events347### Reference scripts by path
247 348
248Prompt-based hooks work with any hook event, but are most useful for:349Use environment variables to reference hook scripts relative to the project or plugin root, regardless of the working directory when the hook runs:
249 350
250* **Stop**: Intelligently decide if Claude should continue working351* `$CLAUDE_PROJECT_DIR`: the project root. Wrap in quotes to handle paths with spaces.
251* **SubagentStop**: Evaluate if a subagent has completed its task352* `${CLAUDE_PLUGIN_ROOT}`: the plugin's installation directory, for scripts bundled with a [plugin](/en/plugins). Changes on each plugin update.
252* **UserPromptSubmit**: Validate user prompts with LLM assistance353* `${CLAUDE_PLUGIN_DATA}`: the plugin's [persistent data directory](/en/plugins-reference#persistent-data-directory), for dependencies and state that should survive plugin updates.
253* **PreToolUse**: Make context-aware permission decisions
254* **PermissionRequest**: Intelligently allow or deny permission dialogs
255 354
256### Example: Intelligent Stop hook355<Tabs>
356 <Tab title="Project scripts">
357 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:
257 358
258```json theme={null}359 ```json theme={null}
259{360 {
260 "hooks": {361 "hooks": {
261 "Stop": [362 "PostToolUse": [
262 {363 {
364 "matcher": "Write|Edit",
263 "hooks": [365 "hooks": [
264 {366 {
265 "type": "prompt",367 "type": "command",
266 "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.",368 "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/check-style.sh"
267 "timeout": 30
268 }369 }
269 ]370 ]
270 }371 }
271 ]372 ]
272 }373 }
273}374 }
274```375 ```
376 </Tab>
275 377
276### Example: SubagentStop with custom logic378 <Tab title="Plugin scripts">
379 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.
277 380
278```json theme={null}381 This example runs a formatting script bundled with the plugin:
279{382
383 ```json theme={null}
384 {
385 "description": "Automatic code formatting",
280 "hooks": {386 "hooks": {
281 "SubagentStop": [387 "PostToolUse": [
282 {388 {
389 "matcher": "Write|Edit",
283 "hooks": [390 "hooks": [
284 {391 {
285 "type": "prompt",392 "type": "command",
286 "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: {\"ok\": true} to allow stopping, or {\"ok\": false, \"reason\": \"explanation\"} to continue."393 "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format.sh",
394 "timeout": 30
287 }395 }
288 ]396 ]
289 }397 }
290 ]398 ]
291 }399 }
292}400 }
293```401 ```
294 402
295### Comparison with bash command hooks403 See the [plugin components reference](/en/plugins-reference#hooks) for details on creating plugin hooks.
404 </Tab>
405</Tabs>
296 406
297| Feature | Bash Command Hooks | Prompt-Based Hooks |407### Hooks in skills and agents
298| --------------------- | ----------------------- | ------------------------------ |
299| **Execution** | Runs bash script | Queries LLM |
300| **Decision logic** | You implement in code | LLM evaluates context |
301| **Setup complexity** | Requires script file | Configure prompt |
302| **Context awareness** | Limited to script logic | Natural language understanding |
303| **Performance** | Fast (local execution) | Slower (API call) |
304| **Use case** | Deterministic rules | Context-aware decisions |
305 408
306### Best practices409In addition to settings files and plugins, hooks can be defined directly in [skills](/en/skills) and [subagents](/en/sub-agents) using frontmatter. These hooks are scoped to the component's lifecycle and only run when that component is active.
307 410
308* **Be specific in prompts**: Clearly state what you want the LLM to evaluate411All hook events are supported. For subagents, `Stop` hooks are automatically converted to `SubagentStop` since that is the event that fires when a subagent completes.
309* **Include decision criteria**: List the factors the LLM should consider
310* **Test your prompts**: Verify the LLM makes correct decisions for your use cases
311* **Set appropriate timeouts**: Default is 30 seconds, adjust if needed
312* **Use for complex decisions**: Bash hooks are better for simple, deterministic rules
313 412
314See the [plugin components reference](/en/plugins-reference#hooks) for details on creating plugin hooks.413Hooks use the same configuration format as settings-based hooks but are scoped to the component's lifetime and cleaned up when it finishes.
315 414
316## Hook Events415This skill defines a `PreToolUse` hook that runs a security validation script before each `Bash` command:
317 416
318### PreToolUse417```yaml theme={null}
418---
419name: secure-operations
420description: Perform operations with security checks
421hooks:
422 PreToolUse:
423 - matcher: "Bash"
424 hooks:
425 - type: command
426 command: "./scripts/security-check.sh"
427---
428```
319 429
320Runs after Claude creates tool parameters and before processing the tool call.430Agents use the same format in their YAML frontmatter.
321 431
322**Common matchers:**432### The `/hooks` menu
323 433
324* `Task` - Subagent tasks (see [subagents documentation](/en/sub-agents))434Type `/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.
325* `Bash` - Shell commands
326* `Glob` - File pattern matching
327* `Grep` - Content search
328* `Read` - File reading
329* `Edit` - File editing
330* `Write` - File writing
331* `WebFetch`, `WebSearch` - Web operations
332 435
333Use [PreToolUse decision control](#pretooluse-decision-control) to allow, deny, or ask for permission to use the tool.436The menu displays all four hook types: `command`, `prompt`, `agent`, and `http`. Each hook is labeled with a `[type]` prefix and a source indicating where it was defined:
334 437
335### PermissionRequest438* `User`: from `~/.claude/settings.json`
439* `Project`: from `.claude/settings.json`
440* `Local`: from `.claude/settings.local.json`
441* `Plugin`: from a plugin's `hooks/hooks.json`
442* `Session`: registered in memory for the current session
443* `Built-in`: registered internally by Claude Code
336 444
337Runs when the user is shown a permission dialog.445Selecting 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.
338Use [PermissionRequest decision control](#permissionrequest-decision-control) to allow or deny on behalf of the user.
339 446
340Recognizes the same matcher values as PreToolUse.447### Disable or remove hooks
341 448
342### PostToolUse449To remove a hook, delete its entry from the settings JSON file.
343 450
344Runs immediately after a tool completes successfully.451To 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.
345 452
346Recognizes the same matcher values as PreToolUse.453The `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 cannot disable those managed hooks. Only `disableAllHooks` set at the managed settings level can disable managed hooks.
347 454
348### Notification455Direct edits to hooks in settings files are normally picked up automatically by the file watcher.
456
457## Hook input and output
349 458
350Runs when Claude Code sends notifications. Supports matchers to filter by notification type.459Command 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](#hook-events) includes its specific input schema and decision control options.
351 460
352**Common matchers:**461### Common input fields
353 462
354* `permission_prompt` - Permission requests from Claude Code463Hook events receive these fields as JSON, in addition to event-specific fields documented in each [hook event](#hook-events) section. For command hooks, this JSON arrives via stdin. For HTTP hooks, it arrives as the POST request body.
355* `idle_prompt` - When Claude is waiting for user input (after 60+ seconds of idle time)
356* `auth_success` - Authentication success notifications
357* `elicitation_dialog` - When Claude Code needs input for MCP tool elicitation
358 464
359You can use matchers to run different hooks for different notification types, or omit the matcher to run hooks for all notifications.465| Field | Description |
466| :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
467| `session_id` | Current session identifier |
468| `transcript_path` | Path to conversation JSON |
469| `cwd` | Current working directory when the hook is invoked |
470| `permission_mode` | Current [permission mode](/en/permissions#permission-modes): `"default"`, `"plan"`, `"acceptEdits"`, `"auto"`, `"dontAsk"`, or `"bypassPermissions"`. Not all events receive this field: see each event's JSON example below to check |
471| `hook_event_name` | Name of the event that fired |
360 472
361**Example: Different notifications for different types**473When running with `--agent` or inside a subagent, two additional fields are included:
474
475| Field | Description |
476| :----------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
477| `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. |
478| `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. |
479
480For example, a `PreToolUse` hook for a Bash command receives this on stdin:
362 481
363```json theme={null}482```json theme={null}
364{483{
365 "hooks": {484 "session_id": "abc123",
366 "Notification": [485 "transcript_path": "/home/user/.claude/projects/.../transcript.jsonl",
367 {486 "cwd": "/home/user/my-project",
368 "matcher": "permission_prompt",487 "permission_mode": "default",
369 "hooks": [488 "hook_event_name": "PreToolUse",
370 {489 "tool_name": "Bash",
371 "type": "command",490 "tool_input": {
372 "command": "/path/to/permission-alert.sh"491 "command": "npm test"
373 }
374 ]
375 },
376 {
377 "matcher": "idle_prompt",
378 "hooks": [
379 {
380 "type": "command",
381 "command": "/path/to/idle-notification.sh"
382 }
383 ]
384 }
385 ]
386 }492 }
387}493}
388```494```
389 495
390### UserPromptSubmit496The `tool_name` and `tool_input` fields are event-specific. Each [hook event](#hook-events) section documents the additional fields for that event.
391
392Runs when the user submits a prompt, before Claude processes it. This allows you
393to add additional context based on the prompt/conversation, validate prompts, or
394block certain types of prompts.
395
396### Stop
397
398Runs when the main Claude Code agent has finished responding. Does not run if
399the stoppage occurred due to a user interrupt.
400
401### SubagentStop
402
403Runs when a Claude Code subagent (Task tool call) has finished responding.
404
405### PreCompact
406
407Runs before Claude Code is about to run a compact operation.
408 497
409**Matchers:**498### Exit code output
410 499
411* `manual` - Invoked from `/compact`500The exit code from your hook command tells Claude Code whether the action should proceed, be blocked, or be ignored.
412* `auto` - Invoked from auto-compact (due to full context window)
413 501
414### SessionStart502**Exit 0** means success. Claude Code parses stdout for [JSON output fields](#json-output). JSON output is only processed on exit 0. For most events, stdout is only shown in verbose mode (`Ctrl+O`). The exceptions are `UserPromptSubmit` and `SessionStart`, where stdout is added as context that Claude can see and act on.
415
416Runs when Claude Code starts a new session or resumes an existing session (which
417currently does start a new session under the hood). Useful for loading in
418development context like existing issues or recent changes to your codebase, installing dependencies, or setting up environment variables.
419
420**Matchers:**
421
422* `startup` - Invoked from startup
423* `resume` - Invoked from `--resume`, `--continue`, or `/resume`
424* `clear` - Invoked from `/clear`
425* `compact` - Invoked from auto or manual compact.
426 503
427#### Persisting environment variables504**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](#exit-code-2-behavior-per-event) for the full list.
428 505
429SessionStart 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.506**Any other exit code** is a non-blocking error. stderr is shown in verbose mode (`Ctrl+O`) and execution continues.
430 507
431**Example: Setting individual environment variables**508For example, a hook command script that blocks dangerous Bash commands:
432 509
433```bash theme={null}510```bash theme={null}
434#!/bin/bash511#!/bin/bash
512# Reads JSON input from stdin, checks the command
513command=$(jq -r '.tool_input.command' < /dev/stdin)
435 514
436if [ -n "$CLAUDE_ENV_FILE" ]; then515if [[ "$command" == rm* ]]; then
437 echo 'export NODE_ENV=production' >> "$CLAUDE_ENV_FILE"516 echo "Blocked: rm commands are not allowed" >&2
438 echo 'export API_KEY=your-api-key' >> "$CLAUDE_ENV_FILE"517 exit 2 # Blocking error: tool call is prevented
439 echo 'export PATH="$PATH:./node_modules/.bin"' >> "$CLAUDE_ENV_FILE"
440fi518fi
441 519
442exit 0520exit 0 # Success: tool call proceeds
443```521```
444 522
445**Example: Persisting all environment changes from the hook**523#### Exit code 2 behavior per event
524
525Exit 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.
526
527| Hook event | Can block? | What happens on exit 2 |
528| :------------------- | :--------- | :----------------------------------------------------------------------------------------------------------------------------------- |
529| `PreToolUse` | Yes | Blocks the tool call |
530| `PermissionRequest` | Yes | Denies the permission |
531| `UserPromptSubmit` | Yes | Blocks prompt processing and erases the prompt |
532| `Stop` | Yes | Prevents Claude from stopping, continues the conversation |
533| `SubagentStop` | Yes | Prevents the subagent from stopping |
534| `TeammateIdle` | Yes | Prevents the teammate from going idle (teammate continues working) |
535| `TaskCreated` | Yes | Rolls back the task creation |
536| `TaskCompleted` | Yes | Prevents the task from being marked as completed |
537| `ConfigChange` | Yes | Blocks the configuration change from taking effect (except `policy_settings`) |
538| `StopFailure` | No | Output and exit code are ignored |
539| `PostToolUse` | No | Shows stderr to Claude (tool already ran) |
540| `PostToolUseFailure` | No | Shows stderr to Claude (tool already failed) |
541| `PermissionDenied` | No | Exit code and stderr are ignored (denial already occurred). Use JSON `hookSpecificOutput.retry: true` to tell the model it may retry |
542| `Notification` | No | Shows stderr to user only |
543| `SubagentStart` | No | Shows stderr to user only |
544| `SessionStart` | No | Shows stderr to user only |
545| `SessionEnd` | No | Shows stderr to user only |
546| `CwdChanged` | No | Shows stderr to user only |
547| `FileChanged` | No | Shows stderr to user only |
548| `PreCompact` | No | Shows stderr to user only |
549| `PostCompact` | No | Shows stderr to user only |
550| `Elicitation` | Yes | Denies the elicitation |
551| `ElicitationResult` | Yes | Blocks the response (action becomes decline) |
552| `WorktreeCreate` | Yes | Any non-zero exit code causes worktree creation to fail |
553| `WorktreeRemove` | No | Failures are logged in debug mode only |
554| `InstructionsLoaded` | No | Exit code is ignored |
555
556### HTTP response handling
557
558HTTP hooks use HTTP status codes and response bodies instead of exit codes and stdout:
559
560* **2xx with an empty body**: success, equivalent to exit code 0 with no output
561* **2xx with a plain text body**: success, the text is added as context
562* **2xx with a JSON body**: success, parsed using the same [JSON output](#json-output) schema as command hooks
563* **Non-2xx status**: non-blocking error, execution continues
564* **Connection failure or timeout**: non-blocking error, execution continues
565
566Unlike command hooks, HTTP hooks cannot 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.
567
568### JSON output
569
570Exit codes let you allow or block, 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](#decision-control) for blocking, allowing, or escalating to the user.
446 571
447When your setup modifies the environment (for example, `nvm use`), capture and persist all changes by diffing the environment:572<Note>
448 573 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.
449```bash theme={null}574</Note>
450#!/bin/bash
451 575
452ENV_BEFORE=$(export -p | sort)576Your 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](/en/hooks-guide#json-validation-failed) in the troubleshooting guide.
453 577
454# Run your setup commands that modify the environment578Hook output injected into context (`additionalContext`, `systemMessage`, or plain stdout) is 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.
455source ~/.nvm/nvm.sh
456nvm use 20
457 579
458if [ -n "$CLAUDE_ENV_FILE" ]; then580The JSON object supports three kinds of fields:
459 ENV_AFTER=$(export -p | sort)
460 comm -13 <(echo "$ENV_BEFORE") <(echo "$ENV_AFTER") >> "$CLAUDE_ENV_FILE"
461fi
462 581
463exit 0582* **Universal fields** like `continue` work across all events. These are listed in the table below.
464```583* **Top-level `decision` and `reason`** are used by some events to block or provide feedback.
584* **`hookSpecificOutput`** is a nested object for events that need richer control. It requires a `hookEventName` field set to the event name.
465 585
466Any variables written to this file will be available in all subsequent bash commands that Claude Code executes during the session.586| Field | Default | Description |
587| :--------------- | :------ | :------------------------------------------------------------------------------------------------------------------------- |
588| `continue` | `true` | If `false`, Claude stops processing entirely after the hook runs. Takes precedence over any event-specific decision fields |
589| `stopReason` | none | Message shown to the user when `continue` is `false`. Not shown to Claude |
590| `suppressOutput` | `false` | If `true`, hides stdout from verbose mode output |
591| `systemMessage` | none | Warning message shown to the user |
467 592
468<Note>593To stop Claude entirely regardless of event type:
469 `CLAUDE_ENV_FILE` is only available for SessionStart hooks. Other hook types do not have access to this variable.
470</Note>
471 594
472### SessionEnd595```json theme={null}
596{ "continue": false, "stopReason": "Build failed, fix errors before continuing" }
597```
473 598
474Runs when a Claude Code session ends. Useful for cleanup tasks, logging session599#### Decision control
475statistics, or saving session state.
476 600
477The `reason` field in the hook input will be one of:601Not 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:
478 602
479* `clear` - Session cleared with /clear command603| Events | Decision pattern | Key fields |
480* `logout` - User logged out604| :-------------------------------------------------------------------------------------------------------------------------- | :----------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
481* `prompt_input_exit` - User exited while prompt input was visible605| UserPromptSubmit, PostToolUse, PostToolUseFailure, Stop, SubagentStop, ConfigChange | Top-level `decision` | `decision: "block"`, `reason` |
482* `other` - Other exit reasons606| 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 |
607| PreToolUse | `hookSpecificOutput` | `permissionDecision` (allow/deny/ask/defer), `permissionDecisionReason` |
608| PermissionRequest | `hookSpecificOutput` | `decision.behavior` (allow/deny) |
609| PermissionDenied | `hookSpecificOutput` | `retry: true` tells the model it may retry the denied tool call |
610| WorktreeCreate | path return | Command hook prints path on stdout; HTTP hook returns `hookSpecificOutput.worktreePath`. Hook failure or missing path fails creation |
611| Elicitation | `hookSpecificOutput` | `action` (accept/decline/cancel), `content` (form field values for accept) |
612| ElicitationResult | `hookSpecificOutput` | `action` (accept/decline/cancel), `content` (form field values override) |
613| WorktreeRemove, Notification, SessionEnd, PreCompact, PostCompact, InstructionsLoaded, StopFailure, CwdChanged, FileChanged | None | No decision control. Used for side effects like logging or cleanup |
483 614
484## Hook Input615Here are examples of each pattern in action:
485 616
486Hooks receive JSON data via stdin containing session information and617<Tabs>
487event-specific data:618 <Tab title="Top-level decision">
619 Used by `UserPromptSubmit`, `PostToolUse`, `PostToolUseFailure`, `Stop`, `SubagentStop`, and `ConfigChange`. The only value is `"block"`. To allow the action to proceed, omit `decision` from your JSON, or exit 0 without any JSON at all:
488 620
489```typescript theme={null}621 ```json theme={null}
490{622 {
491 // Common fields623 "decision": "block",
492 session_id: string624 "reason": "Test suite must pass before proceeding"
493 transcript_path: string // Path to conversation JSON625 }
494 cwd: string // The current working directory when the hook is invoked626 ```
495 permission_mode: string // Current permission mode: "default", "plan", "acceptEdits", "dontAsk", or "bypassPermissions"627 </Tab>
496
497 // Event-specific fields
498 hook_event_name: string
499 ...
500}
501```
502 628
503### PreToolUse Input629 <Tab title="PreToolUse">
630 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](#pretooluse-decision-control) for the full set of options.
504 631
505The exact schema for `tool_input` depends on the tool. Here are examples for commonly hooked tools.632 ```json theme={null}
633 {
634 "hookSpecificOutput": {
635 "hookEventName": "PreToolUse",
636 "permissionDecision": "deny",
637 "permissionDecisionReason": "Database writes are not allowed"
638 }
639 }
640 ```
641 </Tab>
506 642
507#### Bash tool643 <Tab title="PermissionRequest">
644 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](#permissionrequest-decision-control) for the full set of options.
508 645
509The Bash tool is the most commonly hooked tool for command validation:646 ```json theme={null}
647 {
648 "hookSpecificOutput": {
649 "hookEventName": "PermissionRequest",
650 "decision": {
651 "behavior": "allow",
652 "updatedInput": {
653 "command": "npm run lint"
654 }
655 }
656 }
657 }
658 ```
659 </Tab>
660</Tabs>
661
662For extended examples including Bash command validation, prompt filtering, and auto-approval scripts, see [What you can automate](/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).
663
664## Hook events
665
666Each 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.
667
668### SessionStart
669
670Runs 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 does not require a script, use [CLAUDE.md](/en/memory) instead.
671
672SessionStart runs on every session, so keep these hooks fast. Only `type: "command"` hooks are supported.
673
674The matcher value corresponds to how the session was initiated:
675
676| Matcher | When it fires |
677| :-------- | :------------------------------------- |
678| `startup` | New session |
679| `resume` | `--resume`, `--continue`, or `/resume` |
680| `clear` | `/clear` |
681| `compact` | Auto or manual compaction |
682
683#### SessionStart input
684
685In addition to the [common input fields](#common-input-fields), SessionStart hooks receive `source`, `model`, and optionally `agent_type`. The `source` field indicates how the session started: `"startup"` for new sessions, `"resume"` for resumed sessions, `"clear"` after `/clear`, or `"compact"` after compaction. The `model` field contains the model identifier. If you start Claude Code with `claude --agent <name>`, an `agent_type` field contains the agent name.
510 686
511```json theme={null}687```json theme={null}
512{688{
513 "session_id": "abc123",689 "session_id": "abc123",
514 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",690 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
515 "cwd": "/Users/...",691 "cwd": "/Users/...",
516 "permission_mode": "default",692 "hook_event_name": "SessionStart",
517 "hook_event_name": "PreToolUse",693 "source": "startup",
518 "tool_name": "Bash",694 "model": "claude-sonnet-4-6"
519 "tool_input": {695}
520 "command": "psql -c 'SELECT * FROM users'",696```
521 "description": "Query the users table",697
522 "timeout": 120000698#### SessionStart decision control
523 },699
524 "tool_use_id": "toolu_01ABC123..."700Any text your hook script prints to stdout is added as context for Claude. In addition to the [JSON output fields](#json-output) available to all hooks, you can return these event-specific fields:
701
702| Field | Description |
703| :------------------ | :------------------------------------------------------------------------ |
704| `additionalContext` | String added to Claude's context. Multiple hooks' values are concatenated |
705
706```json theme={null}
707{
708 "hookSpecificOutput": {
709 "hookEventName": "SessionStart",
710 "additionalContext": "My additional context here"
711 }
525}712}
526```713```
527 714
528| Field | Type | Description |715#### Persist environment variables
529| :------------------ | :------ | :-------------------------------------------- |716
530| `command` | string | The shell command to execute |717SessionStart 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.
531| `description` | string | Optional description of what the command does |718
532| `timeout` | number | Optional timeout in milliseconds |719To set individual environment variables, write `export` statements to `CLAUDE_ENV_FILE`. Use append (`>>`) to preserve variables set by other hooks:
533| `run_in_background` | boolean | Whether to run the command in background |720
721```bash theme={null}
722#!/bin/bash
723
724if [ -n "$CLAUDE_ENV_FILE" ]; then
725 echo 'export NODE_ENV=production' >> "$CLAUDE_ENV_FILE"
726 echo 'export DEBUG_LOG=true' >> "$CLAUDE_ENV_FILE"
727 echo 'export PATH="$PATH:./node_modules/.bin"' >> "$CLAUDE_ENV_FILE"
728fi
729
730exit 0
731```
732
733To capture all environment changes from setup commands, compare the exported variables before and after:
734
735```bash theme={null}
736#!/bin/bash
737
738ENV_BEFORE=$(export -p | sort)
739
740# Run your setup commands that modify the environment
741source ~/.nvm/nvm.sh
742nvm use 20
743
744if [ -n "$CLAUDE_ENV_FILE" ]; then
745 ENV_AFTER=$(export -p | sort)
746 comm -13 <(echo "$ENV_BEFORE") <(echo "$ENV_AFTER") >> "$CLAUDE_ENV_FILE"
747fi
748
749exit 0
750```
751
752Any variables written to this file will be available in all subsequent Bash commands that Claude Code executes during the session.
753
754<Note>
755 `CLAUDE_ENV_FILE` is available for SessionStart, [CwdChanged](#cwdchanged), and [FileChanged](#filechanged) hooks. Other hook types do not have access to this variable.
756</Note>
757
758### InstructionsLoaded
759
760Fires 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 does not support blocking or decision control. It runs asynchronously for observability purposes.
761
762The 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.
763
764#### InstructionsLoaded input
534 765
535#### Write tool766In addition to the [common input fields](#common-input-fields), InstructionsLoaded hooks receive these fields:
767
768| Field | Description |
769| :------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
770| `file_path` | Absolute path to the instruction file that was loaded |
771| `memory_type` | Scope of the file: `"User"`, `"Project"`, `"Local"`, or `"Managed"` |
772| `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 |
773| `globs` | Path glob patterns from the file's `paths:` frontmatter, if any. Present only for `path_glob_match` loads |
774| `trigger_file_path` | Path to the file whose access triggered this load, for lazy loads |
775| `parent_file_path` | Path to the parent instruction file that included this one, for `include` loads |
536 776
537```json theme={null}777```json theme={null}
538{778{
539 "session_id": "abc123",779 "session_id": "abc123",
540 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",780 "transcript_path": "/Users/.../.claude/projects/.../transcript.jsonl",
541 "cwd": "/Users/...",781 "cwd": "/Users/my-project",
542 "permission_mode": "default",782 "hook_event_name": "InstructionsLoaded",
543 "hook_event_name": "PreToolUse",783 "file_path": "/Users/my-project/CLAUDE.md",
544 "tool_name": "Write",784 "memory_type": "Project",
545 "tool_input": {785 "load_reason": "session_start"
546 "file_path": "/path/to/file.txt",
547 "content": "file content"
548 },
549 "tool_use_id": "toolu_01ABC123..."
550}786}
551```787```
552 788
553| Field | Type | Description |789#### InstructionsLoaded decision control
554| :---------- | :----- | :--------------------------------- |790
555| `file_path` | string | Absolute path to the file to write |791InstructionsLoaded hooks have no decision control. They cannot block or modify instruction loading. Use this event for audit logging, compliance tracking, or observability.
556| `content` | string | Content to write to the file |792
793### UserPromptSubmit
794
795Runs when the user submits a prompt, before Claude processes it. This allows you
796to add additional context based on the prompt/conversation, validate prompts, or
797block certain types of prompts.
798
799#### UserPromptSubmit input
557 800
558#### Edit tool801In addition to the [common input fields](#common-input-fields), UserPromptSubmit hooks receive the `prompt` field containing the text the user submitted.
559 802
560```json theme={null}803```json theme={null}
561{804{
563 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",806 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
564 "cwd": "/Users/...",807 "cwd": "/Users/...",
565 "permission_mode": "default",808 "permission_mode": "default",
566 "hook_event_name": "PreToolUse",809 "hook_event_name": "UserPromptSubmit",
567 "tool_name": "Edit",810 "prompt": "Write a function to calculate the factorial of a number"
568 "tool_input": {811}
569 "file_path": "/path/to/file.txt",812```
570 "old_string": "original text",813
571 "new_string": "replacement text"814#### UserPromptSubmit decision control
815
816`UserPromptSubmit` hooks can control whether a user prompt is processed and add context. All [JSON output fields](#json-output) are available.
817
818There are two ways to add context to the conversation on exit code 0:
819
820* **Plain text stdout**: any non-JSON text written to stdout is added as context
821* **JSON with `additionalContext`**: use the JSON format below for more control. The `additionalContext` field is added as context
822
823Plain stdout is shown as hook output in the transcript. The `additionalContext` field is added more discretely.
824
825To block a prompt, return a JSON object with `decision` set to `"block"`:
826
827| Field | Description |
828| :------------------ | :----------------------------------------------------------------------------------------------------------------- |
829| `decision` | `"block"` prevents the prompt from being processed and erases it from context. Omit to allow the prompt to proceed |
830| `reason` | Shown to the user when `decision` is `"block"`. Not added to context |
831| `additionalContext` | String added to Claude's context |
832
833```json theme={null}
834{
835 "decision": "block",
836 "reason": "Explanation for decision",
837 "hookSpecificOutput": {
838 "hookEventName": "UserPromptSubmit",
839 "additionalContext": "My additional context here"
840 }
841}
842```
843
844<Note>
845 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
846 block prompts or want more structured control.
847</Note>
848
849### PreToolUse
850
851Runs 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](#match-mcp-tools).
852
853Use [PreToolUse decision control](#pretooluse-decision-control) to allow, deny, ask, or defer the tool call.
854
855#### PreToolUse input
856
857In addition to the [common input fields](#common-input-fields), PreToolUse hooks receive `tool_name`, `tool_input`, and `tool_use_id`. The `tool_input` fields depend on the tool:
858
859##### Bash
860
861Executes shell commands.
862
863| Field | Type | Example | Description |
864| :------------------ | :------ | :----------------- | :-------------------------------------------- |
865| `command` | string | `"npm test"` | The shell command to execute |
866| `description` | string | `"Run test suite"` | Optional description of what the command does |
867| `timeout` | number | `120000` | Optional timeout in milliseconds |
868| `run_in_background` | boolean | `false` | Whether to run the command in background |
869
870##### Write
871
872Creates or overwrites a file.
873
874| Field | Type | Example | Description |
875| :---------- | :----- | :-------------------- | :--------------------------------- |
876| `file_path` | string | `"/path/to/file.txt"` | Absolute path to the file to write |
877| `content` | string | `"file content"` | Content to write to the file |
878
879##### Edit
880
881Replaces a string in an existing file.
882
883| Field | Type | Example | Description |
884| :------------ | :------ | :-------------------- | :--------------------------------- |
885| `file_path` | string | `"/path/to/file.txt"` | Absolute path to the file to edit |
886| `old_string` | string | `"original text"` | Text to find and replace |
887| `new_string` | string | `"replacement text"` | Replacement text |
888| `replace_all` | boolean | `false` | Whether to replace all occurrences |
889
890##### Read
891
892Reads file contents.
893
894| Field | Type | Example | Description |
895| :---------- | :----- | :-------------------- | :----------------------------------------- |
896| `file_path` | string | `"/path/to/file.txt"` | Absolute path to the file to read |
897| `offset` | number | `10` | Optional line number to start reading from |
898| `limit` | number | `50` | Optional number of lines to read |
899
900##### Glob
901
902Finds files matching a glob pattern.
903
904| Field | Type | Example | Description |
905| :-------- | :----- | :--------------- | :--------------------------------------------------------------------- |
906| `pattern` | string | `"**/*.ts"` | Glob pattern to match files against |
907| `path` | string | `"/path/to/dir"` | Optional directory to search in. Defaults to current working directory |
908
909##### Grep
910
911Searches file contents with regular expressions.
912
913| Field | Type | Example | Description |
914| :------------ | :------ | :--------------- | :------------------------------------------------------------------------------------ |
915| `pattern` | string | `"TODO.*fix"` | Regular expression pattern to search for |
916| `path` | string | `"/path/to/dir"` | Optional file or directory to search in |
917| `glob` | string | `"*.ts"` | Optional glob pattern to filter files |
918| `output_mode` | string | `"content"` | `"content"`, `"files_with_matches"`, or `"count"`. Defaults to `"files_with_matches"` |
919| `-i` | boolean | `true` | Case insensitive search |
920| `multiline` | boolean | `false` | Enable multiline matching |
921
922##### WebFetch
923
924Fetches and processes web content.
925
926| Field | Type | Example | Description |
927| :------- | :----- | :---------------------------- | :----------------------------------- |
928| `url` | string | `"https://example.com/api"` | URL to fetch content from |
929| `prompt` | string | `"Extract the API endpoints"` | Prompt to run on the fetched content |
930
931##### WebSearch
932
933Searches the web.
934
935| Field | Type | Example | Description |
936| :---------------- | :----- | :----------------------------- | :------------------------------------------------ |
937| `query` | string | `"react hooks best practices"` | Search query |
938| `allowed_domains` | array | `["docs.example.com"]` | Optional: only include results from these domains |
939| `blocked_domains` | array | `["spam.example.com"]` | Optional: exclude results from these domains |
940
941##### Agent
942
943Spawns a [subagent](/en/sub-agents).
944
945| Field | Type | Example | Description |
946| :-------------- | :----- | :------------------------- | :------------------------------------------- |
947| `prompt` | string | `"Find all API endpoints"` | The task for the agent to perform |
948| `description` | string | `"Find API endpoints"` | Short description of the task |
949| `subagent_type` | string | `"Explore"` | Type of specialized agent to use |
950| `model` | string | `"sonnet"` | Optional model alias to override the default |
951
952##### AskUserQuestion
953
954Asks the user one to four multiple-choice questions.
955
956| Field | Type | Example | Description |
957| :---------- | :----- | :----------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
958| `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 |
959| `answers` | object | `{"Which framework?": "React"}` | Optional. Maps question text to the selected option label. Multi-select answers join labels with commas. Claude does not set this field; supply it via `updatedInput` to answer programmatically |
960
961#### PreToolUse decision control
962
963`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.
964
965| Field | Description |
966| :------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
967| `permissionDecision` | `"allow"` skips the permission prompt. `"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](/en/permissions#manage-permissions) still apply when a hook returns `"allow"` |
968| `permissionDecisionReason` | For `"allow"` and `"ask"`, shown to the user but not Claude. For `"deny"`, shown to Claude. For `"defer"`, ignored |
969| `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 |
970| `additionalContext` | String added to Claude's context before the tool executes. For `"defer"`, ignored |
971
972When multiple PreToolUse hooks return different decisions, precedence is `deny` > `defer` > `ask` > `allow`.
973
974When 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.
975
976```json theme={null}
977{
978 "hookSpecificOutput": {
979 "hookEventName": "PreToolUse",
980 "permissionDecision": "allow",
981 "permissionDecisionReason": "My reason here",
982 "updatedInput": {
983 "field_to_modify": "new value"
572 },984 },
573 "tool_use_id": "toolu_01ABC123..."985 "additionalContext": "Current environment: production. Proceed with caution."
986 }
987}
988```
989
990`AskUserQuestion` and `ExitPlanMode` require user interaction and normally block in [non-interactive mode](/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`](#askuserquestion) object mapping each question's text to the chosen answer.
991
992<Note>
993 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.
994</Note>
995
996#### Defer a tool call for later
997
998`"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](/en/headless) with the `-p` flag. In interactive sessions it logs a warning and ignores the hook result.
999
1000<Note>
1001 The `defer` value requires Claude Code v2.1.89 or later. Earlier versions do not recognize it and the tool proceeds through the normal permission flow.
1002</Note>
1003
1004The `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:
1005
10061. Claude calls `AskUserQuestion`. The `PreToolUse` hook fires.
10072. The hook returns `permissionDecision: "defer"`. The tool does not execute. The process exits with `stop_reason: "tool_deferred"` and the pending tool call preserved in the transcript.
10083. The calling process reads `deferred_tool_use` from the SDK result, surfaces the question in its own UI, and waits for an answer.
10094. The calling process runs `claude -p --resume <session-id>`. The same tool call fires `PreToolUse` again.
10105. The hook returns `permissionDecision: "allow"` with the answer in `updatedInput`. The tool executes and Claude continues.
1011
1012The `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:
1013
1014```json theme={null}
1015{
1016 "type": "result",
1017 "subtype": "success",
1018 "stop_reason": "tool_deferred",
1019 "session_id": "abc123",
1020 "deferred_tool_use": {
1021 "id": "toolu_01abc",
1022 "name": "AskUserQuestion",
1023 "input": { "questions": [{ "question": "Which framework?", "header": "Framework", "options": [{"label": "React"}, {"label": "Vue"}], "multiSelect": false }] }
1024 }
574}1025}
575```1026```
576 1027
577| Field | Type | Description |1028There is no timeout or retry limit. The session remains on disk until you resume it. 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.
578| :------------ | :------ | :-------------------------------------------------- |1029
579| `file_path` | string | Absolute path to the file to edit |1030`"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.
580| `old_string` | string | Text to find and replace |1031
581| `new_string` | string | Replacement text |1032If 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.
582| `replace_all` | boolean | Whether to replace all occurrences (default: false) |1033
1034<Warning>
1035 `--resume` does not restore the permission mode from the prior session. Pass the same `--permission-mode` flag on resume that was active when the tool was deferred. Claude Code logs a warning if the modes differ.
1036</Warning>
1037
1038### PermissionRequest
1039
1040Runs when the user is shown a permission dialog.
1041Use [PermissionRequest decision control](#permissionrequest-decision-control) to allow or deny on behalf of the user.
1042
1043Matches on tool name, same values as PreToolUse.
583 1044
584#### Read tool1045#### PermissionRequest input
1046
1047PermissionRequest 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.
585 1048
586```json theme={null}1049```json theme={null}
587{1050{
589 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",1052 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
590 "cwd": "/Users/...",1053 "cwd": "/Users/...",
591 "permission_mode": "default",1054 "permission_mode": "default",
592 "hook_event_name": "PreToolUse",1055 "hook_event_name": "PermissionRequest",
593 "tool_name": "Read",1056 "tool_name": "Bash",
594 "tool_input": {1057 "tool_input": {
595 "file_path": "/path/to/file.txt"1058 "command": "rm -rf node_modules",
1059 "description": "Remove node_modules directory"
596 },1060 },
597 "tool_use_id": "toolu_01ABC123..."1061 "permission_suggestions": [
1062 {
1063 "type": "addRules",
1064 "rules": [{ "toolName": "Bash", "ruleContent": "rm -rf node_modules" }],
1065 "behavior": "allow",
1066 "destination": "localSettings"
1067 }
1068 ]
1069}
1070```
1071
1072#### PermissionRequest decision control
1073
1074`PermissionRequest` hooks can allow or deny permission requests. In addition to the [JSON output fields](#json-output) available to all hooks, your hook script can return a `decision` object with these event-specific fields:
1075
1076| Field | Description |
1077| :------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
1078| `behavior` | `"allow"` grants the permission, `"deny"` denies it |
1079| `updatedInput` | For `"allow"` only: modifies the tool's input parameters before execution. Replaces the entire input object, so include unchanged fields alongside modified ones |
1080| `updatedPermissions` | For `"allow"` only: array of [permission update entries](#permission-update-entries) to apply, such as adding an allow rule or changing the session permission mode |
1081| `message` | For `"deny"` only: tells Claude why the permission was denied |
1082| `interrupt` | For `"deny"` only: if `true`, stops Claude |
1083
1084```json theme={null}
1085{
1086 "hookSpecificOutput": {
1087 "hookEventName": "PermissionRequest",
1088 "decision": {
1089 "behavior": "allow",
1090 "updatedInput": {
1091 "command": "npm run lint"
1092 }
1093 }
1094 }
598}1095}
599```1096```
600 1097
601| Field | Type | Description |1098#### Permission update entries
602| :---------- | :----- | :----------------------------------------- |1099
603| `file_path` | string | Absolute path to the file to read |1100The `updatedPermissions` output field and the [`permission_suggestions` input field](#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.
604| `offset` | number | Optional line number to start reading from |1101
605| `limit` | number | Optional number of lines to read |1102| `type` | Fields | Effect |
1103| :------------------ | :--------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1104| `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"` |
1105| `replaceRules` | `rules`, `behavior`, `destination` | Replaces all rules of the given `behavior` at the `destination` with the provided `rules` |
1106| `removeRules` | `rules`, `behavior`, `destination` | Removes matching rules of the given `behavior` |
1107| `setMode` | `mode`, `destination` | Changes the permission mode. Valid modes are `default`, `acceptEdits`, `dontAsk`, `bypassPermissions`, and `plan` |
1108| `addDirectories` | `directories`, `destination` | Adds working directories. `directories` is an array of path strings |
1109| `removeDirectories` | `directories`, `destination` | Removes working directories |
1110
1111The `destination` field on every entry determines whether the change stays in memory or persists to a settings file.
606 1112
607### PostToolUse Input1113| `destination` | Writes to |
1114| :---------------- | :---------------------------------------------- |
1115| `session` | in-memory only, discarded when the session ends |
1116| `localSettings` | `.claude/settings.local.json` |
1117| `projectSettings` | `.claude/settings.json` |
1118| `userSettings` | `~/.claude/settings.json` |
608 1119
609The exact schema for `tool_input` and `tool_response` depends on the tool.1120A 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.
1121
1122### PostToolUse
1123
1124Runs immediately after a tool completes successfully.
1125
1126Matches on tool name, same values as PreToolUse.
1127
1128#### PostToolUse input
1129
1130`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.
610 1131
611```json theme={null}1132```json theme={null}
612{1133{
628}1149}
629```1150```
630 1151
631### Notification Input1152#### PostToolUse decision control
1153
1154`PostToolUse` hooks can provide feedback to Claude after tool execution. In addition to the [JSON output fields](#json-output) available to all hooks, your hook script can return these event-specific fields:
1155
1156| Field | Description |
1157| :--------------------- | :----------------------------------------------------------------------------------------- |
1158| `decision` | `"block"` prompts Claude with the `reason`. Omit to allow the action to proceed |
1159| `reason` | Explanation shown to Claude when `decision` is `"block"` |
1160| `additionalContext` | Additional context for Claude to consider |
1161| `updatedMCPToolOutput` | For [MCP tools](#match-mcp-tools) only: replaces the tool's output with the provided value |
1162
1163```json theme={null}
1164{
1165 "decision": "block",
1166 "reason": "Explanation for decision",
1167 "hookSpecificOutput": {
1168 "hookEventName": "PostToolUse",
1169 "additionalContext": "Additional information for Claude"
1170 }
1171}
1172```
1173
1174### PostToolUseFailure
1175
1176Runs 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.
1177
1178Matches on tool name, same values as PreToolUse.
1179
1180#### PostToolUseFailure input
1181
1182PostToolUseFailure hooks receive the same `tool_name` and `tool_input` fields as PostToolUse, along with error information as top-level fields:
1183
1184```json theme={null}
1185{
1186 "session_id": "abc123",
1187 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
1188 "cwd": "/Users/...",
1189 "permission_mode": "default",
1190 "hook_event_name": "PostToolUseFailure",
1191 "tool_name": "Bash",
1192 "tool_input": {
1193 "command": "npm test",
1194 "description": "Run test suite"
1195 },
1196 "tool_use_id": "toolu_01ABC123...",
1197 "error": "Command exited with non-zero status code 1",
1198 "is_interrupt": false
1199}
1200```
1201
1202| Field | Description |
1203| :------------- | :------------------------------------------------------------------------------ |
1204| `error` | String describing what went wrong |
1205| `is_interrupt` | Optional boolean indicating whether the failure was caused by user interruption |
1206
1207#### PostToolUseFailure decision control
1208
1209`PostToolUseFailure` hooks can provide context to Claude after a tool failure. In addition to the [JSON output fields](#json-output) available to all hooks, your hook script can return these event-specific fields:
1210
1211| Field | Description |
1212| :------------------ | :------------------------------------------------------------ |
1213| `additionalContext` | Additional context for Claude to consider alongside the error |
1214
1215```json theme={null}
1216{
1217 "hookSpecificOutput": {
1218 "hookEventName": "PostToolUseFailure",
1219 "additionalContext": "Additional information about the failure for Claude"
1220 }
1221}
1222```
1223
1224### PermissionDenied
1225
1226Runs when the [auto mode](/en/permission-modes#eliminate-prompts-with-auto-mode) classifier denies a tool call. This hook only fires in auto mode: it does not 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.
1227
1228Matches on tool name, same values as PreToolUse.
1229
1230#### PermissionDenied input
1231
1232In addition to the [common input fields](#common-input-fields), PermissionDenied hooks receive `tool_name`, `tool_input`, `tool_use_id`, and `reason`.
1233
1234```json theme={null}
1235{
1236 "session_id": "abc123",
1237 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
1238 "cwd": "/Users/...",
1239 "permission_mode": "auto",
1240 "hook_event_name": "PermissionDenied",
1241 "tool_name": "Bash",
1242 "tool_input": {
1243 "command": "rm -rf /tmp/build",
1244 "description": "Clean build directory"
1245 },
1246 "tool_use_id": "toolu_01ABC123...",
1247 "reason": "Auto mode denied: command targets a path outside the project"
1248}
1249```
1250
1251| Field | Description |
1252| :------- | :------------------------------------------------------------ |
1253| `reason` | The classifier's explanation for why the tool call was denied |
1254
1255#### PermissionDenied decision control
1256
1257PermissionDenied hooks can tell the model it may retry the denied tool call. Return a JSON object with `hookSpecificOutput.retry` set to `true`:
1258
1259```json theme={null}
1260{
1261 "hookSpecificOutput": {
1262 "hookEventName": "PermissionDenied",
1263 "retry": true
1264 }
1265}
1266```
1267
1268When `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 does not return JSON, or returns `retry: false`, the denial stands and the model receives the original rejection message.
1269
1270### Notification
1271
1272Runs when Claude Code sends notifications. Matches on notification type: `permission_prompt`, `idle_prompt`, `auth_success`, `elicitation_dialog`. Omit the matcher to run hooks for all notification types.
1273
1274Use 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:
1275
1276```json theme={null}
1277{
1278 "hooks": {
1279 "Notification": [
1280 {
1281 "matcher": "permission_prompt",
1282 "hooks": [
1283 {
1284 "type": "command",
1285 "command": "/path/to/permission-alert.sh"
1286 }
1287 ]
1288 },
1289 {
1290 "matcher": "idle_prompt",
1291 "hooks": [
1292 {
1293 "type": "command",
1294 "command": "/path/to/idle-notification.sh"
1295 }
1296 ]
1297 }
1298 ]
1299 }
1300}
1301```
1302
1303#### Notification input
1304
1305In addition to the [common input fields](#common-input-fields), Notification hooks receive `message` with the notification text, an optional `title`, and `notification_type` indicating which type fired.
1306
1307```json theme={null}
1308{
1309 "session_id": "abc123",
1310 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
1311 "cwd": "/Users/...",
1312 "hook_event_name": "Notification",
1313 "message": "Claude needs your permission to use Bash",
1314 "title": "Permission needed",
1315 "notification_type": "permission_prompt"
1316}
1317```
1318
1319Notification hooks cannot block or modify notifications. In addition to the [JSON output fields](#json-output) available to all hooks, you can return `additionalContext` to add context to the conversation:
1320
1321| Field | Description |
1322| :------------------ | :------------------------------- |
1323| `additionalContext` | String added to Claude's context |
1324
1325### SubagentStart
1326
1327Runs when a Claude Code subagent is spawned via the Agent tool. Supports matchers to filter by agent type name (built-in agents like `Bash`, `Explore`, `Plan`, or custom agent names from `.claude/agents/`).
1328
1329#### SubagentStart input
1330
1331In addition to the [common input fields](#common-input-fields), SubagentStart hooks receive `agent_id` with the unique identifier for the subagent and `agent_type` with the agent name (built-in agents like `"Bash"`, `"Explore"`, `"Plan"`, or custom agent names).
1332
1333```json theme={null}
1334{
1335 "session_id": "abc123",
1336 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
1337 "cwd": "/Users/...",
1338 "hook_event_name": "SubagentStart",
1339 "agent_id": "agent-abc123",
1340 "agent_type": "Explore"
1341}
1342```
1343
1344SubagentStart hooks cannot block subagent creation, but they can inject context into the subagent. In addition to the [JSON output fields](#json-output) available to all hooks, you can return:
1345
1346| Field | Description |
1347| :------------------ | :------------------------------------- |
1348| `additionalContext` | String added to the subagent's context |
1349
1350```json theme={null}
1351{
1352 "hookSpecificOutput": {
1353 "hookEventName": "SubagentStart",
1354 "additionalContext": "Follow security guidelines for this task"
1355 }
1356}
1357```
1358
1359### SubagentStop
1360
1361Runs when a Claude Code subagent has finished responding. Matches on agent type, same values as SubagentStart.
1362
1363#### SubagentStop input
1364
1365In addition to the [common input fields](#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.
1366
1367```json theme={null}
1368{
1369 "session_id": "abc123",
1370 "transcript_path": "~/.claude/projects/.../abc123.jsonl",
1371 "cwd": "/Users/...",
1372 "permission_mode": "default",
1373 "hook_event_name": "SubagentStop",
1374 "stop_hook_active": false,
1375 "agent_id": "def456",
1376 "agent_type": "Explore",
1377 "agent_transcript_path": "~/.claude/projects/.../abc123/subagents/agent-def456.jsonl",
1378 "last_assistant_message": "Analysis complete. Found 3 potential issues..."
1379}
1380```
1381
1382SubagentStop hooks use the same decision control format as [Stop hooks](#stop-decision-control).
1383
1384### TaskCreated
1385
1386Runs 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.
1387
1388When 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 do not support matchers and fire on every occurrence.
1389
1390#### TaskCreated input
1391
1392In addition to the [common input fields](#common-input-fields), TaskCreated hooks receive `task_id`, `task_subject`, and optionally `task_description`, `teammate_name`, and `team_name`.
1393
1394```json theme={null}
1395{
1396 "session_id": "abc123",
1397 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
1398 "cwd": "/Users/...",
1399 "permission_mode": "default",
1400 "hook_event_name": "TaskCreated",
1401 "task_id": "task-001",
1402 "task_subject": "Implement user authentication",
1403 "task_description": "Add login and signup endpoints",
1404 "teammate_name": "implementer",
1405 "team_name": "my-project"
1406}
1407```
1408
1409| Field | Description |
1410| :----------------- | :---------------------------------------------------- |
1411| `task_id` | Identifier of the task being created |
1412| `task_subject` | Title of the task |
1413| `task_description` | Detailed description of the task. May be absent |
1414| `teammate_name` | Name of the teammate creating the task. May be absent |
1415| `team_name` | Name of the team. May be absent |
1416
1417#### TaskCreated decision control
1418
1419TaskCreated hooks support two ways to control task creation:
1420
1421* **Exit code 2**: the task is not created and the stderr message is fed back to the model as feedback.
1422* **JSON `{"continue": false, "stopReason": "..."}`**: stops the teammate entirely, matching `Stop` hook behavior. The `stopReason` is shown to the user.
1423
1424This example blocks tasks whose subjects don't follow the required format:
1425
1426```bash theme={null}
1427#!/bin/bash
1428INPUT=$(cat)
1429TASK_SUBJECT=$(echo "$INPUT" | jq -r '.task_subject')
1430
1431if [[ ! "$TASK_SUBJECT" =~ ^\[TICKET-[0-9]+\] ]]; then
1432 echo "Task subject must start with a ticket number, e.g. '[TICKET-123] Add feature'" >&2
1433 exit 2
1434fi
1435
1436exit 0
1437```
1438
1439### TaskCompleted
1440
1441Runs 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](/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.
1442
1443When 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 do not support matchers and fire on every occurrence.
1444
1445#### TaskCompleted input
1446
1447In addition to the [common input fields](#common-input-fields), TaskCompleted hooks receive `task_id`, `task_subject`, and optionally `task_description`, `teammate_name`, and `team_name`.
1448
1449```json theme={null}
1450{
1451 "session_id": "abc123",
1452 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
1453 "cwd": "/Users/...",
1454 "permission_mode": "default",
1455 "hook_event_name": "TaskCompleted",
1456 "task_id": "task-001",
1457 "task_subject": "Implement user authentication",
1458 "task_description": "Add login and signup endpoints",
1459 "teammate_name": "implementer",
1460 "team_name": "my-project"
1461}
1462```
1463
1464| Field | Description |
1465| :----------------- | :------------------------------------------------------ |
1466| `task_id` | Identifier of the task being completed |
1467| `task_subject` | Title of the task |
1468| `task_description` | Detailed description of the task. May be absent |
1469| `teammate_name` | Name of the teammate completing the task. May be absent |
1470| `team_name` | Name of the team. May be absent |
1471
1472#### TaskCompleted decision control
1473
1474TaskCompleted hooks support two ways to control task completion:
1475
1476* **Exit code 2**: the task is not marked as completed and the stderr message is fed back to the model as feedback.
1477* **JSON `{"continue": false, "stopReason": "..."}`**: stops the teammate entirely, matching `Stop` hook behavior. The `stopReason` is shown to the user.
1478
1479This example runs tests and blocks task completion if they fail:
1480
1481```bash theme={null}
1482#!/bin/bash
1483INPUT=$(cat)
1484TASK_SUBJECT=$(echo "$INPUT" | jq -r '.task_subject')
1485
1486# Run the test suite
1487if ! npm test 2>&1; then
1488 echo "Tests not passing. Fix failing tests before completing: $TASK_SUBJECT" >&2
1489 exit 2
1490fi
1491
1492exit 0
1493```
1494
1495### Stop
1496
1497Runs when the main Claude Code agent has finished responding. Does not run if
1498the stoppage occurred due to a user interrupt. API errors fire
1499[StopFailure](#stopfailure) instead.
1500
1501#### Stop input
1502
1503In addition to the [common input fields](#common-input-fields), Stop hooks receive `stop_hook_active` and `last_assistant_message`. 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 prevent Claude Code from running indefinitely. The `last_assistant_message` field contains the text content of Claude's final response, so hooks can access it without parsing the transcript file.
1504
1505```json theme={null}
1506{
1507 "session_id": "abc123",
1508 "transcript_path": "~/.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
1509 "cwd": "/Users/...",
1510 "permission_mode": "default",
1511 "hook_event_name": "Stop",
1512 "stop_hook_active": true,
1513 "last_assistant_message": "I've completed the refactoring. Here's a summary..."
1514}
1515```
1516
1517#### Stop decision control
1518
1519`Stop` and `SubagentStop` hooks can control whether Claude continues. In addition to the [JSON output fields](#json-output) available to all hooks, your hook script can return these event-specific fields:
1520
1521| Field | Description |
1522| :--------- | :------------------------------------------------------------------------- |
1523| `decision` | `"block"` prevents Claude from stopping. Omit to allow Claude to stop |
1524| `reason` | Required when `decision` is `"block"`. Tells Claude why it should continue |
1525
1526```json theme={null}
1527{
1528 "decision": "block",
1529 "reason": "Must be provided when Claude is blocked from stopping"
1530}
1531```
1532
1533### StopFailure
1534
1535Runs instead of [Stop](#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 cannot complete a response due to rate limits, authentication problems, or other API errors.
1536
1537#### StopFailure input
1538
1539In addition to the [common input fields](#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.
1540
1541| Field | Description |
1542| :----------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1543| `error` | Error type: `rate_limit`, `authentication_failed`, `billing_error`, `invalid_request`, `server_error`, `max_output_tokens`, or `unknown` |
1544| `error_details` | Additional details about the error, when available |
1545| `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"` |
1546
1547```json theme={null}
1548{
1549 "session_id": "abc123",
1550 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
1551 "cwd": "/Users/...",
1552 "hook_event_name": "StopFailure",
1553 "error": "rate_limit",
1554 "error_details": "429 Too Many Requests",
1555 "last_assistant_message": "API Error: Rate limit reached"
1556}
1557```
1558
1559StopFailure hooks have no decision control. They run for notification and logging purposes only.
1560
1561### TeammateIdle
1562
1563Runs when an [agent team](/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.
1564
1565When 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 do not support matchers and fire on every occurrence.
1566
1567#### TeammateIdle input
1568
1569In addition to the [common input fields](#common-input-fields), TeammateIdle hooks receive `teammate_name` and `team_name`.
1570
1571```json theme={null}
1572{
1573 "session_id": "abc123",
1574 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
1575 "cwd": "/Users/...",
1576 "permission_mode": "default",
1577 "hook_event_name": "TeammateIdle",
1578 "teammate_name": "researcher",
1579 "team_name": "my-project"
1580}
1581```
1582
1583| Field | Description |
1584| :-------------- | :-------------------------------------------- |
1585| `teammate_name` | Name of the teammate that is about to go idle |
1586| `team_name` | Name of the team |
1587
1588#### TeammateIdle decision control
1589
1590TeammateIdle hooks support two ways to control teammate behavior:
1591
1592* **Exit code 2**: the teammate receives the stderr message as feedback and continues working instead of going idle.
1593* **JSON `{"continue": false, "stopReason": "..."}`**: stops the teammate entirely, matching `Stop` hook behavior. The `stopReason` is shown to the user.
1594
1595This example checks that a build artifact exists before allowing a teammate to go idle:
1596
1597```bash theme={null}
1598#!/bin/bash
1599
1600if [ ! -f "./dist/output.js" ]; then
1601 echo "Build artifact missing. Run the build before stopping." >&2
1602 exit 2
1603fi
1604
1605exit 0
1606```
1607
1608### ConfigChange
1609
1610Runs when a configuration file changes during a session. Use this to audit settings changes, enforce security policies, or block unauthorized modifications to configuration files.
1611
1612ConfigChange 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.
1613
1614The matcher filters on the configuration source:
1615
1616| Matcher | When it fires |
1617| :----------------- | :---------------------------------------- |
1618| `user_settings` | `~/.claude/settings.json` changes |
1619| `project_settings` | `.claude/settings.json` changes |
1620| `local_settings` | `.claude/settings.local.json` changes |
1621| `policy_settings` | Managed policy settings change |
1622| `skills` | A skill file in `.claude/skills/` changes |
1623
1624This example logs all configuration changes for security auditing:
1625
1626```json theme={null}
1627{
1628 "hooks": {
1629 "ConfigChange": [
1630 {
1631 "hooks": [
1632 {
1633 "type": "command",
1634 "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/audit-config-change.sh"
1635 }
1636 ]
1637 }
1638 ]
1639 }
1640}
1641```
1642
1643#### ConfigChange input
1644
1645In addition to the [common input fields](#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.
1646
1647```json theme={null}
1648{
1649 "session_id": "abc123",
1650 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
1651 "cwd": "/Users/...",
1652 "hook_event_name": "ConfigChange",
1653 "source": "project_settings",
1654 "file_path": "/Users/.../my-project/.claude/settings.json"
1655}
1656```
1657
1658#### ConfigChange decision control
1659
1660ConfigChange 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.
1661
1662| Field | Description |
1663| :--------- | :--------------------------------------------------------------------------------------- |
1664| `decision` | `"block"` prevents the configuration change from being applied. Omit to allow the change |
1665| `reason` | Explanation shown to the user when `decision` is `"block"` |
1666
1667```json theme={null}
1668{
1669 "decision": "block",
1670 "reason": "Configuration changes to project settings require admin approval"
1671}
1672```
1673
1674`policy_settings` changes cannot 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.
1675
1676### CwdChanged
1677
1678Runs 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](#filechanged) for tools like [direnv](https://direnv.net/) that manage per-directory environment.
1679
1680CwdChanged 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](#persist-environment-variables). Only `type: "command"` hooks are supported.
1681
1682CwdChanged does not support matchers and fires on every directory change.
1683
1684#### CwdChanged input
1685
1686In addition to the [common input fields](#common-input-fields), CwdChanged hooks receive `old_cwd` and `new_cwd`.
1687
1688```json theme={null}
1689{
1690 "session_id": "abc123",
1691 "transcript_path": "/Users/.../.claude/projects/.../transcript.jsonl",
1692 "cwd": "/Users/my-project/src",
1693 "hook_event_name": "CwdChanged",
1694 "old_cwd": "/Users/my-project",
1695 "new_cwd": "/Users/my-project/src"
1696}
1697```
1698
1699#### CwdChanged output
1700
1701In addition to the [JSON output fields](#json-output) available to all hooks, CwdChanged hooks can return `watchPaths` to dynamically set which file paths [FileChanged](#filechanged) watches:
1702
1703| Field | Description |
1704| :----------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
1705| `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 |
1706
1707CwdChanged hooks have no decision control. They cannot block the directory change.
1708
1709### FileChanged
1710
1711Runs when a watched file changes on disk. The `matcher` field in your hook configuration controls which filenames to watch: it is a pipe-separated list of basenames (filenames without directory paths, for example `".envrc|.env"`). The same `matcher` value is also used to filter which hooks run when a file changes, matching against the basename of the changed file. Useful for reloading environment variables when project configuration files are modified.
1712
1713FileChanged 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](#persist-environment-variables). Only `type: "command"` hooks are supported.
1714
1715#### FileChanged input
1716
1717In addition to the [common input fields](#common-input-fields), FileChanged hooks receive `file_path` and `event`.
1718
1719| Field | Description |
1720| :---------- | :---------------------------------------------------------------------------------------------- |
1721| `file_path` | Absolute path to the file that changed |
1722| `event` | What happened: `"change"` (file modified), `"add"` (file created), or `"unlink"` (file deleted) |
1723
1724```json theme={null}
1725{
1726 "session_id": "abc123",
1727 "transcript_path": "/Users/.../.claude/projects/.../transcript.jsonl",
1728 "cwd": "/Users/my-project",
1729 "hook_event_name": "FileChanged",
1730 "file_path": "/Users/my-project/.envrc",
1731 "event": "change"
1732}
1733```
1734
1735#### FileChanged output
1736
1737In addition to the [JSON output fields](#json-output) available to all hooks, FileChanged hooks can return `watchPaths` to dynamically update which file paths are watched:
1738
1739| Field | Description |
1740| :----------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1741| `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 |
1742
1743FileChanged hooks have no decision control. They cannot block the file change from occurring.
1744
1745### WorktreeCreate
1746
1747When you run `claude --worktree` or a [subagent uses `isolation: "worktree"`](/en/sub-agents#choose-the-subagent-scope), Claude Code creates an isolated working copy using `git worktree`. If you configure a WorktreeCreate hook, it replaces the default git behavior, letting you use a different version control system like SVN, Perforce, or Mercurial.
1748
1749Because the hook replaces the default behavior entirely, [`.worktreeinclude`](/en/common-workflows#copy-gitignored-files-to-worktrees) is not processed. If you need to copy local configuration files like `.env` into the new worktree, do it inside your hook script.
1750
1751The hook must return the absolute path to the created worktree directory. Claude Code uses this path as the working directory for the isolated session. Command hooks print it on stdout; HTTP hooks return it via `hookSpecificOutput.worktreePath`.
1752
1753This example creates an SVN working copy and prints the path for Claude Code to use. Replace the repository URL with your own:
1754
1755```json theme={null}
1756{
1757 "hooks": {
1758 "WorktreeCreate": [
1759 {
1760 "hooks": [
1761 {
1762 "type": "command",
1763 "command": "bash -c 'NAME=$(jq -r .name); DIR=\"$HOME/.claude/worktrees/$NAME\"; svn checkout https://svn.example.com/repo/trunk \"$DIR\" >&2 && echo \"$DIR\"'"
1764 }
1765 ]
1766 }
1767 ]
1768 }
1769}
1770```
1771
1772The 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.
1773
1774#### WorktreeCreate input
1775
1776In addition to the [common input fields](#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`).
1777
1778```json theme={null}
1779{
1780 "session_id": "abc123",
1781 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
1782 "cwd": "/Users/...",
1783 "hook_event_name": "WorktreeCreate",
1784 "name": "feature-auth"
1785}
1786```
1787
1788#### WorktreeCreate output
1789
1790WorktreeCreate hooks do not use the standard allow/block decision model. Instead, the hook's success or failure determines the outcome. The hook must return the absolute path to the created worktree directory:
1791
1792* **Command hooks** (`type: "command"`): print the path on stdout.
1793* **HTTP hooks** (`type: "http"`): return `{ "hookSpecificOutput": { "hookEventName": "WorktreeCreate", "worktreePath": "/absolute/path" } }` in the response body.
1794
1795If the hook fails or produces no path, worktree creation fails with an error.
1796
1797### WorktreeRemove
1798
1799The cleanup counterpart to [WorktreeCreate](#worktreecreate). This hook fires 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. For git-based worktrees, Claude 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.
1800
1801Claude Code passes the path returned by WorktreeCreate as `worktree_path` in the hook input. This example reads that path and removes the directory:
1802
1803```json theme={null}
1804{
1805 "hooks": {
1806 "WorktreeRemove": [
1807 {
1808 "hooks": [
1809 {
1810 "type": "command",
1811 "command": "bash -c 'jq -r .worktree_path | xargs rm -rf'"
1812 }
1813 ]
1814 }
1815 ]
1816 }
1817}
1818```
1819
1820#### WorktreeRemove input
1821
1822In addition to the [common input fields](#common-input-fields), WorktreeRemove hooks receive the `worktree_path` field, which is the absolute path to the worktree being removed.
632 1823
633```json theme={null}1824```json theme={null}
634{1825{
635 "session_id": "abc123",1826 "session_id": "abc123",
636 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",1827 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
637 "cwd": "/Users/...",1828 "cwd": "/Users/...",
638 "permission_mode": "default",1829 "hook_event_name": "WorktreeRemove",
639 "hook_event_name": "Notification",1830 "worktree_path": "/Users/.../my-project/.claude/worktrees/feature-auth"
640 "message": "Claude needs your permission to use Bash",
641 "notification_type": "permission_prompt"
642}1831}
643```1832```
644 1833
645### UserPromptSubmit Input1834WorktreeRemove hooks have no decision control. They cannot block worktree removal but can perform cleanup tasks like removing version control state or archiving changes. Hook failures are logged in debug mode only.
646 1835
647```json theme={null}1836### PreCompact
648{
649 "session_id": "abc123",
650 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
651 "cwd": "/Users/...",
652 "permission_mode": "default",
653 "hook_event_name": "UserPromptSubmit",
654 "prompt": "Write a function to calculate the factorial of a number"
655}
656```
657 1837
658### Stop and SubagentStop Input1838Runs before Claude Code is about to run a compact operation.
659 1839
660`stop_hook_active` is true when Claude Code is already continuing as a result of1840The matcher value indicates whether compaction was triggered manually or automatically:
661a stop hook. Check this value or process the transcript to prevent Claude Code
662from running indefinitely.
663 1841
664```json theme={null}1842| Matcher | When it fires |
665{1843| :------- | :------------------------------------------- |
666 "session_id": "abc123",1844| `manual` | `/compact` |
667 "transcript_path": "~/.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",1845| `auto` | Auto-compact when the context window is full |
668 "permission_mode": "default",
669 "hook_event_name": "Stop",
670 "stop_hook_active": true
671}
672```
673 1846
674### PreCompact Input1847#### PreCompact input
675 1848
676For `manual`, `custom_instructions` comes from what the user passes into1849In addition to the [common input fields](#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.
677`/compact`. For `auto`, `custom_instructions` is empty.
678 1850
679```json theme={null}1851```json theme={null}
680{1852{
681 "session_id": "abc123",1853 "session_id": "abc123",
682 "transcript_path": "~/.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",1854 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
683 "permission_mode": "default",1855 "cwd": "/Users/...",
684 "hook_event_name": "PreCompact",1856 "hook_event_name": "PreCompact",
685 "trigger": "manual",1857 "trigger": "manual",
686 "custom_instructions": ""1858 "custom_instructions": ""
687}1859}
688```1860```
689 1861
690### SessionStart Input1862### PostCompact
691 1863
692```json theme={null}1864Runs 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.
693{1865
694 "session_id": "abc123",1866The same matcher values apply as for `PreCompact`:
695 "transcript_path": "~/.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",1867
696 "permission_mode": "default",1868| Matcher | When it fires |
697 "hook_event_name": "SessionStart",1869| :------- | :------------------------------------------------- |
698 "source": "startup"1870| `manual` | After `/compact` |
699}1871| `auto` | After auto-compact when the context window is full |
700```1872
1873#### PostCompact input
701 1874
702### SessionEnd Input1875In addition to the [common input fields](#common-input-fields), PostCompact hooks receive `trigger` and `compact_summary`. The `compact_summary` field contains the conversation summary generated by the compact operation.
703 1876
704```json theme={null}1877```json theme={null}
705{1878{
706 "session_id": "abc123",1879 "session_id": "abc123",
707 "transcript_path": "~/.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",1880 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
708 "cwd": "/Users/...",1881 "cwd": "/Users/...",
709 "permission_mode": "default",1882 "hook_event_name": "PostCompact",
710 "hook_event_name": "SessionEnd",1883 "trigger": "manual",
711 "reason": "exit"1884 "compact_summary": "Summary of the compacted conversation..."
712}1885}
713```1886```
714 1887
715## Hook Output1888PostCompact hooks have no decision control. They cannot affect the compaction result but can perform follow-up tasks.
716
717There are two mutually exclusive ways for hooks to return output back to Claude Code. The output
718communicates whether to block and any feedback that should be shown to Claude
719and the user.
720
721### Simple: Exit Code
722
723Hooks communicate status through exit codes, stdout, and stderr:
724
725* **Exit code 0**: Success. `stdout` is shown to the user in verbose mode
726 (ctrl+o), except for `UserPromptSubmit` and `SessionStart`, where stdout is
727 added to the context. JSON output in `stdout` is parsed for structured control
728 (see [Advanced: JSON Output](#advanced-json-output)).
729* **Exit code 2**: Blocking error. Only `stderr` is used as the error message
730 and fed back to Claude. The format is `[command]: {stderr}`. JSON in `stdout`
731 is **not** processed for exit code 2. See per-hook-event behavior below.
732* **Other exit codes**: Non-blocking error. `stderr` is shown to the user in verbose mode (ctrl+o) with
733 format `Failed with non-blocking status code: {stderr}`. If `stderr` is empty,
734 it shows `No stderr output`. Execution continues.
735
736<Warning>
737 Reminder: Claude Code does not see stdout if the exit code is 0, except for
738 the `UserPromptSubmit` hook where stdout is injected as context.
739</Warning>
740
741#### Exit Code 2 Behavior
742 1889
743| Hook Event | Behavior |1890### SessionEnd
744| ------------------- | ------------------------------------------------------------------ |
745| `PreToolUse` | Blocks the tool call, shows stderr to Claude |
746| `PermissionRequest` | Denies the permission, shows stderr to Claude |
747| `PostToolUse` | Shows stderr to Claude (tool already ran) |
748| `Notification` | N/A, shows stderr to user only |
749| `UserPromptSubmit` | Blocks prompt processing, erases prompt, shows stderr to user only |
750| `Stop` | Blocks stoppage, shows stderr to Claude |
751| `SubagentStop` | Blocks stoppage, shows stderr to Claude subagent |
752| `PreCompact` | N/A, shows stderr to user only |
753| `SessionStart` | N/A, shows stderr to user only |
754| `SessionEnd` | N/A, shows stderr to user only |
755 1891
756### Advanced: JSON Output1892Runs when a Claude Code session ends. Useful for cleanup tasks, logging session
1893statistics, or saving session state. Supports matchers to filter by exit reason.
757 1894
758Hooks can return structured JSON in `stdout` for more sophisticated control.1895The `reason` field in the hook input indicates why the session ended:
759 1896
760<Warning>1897| Reason | Description |
761 JSON output is only processed when the hook exits with code 0. If your hook1898| :---------------------------- | :----------------------------------------- |
762 exits with code 2 (blocking error), `stderr` text is used directly—any JSON in `stdout`1899| `clear` | Session cleared with `/clear` command |
763 is ignored. For other non-zero exit codes, only `stderr` is shown to the user in verbose mode (ctrl+o).1900| `resume` | Session switched via interactive `/resume` |
764</Warning>1901| `logout` | User logged out |
1902| `prompt_input_exit` | User exited while prompt input was visible |
1903| `bypass_permissions_disabled` | Bypass permissions mode was disabled |
1904| `other` | Other exit reasons |
765 1905
766#### Common JSON Fields1906#### SessionEnd input
767 1907
768All hook types can include these optional fields:1908In addition to the [common input fields](#common-input-fields), SessionEnd hooks receive a `reason` field indicating why the session ended. See the [reason table](#sessionend) above for all values.
769 1909
770```json theme={null}1910```json theme={null}
771{1911{
772 "continue": true, // Whether Claude should continue after hook execution (default: true)1912 "session_id": "abc123",
773 "stopReason": "string", // Message shown when continue is false1913 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
774 1914 "cwd": "/Users/...",
775 "suppressOutput": true, // Hide stdout from transcript mode (default: false)1915 "hook_event_name": "SessionEnd",
776 "systemMessage": "string" // Optional warning message shown to the user1916 "reason": "other"
777}1917}
778```1918```
779 1919
780If `continue` is false, Claude stops processing after the hooks run.1920SessionEnd hooks have no decision control. They cannot block session termination but can perform cleanup tasks.
781 1921
782* For `PreToolUse`, this is different from `"permissionDecision": "deny"`, which1922SessionEnd hooks have a default timeout of 1.5 seconds. This applies to session exit, `/clear`, and switching sessions via interactive `/resume`. If your hooks need more time, set the `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` environment variable to a higher value in milliseconds. Any per-hook `timeout` setting is also capped by this value.
783 only blocks a specific tool call and provides automatic feedback to Claude.
784* For `PostToolUse`, this is different from `"decision": "block"`, which
785 provides automated feedback to Claude.
786* For `UserPromptSubmit`, this prevents the prompt from being processed.
787* For `Stop` and `SubagentStop`, this takes precedence over any
788 `"decision": "block"` output.
789* In all cases, `"continue" = false` takes precedence over any
790 `"decision": "block"` output.
791 1923
792`stopReason` accompanies `continue` with a reason shown to the user, not shown1924```bash theme={null}
793to Claude.1925CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS=5000 claude
794 1926```
795#### `PreToolUse` Decision Control
796 1927
797`PreToolUse` hooks can control whether a tool call proceeds.1928### Elicitation
798 1929
799* `"allow"` bypasses the permission system. `permissionDecisionReason` is shown1930Runs 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.
800 to the user but not to Claude.
801* `"deny"` prevents the tool call from executing. `permissionDecisionReason` is
802 shown to Claude.
803* `"ask"` asks the user to confirm the tool call in the UI.
804 `permissionDecisionReason` is shown to the user but not to Claude.
805 1931
806Additionally, hooks can modify tool inputs before execution using `updatedInput`:1932The matcher field matches against the MCP server name.
807 1933
808* `updatedInput` modifies the tool's input parameters before the tool executes1934#### Elicitation input
809* Combine with `"permissionDecision": "allow"` to modify the input and auto-approve the tool call
810* Combine with `"permissionDecision": "ask"` to modify the input and show it to the user for confirmation
811 1935
812Hooks can also provide context to Claude using `additionalContext`:1936In addition to the [common input fields](#common-input-fields), Elicitation hooks receive `mcp_server_name`, `message`, and optional `mode`, `url`, `elicitation_id`, and `requested_schema` fields.
813 1937
814* `"hookSpecificOutput.additionalContext"` adds a string to Claude's context before the tool executes.1938For form-mode elicitation (the most common case):
815 1939
816```json theme={null}1940```json theme={null}
817{1941{
818 "hookSpecificOutput": {1942 "session_id": "abc123",
819 "hookEventName": "PreToolUse",1943 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
820 "permissionDecision": "allow",1944 "cwd": "/Users/...",
821 "permissionDecisionReason": "My reason here",1945 "permission_mode": "default",
822 "updatedInput": {1946 "hook_event_name": "Elicitation",
823 "field_to_modify": "new value"1947 "mcp_server_name": "my-mcp-server",
824 },1948 "message": "Please provide your credentials",
825 "additionalContext": "Current environment: production. Proceed with caution."1949 "mode": "form",
1950 "requested_schema": {
1951 "type": "object",
1952 "properties": {
1953 "username": { "type": "string", "title": "Username" }
1954 }
826 }1955 }
827}1956}
828```1957```
829 1958
830<Note>1959For URL-mode elicitation (browser-based authentication):
831 The `decision` and `reason` fields are deprecated for PreToolUse hooks.
832 Use `hookSpecificOutput.permissionDecision` and
833 `hookSpecificOutput.permissionDecisionReason` instead. The deprecated fields
834 `"approve"` and `"block"` map to `"allow"` and `"deny"` respectively.
835</Note>
836 1960
837#### `PermissionRequest` Decision Control1961```json theme={null}
1962{
1963 "session_id": "abc123",
1964 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
1965 "cwd": "/Users/...",
1966 "permission_mode": "default",
1967 "hook_event_name": "Elicitation",
1968 "mcp_server_name": "my-mcp-server",
1969 "message": "Please authenticate",
1970 "mode": "url",
1971 "url": "https://auth.example.com/login"
1972}
1973```
838 1974
839`PermissionRequest` hooks can allow or deny permission requests shown to the user.1975#### Elicitation output
840 1976
841* For `"behavior": "allow"` you can also optionally pass in an `"updatedInput"` that modifies the tool's input parameters before the tool executes.1977To respond programmatically without showing the dialog, return a JSON object with `hookSpecificOutput`:
842* 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.
843 1978
844```json theme={null}1979```json theme={null}
845{1980{
846 "hookSpecificOutput": {1981 "hookSpecificOutput": {
847 "hookEventName": "PermissionRequest",1982 "hookEventName": "Elicitation",
848 "decision": {1983 "action": "accept",
849 "behavior": "allow",1984 "content": {
850 "updatedInput": {1985 "username": "alice"
851 "command": "npm run lint"
852 }
853 }1986 }
854 }1987 }
855}1988}
856```1989```
857 1990
858#### `PostToolUse` Decision Control1991| Field | Values | Description |
1992| :-------- | :---------------------------- | :--------------------------------------------------------------- |
1993| `action` | `accept`, `decline`, `cancel` | Whether to accept, decline, or cancel the request |
1994| `content` | object | Form field values to submit. Only used when `action` is `accept` |
1995
1996Exit code 2 denies the elicitation and shows stderr to the user.
1997
1998### ElicitationResult
859 1999
860`PostToolUse` hooks can provide feedback to Claude after tool execution.2000Runs 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.
861 2001
862* `"block"` automatically prompts Claude with `reason`.2002The matcher field matches against the MCP server name.
863* `undefined` does nothing. `reason` is ignored.2003
864* `"hookSpecificOutput.additionalContext"` adds context for Claude to consider.2004#### ElicitationResult input
2005
2006In addition to the [common input fields](#common-input-fields), ElicitationResult hooks receive `mcp_server_name`, `action`, and optional `mode`, `elicitation_id`, and `content` fields.
2007
2008```json theme={null}
2009{
2010 "session_id": "abc123",
2011 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
2012 "cwd": "/Users/...",
2013 "permission_mode": "default",
2014 "hook_event_name": "ElicitationResult",
2015 "mcp_server_name": "my-mcp-server",
2016 "action": "accept",
2017 "content": { "username": "alice" },
2018 "mode": "form",
2019 "elicitation_id": "elicit-123"
2020}
2021```
2022
2023#### ElicitationResult output
2024
2025To override the user's response, return a JSON object with `hookSpecificOutput`:
865 2026
866```json theme={null}2027```json theme={null}
867{2028{
868 "decision": "block" | undefined,
869 "reason": "Explanation for decision",
870 "hookSpecificOutput": {2029 "hookSpecificOutput": {
871 "hookEventName": "PostToolUse",2030 "hookEventName": "ElicitationResult",
872 "additionalContext": "Additional information for Claude"2031 "action": "decline",
2032 "content": {}
873 }2033 }
874}2034}
875```2035```
876 2036
877#### `UserPromptSubmit` Decision Control2037| Field | Values | Description |
2038| :-------- | :---------------------------- | :--------------------------------------------------------------------- |
2039| `action` | `accept`, `decline`, `cancel` | Overrides the user's action |
2040| `content` | object | Overrides form field values. Only meaningful when `action` is `accept` |
2041
2042Exit code 2 blocks the response, changing the effective action to `decline`.
2043
2044## Prompt-based hooks
2045
2046In addition to command and HTTP 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.
2047
2048Events that support all four hook types (`command`, `http`, `prompt`, and `agent`):
2049
2050* `PermissionRequest`
2051* `PostToolUse`
2052* `PostToolUseFailure`
2053* `PreToolUse`
2054* `Stop`
2055* `SubagentStop`
2056* `TaskCompleted`
2057* `TaskCreated`
2058* `UserPromptSubmit`
2059
2060Events that support `command` and `http` hooks but not `prompt` or `agent`:
2061
2062* `ConfigChange`
2063* `CwdChanged`
2064* `Elicitation`
2065* `ElicitationResult`
2066* `FileChanged`
2067* `InstructionsLoaded`
2068* `Notification`
2069* `PermissionDenied`
2070* `PostCompact`
2071* `PreCompact`
2072* `SessionEnd`
2073* `StopFailure`
2074* `SubagentStart`
2075* `TeammateIdle`
2076* `WorktreeCreate`
2077* `WorktreeRemove`
2078
2079`SessionStart` supports only `command` hooks.
878 2080
879`UserPromptSubmit` hooks can control whether a user prompt is processed and add context.2081### How prompt-based hooks work
880
881**Adding context (exit code 0):**
882There are two ways to add context to the conversation:
883 2082
8841. **Plain text stdout** (simpler): Any non-JSON text written to stdout is added2083Instead of executing a Bash command, prompt-based hooks:
885 as context. This is the easiest way to inject information.
886 2084
8872. **JSON with `additionalContext`** (structured): Use the JSON format below for20851. Send the hook input and your prompt to a Claude model, Haiku by default
888 more control. The `additionalContext` field is added as context.20862. The LLM responds with structured JSON containing a decision
20873. Claude Code processes the decision automatically
889 2088
890Both methods work with exit code 0. Plain stdout is shown as hook output in2089### Prompt hook configuration
891the transcript; `additionalContext` is added more discretely.
892 2090
893**Blocking prompts:**2091Set `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.
894 2092
895* `"decision": "block"` prevents the prompt from being processed. The submitted2093This `Stop` hook asks the LLM to evaluate whether all tasks are complete before allowing Claude to finish:
896 prompt is erased from context. `"reason"` is shown to the user but not added
897 to context.
898* `"decision": undefined` (or omitted) allows the prompt to proceed normally.
899 2094
900```json theme={null}2095```json theme={null}
901{2096{
902 "decision": "block" | undefined,2097 "hooks": {
903 "reason": "Explanation for decision",2098 "Stop": [
904 "hookSpecificOutput": {2099 {
905 "hookEventName": "UserPromptSubmit",2100 "hooks": [
906 "additionalContext": "My additional context here"2101 {
2102 "type": "prompt",
2103 "prompt": "Evaluate if Claude should stop: $ARGUMENTS. Check if all tasks are complete."
2104 }
2105 ]
2106 }
2107 ]
907 }2108 }
908}2109}
909```2110```
910 2111
911<Note>2112| Field | Required | Description |
912 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 to2113| :-------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
913 block prompts or want more structured control.2114| `type` | yes | Must be `"prompt"` |
914</Note>2115| `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 |
915 2116| `model` | no | Model to use for evaluation. Defaults to a fast model |
916#### `Stop`/`SubagentStop` Decision Control2117| `timeout` | no | Timeout in seconds. Default: 30 |
917 2118
918`Stop` and `SubagentStop` hooks can control whether Claude must continue.2119### Response schema
919 2120
920* `"block"` prevents Claude from stopping. You must populate `reason` for Claude2121The LLM must respond with JSON containing:
921 to know how to proceed.
922* `undefined` allows Claude to stop. `reason` is ignored.
923 2122
924```json theme={null}2123```json theme={null}
925{2124{
926 "decision": "block" | undefined,2125 "ok": true | false,
927 "reason": "Must be provided when Claude is blocked from stopping"2126 "reason": "Explanation for the decision"
928}2127}
929```2128```
930 2129
931#### `SessionStart` Decision Control2130| Field | Description |
2131| :------- | :--------------------------------------------------------- |
2132| `ok` | `true` allows the action, `false` prevents it |
2133| `reason` | Required when `ok` is `false`. Explanation shown to Claude |
932 2134
933`SessionStart` hooks allow you to load in context at the start of a session.2135### Example: Multi-criteria Stop hook
934 2136
935* `"hookSpecificOutput.additionalContext"` adds the string to the context.2137This `Stop` hook uses a detailed prompt to check three conditions before allowing Claude to stop. If `"ok"` is `false`, Claude continues working with the provided reason as its next instruction. `SubagentStop` hooks use the same format to evaluate whether a [subagent](/en/sub-agents) should stop:
936* Multiple hooks' `additionalContext` values are concatenated.
937 2138
938```json theme={null}2139```json theme={null}
939{2140{
940 "hookSpecificOutput": {2141 "hooks": {
941 "hookEventName": "SessionStart",2142 "Stop": [
942 "additionalContext": "My additional context here"2143 {
2144 "hooks": [
2145 {
2146 "type": "prompt",
2147 "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.",
2148 "timeout": 30
2149 }
2150 ]
2151 }
2152 ]
943 }2153 }
944}2154}
945```2155```
946 2156
947#### `SessionEnd` Decision Control2157## Agent-based hooks
948 2158
949`SessionEnd` hooks run when a session ends. They cannot block session termination2159Agent-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.
950but can perform cleanup tasks.
951 2160
952#### Exit Code Example: Bash Command Validation2161### How agent hooks work
953 2162
954```python theme={null}2163When an agent hook fires:
955#!/usr/bin/env python3
956import json
957import re
958import sys
959 2164
960# Define validation rules as a list of (regex pattern, message) tuples21651. Claude Code spawns a subagent with your prompt and the hook's JSON input
961VALIDATION_RULES = [21662. The subagent can use tools like Read, Grep, and Glob to investigate
962 (21673. After up to 50 turns, the subagent returns a structured `{ "ok": true/false }` decision
963 r"\bgrep\b(?!.*\|)",21684. Claude Code processes the decision the same way as a prompt hook
964 "Use 'rg' (ripgrep) instead of 'grep' for better performance and features",
965 ),
966 (
967 r"\bfind\s+\S+\s+-name\b",
968 "Use 'rg --files | rg pattern' or 'rg --files -g pattern' instead of 'find -name' for better performance",
969 ),
970]
971 2169
2170Agent hooks are useful when verification requires inspecting actual files or test output, not just evaluating the hook input data alone.
972 2171
973def validate_command(command: str) -> list[str]:2172### Agent hook configuration
974 issues = []
975 for pattern, message in VALIDATION_RULES:
976 if re.search(pattern, command):
977 issues.append(message)
978 return issues
979 2173
2174Set `type` to `"agent"` and provide a `prompt` string. The configuration fields are the same as [prompt hooks](#prompt-hook-configuration), with a longer default timeout:
980 2175
981try:2176| Field | Required | Description |
982 input_data = json.load(sys.stdin)2177| :-------- | :------- | :------------------------------------------------------------------------------------------ |
983except json.JSONDecodeError as e:2178| `type` | yes | Must be `"agent"` |
984 print(f"Error: Invalid JSON input: {e}", file=sys.stderr)2179| `prompt` | yes | Prompt describing what to verify. Use `$ARGUMENTS` as a placeholder for the hook input JSON |
985 sys.exit(1)2180| `model` | no | Model to use. Defaults to a fast model |
2181| `timeout` | no | Timeout in seconds. Default: 60 |
986 2182
987tool_name = input_data.get("tool_name", "")2183The response schema is the same as prompt hooks: `{ "ok": true }` to allow or `{ "ok": false, "reason": "..." }` to block.
988tool_input = input_data.get("tool_input", {})
989command = tool_input.get("command", "")
990 2184
991if tool_name != "Bash" or not command:2185This `Stop` hook verifies that all unit tests pass before allowing Claude to finish:
992 sys.exit(1)
993 2186
994# Validate the command2187```json theme={null}
995issues = validate_command(command)2188{
996 2189 "hooks": {
997if issues:2190 "Stop": [
998 for message in issues:2191 {
999 print(f"• {message}", file=sys.stderr)2192 "hooks": [
1000 # Exit code 2 blocks tool call and shows stderr to Claude2193 {
1001 sys.exit(2)2194 "type": "agent",
2195 "prompt": "Verify that all unit tests pass. Run the test suite and check the results. $ARGUMENTS",
2196 "timeout": 120
2197 }
2198 ]
2199 }
2200 ]
2201 }
2202}
1002```2203```
1003 2204
1004#### JSON Output Example: UserPromptSubmit to Add Context and Validation2205## Run hooks in the background
1005
1006<Note>
1007 For `UserPromptSubmit` hooks, you can inject context using either method:
1008
1009 * **Plain text stdout** with exit code 0: Simplest approach, prints text
1010 * **JSON output** with exit code 0: Use `"decision": "block"` to reject prompts,
1011 or `additionalContext` for structured context injection
1012 2206
1013 Remember: Exit code 2 only uses `stderr` for the error message. To block using2207By 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 cannot 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.
1014 JSON (with a custom reason), use `"decision": "block"` with exit code 0.
1015</Note>
1016 2208
1017```python theme={null}2209### Configure an async hook
1018#!/usr/bin/env python3
1019import json
1020import sys
1021import re
1022import datetime
1023
1024# Load input from stdin
1025try:
1026 input_data = json.load(sys.stdin)
1027except json.JSONDecodeError as e:
1028 print(f"Error: Invalid JSON input: {e}", file=sys.stderr)
1029 sys.exit(1)
1030
1031prompt = input_data.get("prompt", "")
1032
1033# Check for sensitive patterns
1034sensitive_patterns = [
1035 (r"(?i)\b(password|secret|key|token)\s*[:=]", "Prompt contains potential secrets"),
1036]
1037
1038for pattern, message in sensitive_patterns:
1039 if re.search(pattern, prompt):
1040 # Use JSON output to block with a specific reason
1041 output = {
1042 "decision": "block",
1043 "reason": f"Security policy violation: {message}. Please rephrase your request without sensitive information."
1044 }
1045 print(json.dumps(output))
1046 sys.exit(0)
1047 2210
1048# Add current time to context2211Add `"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.
1049context = f"Current time: {datetime.datetime.now()}"
1050print(context)
1051 2212
1052"""2213This 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:
1053The following is also equivalent:
1054print(json.dumps({
1055 "hookSpecificOutput": {
1056 "hookEventName": "UserPromptSubmit",
1057 "additionalContext": context,
1058 },
1059}))
1060"""
1061 2214
1062# Allow the prompt to proceed with the additional context2215```json theme={null}
1063sys.exit(0)2216{
2217 "hooks": {
2218 "PostToolUse": [
2219 {
2220 "matcher": "Write",
2221 "hooks": [
2222 {
2223 "type": "command",
2224 "command": "/path/to/run-tests.sh",
2225 "async": true,
2226 "timeout": 120
2227 }
2228 ]
2229 }
2230 ]
2231 }
2232}
1064```2233```
1065 2234
1066#### JSON Output Example: PreToolUse with Approval2235The `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.
1067 2236
1068```python theme={null}2237### How async hooks execute
1069#!/usr/bin/env python3
1070import json
1071import sys
1072 2238
1073# Load input from stdin2239When 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.
1074try:
1075 input_data = json.load(sys.stdin)
1076except json.JSONDecodeError as e:
1077 print(f"Error: Invalid JSON input: {e}", file=sys.stderr)
1078 sys.exit(1)
1079 2240
1080tool_name = input_data.get("tool_name", "")2241After the background process exits, if the hook produced a JSON response with a `systemMessage` or `additionalContext` field, that content is delivered to Claude as context on the next conversation turn.
1081tool_input = input_data.get("tool_input", {})
1082 2242
1083# Example: Auto-approve file reads for documentation files2243Async hook completion notifications are suppressed by default. To see them, enable verbose mode with `Ctrl+O` or start Claude Code with `--verbose`.
1084if tool_name == "Read":
1085 file_path = tool_input.get("file_path", "")
1086 if file_path.endswith((".md", ".mdx", ".txt", ".json")):
1087 # Use JSON output to auto-approve the tool call
1088 output = {
1089 "decision": "approve",
1090 "reason": "Documentation file auto-approved",
1091 "suppressOutput": True # Don't show in verbose mode
1092 }
1093 print(json.dumps(output))
1094 sys.exit(0)
1095 2244
1096# For other cases, let the normal permission flow proceed2245### Example: run tests after file changes
1097sys.exit(0)
1098```
1099 2246
1100## Working with MCP Tools2247This 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`:
1101 2248
1102Claude Code hooks work seamlessly with2249```bash theme={null}
1103[Model Context Protocol (MCP) tools](/en/mcp). When MCP servers2250#!/bin/bash
1104provide tools, they appear with a special naming pattern that you can match in2251# run-tests-async.sh
1105your hooks.
1106 2252
1107### MCP Tool Naming2253# Read hook input from stdin
2254INPUT=$(cat)
2255FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
1108 2256
1109MCP tools follow the pattern `mcp__<server>__<tool>`, for example:2257# Only run tests for source files
2258if [[ "$FILE_PATH" != *.ts && "$FILE_PATH" != *.js ]]; then
2259 exit 0
2260fi
1110 2261
1111* `mcp__memory__create_entities` - Memory server's create entities tool2262# Run tests and report results via systemMessage
1112* `mcp__filesystem__read_file` - Filesystem server's read file tool2263RESULT=$(npm test 2>&1)
1113* `mcp__github__search_repositories` - GitHub server's search tool2264EXIT_CODE=$?
1114 2265
1115### Configuring Hooks for MCP Tools2266if [ $EXIT_CODE -eq 0 ]; then
2267 echo "{\"systemMessage\": \"Tests passed after editing $FILE_PATH\"}"
2268else
2269 echo "{\"systemMessage\": \"Tests failed after editing $FILE_PATH: $RESULT\"}"
2270fi
2271```
1116 2272
1117You can target specific MCP tools or entire MCP servers:2273Then add this configuration to `.claude/settings.json` in your project root. The `async: true` flag lets Claude keep working while tests run:
1118 2274
1119```json theme={null}2275```json theme={null}
1120{2276{
1121 "hooks": {2277 "hooks": {
1122 "PreToolUse": [2278 "PostToolUse": [
1123 {
1124 "matcher": "mcp__memory__.*",
1125 "hooks": [
1126 {
1127 "type": "command",
1128 "command": "echo 'Memory operation initiated' >> ~/mcp-operations.log"
1129 }
1130 ]
1131 },
1132 {2279 {
1133 "matcher": "mcp__.*__write.*",2280 "matcher": "Write|Edit",
1134 "hooks": [2281 "hooks": [
1135 {2282 {
1136 "type": "command",2283 "type": "command",
1137 "command": "/home/user/scripts/validate-mcp-write.py"2284 "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/run-tests-async.sh",
2285 "async": true,
2286 "timeout": 300
1138 }2287 }
1139 ]2288 ]
1140 }2289 }
1143}2292}
1144```2293```
1145 2294
1146## Examples2295### Limitations
1147
1148<Tip>
1149 For practical examples including code formatting, notifications, and file protection, see [More Examples](/en/hooks-guide#more-examples) in the get started guide.
1150</Tip>
1151
1152## Security Considerations
1153
1154### Disclaimer
1155
1156**USE AT YOUR OWN RISK**: Claude Code hooks execute arbitrary shell commands on
1157your system automatically. By using hooks, you acknowledge that:
1158
1159* You are solely responsible for the commands you configure
1160* Hooks can modify, delete, or access any files your user account can access
1161* Malicious or poorly written hooks can cause data loss or system damage
1162* Anthropic provides no warranty and assumes no liability for any damages
1163 resulting from hook usage
1164* You should thoroughly test hooks in a safe environment before production use
1165
1166Always review and understand any hook commands before adding them to your
1167configuration.
1168
1169### Security Best Practices
1170
1171Here are some key practices for writing more secure hooks:
1172
11731. **Validate and sanitize inputs** - Never trust input data blindly
11742. **Always quote shell variables** - Use `"$VAR"` not `$VAR`
11753. **Block path traversal** - Check for `..` in file paths
11764. **Use absolute paths** - Specify full paths for scripts (use
1177 "\$CLAUDE\_PROJECT\_DIR" for the project path)
11785. **Skip sensitive files** - Avoid `.env`, `.git/`, keys, etc.
1179
1180### Configuration Safety
1181
1182Direct edits to hooks in settings files don't take effect immediately. Claude
1183Code:
1184 2296
11851. Captures a snapshot of hooks at startup2297Async hooks have several constraints compared to synchronous hooks:
11862. Uses this snapshot throughout the session
11873. Warns if hooks are modified externally
11884. Requires review in `/hooks` menu for changes to apply
1189 2298
1190This prevents malicious hook modifications from affecting your current session.2299* Only `type: "command"` hooks support `async`. Prompt-based hooks cannot run asynchronously.
2300* Async hooks cannot block tool calls or return decisions. By the time the hook completes, the triggering action has already proceeded.
2301* Hook output is delivered on the next conversation turn. If the session is idle, the response waits until the next user interaction.
2302* Each execution creates a separate background process. There is no deduplication across multiple firings of the same async hook.
1191 2303
1192## Hook Execution Details2304## Security considerations
1193 2305
1194* **Timeout**: 60-second execution limit by default, configurable per command.2306### Disclaimer
1195 * A timeout for an individual command does not affect the other commands.
1196* **Parallelization**: All matching hooks run in parallel
1197* **Deduplication**: Multiple identical hook commands are deduplicated automatically
1198* **Environment**: Runs in current directory with Claude Code's environment
1199 * The `CLAUDE_PROJECT_DIR` environment variable is available and contains the
1200 absolute path to the project root directory (where Claude Code was started)
1201 * 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.
1202* **Input**: JSON via stdin
1203* **Output**:
1204 * PreToolUse/PermissionRequest/PostToolUse/Stop/SubagentStop: Progress shown in verbose mode (ctrl+o)
1205 * Notification/SessionEnd: Logged to debug only (`--debug`)
1206 * UserPromptSubmit/SessionStart: stdout added as context for Claude
1207
1208## Debugging
1209 2307
1210### Basic Troubleshooting2308Command hooks run with your system user's full permissions.
1211 2309
1212If your hooks aren't working:2310<Warning>
2311 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.
2312</Warning>
1213 2313
12141. **Check configuration** - Run `/hooks` to see if your hook is registered2314### Security best practices
12152. **Verify syntax** - Ensure your JSON settings are valid
12163. **Test commands** - Run hook commands manually first
12174. **Check permissions** - Make sure scripts are executable
12185. **Review logs** - Use `claude --debug` to see hook execution details
1219 2315
1220Common issues:2316Keep these practices in mind when writing hooks:
1221 2317
1222* **Quotes not escaped** - Use `\"` inside JSON strings2318* **Validate and sanitize inputs**: never trust input data blindly
1223* **Wrong matcher** - Check tool names match exactly (case-sensitive)2319* **Always quote shell variables**: use `"$VAR"` not `$VAR`
1224* **Command not found** - Use full paths for scripts2320* **Block path traversal**: check for `..` in file paths
2321* **Use absolute paths**: specify full paths for scripts, using `"$CLAUDE_PROJECT_DIR"` for the project root
2322* **Skip sensitive files**: avoid `.env`, `.git/`, keys, etc.
1225 2323
1226### Advanced Debugging2324## Windows PowerShell tool
1227 2325
1228For complex hook issues:2326On 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` (PowerShell 7+) with a fallback to `powershell.exe` (5.1).
1229 2327
12301. **Inspect hook execution** - Use `claude --debug` to see detailed hook2328```json theme={null}
1231 execution2329{
12322. **Validate JSON schemas** - Test hook input/output with external tools2330 "hooks": {
12333. **Check environment variables** - Verify Claude Code's environment is correct2331 "PostToolUse": [
12344. **Test edge cases** - Try hooks with unusual file paths or inputs2332 {
12355. **Monitor system resources** - Check for resource exhaustion during hook2333 "matcher": "Write",
1236 execution2334 "hooks": [
12376. **Use structured logging** - Implement logging in your hook scripts2335 {
2336 "type": "command",
2337 "shell": "powershell",
2338 "command": "Write-Host 'File written'"
2339 }
2340 ]
2341 }
2342 ]
2343 }
2344}
2345```
1238 2346
1239### Debug Output Example2347## Debug hooks
1240 2348
1241Use `claude --debug` to see hook execution details:2349Run `claude --debug` to see hook execution details, including which hooks matched, their exit codes, and output.
1242 2350
1243```2351```text theme={null}
1244[DEBUG] Executing hooks for PostToolUse:Write2352[DEBUG] Executing hooks for PostToolUse:Write
1245[DEBUG] Getting matching hook commands for PostToolUse with query: Write
1246[DEBUG] Found 1 hook matchers in settings
1247[DEBUG] Matched 1 hooks for query "Write"
1248[DEBUG] Found 1 hook commands to execute2353[DEBUG] Found 1 hook commands to execute
1249[DEBUG] Executing hook command: <Your command> with timeout 60000ms2354[DEBUG] Executing hook command: <Your command> with timeout 600000ms
1250[DEBUG] Hook command completed with status 0: <Your stdout>2355[DEBUG] Hook command completed with status 0: <Your stdout>
1251```2356```
1252 2357
1253Progress messages appear in verbose mode (ctrl+o) showing:2358For 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.
1254
1255* Which hook is running
1256* Command being executed
1257* Success/failure status
1258* Output or error messages
1259
1260
1261 2359
1262> To find navigation and other pages in this documentation, fetch the llms.txt file at: https://code.claude.com/docs/llms.txt2360For troubleshooting common issues like hooks not firing, infinite Stop hook loops, or configuration errors, see [Limitations and troubleshooting](/en/hooks-guide#limitations-and-troubleshooting) in the guide.
