One read of Claude Code CLIclaude-code-20261103T230701Z
11 pages moved out of 228 read.
Pages moved
11
significant first
Pages read
228
in this capture
Captured
23:07 UTC
Corpus hash
76751c2c8f72
corpus-hash
What this read moved
1-11 of 11agent-sdk/hooks Changed · +49 / -1 lines
### Block the action when a callback fails #### Events that behave differently #### Startup errors for `onFailure`
from line 220
220220| `matcher` | `string` | `undefined` | Pattern matched against the event's filter field, following the [rules for matchers in settings files](https://code.claude.com/docs/en/hooks.md#matcher-patterns). For tool hooks, that field is the tool name. Built-in tools include `Bash`, `Read`, `Write`, `Edit`, `Glob`, `Grep`, `WebFetch`, `Agent`, and others. See [Tool Input Types](https://code.claude.com/docs/en/agent-sdk/typescript.md#tool-input-types) for the full list. MCP tools use the pattern `mcp__<server>__<action>`, where `<server>` is the key you use in the `mcpServers` configuration, spelled as the [tool naming convention](https://code.claude.com/docs/en/agent-sdk/mcp.md#tool-naming-convention) describes. |
221221| `hooks` | `HookCallback[]` | - | Required. Array of callback functions to execute when the pattern matches |
222222| `timeout` | `number` | `undefined` | Timeout in seconds. When omitted, Claude Code applies the [event's default timeout](#hook-timeout). Your SDK callbacks follow the `command` hook defaults |
223| `onFailure` | `"continue" \| "block"` | `undefined` | What a failed callback does. Set `"block"` to [block the action when a callback fails](#block-the-action-when-a-callback-fails). In Python, use `on_failure` |
223224
224225Use the `matcher` pattern to target specific tools whenever possible. A matcher with `'Bash'` only runs for Bash commands, while omitting the pattern runs your callbacks for every occurrence of the event.
225226
from line 280
279280>
280281> Async outputs can't block, modify, or inject context into the operation since the agent has already moved on. Use them only for side effects like logging, metrics, or notifications.
281282
283### Block the action when a callback fails
284
285On most events, if a callback throws or returns output that fails validation, the action goes ahead and your app receives an [`SDKInformationalMessage`](https://code.claude.com/docs/en/agent-sdk/typescript#sdkinformationalmessage) warning whose `tag` is `hook_callback_failed`. A `PreToolUse` guard that crashes then lets the tool call reach the normal permission flow. A callback that returns nothing, such as a path with no `return`, also counts as failing. In Python, read `tag` from `SystemMessage.data`.
286
287To block the action instead, set `onFailure: "block"` in TypeScript or `on_failure="block"` in Python on the matcher. Requires TypeScript Agent SDK v0.3.317 or later, or Python Agent SDK v0.2.177 or later. This example blocks a Bash call when `check_policy` in Python or `checkPolicy` in TypeScript fails:
288
289```python Python theme={null}
290options = ClaudeAgentOptions(
291 hooks={
292 "PreToolUse": [
293 HookMatcher(matcher="Bash", hooks=[check_policy], on_failure="block")
294 ]
295 }
296)
297```
298
299```typescript TypeScript theme={null}
300import type { Options } from "@anthropic-ai/claude-agent-sdk";
301
302const options: Options = {
303 hooks: {
304 PreToolUse: [{ matcher: "Bash", hooks: [checkPolicy], onFailure: "block" }]
305 }
306};
307```
308
309To test it, make the callback raise an error and ask Claude to run a Bash command. The tool result includes `failed; blocking because onFailure is "block"`, and Claude doesn't see your error text.
310
311Return `{}` when the callback has no opinion. With `"block"` set, a path with no `return` blocks the action. A callback that catches its own error and returns `{}` isn't failing, so let the error propagate from a guard.
312
313#### Events that behave differently
314
315These events don't always block with `"block"` set:
316
317* **`Stop`, `SubagentStop`, `TaskCompleted`, and `TeammateIdle`**: these events ignore the option, so the action goes ahead.
318* **`PermissionRequest`**: the block counts only if it arrives before your `canUseTool` callback answers.
319* **`PostToolUse`**: the tool has already run, so Claude receives the failure as feedback.
320
321A callback that exceeds its timeout follows [Hook timeout](#hook-timeout). With `"block"` set, a timeout also blocks `PreCompact`, `Elicitation`, and `WorktreeCreate`.
322
323#### Startup errors for `onFailure`
324
325With `"block"` set, the query fails at startup and sends no prompt when it can't honor the option:
326
327* **Claude Code doesn't support the option**: the error includes `does not honor`. Update Claude Code, or remove the option.
328* **The session was already running and didn't register your hooks**: the error includes `did not register your hooks`. Start a new session.
329
282330## Examples
283331
284332Several examples in this section show only the callback function. To run one, register the callback under the matching event in the `hooks` field of your options, as shown in [Configure hooks](#configure-hooks).
from line 823
775823* `Stop` and `SubagentStop`: the timed-out callback counts as returning no decision. The agent or subagent stops as if that callback had allowed it, and a decision from your other hooks on the event still applies. Before Claude Code v2.1.273, a timed-out `Stop` or `SubagentStop` callback counted as a failed hook run, and Claude Code discarded the decisions of your other hooks on the event.
776824* `SessionStart`: the timed-out callback counts as returning no output, and the session continues with the output of your other `SessionStart` hooks.
777825* `PreModelSwitch`: Claude Code blocks the model switch. A hook that doesn't answer hasn't approved the switch.
778* Other events, such as `Notification`, `PreCompact`, and `PostModelSwitch`: Claude Code logs the failure and continues.
826* Other events, such as `Notification`, `PreCompact`, and `PostModelSwitch`: Claude Code logs the failure and continues. With [`onFailure: "block"`](#block-the-action-when-a-callback-fails), a timeout on `PreCompact`, `Elicitation`, or `WorktreeCreate` blocks the action.
779827
780828The first time a `Stop` or `SessionStart` callback times out in the main session, Claude Code also adds an [`SDKInformationalMessage`](https://code.claude.com/docs/en/agent-sdk/typescript#sdkinformationalmessage) to the message stream saying the app driving the session didn't respond. Later timeouts don't repeat that message while your app stays unresponsive.
781829
agent-sdk/python Changed · +6 / -1 lines
from line 2157
21572157 None # Timeout in seconds. When omitted, the per-event default applies:
21582158 # 600 for most events, 30 for UserPromptSubmit
21592159 )
2160 on_failure: Literal["continue", "block"] | None = (
2161 None # "block" blocks the action when a callback fails
2162 )
21602163```
2164
2165To decide what `on_failure` covers, see [Block the action when a callback fails](https://code.claude.com/docs/en/agent-sdk/hooks.md#block-the-action-when-a-callback-fails).
21612166
21622167### `HookInput`
21632168
agent-teams Changed · +12 / -4 lines
from line 158
158158
159159### Have teammates plan before implementing
160160
161For complex or risky tasks, you can have teammates plan before implementing. A teammate that Claude spawns while the lead is in [plan mode](https://code.claude.com/docs/en/permission-modes.md#analyze-before-you-edit-with-plan-mode) works in read-only plan mode until its plan is ready. Switch the lead into plan mode first, then ask for the teammate:
161For complex or risky tasks, you can have teammates plan before implementing. A teammate that Claude spawns while the lead is in [plan mode](https://code.claude.com/docs/en/permission-modes.md#analyze-before-you-edit-with-plan-mode) also works in plan mode until its plan is ready. Switch the lead into plan mode first, then ask for the teammate:
162162
163163```text wrap theme={null}
164164Spawn an architect teammate to refactor the authentication module.
165165```
166166
167When that teammate finishes planning, it sends a plan approval request to the lead. If you haven't changed that teammate's permission mode since it was spawned, Claude Code approves the plan as soon as the request arrives, without the lead reviewing it. The teammate's edits and commands still go through the permission prompts described in [Permissions](#permissions). Once approved, the teammate exits plan mode and begins implementation.
167When that teammate finishes planning, it sends a plan approval request to the lead. If you haven't changed that teammate's permission mode since it was spawned, Claude Code approves the plan as soon as the request arrives, without the lead reviewing it. Once approved, the teammate exits plan mode and begins implementation. Claude Code passes it the lead's current [permission mode](#permissions), or Manual if that's plan mode.
168168
169169If you put a running in-process teammate in plan mode by pressing [`Shift+Tab`](https://code.claude.com/docs/en/permission-modes#switch-permission-modes) while viewing its session, the lead reviews that run's plan instead of Claude Code approving it. You aren't asked to approve it; the lead approves it or sends it back for revision.
170170
from line 284
284284
285285### Permissions
286286
287Teammates start with the lead's permission mode, except [`dontAsk` mode](https://code.claude.com/docs/en/permission-modes#allow-only-pre-approved-tools-with-dontask-mode), which they don't inherit. If the lead runs with `--dangerously-skip-permissions`, all teammates do too. After spawning, you can change an individual teammate's permission mode, but you can't set per-teammate permission modes at spawn time.
287To cycle a running teammate's permission mode, press [`Shift+Tab`](https://code.claude.com/docs/en/permission-modes#switch-permission-modes), though an in-process teammate can run in the lead's mode instead. For a split-pane teammate, press it in its pane. For an [in-process](#choose-a-display-mode) teammate, press it while [viewing its session](#talk-to-teammates-directly), and the teammate checks its mode when it starts its next turn.
288288
289> [!NOTE]
290>
291> An in-process teammate that isn't in [plan mode](#have-teammates-plan-before-implementing) runs in the lead's mode while the lead is in [`acceptEdits`](https://code.claude.com/docs/en/permission-modes#auto-approve-file-edits-with-acceptedits-mode), [`auto`](https://code.claude.com/docs/en/permission-modes#eliminate-prompts-with-auto-mode), or [`bypassPermissions`](https://code.claude.com/docs/en/permission-modes#skip-all-checks-with-bypasspermissions-mode) mode. Switching the teammate to Manual doesn't change that, even if its status bar shows Manual.
292>
293> To have it ask before it edits, press Enter on the `main` row in the agent panel and switch the lead to Manual mode too. The lead then asks too, as does any other teammate in Manual mode.
294
295You can't set per-teammate permission modes at spawn time. A new teammate starts with the lead's mode, including `bypassPermissions` mode, which `--dangerously-skip-permissions` turns on. If the lead is in [`dontAsk` mode](https://code.claude.com/docs/en/permission-modes#allow-only-pre-approved-tools-with-dontask-mode), the teammate starts in [Manual mode](https://code.claude.com/docs/en/permission-modes.md#available-modes) instead.
296
289297An [in-process](#choose-a-display-mode) teammate runs under the lead's live allow and deny rules, so [`--disallowedTools`](https://code.claude.com/docs/en/cli-reference#cli-flags), `--tools`, and `--allowedTools` all apply to it. For a split-pane teammate, check each flag:
290298
291299* **`--disallowedTools` and `--tools`**: the teammate starts with the lead's command-line deny rules and tool list. Requires Claude Code v2.1.309 or later.
from line 492
484492* **No nested teams**: teammates cannot spawn their own teammates. Only the lead can manage the team.
485493* **No background subagents from in-process teammates**: an in-process teammate's own subagents run in the foreground, because a teammate's background work can't outlive the lead's process. Claude Code returns an error when a teammate spawns a subagent whose definition sets `background: true`. A teammate's `run_in_background: true` request also fails, either with an error or by running silently in the foreground. Subagents launched from the main conversation follow the [background default](https://code.claude.com/docs/en/sub-agents.md#run-subagents-in-foreground-or-background).
486494* **Lead is fixed**: the main session is the lead for its lifetime. You can't promote a teammate to lead or transfer leadership.
487* **Permissions set at spawn**: teammates start with the permission mode described under [Permissions](#permissions). You can change an individual teammate's permission mode after spawning, but you can't set per-teammate permission modes at spawn time.
495* **No per-teammate permission modes at spawn**: teammates start with the permission mode described under [Permissions](#permissions).
488496* **Split panes require tmux or iTerm2**: the default in-process mode works in any terminal. Split-pane mode isn't supported in VS Code's integrated terminal, Windows Terminal, or Ghostty.
489497
490498## Next steps
errors Changed · +17 / -0 lines
#### `a hook changed this call's input after auto mode reviewed it`
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 752
752752Auto mode is unavailable — the server returned no safety verdict for the last 10 responses, so Claude stopped. Send a message to try again, or switch out of auto mode.
753753```
754754
755Some denials don't count toward the ten, including [a denial from a hook or mod's change](#hook-changed-input-after-review).
756
755757The stop message appears in a different place in each kind of session:
756758
757759* In an interactive session, the message appears as a warning in the transcript and the turn ends
from line 773
771773
772774Before v2.1.302, on a direct connection to the Anthropic API, Claude Code didn't compact a conversation that had grown too long for the server's check.
773775
776#### `a hook changed this call's input after auto mode reviewed it`
777
778This denial means a hook or mod [changed the call's input](https://code.claude.com/docs/en/hooks.md#pretooluse-updatedinput-in-auto-mode) after the server reviewed it, so the review doesn't cover what would run. It isn't a judgment that the action is unsafe.
779
780Later calls in the same Claude response can be denied with this reason:
781
782```text theme={null}
783another call in this response was changed by a hook after auto mode reviewed it, or could not be confirmed unchanged
784```
785
786Claude can then issue each denied call again so the server reviews it. If a permission prompt opens, answer it. You don't need to do anything else unless Claude says in its reply that auto mode couldn't check the call. Then stop the change or approve the call yourself, and ask Claude to try the call again:
787
788* **Stop the change**: turn off the [hook](https://code.claude.com/docs/en/hooks.md#disable-or-remove-hooks) or [mod](https://code.claude.com/docs/en/plugins/mods/overview.md#turn-mods-on-or-off) that changed the call or an earlier call in the same Claude response, or ask your administrator to turn it off. To look for a hook, run [`/hooks`](https://code.claude.com/docs/en/hooks#the-%2Fhooks-menu) at the Claude Code prompt. In a terminal session, run `/plugin` to see the active mods.
789* **Approve the call yourself**: [switch to Manual mode](https://code.claude.com/docs/en/permission-modes.md#switch-permission-modes)
790
774791### Was not reviewed and did not run
775792
776793A `was not reviewed and did not run` denial means the conversation is too long for the [auto mode](https://code.claude.com/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode) classifier to check the action, so the action didn't run. Claude Code returns this message to Claude:
from line 2514
24972514A tool in the request declared an `input_schema` that fails the API's JSON Schema validation, so the API rejected the whole request. The number after `tools.` is the failing tool's position in the request's tool list, not a name you can look up.
24982515
24992516```text theme={null}
2500API Error: 400 ... tools.N.custom.input_schema: JSON schema is invalid
2501API Error: 400 ... tools.N.custom.input_schema.properties: Property keys should match pattern '^[a-zA-Z0-9_.-]{1,64}$'
2502```
2503
2504The first form means the schema isn't valid JSON Schema draft 2020-12. The second means a top-level property name doesn't match the pattern the message quotes.
2505
2506Claude Code [excludes MCP tools whose input schema would fail this validation](https://code.claude.com/docs/en/mcp.md#tools-with-invalid-input-schemas) when it loads a server's tools, so requests normally never include one.
2507
2508On a [deployment where flag fetching is off](https://code.claude.com/docs/en/env-vars.md#features-that-need-feature-flag-fetching), or on a machine whose flags have never arrived, Claude Code records in the server's log which tool would be rejected but sends it anyway, so this error can still occur.
2509
2510The error can also occur for a tool whose schema declares a JSON Schema dialect other than draft 2020-12 in `$schema`. Claude Code doesn't check those schemas against the JSON Schema meta-schema, though the top-level property-name check still applies.
2511
2512Before v2.1.216, no deployment ran the exclusion checks.
2513
2514**What to do:**
2515
2516* If your Claude Code version is earlier than v2.1.300, run [`claude update`](https://code.claude.com/docs/en/setup#update-claude-code) in your shell. Before v2.1.300, Claude Code didn't [retry the request without the rejected tool's parameters](https://code.claude.com/docs/en/mcp.md#tools-whose-input-schema-the-api-refuses), so this error repeated on every request that included the tool.
2517* Remove or [dis
2517API Error: 400 .
hooks Changed · +19 / -2 lines
#### PreToolUse `updatedInput` in auto mode
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 897
897897
898898#### Block the action when a hook fails
899899
900On most events, when a hook fails or times out, Claude Code still carries out the action. A policy hook with a wrong path or a crashing script then lets everything through. To block the action instead, set `"onFailure": "block"` on a `command` or `http` hook. Requires Claude Code v2.1.295 or later.
900On most events, when a hook fails or times out, Claude Code still carries out the action. A policy hook with a wrong path or a crashing script then lets everything through. To block the action instead, set `"onFailure": "block"` on a `command` or `http` hook. Requires Claude Code v2.1.295 or later. For Agent SDK callback hooks, see [Block the action when a callback fails](https://code.claude.com/docs/en/agent-sdk/hooks.md#block-the-action-when-a-callback-fails).
901901
902902> [!NOTE]
903903>
from line 1956
19561956| :- | :- |
19571957| `permissionDecision` | `"allow"` skips the permission prompt, except for [actions no mode auto-approves](https://code.claude.com/docs/en/permission-modes.md#actions-no-mode-auto-approves) and [reads from network paths](https://code.claude.com/docs/en/permissions.md#network-paths). It doesn't skip approval for calls to [tools an Agent SDK app marks `always_ask`](https://code.claude.com/docs/en/agent-sdk/custom-tools#require-approval-for-specific-tools) either, unless the [permission mode approves the call](https://code.claude.com/docs/en/agent-sdk/typescript.md#permission-modes-that-can-approve-an-always_ask-call). `AskUserQuestion` and `ExitPlanMode` need [`updatedInput` paired with `"allow"`](#allow-with-updatedinput). For plan mode, see [Hook approvals in plan mode](https://code.claude.com/docs/en/permissions.md#hook-approvals-in-plan-mode). `"deny"` prevents the tool call. `"ask"` prompts the user to confirm. `"defer"` ends the turn so the tool can be resumed later, and requires [non-interactive mode](#defer-a-tool-call-for-later) with the `-p` flag. [Deny and ask rules](https://code.claude.com/docs/en/permissions.md#manage-permissions) are still evaluated regardless of what the hook returns |
19581958| `permissionDecisionReason` | For `"ask"`, shown to the user in the permission prompt. When Claude Code [denies the call](https://code.claude.com/docs/en/headless.md#turn-off-permission-prompts-in-unattended-runs) in a `-p` run where no one can answer that prompt, Claude reads the reason in the tool result instead. For `"deny"`, shown to Claude. For `"allow"` and `"defer"`, written to the [debug log](#debug-hooks) only |
1959| `updatedInput` | Modifies the tool's input parameters before execution. Replaces the entire input object, so include unchanged fields alongside modified ones. Claude Code evaluates permission rules and a Bash command's [auto-background eligibility](https://code.claude.com/docs/en/tools-reference.md#foreground-commands-that-move-to-the-background) against the input your hook returns, not the input Claude sent. Combine with `"allow"` to auto-approve, or `"ask"` to show the modified input to the user. For `"defer"`, ignored |
1959| `updatedInput` | Modifies the tool's input parameters before execution. Replaces the entire input object, so include unchanged fields alongside modified ones. Claude Code evaluates permission rules and a Bash command's [auto-background eligibility](https://code.claude.com/docs/en/tools-reference.md#foreground-commands-that-move-to-the-background) against the input your hook returns, not the input Claude sent. Combine with `"allow"` to auto-approve, or `"ask"` to show the modified input to the user. For `"defer"`, ignored. With no `permissionDecision`, [auto mode can deny the changed call](#pretooluse-updatedinput-in-auto-mode) |
19601960| `additionalContext` | String added to Claude's context alongside the tool result. Ignored when `permissionDecision` is `"defer"`. See [Add context for Claude](#add-context-for-claude) |
19611961
19621962When multiple PreToolUse hooks return different decisions, precedence is `deny` > `defer` > `ask` > `allow`.
from line 1983
19831983>
19841984> 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.
19851985
1986#### PreToolUse `updatedInput` in auto mode
1987
1988When your hook returns `updatedInput` with no `permissionDecision` in [auto mode](https://code.claude.com/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode), Claude Code can deny the changed call. [The server reviewed](https://code.claude.com/docs/en/permission-modes.md#server-side-classifier-review) the input Claude wrote, not the input your hook returned. In interactive terminal sessions and VS Code sessions on a direct connection to the Anthropic API, the denial includes this text:
1989
1990```text theme={null}
1991a hook changed this call's input after auto mode reviewed it
1992```
1993
1994After a denial with this text, Claude can issue the changed call again so that the server reviews it. If Claude repeats the changed input exactly in its next response, your hook still runs:
1995
1996* It can deny the call or send it to the permission prompt
1997* Any `updatedInput` it returns is dropped, so what runs is what the server reviewed
1998
1999You don't need to change your hook for this denial unless [Claude tells you in its reply that auto mode couldn't check the call](https://code.claude.com/docs/en/errors.md#hook-changed-input-after-review).
2000
2001In the sessions that show this text, a [`command` hook](#command-hook-fields) in settings or a plugin's hooks file can change Bash, PowerShell, Monitor, Edit, Write, and NotebookEdit calls without this denial. The denial can still appear, such as when any hook changed an earlier call in the same Claude response or a Bash command asks to run outside the sandbox.
2002
19862003#### PreToolUse `ask` decisions in auto mode
19872004
19882005In [auto mode](https://code.claude.com/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode), a PreToolUse hook's `"ask"` normally sends the tool call to the permission prompt, and the [classifier](https://code.claude.com/docs/en/permission-modes.md#how-the-classifier-evaluates-actions) doesn't decide it. Some calls take a different path:
from line 3815
37983815
37993816```json theme={null}
38003817{
3801 "session_id": "abc123",
3802 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
3803 "cwd": "/Users/...",
3804 "hook_event_name": "ElicitationResult",
3805 "mcp_server_name": "my-mcp-server",
3806 "action": "accept",
3807 "content": { "username": "alice" },
3808 "mode": "form"
3809}
3810```
3811
3812#### ElicitationResult output
3813
3814An ElicitationResult hook can let the user's response through, change its values, or block it. To change or block the response, exit 0 and print a `hookSpecificOutput` object with an `action`. Each row of this table shows what to return for one outcome and what the MCP server receives:
3815
3816| To | Return | The server receives |
3817| :- | :- | :- |
3818| Let the response through | No output, with exit code 0 | The user's response, unchanged |
3819| Change the submitted values | `"action": "accept"`, with the new values in `content` | `accept` with your `content` in place of the user's values |
3820| Block the response | `"action": "decline"` | `decline`, without the user's values |
3821| Cancel the request | `"action": "cancel"` | `cancel`, along with the values the user submitted. To withhold them, return `"decline"` |
3822
3823This output changes the response shown under [ElicitationResult input](#elicitationresult-input), so the server receives `[email protected]` where the user submitted `alice`:
3824
3825```json theme={null}
3826{
3827 "hookSpecificOutput": {
3828 "hookEventName": "ElicitationResult",
3829 "action": "accept",
3830 "content": {
3831 "username": "[email protected]"
3832 }
3833 }
3834}
3835```
3836
3837Your `content` replaces the user's whole `content` object, so include the fields you aren't changing. Return `action` along with it, because Claude Code ignores a `hookSpecificOutput` that has no `action`.
3838
3839ElicitationResult hooks also run when the user declines or cancels, and your `action` replaces theirs. Che
3818 "session_i
interactive-mode Changed · +4 / -4 lines
from line 283
283283
284284### Reverse search with Ctrl+R
285285
286Press `Ctrl+R` to interactively search through your command history. In [fullscreen rendering](https://code.claude.com/docs/en/fullscreen.md), `Ctrl+R` opens a search dialog instead: type to filter, press `Up` and `Down` to move through matches, and press `Ctrl+S` to cycle the scope through this session, this project, and all projects. Press `Enter` or `Tab` to place a match in the prompt input, or `Esc` to cancel. The steps below describe the classic renderer's inline search:
286Press `Ctrl+R` to interactively search through your command history. In [fullscreen rendering](https://code.claude.com/docs/en/fullscreen.md), `Ctrl+R` opens a search dialog instead. Type to filter in the dialog, and press `Up` and `Down` to move through the list of matches, with a preview pane showing the start of the highlighted match.
287287
288In the dialog, press `Ctrl+S` to cycle the scope through this session, this project, and all projects. Press `Enter` or `Tab` to place a match in the prompt input, or `Esc` to cancel. The steps below describe the classic renderer's inline search:
289
2882901. **Start search**: press `Ctrl+R` to activate reverse history search
2892. **Type query**: enter text to search for in previous commands. The search term is highlighted in matching results
2912. **Type query**: enter text to search for in previous commands. The current match appears in the prompt input.
2902923. **Navigate matches**: press `Ctrl+R` again to cycle through older matches
2912934. **Search scope**: the inline search always searches prompts from all projects
2922945. **Accept match**:
from line 297
2952976. **Cancel search**:
296298 * Press `Ctrl+C` to cancel and restore your original input
297299 * Press `Backspace` on empty search to cancel
298
299The inline search scans your full prompt history, newest first, with duplicates collapsed to the newest occurrence. The fullscreen dialog searches your whole prompt history in the selected scope, newest first, with duplicates collapsed to the newest occurrence: the most recent prompts appear immediately, and matches from older prompts fill in as Claude Code loads the rest. Matching prompts display with the search term highlighted, so you can find and reuse previous inputs.
300300
301301Accepting a match or canceling the search takes effect immediately, even while Claude Code is still loading the history.
302302
agent-sdk/typescript Changed · +4 / -0 lines
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 2179
21792179 level: "info" | "notice" | "suggestion" | "warning";
21802180 tool_use_id?: string;
21812181 prevent_continuation?: boolean;
2182 tag?: string;
21822183 uuid: UUID;
21832184 session_id: string;
21842185};
from line 2555
25542555 matcher?: string;
25552556 hooks: HookCallback[];
25562557 timeout?: number; // Timeout in seconds for all hooks in this matcher
2558 onFailure?: "continue" | "block"; // "block" blocks the action when a callback fails
25572559}
25582560```
25592561
2562To decide what `onFailure` covers, see [Block the action when a callback fails](https://code.claude.com/docs/en/agent-sdk/hooks.md#block-the-action-when-a-callback-fails).
2563
25602564### `HookInput`
25612565
25622566Union type of all hook input types.
from line 4793
47894793type PushNotificationOutput = {
47904794 message: string;
47914795 pushSent?: boolean;
4792 localSent?: boolean;
4793 disabledReason?: "config_off" | "user_present" | "no_transport";
4794 sentAt?: string;
4795};
4796```
4797
4798Returns delivery details, including whether a push or local notification was sent and why delivery was skipped.
4799
4800### ReportFindings
4801
4802**Tool name:** `ReportFindings`
4803
4804``
4796 localSe
claude-tag Changed · +1 / -1 lines
This page is larger than the 256 KiB this site keeps, so one side of the diff below stops where the stored text does.
Nothing in the body moved in this read. What changed is above.
monitoring-usage Changed · +4 / -0 lines
from line 326
326326
327327In interactive CLI sessions, detailed beta tracing also requires your organization to be allowlisted for the feature. Agent SDK and non-interactive `-p` sessions don't require allowlisting.
328328
329> [!WARNING]
330>
331> Set `ENABLE_BETA_TRACING_DETAILED` only for debugging, not in production. Detailed beta tracing has a high export volume, and its [content attributes](#new-context-gates) aren't part of the stable span schema.
332
329333| Attribute | Description | Gated by |
330334| - | - | - |
331335| `hook_event` | Hook event type, such as `PreToolUse` | |
permission-modes Changed · +3 / -1 lines
from line 379
379379* **The server doesn't review the session**: a response completes with no review results, or the server answers that it doesn't review this session. The most common causes are an LLM gateway or proxy that drops the request for review or the results, and a platform, region, or credential that doesn't have server-side checks yet. Claude Code falls back to its own classifier requests. Once that fallback holds for the rest of the session, it shows a [notice about classifier request charges](https://code.claude.com/docs/en/auto-mode-classifier-billing.md) on accounts where those requests are billed.
380380* **The server gives no verdict for an action**: Claude Code denies the action rather than run it unreviewed. On any connection, this happens when the response ends before the review results arrive or the results arrive in a form Claude Code can't read. An LLM gateway or proxy that cuts responses short or rewrites the results can cause either. On a direct connection to the Anthropic API, it also happens when the server's check fails for the action, for example by timing out. [The server returned no safety verdict](https://code.claude.com/docs/en/errors.md#the-server-returned-no-safety-verdict) covers the denial message, what happens when denials repeat, and what to do.
381381
382 If a [hook](https://code.claude.com/docs/en/hooks.md#pretooluse-updatedinput-in-auto-mode) or [mod](https://code.claude.com/docs/en/plugins/mods/overview.md) changes an action's input after the server's review, Claude Code can deny the action with no verdict. In interactive terminal and VS Code sessions on a direct connection to the Anthropic API, the denial's text includes `a hook changed this call's input after auto mode reviewed it`. [Its error entry](https://code.claude.com/docs/en/errors.md#hook-changed-input-after-review) covers what to do.
383
382384To skip asking the server and always use Claude Code's own classifier requests, set [`CLAUDE_CODE_AUTO_MODE_SERVER=0`](https://code.claude.com/docs/en/env-vars). On a direct connection to the Anthropic API, the variable requires Claude Code v2.1.281 or later. Setting it to `1` there turns server review on in a session that doesn't have it yet, unless you've also set `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`. If you set `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1` and leave `CLAUDE_CODE_AUTO_MODE_SERVER` unset, Claude Code also stops asking the server, except as [Disable pre-release capabilities](https://code.claude.com/docs/en/llm-gateway-protocol.md#disable-pre-release-capabilities) describes.
383385
384386### Default classifier model
from line 555
553555* **A blocked action**: Claude Code shows a notification and lists the action in `/permissions` under the **Recently blocked** tab, where you can [approve the action so Claude may retry](https://code.claude.com/docs/en/auto-mode-config.md#review-denials).
554556* **Repeated blocks**: if the classifier blocks an action 3 times in a row or 20 times total, auto mode pauses and Claude Code resumes prompting. Approving the prompted action resumes auto mode. See [Repeated-block thresholds](#repeated-block-thresholds) for how the blocks are counted.
555557* **No verdict from the classifier**: when a safety check separate from auto mode refuses the classifier's own request, or the classifier's response doesn't parse, Claude Code blocks the action without the notification or the **Recently blocked** entry. See [Auto mode cannot determine the safety of an action](https://code.claude.com/docs/en/errors.md#auto-mode-cannot-determine-the-safety-of-an-action) for the message each case shows and what to do.
556* **No verdict from the server**: under [server-side classifier review](#server-side-classifier-review), Claude Code denies an action the server gives no verdict for, and stops the turn after ten responses in a row with no verdict. See [The server returned no safety verdict](https://code.claude.com/docs/en/errors.md#the-server-returned-no-safety-verdict).
558* **No verdict from the server**: under [server-side classifier review](#server-side-classifier-review), Claude Code denies an action the server gives no verdict for, and can stop the turn after ten responses in a row with no verdict. See [The server returned no safety verdict](https://code.claude.com/docs/en/errors.md#the-server-returned-no-safety-verdict).
557559* **A mode switch during a check**: if you switch permission modes while a classifier check is pending, Claude Code discards a verdict the new mode wouldn't have requested. You're prompted for approval instead, or the action is auto-denied in [`dontAsk` mode](#allow-only-pre-approved-tools-with-dontask-mode).
558560
559561#### Repeated-block thresholds
plugins/mods/troubleshoot Changed · +4 / -0 lines
from line 195
195195
196196The message tells Claude to issue the call once more as recorded. If that's denied too, the hook changes the input every time, so turn off the mod or hook, or leave auto mode and approve the call yourself.
197197
198> [!NOTE]
199>
200> In [some interactive terminal sessions and VS Code sessions](https://code.claude.com/docs/en/hooks.md#pretooluse-updatedinput-in-auto-mode), the same denial gives the reason `a hook changed this call's input after auto mode reviewed it`. The repeated call there carries the mod's first change, and a `tool.call` hook still runs on it, but a further change is dropped. You don't need to change your mod unless Claude tells you in its reply that [auto mode couldn't check the call](https://code.claude.com/docs/en/errors.md#hook-changed-input-after-review).
201
198202### A message about the deny rules in your settings
199203
200204`tried to lift a deny rule in your settings` and `the deny rules in your settings could not be checked for this call, so it is refused` both come from the built-in guard.