One read of Claude Code CLIclaude-code-20261106T210702Z
10 pages moved out of 228 read.
Pages moved
10
significant first
Pages read
228
in this capture
Captured
21:07 UTC
Corpus hash
dc071f01ddba
corpus-hash
What this read moved
1-10 of 10auto-mode-classifier-billing Changed · +6 / -1 lines
from line 25
2525
2626## Make the session eligible
2727
28If a gateway is the cause, ask your company's admin or your gateway provider to pass requests and replies through unchanged. That means forwarding request headers and body fields as they are, including ones the gateway doesn't recognize such as the `safeguards` request field, and returning responses and streaming events without dropping keys such as the `safeguard_results` field or rewriting tool-use IDs, as the [gateway compatibility guide](https://code.claude.com/docs/en/llm-gateway-protocol.md#feature-pass-through) describes. A gateway that passes traffic through this way keeps working with this feature and with future ones. New sessions then use the server's checks again.
28If a gateway keeps auto mode's server-side checks from reaching your sessions and you don't run it, send the requirements below to your company's admin or your gateway provider. Where [the upstream accepts the format that the gateway receives](https://code.claude.com/docs/en/llm-gateway-protocol.md#format-mismatch-with-the-upstream), Claude Code expects the gateway to pass requests and responses through unchanged, as the [gateway compatibility guide](https://code.claude.com/docs/en/llm-gateway-protocol.md#feature-pass-through) describes:
29
30* **Requests**: to let the checks through, the gateway forwards both the `anthropic-beta` header and the `safeguards` body field unchanged, because [the two travel as a pair](https://code.claude.com/docs/en/llm-gateway-protocol.md#beta-header-and-body-field-pairs). On the [Amazon Bedrock InvokeModel format](https://code.claude.com/docs/en/llm-gateway-protocol.md#api-formats), it forwards the `anthropic_beta` body field in place of the header.
31* **Responses**: the gateway returns responses and streaming events without dropping fields or rewriting tool-use IDs. To let the checks' results through, it keeps the `safeguard_results` field.
32
33A gateway that passes traffic through this way keeps working with this feature and with future ones. New sessions then use the server's checks again.
2934
3035If you already know that your gateway can't provide the server's checks, tell Claude Code not to ask for them there by setting `CLAUDE_CODE_AUTO_MODE_SERVER` to `0` before you start the session, in your shell or in the [`env` settings key](https://code.claude.com/docs/en/settings-reference#env):
3136
hooks Changed · +36 / -13 lines
##### Resume when a deferred tool is unavailable #### PostToolUse after an interrupt
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 2059
20592059
20602060#### Defer a tool call for later
20612061
2062`"defer"` is for integrations that run `claude -p` as a subprocess and read its JSON output, such as an Agent SDK app or a custom UI built on top of Claude Code. It lets that calling process pause Claude at a tool call, collect input through its own interface, and resume where it left off. Claude Code honors this value only in [non-interactive mode](https://code.claude.com/docs/en/headless.md) with the `-p` flag. In interactive sessions it logs a warning and ignores the hook result.
2062`"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.
20632063
2064Claude Code honors `"defer"` only in [non-interactive mode](https://code.claude.com/docs/en/headless.md) with the `-p` flag, and only when Claude makes a single tool call in the turn:
2065
2066* **In interactive sessions**: it logs a warning and ignores the hook result
2067* **Several tool calls at once**: `"defer"` is ignored with a warning and the tool proceeds through the normal permission flow
2068
20642069The `AskUserQuestion` tool is the typical case: Claude wants to ask the user something, but there is no terminal to answer in. A `-p` run offers `AskUserQuestion` only when it has a [permission host](https://code.claude.com/docs/en/headless.md#turn-off-permission-prompts-in-unattended-runs), such as an MCP tool you pass with `--permission-prompt-tool`, so start the run with one. The round trip works like this:
20652070
206620711. Claude calls `AskUserQuestion`. The `PreToolUse` hook fires.
from line 2074
206920744. The calling process runs `claude -p --resume <session-id>` with the same permission host. The same tool call fires `PreToolUse` again.
207020755. The hook returns `permissionDecision: "allow"` with the answer in `updatedInput`. The tool executes and Claude continues.
20712076
2072The `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:
2077The `deferred_tool_use` field carries the tool's `id`, `name`, and `input`:
20732078
20742079```json theme={null}
20752080{
from line 2090
20852090}
20862091```
20872092
2088There is no timeout or retry limit. The session remains on disk until you resume it, subject to the [`cleanupPeriodDays`](https://code.claude.com/docs/en/settings-reference#cleanupperioddays) retention sweep, which deletes session files after 30 days by default, following the [retention sweep rules](https://code.claude.com/docs/en/claude-directory.md#cleaned-up-automatically).
2093There is no timeout or retry limit. The session stays on disk until the [`cleanupPeriodDays`](https://code.claude.com/docs/en/settings-reference#cleanupperioddays) [retention sweep](https://code.claude.com/docs/en/claude-directory.md#cleaned-up-automatically) deletes it, after 30 days by default.
20892094
2090If the deferred tool is no longer available when you resume, the resume's first result has `stop_reason: "tool_deferred_unavailable"` and `is_error: true`, and the hook doesn't fire. 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.
2095If the answer isn't ready when you resume, the hook can return `"defer"` again. If you sent a prompt with that resume, Claude answers it without the tool's result and doesn't run the call. Resume without a prompt until the hook returns `"allow"` or `"deny"`.
20912096
2092* **If you sent no prompt, with the resume or after it**, the call is still pending. Resume again with the tool available and it runs first.
2093* **If you sent a prompt, with the resume or after it**, Claude Code answers it without the tool's result and drops the deferred call. Send a new prompt once the tool is available if you still need it called.
2094
2095If the answer you're waiting for is not ready when you resume without a prompt, the hook can return `"defer"` again. If you sent a prompt and the hook defers again, Claude Code treats the prompt the same way: it answers without the tool's result and drops the call. Resume without a prompt until the hook returns `"allow"` or `"deny"`, which is how the calling process breaks the loop.
2096
2097`"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.
2098
20992097> [!NOTE]
21002098>
21012099> To resume a deferred session in plan mode, pass [`--permission-prompt-tool`](https://code.claude.com/docs/en/cli-reference#cli-flags) along with `--resume` so that Claude Code can present the plan for approval. For the other conditions, see [Resume in plan mode with `-p`](https://code.claude.com/docs/en/sessions#resume-in-plan-mode-with-p). Requires Claude Code v2.1.246 or later.
21022100>
2103> When you resume with `-p`, Claude Code doesn't restore any other stored permission mode. It starts the run in the permission mode a new `claude -p` run would start in, so pass `--permission-mode` or `--dangerously-skip-permissions` again if the deferred session used one. When you resume with `claude --resume <session-id>` without `-p`, Claude Code restores the stored permission mode, with the exceptions listed in [permission mode on resume](https://code.claude.com/docs/en/sessions.md#permission-mode-on-resume).
2101> When you resume with `-p`, Claude Code doesn't restore any other stored permission mode. It starts the run in the permission mode a new `claude -p` run would start in, so pass `--permission-mode` or `--dangerously-skip-permissions` again if the deferred session used one.
21042102
2103##### Resume when a deferred tool is unavailable
2104
2105A result with `stop_reason: "tool_deferred_unavailable"` means a deferred call's tool isn't available in the resumed session, for example because its MCP server isn't connected. Your `PreToolUse` hook doesn't fire, and the result's `deferred_tool_use` field names the tool.
2106
2107While the call is pending, any prompt you send doesn't reach Claude and the run exits with code 1. The `result` field starts with `<tool> isn't available, so its deferred call didn't run.` Run the call, or drop it so that it doesn't run:
2108
2109* **To run the call**: make the tool available and resume again.
2110* **To drop the call**: resume with a prompt and [`CLAUDE_CODE_DROP_UNAVAILABLE_DEFERRED_TOOL`](https://code.claude.com/docs/en/env-vars#variables) set to `1`. Claude receives an error as the call's result and answers your prompt. When you resume later, no call is pending.
2111
2112When you drop the call, the run writes the `tool_deferred_unavailable` result with an empty `result` field, then Claude's answer in a second result. It exits with code 0 unless that answer is an error. If you set the variable and send no prompt, the run still drops the call and exits with code 1.
2113
2114Before v2.1.319, Claude Code answered a prompt without the tool's result and dropped the call. On those versions, send a new prompt once the tool is available.
2115
21052116### PermissionRequest
21062117
21072118Runs when Claude Code is about to ask you for permission to use a tool. In sessions that can't show a prompt, such as background subagents in [non-interactive mode](https://code.claude.com/docs/en/headless.md), Claude Code still runs these hooks, and if no hook returns a decision, it denies the tool call. For a call that reaches a `--permission-prompt-tool` or the Agent SDK's [`canUseTool` callback](https://code.claude.com/docs/en/agent-sdk/permissions), the hooks run alongside your host, and whichever decides first applies.
from line 2226
22152226* To run a hook after any tool completes successfully, omit the `matcher` or set it to `"*"`. Your hook can then discover what changed itself, for example by running `git status --porcelain`, which also lists untracked files that `git diff` misses. For tool calls that fail, add the same hook under [PostToolUseFailure](#posttoolusefailure).
22162227* To run a hook when a specific file changes on disk, whatever wrote it, use [FileChanged](#filechanged). Claude Code doesn't run a `PostToolUse` hook matching `Edit|Write` when a `Bash` command or a process outside Claude Code rewrites the same file.
22172228
2229#### PostToolUse after an interrupt
2230
2231If a `PostToolUse` hook stops early after you send a message or interrupt during a tool call, check whether you pressed `Ctrl+Enter`, `Enter`, or `Esc`:
2232
2233* **`Ctrl+Enter`**: if pressing it [ends the turn](https://code.claude.com/docs/en/interactive-mode.md#when-claude-code-sends-what-you-queued) while a tool is running and the tool finishes, your `PostToolUse` hooks run on its result and have 10 seconds to finish. The key acts as `Esc` if you queued a `!` command ahead of your messages or background tasks are disabled, for example with [`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS`](https://code.claude.com/docs/en/env-vars#variables).
2234* **`Enter`**: a message you queue with `Enter` doesn't interrupt the turn, so the hooks keep their usual `timeout`.
2235* **`Esc`**: you cancel the hooks at once, so send the message with `Enter` or `Ctrl+Enter` when the hooks have to run.
2236
2237When the 10 seconds are up, Claude Code kills a command hook that is still running, whatever its [`timeout`](#common-fields). To let a longer command hook finish, run it with [`async: true`](#run-hooks-in-the-background), which means the hook can't block or rewrite the result.
2238
2239Before v2.1.319, the hooks didn't start after you interrupted the turn with a message, and a running hook was stopped.
2240
22182241#### PostToolUse input
22192242
22202243`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. File-tool `tool_input` paths arrive in the same format as for [PreToolUse](#pretooluse-input): always absolute, with the platform's native separators, so backslashes on Windows. For an MCP tool, the input also carries the [`mcp_server`](#pretooluse-input) object.
from line 3741
37183741* **Exits with code 2**: Claude Code ignores a `hookSpecificOutput` printed by the same hook
37193742* **Prints a top-level `"decision": "block"`**: the block overrides an `action` in the same output
37203743
3721When several hooks match the same request, a decline from one of them overrides an `accept` or `cancel` from another.
3722
3723This script declines URL-mode requests and leaves form requests to the dialog:
3724
3725```bash theme={null}
3726#!/bin/bash
3727if [ "$(jq -r '.mode')" = "url" ]; then
3728 exit 2
3729fi
3730```
3731
3732Neither the user nor the server sees why your hook declined, because Claude Code doesn't show your stderr or your `reason`.
3733
3734Claude Code ignored a top-level `decision` from `Elicitation` and `ElicitationResult` hooks from v2.1.105 until the fix in v2.1.284.
3735
3736#### Answer a form request from a script
3737
3738This example answers one recurring question for the user. An MCP server named `issue-tracker` asks for a project key in a form, and the hook fills in `DOCS`. The script accepts when `project_key` is the form's single field. For any other request it prints nothing, so the dialog appears.
3739
3740> [tab] macOS/Linux
3741>
3742> Register a command hook for the event in your settings file, with the server name as the matcher:
3743>
3744> ```json theme={null}
3745> {
3746> "hooks": {
3747> "Elicitation": [
3748> {
3749> "matcher": "issue-tracker",
3750> "hooks": [
3751> {
3752> "type": "command",
3753> "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/answer-project-key.sh",
3754> "args": []
3755> }
3756> ]
3757> }
3758> ]
3759> }
3760> }
3744When several hooks match the same request, a decline from one of them overrides an `accept` or `cancel` from anoth
network-config Changed · +7 / -0 lines
from line 85
8585export NODE_EXTRA_CA_CERTS=/path/to/ca-cert.pem
8686```
8787
88If you see either of these warnings, Claude Code couldn't load the `NODE_EXTRA_CA_CERTS` file as a whole, and connections that need a certificate it skipped can fail:
89
90* `Claude Code used only the certificates that it could read in full from the NODE_EXTRA_CA_CERTS file`
91* `Claude Code ignored all of the NODE_EXTRA_CA_CERTS file: it holds no certificate that Claude Code can read`
92
93The full text of each warning says how to fix the file. A skipped certificate that's also in the [CA certificate store](#ca-certificate-store) still works.
94
8895## mTLS authentication
8996
9097For enterprise environments requiring client certificate authentication:
settings-reference Changed · +6 / -7 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 107
107107| [`footerLinksRegexes`](#footerlinksregexes) | Make issue or review IDs in output into [clickable links](https://code.claude.com/docs/en/statusline.md#clickable-links) below the input box | Interface and terminal | User or managed |
108108| [`forceLoginGatewayUrl`](#forcelogingatewayurl) | Set the [gateway URL](https://code.claude.com/docs/en/claude-apps-gateway#set-the-gateway-url) the login screen connects to | Authentication and providers | User or managed |
109109| [`forceLoginMethod`](#forceloginmethod) | [Restrict login](https://code.claude.com/docs/en/authentication.md#restrict-login-to-your-organization) to claude.ai, Claude Console, or a [cloud gateway](https://code.claude.com/docs/en/claude-apps-gateway) | Authentication and providers | Any file |
110| [`forceLoginOrgUUID`](#forceloginorguuid) | [Pin claude.ai logins to your organization](https://code.claude.com/docs/en/authentication.md#restrict-login-to-your-organization); only a managed source enforces it | Authentication and providers | Any file |
110| [`forceLoginOrgUUID`](#forceloginorguuid) | [Pin claude.ai logins to your organization](https://code.claude.com/docs/en/authentication.md#restrict-login-to-your-organization); only managed settings enforce it | Authentication and providers | Any file |
111111| [`forceRemoteSettingsRefresh`](#forceremotesettingsrefresh) | Block startup until [server-managed settings](https://code.claude.com/docs/en/server-managed-settings.md) are freshly fetched | Enterprise and managed settings | Managed |
112112| [`gatewayInternalNetworks`](#gatewayinternalnetworks) | Let `/login` reach a [cloud gateway](https://code.claude.com/docs/en/claude-apps-gateway#allow-a-gateway-on-public-address-space-you-own) on public IPv4 space your organization uses internally | Authentication and providers | Managed |
113113| [`gcpAuthRefresh`](#gcpauthrefresh) | Refresh [Google Cloud credentials](https://code.claude.com/docs/en/google-vertex-ai.md#advanced-credential-configuration) with your own command | Authentication and providers | Any file |
from line 3400
34003400
34013401To hide all attribution, set `attribution` to `false`. In a settings file that earlier versions also read, set [`commit`](#attribution-commit) and [`pr`](#attribution-pr) to empty strings and [`sessionUrl`](#attribution-sessionurl) to `false` instead.
34023402
3403This example replaces the commit attribution, removes pull reques
3403This example replaces the commit attribution, removes pull request
agent-sdk/python Changed · +1 / -1 lines
from line 1381
13811381| `enabled` | `type`, `budget_tokens`, `display` | Enable thinking with a specific token budget |
13821382| `disabled` | `type` | Disable thinking |
13831383
1384The optional `display` field controls whether thinking text is returned `"summarized"` or `"omitted"`. On Claude Opus 4.7 and later, the API default is `"omitted"`, so set `"summarized"` to receive thinking content in [`ThinkingBlock`](#thinkingblock) outputs. Claude Code doesn't pass your `display` value to some providers, such as Amazon Bedrock and Google Cloud's Agent Platform. On those providers, Opus 4.7 and later return empty `ThinkingBlock` outputs even when you set `display` to `"summarized"`.
1384The optional `display` field controls whether thinking text is returned `"summarized"` or `"omitted"`. On Claude Opus 4.7 and later, the API default is `"omitted"`, so set `"summarized"` to receive thinking content in [`ThinkingBlock`](#thinkingblock) outputs. On providers such as Amazon Bedrock and Google Cloud's Agent Platform, Claude Code doesn't pass `display` for earlier models it recognizes. Those are Opus 4.6, Sonnet 4.6, Haiku 4.5, and earlier models, which use their default.
13851385
13861386Because these are `TypedDict` classes, they're plain dicts at runtime. Either construct them as dict literals or call the class like a constructor; both produce a `dict`. Access fields with `config["budget_tokens"]`, not `config.budget_tokens`:
13871387
agent-sdk/typescript 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.
mobile Changed · +1 / -1 lines
from line 62
6262
6363### Get push notifications
6464
65When Remote Control is active, Claude can send push notifications to your phone, typically when a long-running task finishes or when it needs a decision from you. You can also ask for one in your prompt, such as `notify me when the tests finish`. See [mobile push notifications](https://code.claude.com/docs/en/remote-control.md#mobile-push-notifications) for the two `/config` toggles and delivery troubleshooting.
65When Remote Control is active, Claude can send push notifications to your phone when a long-running task finishes or when it needs a decision from you. You can also ask for one in your prompt, such as `notify me when the tests finish`. See [mobile push notifications](https://code.claude.com/docs/en/remote-control.md#mobile-push-notifications) for the two `/config` toggles and delivery troubleshooting.
6666
6767Dispatch sends its own notification when a Code session it spawned finishes or needs your approval, described in [sessions from Dispatch](https://code.claude.com/docs/en/desktop.md#sessions-from-dispatch).
6868
remote-control Changed · +1 / -1 lines
from line 316
316316
317317When Remote Control is active, Claude can send push notifications to your phone.
318318
319Claude decides when to push. It typically sends one when a long-running task finishes or when it needs a decision from you to continue. You can also request a push in your prompt, for example `notify me when the tests finish`. Beyond the two on/off toggles below, there is no per-event configuration.
319A push can arrive when a long-running task finishes or when Claude needs a decision from you. You can also request a push in your prompt, for example `notify me when the tests finish`. Beyond the two on/off toggles below, there is no per-event configuration.
320320
321321To set up mobile push notifications:
322322
server-managed-settings Changed · +1 / -0 lines
from line 191
191191* A cached [`prependPlugins`](https://code.claude.com/docs/en/settings-reference#prependplugins), [`appendPlugins`](https://code.claude.com/docs/en/settings-reference#appendplugins), or [`enabledPlugins`](https://code.claude.com/docs/en/settings-reference#enabledplugins) value can't remove the built-in guard, change its position, or turn it off until the session's fetch confirms the payload
192192* On a machine where an [endpoint-managed source](https://code.claude.com/docs/en/managed-settings.md#choose-a-delivery-mechanism) lists or enables plugins of its own, a plugin that only a cached list enables counts as [the user's](https://code.claude.com/docs/en/plugins/mods/admin.md#install-your-organizations-mods), not your organization's, until the fetch confirms the payload
193193* Claude Code fetches fresh settings in the background
194* If a session's provider isn't on the cached [`allowedProviders`](https://code.claude.com/docs/en/settings-reference#allowedproviders) list, Claude Code can wait for that fetch and check again before refusing. If the fetch fails, the session is refused
194195* Cached settings persist through network failures. If the startup fetch fails, Claude Code warns in interactive sessions and in the Code tab that the cached policy is in effect
195196* Until a fetch succeeds, the values withheld at startup stay withheld
196197
tools-reference Changed · +1 / -1 lines
from line 35
3535| `Monitor` | Runs a command in the background and feeds each output line back to Claude, so it can react to log entries, file changes, or polled status mid-conversation. Can also open a WebSocket and treat each incoming message as an event. See [Monitor tool](#monitor-tool) | Yes |
3636| `NotebookEdit` | Modifies Jupyter notebook cells. See [NotebookEdit tool behavior](#notebookedit-tool-behavior) | Yes |
3737| `PowerShell` | Executes PowerShell commands natively. See [PowerShell tool](#powershell-tool) for availability | Yes |
38| `PushNotification` | Sends a desktop notification, and a phone push when [Remote Control](https://code.claude.com/docs/en/remote-control.md) is connected, so a long-running task or [session-scoped scheduled task](https://code.claude.com/docs/en/scheduled-tasks.md) can reach you when you step away. Push delivery runs through Anthropic-hosted infrastructure, which is not accessible from Amazon Bedrock, Claude Platform on AWS, Google Cloud's Agent Platform, or Microsoft Foundry | No |
38| `PushNotification` | Sends a desktop notification from a local session, and a phone push with [Remote Control](https://code.claude.com/docs/en/remote-control.md) or in a [cloud session](https://code.claude.com/docs/en/claude-code-on-the-web.md). Push delivery runs through Anthropic-hosted infrastructure, which is not accessible from Amazon Bedrock, Claude Platform on AWS, Google Cloud's Agent Platform, or Microsoft Foundry | No |
3939| `Read` | Reads the contents of files. See [Read tool behavior](#read-tool-behavior) | No |
4040| `ReadMcpResourceTool` | Reads a specific MCP resource by URI | No |
4141| `RemoteTrigger` | Creates, updates, runs, and lists [cloud scheduled tasks](https://code.claude.com/docs/en/routines.md), formerly routines, on claude.ai. Backs the `/schedule` command. The [`RemoteTrigger` input reference](https://code.claude.com/docs/en/agent-sdk/typescript#remotetrigger) documents every action and the organization policies that remove the tool. Cloud scheduled tasks live on claude.ai and require a Pro, Max, Ultra, Team, or Enterprise plan. This tool is therefore not accessible from Amazon Bedrock, Claude Platform on AWS, Google Cloud's Agent Platform, or Microsoft Foundry | No |