One read of Claude Code CLIclaude-code-20261019T173702Z
9 pages moved out of 228 read.
Pages moved
9
significant first
Pages read
228
in this capture
Captured
17:37 UTC
Corpus hash
d8e0fea41517
corpus-hash
What this read moved
1-9 of 9agent-sdk/permissions Changed · +1 / -8 lines
from line 113
113113
114114Permission modes provide global control over how Claude uses tools. You can set the permission mode when calling `query()` or change it dynamically during streaming sessions.
115115
116If you don't set one, Claude Code picks the starting permission mode by the rules in [Which mode a session starts in](/docs/en/permission-modes#which-mode-a-session-starts-in):
117
118* A `permissions.defaultMode` from the session's [settings files](/docs/en/settings#where-settings-live) when one applies
119* Otherwise the built-in default, which can be [auto mode](/docs/en/permission-modes#eliminate-prompts-with-auto-mode)
120
121A session that starts in auto mode drops broad allow rules such as a bare `Bash` entry, as [How auto mode evaluates actions](/docs/en/permission-modes#how-auto-mode-evaluates-actions) describes. If your application relies on the `default` mode or on such a rule, pass `default` explicitly.
122
123Before TypeScript Agent SDK v0.3.286, omitting `permissionMode` was the same as passing `default`.
116With Claude Code v2.1.302 or later, your app starts in `default` mode unless you set a permission mode or it gets one from [`permissions.defaultMode`](/docs/en/settings-reference#permissions-defaultmode) in its settings files. In `default` mode, Claude Code denies any tool call needing approval unless you approve it through an allow rule, hook, `canUseTool` callback, or permission prompt tool. If tool calls are denied, see [Tool calls denied in `claude -p` and Agent SDK runs](/docs/en/permission-modes#which-mode-a-non-interactive-run-starts-in).
124117
125118### Available modes
126119
corporate-launcher Changed · +24 / -4 lines
### Pass arguments to the launcher
from line 106
106106When the launcher can't run, Claude Code refuses to start the process instead of starting it unwrapped. On Windows, [the variable is ignored](#what-the-launcher-covers) and processes start unwrapped. Claude Code holds the script to these rules:
107107
108108* **End with `exec "$@"`.** A launcher that forks a child and exits leaves an orphaned Claude Code process the background service can't track. Agent view marks such a session failed with a message naming the launcher, and the service reaps what the launcher left behind.
109* **Don't reorder, absorb, or prepend arguments.** The first argument is the Claude Code binary and everything after it is its argv.
109* **Don't reorder, absorb, or add to Claude Code's arguments.** Remove the launcher's [own arguments](#pass-arguments-to-the-launcher), which come first, and pass the rest to `exec` as it arrived.
110110* **Pass every inherited environment variable through to `exec`.** Adding variables, such as injected credentials, is fine; dropping inherited ones is not.
111111 * The per-session authentication tokens, the model and provider selection, and `CLAUDE_CODE_PROCESS_WRAPPER` itself all travel on the inherited environment, so a launcher that rebuilds it from an allow list breaks the sessions it starts, and `/status` reports a launcher mismatch.
112112 * If the launcher must enter a namespace or sandbox that resets the environment, re-export the inherited environment inside it verbatim.
113* **Reach `exec` within about three seconds each time the launcher runs.** A cold background dispatch runs the launcher twice in series before the first byte of output, so do slow work such as a single sign-on exchange lazily or from a cache.
113* **Reach `exec` within about three seconds each time the launcher runs.** A background session can run the launcher three times in series before its first output. Do slow work such as a single sign-on exchange lazily or from a cache, and give any step that waits on the network its own time limit.
114114* **Tolerate being invoked from inside itself.** Claude Code applies the launcher to every nested self-spawn, so a launcher that acquires an exclusive resource must detect that it already holds it.
115* **Don't write to the terminal before Claude Code starts.** Anything printed before the `exec` is reported as the crash cause if the session dies before initializing.
115* **Don't write to the terminal or standard output before Claude Code starts.** Anything printed before the `exec` is reported as the crash cause if the session dies before initializing. Text on standard output also reaches a program that reads Claude Code's output, such as a script that parses `claude -p` results.
116116* **Don't depend on how arguments are spelled.** A flag's value can arrive as its own argument, `--flag value`, or joined to the flag, `--flag=value`. Which form a flag uses can change between versions.
117117* **Run `exec` from the directory the launcher started in.** Claude Code works in the directory it starts in, so a launcher that changes directory can start a session in the wrong project. If the launcher must enter a namespace or sandbox that resets the working directory, change back to the starting directory inside it, before the `exec`.
118* **Don't read standard input.** A command that reads it before the `exec`, such as one that asks for a password, can wait for input that doesn't come and leave the session stuck. It can also take input meant for Claude Code, and the session can then run without that input and report no error. Redirect such a command's input from `/dev/null`.
119* **Call other programs by absolute path.** The launcher can start with a `PATH` that lacks the directories your shell profile adds.
118120
119121### Format of the launcher value
120122
from line 124
122124
123125To pass your launcher arguments of its own, write them after the path. Claude Code parses the value as an argument list, not a shell command:
124126
125* Whitespace separates tokens, and double quotes group a token that contains spaces.
127* Whitespace separates tokens, and double quotes group a token that contains spaces. A single quote is an ordinary character, so `'a b'` is two tokens.
126128* A value that starts with `[` is read as a JSON string array, such as `["/opt/corp/launcher", "--profile", "cc"]`.
127129* Shell syntax doesn't work: there is no variable expansion or globbing, and an unquoted operator such as `;`, `|`, `&`, or `$(` is rejected as a configuration error rather than reinterpreted.
128130
129131When the value can't be used, Claude Code refuses to start the affected process and [reports the reason](/docs/en/errors#claude_code_process_wrapper-launcher-errors).
132
133In a settings file, write the array form inside a JSON string and escape its quotes: `"[\"/opt/corp/launcher\", \"--profile\", \"cc\"]"`.
134
135### Pass arguments to the launcher
136
137Write the launcher's own arguments after its path in [the value](#format-of-the-launcher-value), and remove them in the script before the `exec` call. They reach the script first, ahead of the Claude Code command. The following script, written for the value `/opt/corp/launcher --profile cc`, saves the profile name and then removes both arguments with `shift`:
138
139```bash theme={null}
140#!/bin/sh
141if [ "$1" = "--profile" ]; then
142 profile="$2"
143 shift 2
144fi
145# Your organization's setup for "$profile".
146exec "$@"
147```
148
149Use the [Verify step](#set-up-the-launcher) to see the launch command Claude Code resolved from the value.
130150
131151## Relationship to `CLAUDE_CODE_SHELL_PREFIX`
132152
errors Changed · +26 / -2 lines
### Was not reviewed and did not run
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 35
3535| `Auto mode classifier transcript exceeded context window` | [Server errors](#auto-mode-cannot-determine-the-safety-of-an-action) |
3636| `Agent aborted: auto mode classifier request refused by the safety safeguard` | [Server errors](#auto-mode-cannot-determine-the-safety-of-an-action) |
3737| `The server-side auto mode classifier gave no verdict` | [Server errors](#the-server-returned-no-safety-verdict) |
38| `<tool> was not reviewed and did not run: the conversation is too long for auto mode's classifier` | [Server errors](#was-not-reviewed-and-did-not-run) |
3839| `Auto mode is unavailable — the server returned no safety verdict for the last 10 responses` | [Server errors](#the-server-returned-no-safety-verdict) |
3940| `Agent terminated early due to an API error` | [Server errors](#agent-terminated-early-due-to-an-api-error) |
4041| `You've hit your session limit` / `You've hit your weekly limit` / `You've hit your Opus limit` / `You've hit your Sonnet limit` | [Usage limits](#youve-hit-your-session-limit) |
from line 602
601602<model> is temporarily unavailable, so auto mode cannot determine the safety of <tool> right now. Wait a moment and then try this action again.
602603```
603604
604In an interactive session, a dim `Not run · auto mode's check had no usable answer` row appears under the tool call instead of this message. Press `Ctrl+O` to read the message in the [transcript viewer](/docs/en/interactive-mode#transcript-viewer). The denials under [The server returned no safety verdict](#the-server-returned-no-safety-verdict) show the same row. Before v2.1.296, the message appeared under the call as a red error.
605In an interactive session, a dim `Not run · auto mode's check had no usable answer` row appears under the tool call instead of this message. Press `Ctrl+O` to read the message in the [transcript viewer](/docs/en/interactive-mode#transcript-viewer). The `gave no verdict` denials under [The server returned no safety verdict](#the-server-returned-no-safety-verdict) show the same row. Before v2.1.296, the message appeared under the call as a red error.
605606
606607When Claude Code can determine the failure category, it names the category in parentheses after `temporarily unavailable`, for example `<model> is temporarily unavailable (rate-limited), so auto mode cannot determine the safety of <tool> right now`. The categories are `(rate-limited)`, `(overloaded)`, `(server error)`, `(timed out)`, and `(connection failed)`. If `(timed out)` or `(connection failed)` repeats, check your connection; see [Unable to connect to API](#unable-to-connect-to-api). Before v2.1.229, the message never named a category and read `Wait briefly and then try this action again`.
607608
from line 613
612613* Retry after a few seconds; Claude sees the same message and usually retries on its own. A transient failure is unrelated to [auto mode eligibility](/docs/en/permission-modes#eliminate-prompts-with-auto-mode); you don't need to change settings
613614* If retries keep failing, continue with read-only tasks and come back to the blocked action later
614615* On Amazon Bedrock, if the message returns on every retry, check that your account can invoke the model it names: for standard Amazon Bedrock models, confirm your [IAM policy](/docs/en/amazon-bedrock#iam-configuration) allows invoking it; for Mantle model IDs, [contact your AWS account team](/docs/en/amazon-bedrock#mantle-endpoint-errors)
616* If the message returns on every retry and names the model you set in [`CLAUDE_CODE_AUTO_MODE_MODEL`](/docs/en/permission-modes#choose-the-classifier-model), check that the API or cloud provider your session runs on serves that model ID. If it doesn't, set the variable to a model ID it serves, or unset the variable to use the [default classifier model](/docs/en/permission-modes#default-classifier-model).
615617
616618When a classifier request fails because your OAuth token expired or was rotated by another session, Claude Code refreshes the token and retries the request once, so a routine token expiry doesn't surface as this message. Before v2.1.216, an expired or rotated token failed each classifier request, and auto mode denied every checked action with this message until the token was refreshed.
617619
from line 648
646648* In an interactive session, switch to a different [permission mode](/docs/en/permission-modes) so you can approve the action when prompted
647649* Start a fresh conversation without the triggering content
648650
649When the conversation has grown larger than the classifier's context window:
651When the conversation is too long for Claude Code's classifier request and Claude Code can't [compact it on its own](#was-not-reviewed-and-did-not-run):
650652
651653```text theme={null}
652654Auto mode classifier transcript exceeded context window — falling back to manual approval (try /compact to reduce conversation size)
from line 689
687689
688690**What to do:**
689691
692* In an interactive session, press `Ctrl+O` to read the denial text in the [transcript viewer](/docs/en/interactive-mode#transcript-viewer).
693* If the denial names `(the conversation is too long for the check)`, run `/compact` at the Claude Code prompt to shorten the conversation. Until the conversation is shorter, sending another message gets the same denial. If you turned [auto-compact](/docs/en/settings-reference#autocompactenabled) off, turn it back on so Claude Code compacts on its own next time.
690694* Send another message to have Claude try again. The count of responses starts over.
691695* If the stop repeats and your requests go through an [LLM gateway or proxy](/docs/en/llm-gateway), check whether it cuts streaming responses short or rewrites them. [Server-side classifier review](/docs/en/permission-modes#server-side-classifier-review) says which gateway behavior causes denials, and the [gateway compatibility guide](/docs/en/llm-gateway-protocol#feature-pass-through) lists what to pass through unchanged.
692696* Set `CLAUDE_CODE_AUTO_MODE_SERVER=0` before you start Claude Code to use its own classifier requests instead. Before v2.1.281, Claude Code didn't read the variable on a direct connection to the Anthropic API.
from line 698
694698
695699Before v2.1.280, Claude Code denied each action from a response without a verdict immediately and never stopped the turn.
696700
701Before 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.
702
703### Was not reviewed and did not run
704
705A `was not reviewed and did not run` denial means the conversation is too long for the [auto mode](/docs/en/permission-modes#eliminate-prompts-with-auto-mode) classifier to check the action, so the action didn't run. Claude Code returns this message to Claude:
706
707```text theme={null}
708<tool> was not reviewed and did not run: the conversation is too long for auto mode's classifier. Claude Code will try to compact the conversation before the next request; if this action is still needed after that, issue it again and it will be reviewed normally.
709```
710
711If the compaction fails, later actions the classifier can't check get one of two other messages:
712
713* A [`gave no verdict (the conversation is too long for the check)`](#the-server-returned-no-safety-verdict) denial
714* The [`Auto mode classifier transcript exceeded context window`](#auto-mode-cannot-determine-the-safety-of-an-action) message
715
716**What to do:**
717
718* If the compaction the message announces succeeds, you don't need to do anything.
719* If you see either of those two messages, run `/compact` at the Claude Code prompt to shorten the conversation yourself. If you turned [auto-compact](/docs/en/settings-reference#autocompactenabled) off, turn it back on so Claude Code compacts on its own next time.
720
697721### Agent terminated early due to an API error
698722
699723A [subagent](/docs/en/sub-agents)'s API request failed terminally, for example because a usage limit was reached or retries for a server error ran out, so the subagent stopped before finishing its task. This message requires Claude Code v2.1.199 or later; before then the API error text was returned to Claude as if it were the subagent's result.
from line 2755
27312755[Unsupported tool content removed]
27322756```
27332757
2734Such content reaches a session file when something other than the Anthropic API answered in the API's format, typically a third-party proxy set through [`ANTHROPIC_BASE_URL`](/docs/en/env-vars) that translates another provider's tool calls. Claude Code removes it only when the session connects directly to the Anthropic API, and loads the saved history as it is when the session runs through a proxy or on another provider. Before v2.1.246, Claude Code sent the tool use and its result back to the API, and every turn of the resumed session failed with a 400 error such as `messages.1.content.0.server_tool_use.name: Input should be 'web_search', 'web_fetch', ...`.
2735
2736**What to do:**
2737
2738* None needed when you see the placeholder line. The session continues without the removed content.
2739* If every turn of a resumed session fails with the 400 error instead, run `claude update` and resume the session again. Versions before v2.1.246 don't remove the content.
2740
2741<h3 id="role-system-must-precede-an-assistant-message">
2742 role 'system' must precede an 'assistant' message
2743</h3>
2744
2745The API refused the request with a 400 because a system message sits at a position in the conversation it doesn't accept:
2746
2747```text theme={null}
2748API Error: 400 messages.6: role 'system' must precede an 'assistant' message or end the array; ...
2749```
2750
2751Claude Code sends some of its reminder and attachment text as system messages inside the conversation. When the API refuses one's position, Claude Code retries the request once with that text sent as ordinary user messages instead. The API's sibling placement wordings, such as `use the top-level 'system' parameter for the initial system prompt`, get the same recovery.
2752
2753When the error does appear, the refused system message isn't one Claude Code can remove. That usually means a proxy or [LLM gateway](/docs/en/llm-gateway) between Claude Code and the API added a system message of its own.
2754
2755**What to do:**
2756
2757* If the error repeats on every turn behind a proxy or gateway configured through [`ANTHROPIC_BASE_URL`](/docs/en/env-vars), connect without the proxy to confirm the source, and report the error to whoever operates it
2758* Run `/clear` to start a fresh conversation. If the error returns there too, the cause is on the request path, not in the saved conversation.
2759
2760Before v2.1.280, Claude Code didn't recognize this wording, so the error also appeared when the refused system message was one Claude Code itself sent, and every later turn of the conversation failed the same way.
2761
2762<h3 id="invalid-encrypted-content-in-search-result-block">
2763 Invalid encrypted\_content in search\_result block
2764</h3>
2765
2766The API refused the request with a 400 because the conversation history holds hosted web-search content it can't decrypt. The wording names the field it can't read:
2767
2768```text theme={null}
2769API Error: 400 ... Invalid `encrypted_content` in `search_result` block
2770API Error: 400 ... Invalid `encrypted_index` in `text` block
2771API Error: 400
2758Such content reaches a session file when something other than the Anthropic API answered in the API's format, typically a third-party proxy set through [`ANTHROPIC_BASE_URL`](/docs/en/env-vars) that translates another provider's tool calls. Claude Code removes it only when the session connects directly to the Anthropic API, and loads the saved
permission-modes Changed · +102 / -7 lines
### Choose the classifier model
from line 78
7878| How you run Claude Code | Built-in starting permission mode |
7979| :- | :- |
8080| Any settings file sets `disableAutoMode` to `"disable"` | `default` |
81| `claude -p` or the [Agent SDK](/docs/en/agent-sdk/permissions#permission-modes) | `default` in sessions that [fetch feature flags](/docs/en/env-vars#features-that-need-feature-flag-fetching). In sessions that don't, such as on a third-party provider or with telemetry off, `auto` with Claude Code v2.1.285 or later and `default` on earlier versions. A session in an organization whose policy withholds the `auto` default starts in `default` instead |
81| `claude -p` or the [Agent SDK](/docs/en/agent-sdk/permissions#permission-modes) | `default` |
8282| Your organization has the [HIPAA configuration](#hipaa-configuration) applied and the session is [eligible for it](/docs/en/hipaa-setup#check-how-developers-sign-in-and-connect) | `default` with Claude Code v2.1.285 or later; auto mode stays available to switch to |
8383| In a terminal or through the [VS Code extension](/docs/en/vs-code) | `auto` with Claude Code v2.1.283 or later; on earlier versions, `auto` on Pro, Max, or Team plans in sessions that [fetch feature flags](/docs/en/env-vars#features-that-need-feature-flag-fetching), and `default` otherwise |
8484
85In your [first session after an install or upgrade](/docs/en/env-vars#first-session-after-an-install-or-upgrade), Claude Code can choose the starting permission mode before its feature flags arrive. That session can start in a different permission mode than the table gives.
86
8785When the flag, a settings file, or the built-in default selects `auto` but auto mode isn't available to the session, Claude Code starts the session in Manual instead. Auto mode is unavailable when the session doesn't meet the [availability requirements](#eliminate-prompts-with-auto-mode), such as a settings file turning it off or a model that doesn't support it, or when Anthropic has temporarily turned it off server-side.
8886
8987The first time the built-in default starts one of your sessions in auto mode, Claude Code shows a notice that links to this page:
from line 91
9391
9492If your `~/.claude/settings.json` sets a `defaultMode` other than `auto` and no other settings file sets one, your sessions keep starting in that mode. On Pro, Max, and Team plans, and in sessions that [don't fetch feature flags](/docs/en/env-vars#features-that-need-feature-flag-fetching), Claude Code asks once, in the terminal or in the VS Code extension, whether to change the setting to auto mode. If you decline, your setting stays as it is.
9593
94<h3 id="which-mode-a-non-interactive-run-starts-in">
95 Tool calls denied in `claude -p` and Agent SDK runs
96</h3>
97
98In Claude Code v2.1.302 or later, `claude -p` and [Agent SDK](/docs/en/agent-sdk/permissions#permission-modes) runs with [no permission mode set](#which-mode-a-session-starts-in) start in Manual mode. This mode appears as `default` in SDK options and settings. Calls needing approval are denied unless you approve them with an allow rule, hook, `canUseTool` callback, or `--permission-prompt-tool`.
99
100To get these calls approved, add allow rules or start in auto mode:
101
102* **[Add allow rules](/docs/en/permissions#manage-permissions)**: Claude runs the calls you list. Pass [`--allowedTools "Bash(npm test)"`](/docs/en/headless#auto-approve-tools) to `claude -p`, or set your SDK's [allowed-tools option](/docs/en/agent-sdk/permissions#allow-and-deny-rules).
103* **Start in [auto mode](#eliminate-prompts-with-auto-mode)**: a classifier model reviews calls, so you list nothing beforehand. Pass `--permission-mode auto` to `claude -p`, or set your SDK's [permission mode option](/docs/en/agent-sdk/permissions#set-permission-mode).
104
105These examples show the auto mode form for the CLI and each SDK:
106
107<Tabs>
108 <Tab title="CLI">
109 ```bash theme={null}
110 claude -p "Run the test suite and fix any failures" --permission-mode auto
111 ```
112 </Tab>
113
114 <Tab title="TypeScript">
115 ```typescript theme={null}
116 const options = {
117 permissionMode: "auto"
118 };
119 ```
120 </Tab>
121
122 <Tab title="Python">
123 ```python theme={null}
124 from claude_agent_sdk import ClaudeAgentOptions
125
126 options = ClaudeAgentOptions(permission_mode="auto")
127 ```
128 </Tab>
129</Tabs>
130
131Before v2.1.302, these runs could start in auto mode if they didn't [fetch feature flags](/docs/en/env-vars#features-that-need-feature-flag-fetching), for example on a [third-party provider](/docs/en/third-party-integrations) or with `DISABLE_TELEMETRY`.
132
96133<h3 id="start-in-a-different-mode">
97134 Start in a different permission mode
98135</h3>
from line 364
327364 Auto mode on Bedrock, Agent Platform, or Foundry
328365</h3>
329366
330On [Amazon Bedrock](/docs/en/amazon-bedrock), [Google Cloud's Agent Platform](/docs/en/google-vertex-ai), [Microsoft Foundry](/docs/en/microsoft-foundry), and signed-in [Claude apps gateway](/docs/en/claude-apps-gateway) sessions, auto mode is available by default. When nothing else sets a permission mode, it's also the [built-in starting permission mode](#which-mode-a-session-starts-in), on the versions that section's table lists. To choose the starting permission mode yourself, set `permissions.defaultMode` as [Start in a different permission mode](#start-in-a-different-mode) describes, or pick a permission mode from the VS Code extension's mode indicator.
367On [Amazon Bedrock](/docs/en/amazon-bedrock), [Google Cloud's Agent Platform](/docs/en/google-vertex-ai), [Microsoft Foundry](/docs/en/microsoft-foundry), and signed-in [Claude apps gateway](/docs/en/claude-apps-gateway) sessions, auto mode is available by default. If you don't set a permission mode there, interactive sessions start in auto mode, and `claude -p` or Agent SDK runs start in Manual mode, whose config value is `default`:
331368
369* **Interactive terminal and VS Code sessions**: to start them in a permission mode other than auto, set `permissions.defaultMode` as [Start in a different permission mode](#start-in-a-different-mode) describes, or pick one from the VS Code extension's [mode indicator](#switch-permission-modes). [Which mode a session starts in](#which-mode-a-session-starts-in) lists the Claude Code versions that start them in auto mode.
370* **`claude -p` and Agent SDK runs**: to start one in auto mode, pass `--permission-mode auto` to `claude -p`, or pass `permissionMode: "auto"` in TypeScript or `permission_mode="auto"` in Python. If you pass no permission mode, see [Tool calls denied in `claude -p` and Agent SDK runs](#which-mode-a-non-interactive-run-starts-in), which also covers earlier Claude Code versions.
371
332372Only Claude Sonnet 5 or later, Opus 4.7 or later, Haiku 5.5, and the Fable models are supported on these providers. On any other model, the session starts in Manual instead. Auto mode with Haiku 5.5 on these providers requires Claude Code v2.1.293 or later.
333373
334374To prevent developers from using auto mode, set `disableAutoMode` to `"disable"` in [managed settings](/docs/en/managed-settings). This removes `auto` from the `Shift+Tab` cycle, and a session started with `--permission-mode auto` starts in Manual instead. A session already running in auto mode leaves it when the setting reaches that session from an [admin-deployed source](/docs/en/managed-settings#which-managed-source-claude-code-uses), and shows `auto mode disabled by settings`. Before v2.1.251, a running session kept auto mode until it ended.
from line 388
348388
349389To skip asking the server and always use Claude Code's own classifier requests, set [`CLAUDE_CODE_AUTO_MODE_SERVER=0`](/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](/docs/en/llm-gateway-protocol#disable-pre-release-capabilities) describes.
350390
391<h3 id="default-classifier-model">
392 Default classifier model
393</h3>
394
395By default, classifier requests go to Claude Sonnet 5. If `/status` shows `Auto mode server` as `Enabled`, they're sent only for calls outside [the server's review](#server-side-classifier-review).
396
397Find the first row in this table that matches your session. You get that row's model in place of Sonnet 5.
398
399| Your session | Classifier model |
400| - | - |
401| Has an Anthropic-configured classifier model | The configured model. [Check the debug log](#classifier-model-check) to see which |
402| Runs on Claude Sonnet 4.6 | Sonnet 4.6 |
403| Has [`ANTHROPIC_DEFAULT_SONNET_MODEL`](/docs/en/model-config#environment-variables) set | Its value, or Sonnet 5 if its value is Claude Sonnet 5.5 or Claude Opus 5.5 |
404
405If Sonnet 5 or the model in `ANTHROPIC_DEFAULT_SONNET_MODEL` is unavailable from your provider or excluded by your organization's [model policy](/docs/en/model-config#restrict-model-selection), Claude Code uses a fallback model. That's your session's model, or an Opus model in a [Fable session](/docs/en/model-config#work-with-fable).
406
407### Choose the classifier model
408
409With Claude Code v2.1.302 or later, set [`CLAUDE_CODE_AUTO_MODE_MODEL`](/docs/en/env-vars) to a full model ID to run the classifier on a model other than the [default](#default-classifier-model). Your cloud provider's own full model IDs work too. This `~/.claude/settings.json` example sets Claude Sonnet 4.6:
410
411```json theme={null}
412{
413 "env": {
414 "CLAUDE_CODE_AUTO_MODE_MODEL": "claude-sonnet-4-6"
415 }
416}
417```
418
419<h4 id="classifier-model-not-reviewing">
420 When your model isn't the one reviewing
421</h4>
422
423| Situation | What happens | What to do |
424| - | - | - |
425| In a session, `/status` shows [`Auto mode server`](#server-side-classifier-review) as `Enabled` | Your model reviews only what the server doesn't | None needed |
426| You set Claude Opus 5, Claude Sonnet 5.5, Claude Opus 5.5 or a model your organization's [model policy](/docs/en/model-config#restrict-model-selection) excludes | The [default classifier model](#default-classifier-model) reviews | Set a different model |
427| Anthropic configured a classifier model for your session | That model reviews | None needed |
428| Your provider can't serve the model | Requests fail and Claude Code [denies every reviewed action](/docs/en/errors#auto-mode-cannot-determine-the-safety-of-an-action) | Set a model it serves, or remove the variable |
429
430<h4 id="classifier-model-check">
431 Check which model the classifier used
432</h4>
433
434From your shell, start an auto mode session with [`--debug-file`](/docs/en/cli-reference#cli-flags):
435
436```bash theme={null}
437claude --permission-mode auto --debug-file classifier-debug.log
438```
439
440Have Claude run a shell command that isn't read-only, then search the log for `classifier_request_started`:
441
442* **Your model after `model=`**: the variable took effect
443* **A different model after `model=`**: search the log for `ignoring CLAUDE_CODE_AUTO_MODE_MODEL`, which gives the reason and any step to take
444* **No such line**: read `Auto mode server` in `/status` at the Claude Code prompt:
445 * **`Enabled`**: the [server](#server-side-classifier-review) is set to review this session's calls. Nothing to change.
446 * **`Disabled`**: make sure the [permission mode](#switch-permission-modes) is auto, then have Claude run another command that isn't read-only.
447
351448### What the classifier blocks by default
352449
353450The classifier trusts your working directory and the remotes that were configured for it when the session started. A remote added or repointed during the session with `git remote add` or `git remote set-url` isn't trusted, and everything else is treated as external until you [configure trusted infrastructure](/docs/en/auto-mode-config).
from line 633
536633 </Accordion>
537634
538635 <Accordion title="Cost and latency">
539 The classifier runs on Claude Sonnet 5 by default rather than on your `/model` selection. A classifier model that Anthropic configures server-side takes precedence over that default. When your session's model is Claude Sonnet 4.6, or when [`availableModels`](/docs/en/model-config#restrict-model-selection) excludes Sonnet 5, the classifier runs on the session's model instead, or on an Opus model when the session runs on a [Fable model](/docs/en/model-config#work-with-fable). On providers other than the Anthropic API, that Opus fallback is the model you set in [`ANTHROPIC_DEFAULT_OPUS_MODEL`](/docs/en/model-config#environment-variables), or Opus 5 if you haven't set one.
540
541 The session's first auto-mode request validates the Sonnet 5 default: if the request succeeds, Sonnet 5 stays the session's classifier model, and if it fails because the model isn't available, the session uses the fallback instead.
636 Claude Code's classifier requests can run on a model other than your `/model` selection. See [which model they run on](#default-classifier-model).
542637
543638 On Enterprise plans and on accounts that use the Claude API, [Claude Platform on AWS](/docs/en/claude-platform-on-aws), Amazon Bedrock, Google Cloud's Agent Platform, or Microsoft Foundry, classifier calls count toward your token usage. Each check sends a portion of the transcript plus the pending action, adding a round-trip before execution. Reads and working-directory edits outside protected paths skip the classifier, so the overhead comes mainly from shell commands and network operations. Where the server reviews the actions as part of the session's model requests, there are no separate classifier calls to count; see [Server-side classifier review](#server-side-classifier-review).
544639
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.
from line 526
526526| `outputFormat` | `{ type: 'json_schema', schema: JSONSchema }` | `undefined` | Define output format for agent results. See [Structured outputs](/docs/en/agent-sdk/structured-outputs) for details |
527527| `outputStyle` | `string` | `undefined` | Not an `Options` field. Set `outputStyle` in the inline [`settings`](/docs/en/settings) object or a settings file instead. See [Activate an output style](/docs/en/agent-sdk/modifying-system-prompts#activate-an-output-style) |
528528| `pathToClaudeCodeExecutable` | `string` | Auto-resolved from bundled native binary | Path to Claude Code executable. Only needed if optional dependencies were skipped during install or your platform isn't in the supported set |
529| `permissionMode` | [`PermissionMode`](#permissionmode) | `undefined` | Permission mode for the session. If you omit it, the session can start in auto mode. See [Permission modes](/docs/en/agent-sdk/permissions#permission-modes) for how Claude Code picks the starting permission mode |
529| `permissionMode` | [`PermissionMode`](#permissionmode) | `undefined` | Permission mode for the session. If you omit it and nothing else sets a permission mode, such as a [`permissions.defaultMode`](/docs/en/settings-reference#permissions-defaultmode) setting, the session starts in `default`. See [Permission modes](/docs/en/agent-sdk/permissions#permission-modes) |
530530| `permissionPromptToolName` | `string` | `undefined` | MCP tool name for permission prompts |
531531| `permissionPrompts` | `'host' \| 'none'` | `'host'` | Who answers permission prompts: `'host'` routes them to your [`canUseTool`](#canusetool) callback or the `permissionPromptToolName` tool, and `'none'` [denies the calls that would have prompted](/docs/en/agent-sdk/permissions#how-permissions-are-evaluated). Requires Claude Code v2.1.259 or later |
532532| `persistSession` | `boolean` | `true` | When `false`, disables session persistence to disk. Sessions cannot be resumed later |
from line 5266
52665266
52675267When Claude Code [moves a long MCP tool call to the background](/docs/en/mcp#automatic-backgrounding-of-long-tool-calls), the `tool_result` block for that call holds only a placeholder and the call's real result arrives in this notification. Match the notification to the call with `tool_use_id`. On a `completed` notification, `resource_links` lists the files the tool returned by reference as [`SDKMcpResourceLink`](#sdkmcpresourcelink) entries, with the same 50-link and 64 KiB limits as [`tool_use_result.resourceLinks`](#sdkusermessage). Claude Code omits `resource_links` when the result had no links and on notifications for tasks that aren't MCP tool calls. `resource_links` requires Agent SDK v0.3.257 or later.
52685268
5269Claude Code prepends a notice to every task notification it sends to the model, except deliveries stamped with the [`scheduled-trigger` subkind](#task-notification-subkinds), which carry an assigned-task framing instead. The notice states that no human input has occurred, so the model doesn't treat the notification as a user instruction or approval.
5270
5271To detect a task-notification turn, check `origin.kind === "task-notifica
5269Claude Code prepends a notice to every task notification it sends to the model, except deliveries stamped with the [`scheduled-trigger` subkind](#task-notification-subkinds), which carry an assigned-task framing instead. The notice states that no human input has occurred, so the model doesn't treat the notification as a user instruction or ap
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.
headless Changed · +3 / -1 lines
from line 300
300300 --allowedTools "Bash,Read,Edit"
301301```
302302
303To set a baseline for the whole session instead of listing individual tools, pass a [permission mode](/docs/en/permission-modes). A run where nothing sets a permission mode takes the [built-in starting permission mode](/docs/en/permission-modes#which-mode-a-session-starts-in), which can be `auto`, so pass the one you want:
303Calls to tools you didn't list run if they need no approval. In a [Manual mode](/docs/en/permission-modes#available-modes) `claude -p` run, a call that needs approval is denied unless something approves it, such as a [`PermissionRequest` hook](/docs/en/hooks#permissionrequest) or a [`--permission-prompt-tool`](/docs/en/cli-reference#cli-flags). With Claude Code v2.1.302 or later, `claude -p` runs start in Manual mode when [nothing sets a permission mode](/docs/en/permission-modes#which-mode-a-non-interactive-run-starts-in).
304
305To set a baseline for the whole session instead of listing individual tools, pass a [permission mode](/docs/en/permission-modes) with `--permission-mode`, such as `auto`, `dontAsk`, or `acceptEdits`:
304306
305307* **`auto`**: pass `--permission-mode auto` to have a classifier review most actions instead of you
306308* **`dontAsk`**: Claude Code denies every call that would otherwise prompt, which is useful for locked-down CI runs. Actions that need no approval in Manual mode still run, such as file reads in your working directories and the [read-only command set](/docs/en/permissions#read-only-commands), and so do actions your `--allowedTools` entries or `permissions.allow` rules cover. `AskUserQuestion`, connector tools [your organization set to `ask`](/docs/en/mcp#organization-controls-on-connector-tools), MCP tools marked [`requiresUserInteraction`](/docs/en/mcp#require-approval-for-a-specific-tool), and [reads from network paths](/docs/en/permissions#network-paths) are denied even when an allow rule matches
model-config Changed · +2 / -1 lines
from line 254
254254* **Skill or command override**: Claude Code ignores the override, including a blocked family alias, and the skill or command runs on the session model. A skill or command that [runs in a subagent](/docs/en/skills#run-skills-in-a-subagent) follows the subagent behavior above instead
255255* **`advisorModel` setting**: the advisor is disabled for the session
256256* **`--advisor` flag**: Claude Code exits with an error at launch. In a [background session](/docs/en/agent-view), it starts the session without the advisor instead of exiting
257* **`CLAUDE_CODE_AUTO_MODE_MODEL`**: Claude Code ignores the variable and picks the model for its [auto mode classifier requests](/docs/en/permission-modes#default-classifier-model) as if you hadn't set it
257258
258259Claude Code hides excluded models from the `/model` picker. Whether a model ID you list also gets a row of its own differs by provider:
259260
from line 266
265266* **[Fallback model chains](#fallback-model-chains)**: entries outside the allowlist are dropped
266267* **Plan-mode upgrades**: on the Anthropic API and Claude Platform on AWS, an upgrade such as [`opusplan`](#opusplan-model-setting) to an excluded model uses the newest permitted version of the upgrade family. On providers with provider-specific model IDs, and when no version is permitted, the upgrade is skipped and planning continues on the session's model
267268* **[Automatic model fallback](#automatic-model-fallback)**: a fallback whose target is excluded does not run, so the flagged request ends with a refusal instead
268* **[Auto mode classifier](/docs/en/permission-modes#eliminate-prompts-with-auto-mode)**: the classifier's Claude Sonnet 5 default applies only when the allowlist permits Sonnet 5. When it's excluded, the classifier runs on the session's model, which the allowlist already governs, or on an Opus model when the session runs on a [Fable model](#work-with-fable). On providers other than the Anthropic API, that Opus fallback runs on the model you set in `ANTHROPIC_DEFAULT_OPUS_MODEL` or otherwise on Opus 5, without consulting the allowlist. Requires Claude Code v2.1.210 or later
269* **[Auto mode classifier](/docs/en/permission-modes#eliminate-prompts-with-auto-mode)**: when the allowlist excludes the [default classifier model](/docs/en/permission-modes#default-classifier-model), classifier requests that would use that model run on the session model, or an Opus model in [Fable](#work-with-fable) sessions. On providers other than the Anthropic API, that Opus fallback runs on the model you set in `ANTHROPIC_DEFAULT_OPUS_MODEL` or otherwise on Opus 5, without consulting the allowlist. Requires Claude Code v2.1.210 or later
269270* **[Fast mode](/docs/en/fast-mode)**: enabling fast mode is refused when the model the session would run on afterward is outside the allowlist
270271* **Availability fallback on Amazon Bedrock and Google Cloud's Agent Platform**: when your account loses access to a model mid-session, the switch to another model skips excluded models. The startup model checks on [Amazon Bedrock](/docs/en/amazon-bedrock#when-your-organization-enforces-a-model-allowlist) and [Google Cloud's Agent Platform](/docs/en/google-vertex-ai#when-your-organization-enforces-a-model-allowlist) skip excluded models only when managed settings also set [`enforceAvailableModels`](#enforce-the-allowlist-for-the-default-model)
271272
troubleshooting Changed · +1 / -0 lines
from line 11
1111| Login loops, OAuth errors, `403 Forbidden`, "organization disabled", Amazon Bedrock, Google Cloud's Agent Platform, or Microsoft Foundry credentials | [Troubleshoot installation and login](/docs/en/troubleshoot-install#login-and-authentication) |
1212| Settings not applying, hooks not firing, MCP servers not loading | [Debug your configuration](/docs/en/debug-your-config) |
1313| Session started in auto mode, or Claude edits files and runs commands without asking | [Which mode a session starts in](/docs/en/permission-modes#which-mode-a-session-starts-in) |
14| After you update Claude Code or the Agent SDK, tool calls are denied in `claude -p` or SDK runs that don't pass `--permission-mode`, `permissionMode`, or `permission_mode` | [Tool calls denied in `claude -p` and Agent SDK runs](/docs/en/permission-modes#which-mode-a-non-interactive-run-starts-in) |
1415| `API Error: 5xx`, `529 Overloaded`, `429`, request validation errors | [Error reference](/docs/en/errors) |
1516| `model not found` or `you may not have access to it` | [Error reference](/docs/en/errors#theres-an-issue-with-the-selected-model) |
1617| A command Claude runs fails with `Your disk quota is full`, `is full (ENOSPC)`, or `Command output was lost` | [Error reference](/docs/en/errors#disk-quota-or-temp-filesystem-is-full) |