Hooks reference changedhooks
Nearest release: v2.1.233, published 2 hours before this site recorded the change. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Recorded here
Lines+24added
Lines−22removed
From line
400
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits112to this page, all time
The whole hunk
from line 400, old and new numbered
/
This page is larger than the 256 KiB this site keeps, so one side of the diff below stops where the stored text does.
from line 400
400400* **[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.
401401* **[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.
402402* **[MCP tool hooks](#mcp-tool-hook-fields)** (`type: "mcp_tool"`): call a tool on an already-connected [MCP server](/docs/en/mcp). The tool's text output is treated like command-hook stdout.
403* **[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).
403* **[Prompt hooks](#prompt-and-agent-hook-fields)** (`type: "prompt"`): send a prompt to a Claude model for single-turn evaluation. The model returns its decision as JSON. See [Prompt-based hooks](#prompt-based-hooks).
404404* **[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. Agent hooks are experimental and may change. See [Agent-based hooks](#agent-based-hooks).
405405
406406All matching hooks run in parallel. If you define the same handler in more than one settings file, it runs once. A plugin's or skill's copy of the same handler stays separate.
from line 2367
23672367[StopFailure](#stopfailure) instead.
23682368
23692369<Tip>
2370 The [`/goal`](/docs/en/goal) command is a built-in shortcut for a session-scoped prompt-based Stop hook. Use it when you want Claude to keep working until a condition holds without writing hook configuration.
2370 The [`/goal`](/docs/en/goal) command is a built-in shortcut for a session-scoped prompt-based Stop hook. Use it when you want Claude to keep working toward a condition without writing hook configuration.
23712371</Tip>
23722372
23732373#### Stop input
from line 3129
31293129}
31303130```
31313131
3132| Field | Required | Description |
3133| :---------------- | :------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
3134| `type` | yes | Must be `"prompt"` |
3135| `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 |
3136| `model` | no | Model to use for evaluation. Defaults to a fast model |
3137| `timeout` | no | Timeout in seconds. Default: 30 |
3138| `continueOnBlock` | no | When the prompt returns `ok: false`, feed the reason back to Claude and continue the turn instead of stopping. Default: `false`. Implemented as `continue: true` on the resulting `decision: "block"`. See [Response schema](#response-schema) for per-event behavior |
3132| Field | Required | Description |
3133| :---------------- | :------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
3134| `type` | yes | Must be `"prompt"` |
3135| `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 |
3136| `model` | no | Model to use for evaluation. Defaults to a fast model |
3137| `timeout` | no | Timeout in seconds. Default: 30 |
3138| `continueOnBlock` | no | On the events it applies to, `true` feeds an `ok: false` reason back to Claude and continues instead of ending the turn. Default: `false`. See [Response schema](#response-schema) for per-event behavior |
31393139
31403140### Response schema
31413141
from line 3144
31443144```json theme={null}
31453145{
31463146 "ok": true | false,
3147 "reason": "Explanation for the decision"
3147 "reason": "Explanation for the decision",
3148 "impossible": true | false
31483149}
31493150```
31503151
3151| Field | Description |
3152| :------- | :---------------------------------------------------------------------------------------- |
3153| `ok` | `true` to allow. `false` produces a `decision: "block"`. See the per-event behavior below |
3154| `reason` | Required when `ok` is `false`. Used as the block reason |
3152| Field | Description |
3153| :----------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
3154| `ok` | `true` to allow. For `false`, see the per-event behavior below |
3155| `reason` | Required when `ok` is `false` |
3156| `impossible` | Optional. The model returns it with `ok: false` when it judges the condition can never be satisfied. On `Stop` and `SubagentStop`, Claude Code then lets the turn end instead of feeding the reason back. Agent hooks and other events ignore it |
31553157
31563158What happens on `ok: false` depends on the event:
31573159
3158* `Stop` and `SubagentStop`: the reason is fed back to Claude as its next instruction and the turn continues
3160* `Stop` and `SubagentStop`: the reason is fed back to Claude as its next instruction and the turn continues, unless the response also sets `impossible: true`, in which case Claude Code allows the stop and the turn ends
31593161* `PreToolUse`: the tool call is denied; by default the turn ends and the deny reason appears in the chat as a warning line. Set `continueOnBlock: true` to instead return the reason to Claude as the tool error so it can adjust and continue, equivalent to a command hook's `permissionDecision: "deny"`. Before v2.1.210, the deny reason was returned to Claude as the tool error and the turn continued
31603162* `PostToolUse`: by default the turn ends and the reason appears in the chat as a warning line. Set `continueOnBlock: true` to feed the reason back to Claude and continue the turn instead
31613163* `PostToolBatch`, `UserPromptSubmit`, and `UserPromptExpansion`: the turn ends and the reason appears as a warning line. These events end the turn on `decision: "block"` regardless of `continue`
from line 3171
31693171
31703172### Check multiple conditions before stopping
31713173
3172This `Stop` hook uses a detailed prompt to check three conditions before allowing Claude to stop. `SubagentStop` hooks use the same format to evaluate whether a [subagent](/docs/en/sub-agents) should stop. If `"ok"` is `false`, Claude continues working with the provided reason as its next instruction:
3174This `Stop` hook uses a detailed prompt to check three conditions before allowing Claude to stop. `SubagentStop` hooks use the same format to evaluate whether a [subagent](/docs/en/sub-agents) should stop. If the model returns `"ok": false` because the condition isn't met yet, Claude continues working with the provided reason as its next instruction:
31733175
31743176```json theme={null}
31753177{
from line 3206
320432061. Claude Code spawns a subagent with your prompt and the hook's JSON input
320532072. The subagent can use tools like Read, Grep, and Glob to investigate
320632083. After up to 50 turns, the subagent returns a structured `{ "ok": true/false }` decision
32074. Claude Code processes the decision the same way as a prompt hook with `continueOnBlock: true`, as described under [Agent hook configuration](#agent-hook-configuration)
32094. Claude Code allows the action if `ok` is `true`. If `ok` is `false`, Claude Code handles the block the same way as a prompt hook with `continueOnBlock: true` on that event, as listed under [Response schema](#response-schema)
32083210
32093211Agent hooks are useful when verification requires inspecting actual files or test output, not just evaluating the hook input data alone.
32103212
32113213### Agent hook configuration
32123214
3213Set `type` to `"agent"` and provide a `prompt` string. The configuration fields are the same as [prompt hooks](#prompt-hook-configuration) except `continueOnBlock`, with a longer default timeout:
3215Set `type` to `"agent"` and provide a `prompt` string. The configuration fields are the same as [prompt hooks](#prompt-hook-configuration), except that agent hooks have a longer default timeout and no `continueOnBlock` field:
32143216
32153217| Field | Required | Description |
32163218| :-------- | :------- | :------------------------------------------------------------------------------------------ |
from line 3221
32193221| `model` | no | Model to use. Defaults to a fast model |
32203222| `timeout` | no | Timeout in seconds. Default: 60 |
32213223
3222The response schema is the same as prompt hooks: `{ "ok": true }` to allow or `{ "ok": false, "reason": "..." }` to block. On `ok: false`, Claude Code handles an agent hook the way it handles a [prompt hook with `continueOnBlock: true`](#response-schema) on the same event; agent hooks have no `continueOnBlock` field.
3223
3224This `Stop` hook verifies that all unit tests pass before allowing Claude to finish:
3225
3226```json theme={null}
3227{
3228 "hooks": {
3229 "Stop": [
3230 {
3231 "hooks": [
3232 {
3233 "type": "agent",
3234 "prompt": "Verify that all unit tests pass. Run the test suite and check the results. $ARGUMENTS",
3235 "timeout": 120
3236 }
3237 ]
3238 }
3239 ]
3240 }
3241}
3242```
3243
3244## Run hooks in the background
3245
3246By default, hooks block Claude's execution until they complete. For long-running tasks like deployments, test suites, or external API calls, set `"async": true` to run the hook in the background while Claude continues working. Async hooks can't block or control Claude's behavior: response fields like `decision`, `permissionDecision
3224The response schema is `{ "ok": true }` to allow or `{ "ok": false, "reason": "..." }` to block. On `ok: false`, Claude Code handles an agent hook the way it handles a [prompt hook with `continueOnBlock: true`](#response-schema) on the same event; agent hooks have no `continueOnBlock` field, and don't support the prompt-hook `impossible` field.
No line in this hunk matches that.