One read of Claude Code CLIclaude-code-20260816T143701Z
18 pages moved out of 187 read.
Pages moved
18
significant first
Pages read
187
in this capture
Captured
14:37 UTC
Corpus hash
43fd70e9a19d
corpus-hash
What this read moved
1-18 of 18agent-sdk/hooks Changed · +6 / -8 lines
from line 645
645645
646646### Forward notifications to Slack
647647
648Use `Notification` hooks to receive system notifications from the agent and forward them to external services. Notifications fire for event types such as:
648Use `Notification` hooks to receive system notifications from the agent and forward them to external services. In SDK sessions, Claude Code runs this hook for the following notification types:
649649
650* `permission_prompt` when Claude needs permission
651* `idle_prompt` when Claude is waiting for input
652* `auth_success` when authentication completes
653* `elicitation_dialog`, `elicitation_complete`, and `elicitation_response` for user-prompt elicitation flows
650* [`permission_prompt`](/docs/en/hooks#notification) once a permission request has waited about six seconds on your [`canUseTool` callback](/docs/en/agent-sdk/user-input). Requires TypeScript Agent SDK v0.3.233 or later, or Python Agent SDK v0.2.139 or later
651* `elicitation_complete` and `elicitation_response` for user-prompt elicitation flows
654652
655In headless SDK sessions, only the elicitation events `elicitation_complete` and `elicitation_response` fire this hook; the other types are emitted by interactive UI that SDK sessions don't run. Permission requests, for example, go to the `canUseTool` callback instead.
653Claude Code emits the other types, such as `idle_prompt`, `auth_success`, and `elicitation_dialog`, from interactive UI that SDK sessions don't run.
656654
657655Each notification includes a `message` field with a human-readable description and optionally a `title`.
658656
agent-sdk/typescript Changed · +97 / -2 lines
### `SDKContextUsage` ### `SDKContextUsageCategory`
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 657
657657
658658### `SDKControlGetContextUsageResponse`
659659
660Return type of [`getContextUsage()`](#query-object). This is the same payload the `/context` command renders in an interactive session, so alongside the token counts it carries display fields such as `color`, `gridRows`, and `percentage` that `/context` uses to draw its usage grid.
660Return type of [`getContextUsage()`](#query-object). This is the same payload Claude Code renders for the `/context` command in an interactive session, so alongside the token counts it carries display fields such as `color` and `gridRows` that Claude Code uses to draw the `/context` usage grid.
661661
662When you send `/context` as a prompt instead of calling the method, Claude Code attaches an [`SDKContextUsage`](#sdkcontextusage) payload to the `context_usage` field of the assistant message that delivers the result. That field requires Agent SDK v0.3.232 or later.
663
662664```typescript theme={null}
663665type SDKControlGetContextUsageResponse = {
664666 categories: {
from line 762
760762* `memoryFiles` lists each loaded memory file with its cost.
761763* `skills.skillFrontmatter` attributes the skill listing's tokens to each included skill. The per-skill counts measure each skill's listing entry as Claude Code actually sends it, which can be shorter than the skill's full frontmatter. Compare `skills.totalSkills` with `skills.includedSkills` to see whether every discovered skill made it into the listing.
762764
763`totalTokens` is the session's current context usage, and `maxTokens` is the window that usage is measured against. That window is the model's context window, or the lower auto-compaction window when one applies. Claude Code leaves the optional `deferredBuiltinTools`, `systemTools`, and `systemPromptSections` diagnostics unset, so expect them to be absent even though the type declares them.
765`totalTokens` is the session's current context usage, and `maxTokens` is the window that usage is measured against. That window is the model's context window, or the lower auto-compaction window when one applies. `rawMaxTokens` carries the same value as `maxTokens`, and `percentage` is `totalTokens` as a rounded percentage of that window.
764766
767Claude Code leaves the optional `deferredBuiltinTools`, `systemTools`, and `systemPromptSections` diagnostics unset, so expect them to be absent even though the type declares them.
768
765769### `SDKControlReadFileResponse`
766770
767771Return type of [`readFile()`](#query-object).
from line 1144
11401144 error?: SDKAssistantMessageError;
11411145 aborted?: true;
11421146 timestamp?: string;
1147 context_usage?: SDKContextUsage;
11431148};
11441149```
11451150
from line 1156
11511156
11521157`timestamp` is the ISO 8601 time when the message's content finished generating on the process that produced it. The value comes from that machine's clock, so use it for display only and don't order messages by it. One API turn can produce several assistant messages that share a `message.id`, each with its own `timestamp`. When the field is absent, fall back to the time you received the message.
11531158
1159`context_usage` is a structured copy of the `/context` report, typed as [`SDKContextUsage`](#sdkcontextusage), and requires Agent SDK v0.3.232 or later. When you send `/context` as a prompt, Claude Code delivers the report as an assistant message whose `message.content` holds the markdown table, and attaches `context_usage` to that same message. Claude Code doesn't set the field on any other assistant message, and earlier versions deliver the `/context` table without it, so read the breakdown from the field when it's present and fall back to the markdown text when it isn't.
1160
11541161### `SDKUserMessage`
11551162
11561163User input message.
from line 1467
14601467};
14611468```
14621469
1470### `SDKContextUsage`
1471
1472Structured form of the `/context` report, carried as `context_usage` on the [`SDKAssistantMessage`](#sdkassistantmessage) that delivers a `/context` result. Agent SDK v0.3.232 and later export the type. Unlike [`SDKControlGetContextUsageResponse`](#sdkcontrolgetcontextusageresponse), it carries only the data needed to render the usage breakdown, without display fields such as `color` and `gridRows`.
1473
1474```typescript theme={null}
1475type SDKContextUsage = {
1476 model: string;
1477 total_tokens: number;
1478 raw_max_tokens: number;
1479 percentage: number;
1480 over_limit?: {
1481 tokens_over: number;
1482 kind: "hard_limit" | "compaction_window";
1483 };
1484 categories: SDKContextUsageCategory[];
1485 mcp_tools: {
1486 name: string;
1487 server_name: string;
1488 tokens: number;
1489 }[];
1490 memory_files: {
1491 path: string;
1492 type: string;
1493 tokens: number;
1494 }[];
1495 agents: {
1496 agent_type: string;
1497 source: string;
1498 tokens: number;
1499 }[];
1500 skills?: {
1501 name: string;
1502 source: string;
1503 plugin_name?: string;
1504 tokens: number;
1505 }[];
1506};
1507```
1508
1509The table lists what Claude Code puts in each field. The fields from `model` through `over_limit` describe the session as a whole, and the collection fields attribute tokens to individual items.
1510
1511| Field | Type | Description |
1512| ---------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1513| `model` | `string` | The main loop's model Claude Code computed the usage for, not a subagent's |
1514| `total_tokens` | `number` | Claude Code's estimate of the tokens in use. Not clamped to the window, so it can exceed `raw_max_tokens` when the session is over the limit |
1515| `raw_max_tokens` | `number` | The model's context window, or the lower [auto-compact window](/docs/en/model-config#context-window-and-auto-compaction) when one applies, such as one you set or the 200K boundary Claude Code applies to some models with a 1M-token window. Claude Code measures `total_tokens` against this window |
1516| `percentage` | `number` | `total_tokens` as a rounded percentage of `raw_max_tokens`, so it can exceed 100 when the session is over the limit |
1517| `over_limit` | `object` | Present only when `total_tokens` exceeds `raw_max_tokens`. `tokens_over` is the amount over, and `kind` says how Claude Code resolved the window |
1518| `categories` | [`SDKContextUsageCategory`](#sdkcontextusagecategory)`[]` | One entry per row of the usage-by-category breakdown |
1519| `mcp_tools` | `object[]` | Tokens attributed to each MCP tool, with its wire name, such as `mcp__linear__create_issue`, and its `server_name` |
1520| `memory_files` | `object[]` | Tokens attributed to each loaded memory file, with its `path` and a source label such as `Project` or `User` in `type` |
1521| `agents` | `object[]` | Tokens attributed to each custom subagent definition, with a source identifier such as `projectSettings`, `userSettings`, or `plugin`. Built-in subagents aren't listed |
1522| `skills` | `object[]` | Tokens attributed to each skill in the skill listing, with a source identifier and, for plugin skills, the plugin's name in `plugin_name`. Absent when no skills contribute tokens |
1523
1524`over_limit.kind` records how Claude Code resolved the window, not whether the API accepts the next request:
1525
1526* `hard_limit`: the window is what Claude Code believes to be the model's own limit, past which the API refuses requests
1527* `compaction_window`: the window is a compaction-policy window, which may or may not coincide with the model's limit
1528
1529Claude Code evolves the type additively, adding new data as optional fields rather than reshaping existing ones. Read the fields you know and ignore any you don't recognize.
1530
1531### `SDKContextUsageCategory`
1532
1533One row of the `/context` usage-by-category breakdown.
1534
1535```typescript theme={null}
1536type SDKContextUsageCategory = {
1537 name: string;
1538 tokens: number;
1539 kind: "used" | "free" | "buffer" | "deferred";
1540};
1541```
1542
1543The table lists what Claude Code puts in each field of a row.
1544
1545| Field | Type | Description |
1546| -------- | -------- | -------------------------------------------------------------------------------------------------------- |
1547| `name` | `string` | The row's display name as `/context` prints it, such as `Messages`. Classify rows by `kind`, not by name |
1548| `tokens` | `number` | The row's token count. Rows can carry zero tokens |
1549| `kind` | `string` | What the row represents: `used`, `free`, `buffer`, or `deferred` |
1550
1551Each `kind` value says what the row's tokens are:
1552
1553* `used`: content that occupies the context window
1554* `free`: the remaining window
1555* `buffer`: the compaction reserve
1556* `deferred`: tool schemas Claude Code holds out of the window and excludes from the usage calculation, listed for awareness
1557
14631558### `SDKMessageOrigin`
14641559
14651560Provenance of a user-role message. This appears as `origin` on [`SDKUserMessage`](#sdkusermessage) and is forwarded onto the corresponding [`SDKResultMessage`](#sdkresultmessage) so you can tell what triggered a given turn.
from line 4321
42264321 | { type: "disabled" }; // No extended thinking
42274322```
42284323
4229The 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 `thinking` blocks. Claude Code doesn't send `display` to Amazon Bedrock or Google Cloud's Agent Platform, so on those providers Opus 4.7 and later return empty `thinking` blocks even when you set `display` to `"summarized"`.
4230
4231### `SpawnedProcess`
4232
4233Interface for custom process spawning (used with `spawnClaudeCodeProcess` option). `ChildProcess` already satisfies this interface.
4234
4235```typescript theme={null}
4236interface SpawnedProcess {
4237 stdin: Writable;
4238 stdout: Readable;
4239 readonly killed: boolean;
4240 readonly exitCode: number | null;
4241 kill(signal: NodeJS.Signals): boolean;
4242 on(
4243 event: "exit",
4244 listener: (code: number | null, signal: NodeJS.Signals | null) => void
4245 ): void;
4246 on(event: "error", listener: (error: Error) => void): void;
4247 once(
4248 event: "exit",
4249 listener: (code: number | null, signal: NodeJS.Signals | null) => void
4250 ): void;
4251 once(event: "error", listener: (error: Error) => void): void;
4252 off(
4253 event: "exit",
4254 listener: (code: number | null, signal: NodeJS.Signals | null) => void
4255 ): void;
4256 off(event: "error", listener: (error: Error) => void): void;
4257}
4258```
4259
4260### `SpawnOptions`
4261
4262Options passed to the custom spawn function.
4263
4264```typescript theme={null}
4265interface SpawnOptions {
4266 command: string;
4267 args: string[];
4268 cwd?: string;
4269 env: Record<string, string | undefined>;
4270 signal: AbortSignal;
4271}
4272```
4273
4274<Note>
4275 The `signal` field tells your spawn function when to tear down the process. Pass it as the `signal` option to Node's `spawn()`, or pass it to your VM or container teardown handler.
4276
4277 This signal does not fire the instant [`Options.abortController`](#options) aborts. The SDK first closes the process's stdin and waits about two seconds so the CLI can shut down cleanly, then aborts this signal. To react the moment the caller aborts instead, listen on your own `Options.abortController.signal`, which your spawn function can reference from its enclosing scope.
4278</Note>
4279
4280### `McpSetServersResult`
4281
4282Result of a `setMcpServers()` operation.
4283
4284```typescript theme={null}
4285type McpSetServersResult = {
4286 added: string[];
4287 removed: string[];
4288 errors: Record<string, string>;
4289};
4290```
4291
4292### `RewindFilesResult`
4293
4294Result of a `rewindFiles()` operation.
4295
4296```typescript theme={null}
4297type RewindFilesResult = {
4298 canRewind: boolean;
4299 error?: string;
4300 filesChanged?: string[];
4301 insertions?: number;
4302 deletions?: number;
4303 skippedLinks?: number;
4304};
4305```
4306
4307`skippedLinks` counts the tracked paths the rewind refused to restore or delete for link safety: a symlink, hard link, or other non-regular file at the tracked path, a parent directory that no longer resolves to where it pointed when the checkpoint was taken, or a backup that couldn't be read safely. The field requires Claude Code v2.1.216 or later. A preview call with `rewindFiles(userMessageId, { dryRun: true })` never sets it.
4308
4309### `SDKStatusMessage`
4310
4311Status update message (e.g., compacting).
4312
4313```typescript theme={null}
4314type SDKStatusMessage = {
4315 type: "system";
4316 subtype: "status";
4317 status: "compacting" | null;
4318 permissionMode?: PermissionMode;
4319 uuid: UUID;
4320 session_id: string;
4321};
4322```
4323
4324### `SDKTaskNotificationMessage`
4325
4326Notification when a background task completes, fails, or is stopped. Background tasks include `run_in_background` Bash commands, [Monitor](#monitor) watches, and background subagents.
4327
4328```typescript theme={null}
4329type SDKTaskNotificationMessage = {
4330 type: "system";
4331 subtype: "task_notification";
4332 task_id: string;
4333 tool_use_id?: string;
4334 status: "completed" | "failed" | "stopped";
4335 output_file: string;
4336 summary: string;
4337 usage?: {
4338 total_tokens: number;
4339 tool_uses: number;
4340 duration_ms: number;
4341 };
4342 uuid: UUID;
4343 session_id: string;
4344};
4345```
4346
4347Claude 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.
4348
4349To detect a task-notification turn, check `origin.kind === "task-notification"` on the [`SDKUserMessage`](#sdkusermessage) or [`SDKResultMessage`](#sdkresultmessage) rather than matching on the notice text. Read `subkind` from the same field if you need to know what raised it. Before v2.1.205, Claude Code left the notice off notifications that arrived while the session was idle.
4350
4351### `SDKToolUseSummaryMessage`
4352
4353Summary of tool usage in a conversation.
4354
4355```typescript theme={null}
4356type SDKToolUseSummaryMessage = {
4357 type: "tool_use_summary";
4358 summary: string;
4359 preceding_tool_use_ids: string[];
4360 uuid: UUID;
4361 session_id: string;
4362};
4363```
4364
4365### `SDKHookStartedMessage`
4366
4367Emitted when a hook begins executing.
4368
4369Claude Code delivers this message, [`SDKHookProgressMessage`](#sdkhookprogressmessage), and [`SDKHookResponseMessage`](#sdkhookresponsemessage) to the message stream immediately, including while a `SessionStart` or `Setup` hook is still running during session startup. Claude Code v2.1.169 through v2.1.203 delivered these messages in one batch after a `SessionStart` or `Setup` hook completed; v2.1.204 restored live delivery.
4370
4371```typescript theme={null}
4372type SDKHookStartedMessage = {
4373 type: "system";
4374 subtype: "hook_started";
4375 hook_id: string;
4376 hook_name: string;
4377 hook_event: string;
4378 uuid: UUID;
4379 session_id: string;
4380};
4381```
4382
4383### `SDKHookProgressMessage`
4384
4385Emitted while a hook is running, with stdout/stderr output.
4386
4387```typescript theme={null}
4388type SDKHookProgressMessage = {
4389 type: "system";
4390 subtype: "hook_progress";
4391 hook_id: string;
4392 hook_name: string;
4393 hook_event: string;
4394 stdout: string;
4395 stderr: string;
4396 output: string;
4397 uuid: UUID;
4398 session_id: string;
4399};
4400```
4401
4402### `SDKHookResponseMessage`
4403
4404Emitted when a hook finishes executing.
4405
4406```typescript theme={null}
4407type SDKHookResponseMessage = {
4408 type: "system";
4409 subtype: "hook_response";
4410 hook_id: string;
4411 hook_name: string;
4412 hook_event: string;
4413 output: string;
4414 stdout: string;
4415 stderr: string;
4416 exit_code?: number;
4417 outcome: "success" | "error" | "cancelled";
4418 uuid: UUID;
4419 session_id: string;
4420};
4421```
4422
4423### `SDKToolProgressMessage`
4424
4425Emitted periodically while a tool is executing to indicate progress.
4426
4427```typescript theme={null}
4428type SDKToolProgressMessage = {
4429 type: "tool_progress";
4430 tool_use_id: string;
4431 tool_name: string;
4432 parent_tool_use_id: string | null;
4433 elapsed_time_seconds: number;
4434 task_id?: string;
4435 heartbeat?: boolean;
4436 subagent_type?: string;
4437 subagent_retry?: {
4438 agent_id: string;
4439 attempt: number;
4440 max_retries: number;
4441 retry_delay_ms: number;
4442 error_status: number | null;
4443 error_category: string;
4444 };
4445 uuid: UUID;
4446 session_id: string;
4447};
4448```
4449
4450While a tool call runs in the main conversation, Claude Code emits a `tool_progress` message every 30 seconds with `heartbeat: true`. Each heartbeat carries the tool name and elapsed seconds, so you can distinguish a long-running call from a stalled session. Claude Code doesn't emit heartbeats for the Agent tool, whose subagents stream their own progress, or for tool calls inside a subagent. The `heartbeat` field requires Agent SDK v0.3.214 or later.
4451
4452On `tool_progress` messages for the Agent tool, `subagent_type` names the running subagent type, such as `general-purpose`. `subagent_retry` is present while that subagent waits out an API error backoff, such as a rate limit or overload, with one message per retry attempt. Both fields require Agent SDK v0.3.214 or later.
4453
4454To render a retry indicator from `subagent_retry`:
4455
4456* Track the indicator by `parent_tool_use_id`, which is unique per subagent. `tool_use_id` is shared by parallel subagents from one assistant turn, so tracking by it would let one subagent's update clear another's indicator.
4457* Clear the indicator when a later `tool_progress` for the same `parent_tool_use_id` arrives without the field, or when the tool's result message arrives. `attempt` can exceed `max_retries` under persistent retry, so don't derive clearing from the counters.
4458* Treat `error_category` as a closed set of tokens for choosing your own message text, not as display text: `rate_limit`, `overloaded`, `authentication_failed`, `server_error`, or `unknown`.
4459
4460### `SDKAuthStatusMessage`
4461
4462Emitted during authentication flows.
4463
4464```typescript theme={null}
4465type SDKAuthStatusMessage = {
4466 type: "auth_status";
4467 isAuthenticating: boolean;
4468 output: string[];
4469 error?: string;
4470 uuid: UUID;
4471 session_id: string;
4472};
4473```
4474
4475### `SDKTaskStartedMessage`
4476
4477Emitted when a background task begins. The `
4324The 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 `thinking` blocks. Claude Code doesn't send `display` to A
claude-apps-gateway-config Changed · +1 / -6 lines
from line 309
309309 auth:
310310 api_key: ${ANTHROPIC_API_KEY}
311311
312# Per-upstream model IDs are keyed on the upstream's `name:`; an upstream
313# without a `name:` defaults to its provider string (e.g. `bedrock`). For a
314# built-in Claude model, an upstream you leave out of the map still serves it
315# with that provider's default ID; list the upstream to override the ID, for
316# example with a provisioned-throughput ARN. Only a custom `id` that isn't a
317# built-in model skips the upstreams missing from its map.
312# Per-upstream model IDs are keyed on the upstream's `name:`.
318313models:
319314 - id: claude-opus-4-8
320315 label: Claude Opus 4.8
claude-apps-gateway-deploy Changed · +2 / -12 lines
from line 35
3535* **Microsoft Entra ID**: `issuer` = `https://login.microsoftonline.com/<tenant-id>/v2.0`. Entra emits group Object IDs rather than names, so use the GUIDs in `managed.policies.match.groups`, or use App Roles for human-readable names. If your tenant emits roles under `roles` instead of `groups`, set `oidc.groups_claim: roles`.
3636* **Google Workspace**: `issuer` = `https://accounts.google.com`. Google's id\_token doesn't carry groups. To use group-based `allowed_groups` or `managed.policies` with Google as the IdP, configure [`oidc.google_groups`](/docs/en/claude-apps-gateway-config#oidc), which looks up each user's groups through the Admin SDK Directory API using a service account with domain-wide delegation. Without it, use `oidc.allowed_email_domains` for membership gating and `managed.policies.match.email_domain` for policy assignment. Google also ignores the standard `offline_access` scope. For refresh tokens, set `oidc.scopes: [openid, profile, email]` and `oidc.extra_auth_params: { access_type: offline, prompt: consent }`.
3737
38For support with an identity provider not covered above, see [Troubleshooting](#troubleshooting).
39
4038<Warning>
4139 Refresh tokens let the gateway renew a developer's session silently, without sending the developer back to the browser. They also drive deprovisioning, because when the IdP disables a user, the next refresh fails and the session ends within `ttl_hours`. The gateway requests `offline_access` by default to get a refresh token. If your IdP requires explicit consent for offline access, configure the OAuth client to allow it.
4240
from line 87
8987
9088For a complete worked example on AWS, covering ECS Fargate or EKS, Amazon RDS, and AWS Secrets Manager, see [Deploy on AWS](/docs/en/claude-apps-gateway-on-aws).
9189
92<Note>
93 **Workload identity**
90Prefer the platform's workload identity over static keys; the [`upstreams` reference](/docs/en/claude-apps-gateway-config#upstreams) has per-platform setup details. For a cross-cloud pairing, such as an Amazon Bedrock upstream on GKE, set explicit credentials in the upstream's `auth` block instead.
9491
95 Prefer the platform's workload identity over static keys: IRSA on EKS for Amazon Bedrock and for Claude Platform on AWS, Workload Identity on GKE for Google Cloud's Agent Platform, and workload identity on AKS for Microsoft Foundry. Set `auth: {}` in the upstream block, or `use_azure_ad: true` for Microsoft Foundry, and the gateway picks up the pod's identity through that provider's default credential chain. For a cross-cloud pairing, such as an Amazon Bedrock upstream on GKE, set explicit credentials in the upstream's `auth` block instead. The [`upstreams` reference](/docs/en/claude-apps-gateway-config#upstreams) has per-platform setup details.
96</Note>
97
9892### Cloud Run
9993
10094Configure the service as follows:
from line 98
10498* Mount the config as a secret volume
10599* Set `min-instances: 1` to avoid a cold OIDC discovery on first request
106100
107<Note>
108 For a complete worked example on Google Cloud, covering Cloud Run or GKE, Cloud SQL, and Secret Manager, see [Deploy on Google Cloud](/docs/en/claude-apps-gateway-on-gcp).
109</Note>
101For a complete worked example on Google Cloud, covering Cloud Run or GKE, Cloud SQL, and Secret Manager, see [Deploy on Google Cloud](/docs/en/claude-apps-gateway-on-gcp).
110102
111103### Push the gateway URL to developer machines
112104
from line 125
133125The gateway serves `GET /healthz` as a liveness probe and `GET /readyz` as a readiness probe; `/readyz` verifies the store is reachable. Both are exempt from `access_control.allow_cidrs`, so probes keep working on a locked-down listener.
134126
135127The OAuth discovery document at `/.well-known/oauth-authorization-server` also returns `200` only after config load, OIDC discovery, upstream client construction, and Postgres migration all succeed, so it doubles as an end-to-end boot check.
136
137A running gateway also serves a description of the paths and request shapes it accepts at `<public_url>/protocol`, matched to the version you're running. The contents aren't stable across releases.
138128
139129### Outage behavior
140130
hooks Changed · +16 / -8 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 1783
17831783Runs when Claude Code is about to ask you for permission. In sessions that can't show a prompt, such as background subagents in [non-interactive mode](/docs/en/headless), Claude Code still runs these hooks, and if no hook returns a decision, it denies the tool call.
17841784Use [PermissionRequest decision control](#permissionrequest-decision-control) to allow or deny on behalf of the user.
17851785
1786Use this event when you need a signal the moment Claude asks for permission. The [Notification](#notification) event's `permission_prompt` type reaches you only after about 6 seconds without terminal input.
1786Use this event when you need a signal the moment Claude asks for permission. The [Notification](#notification) event's `permission_prompt` type reaches you only after the prompt has waited about six seconds.
17871787
17881788Matches on tool name, same values as PreToolUse.
17891789
from line 2117
21172117
21182118| Matcher | When it fires |
21192119| :----------------------- | :--------------------------------------------------------------------------------------------------------------------- |
2120| `permission_prompt` | Claude needs you to approve a tool use and you haven't typed for about 6 seconds |
2120| `permission_prompt` | Claude needs you to approve a tool use and the prompt has waited about six seconds |
21212121| `idle_prompt` | Claude finished responding about 60 seconds ago and you haven't typed since |
21222122| `auth_success` | Authentication completes |
2123| `elicitation_dialog` | An MCP server opens an elicitation form and you haven't typed for about 6 seconds |
2124| `elicitation_url_dialog` | An MCP server asks you to open a browser URL and you haven't typed for about 6 seconds |
2123| `elicitation_dialog` | An MCP server opens an elicitation form and you haven't typed for about six seconds |
2124| `elicitation_url_dialog` | An MCP server asks you to open a browser URL and you haven't typed for about six seconds |
21252125| `elicitation_complete` | An MCP elicitation form is submitted or dismissed |
21262126| `elicitation_response` | An MCP elicitation response is sent back to the server |
21272127| `agent_needs_input` | A background session starts waiting on your input. Fires only while [agent view](/docs/en/agent-view) is open in a terminal |
from line 2130
21302130The `agent_needs_input` and `agent_completed` types require Claude Code v2.1.198 or later.
21312131
21322132<Note>
2133 The `permission_prompt`, `idle_prompt`, `elicitation_dialog`, and `elicitation_url_dialog` types share their timing with desktop notifications, so you only see them when you appear to be away from the terminal:
2133 The `permission_prompt`, `idle_prompt`, `elicitation_dialog`, and `elicitation_url_dialog` types share their timing with desktop notifications, so in terminal sessions you only see them when you appear to be away from the terminal:
21342134
2135 * Expect `permission_prompt` once you haven't typed for about 6 seconds. The timer starts when the permission prompt appears, and each keystroke defers it. To run a hook immediately on every permission ask, use [PermissionRequest](#permissionrequest) instead.
2135 * Expect `permission_prompt` once you haven't typed for about six seconds. The timer starts when the permission prompt appears, and each keystroke defers it. To run a hook immediately on every permission ask, use [PermissionRequest](#permissionrequest) instead.
21362136 * Expect `idle_prompt` about 60 seconds after Claude finishes responding, and only if you haven't typed since.
2137 * Expect `elicitation_dialog` for an elicitation form, or `elicitation_url_dialog` for a browser URL request, once you haven't typed for about 6 seconds. Both share the same 6-second gate as `permission_prompt`: the timer starts when the dialog appears, and each keystroke defers it.
2137 * Expect `elicitation_dialog` for an elicitation form, or `elicitation_url_dialog` for a browser URL request, once you haven't typed for about six seconds. Both share the same six-second gate as `permission_prompt`: the timer starts when the dialog appears, and each keystroke defers it.
21382138</Note>
21392139
2140Claude Code times `permission_prompt` differently in sessions where it sends permission requests to the Agent SDK's [`canUseTool` callback](/docs/en/agent-sdk/user-input), which is how Claude Desktop and the VS Code extension host Claude Code:
2141
2142* Expect `permission_prompt` about six seconds after Claude asks for permission. Claude Code doesn't defer it while you type.
2143* If you or a [PermissionRequest](#permissionrequest) hook answer sooner, Claude Code doesn't run `permission_prompt`.
2144* Set [`CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS`](/docs/en/env-vars) to `1` to turn `permission_prompt` off in these sessions.
2145
2146Before v2.1.233, `permission_prompt` didn't fire in these sessions.
2147
21402148Use separate matchers to run different handlers depending on the notification type. This configuration triggers a permission-specific alert script when Claude needs permission approval and a different notification when Claude has been idle:
21412149
21422150```json theme={null}
from line 3223
32153223Set `type` to `"agent"` and provide a `prompt` string. The configuration fields are the same as [prompt hooks](#prompt-hook-configuration), except that agent hooks have a longer default timeout and no `continueOnBlock` field:
32163224
32173225| Field | Required | Description |
3218| :-------- | :------- | :------------------------------------------------------------------------------------------ |
3219| `type` | yes | Must be `"agent"` |
3220| `prompt` | yes | Prompt describing what to verify. Use `$ARGUMENTS` as a placeholder for the hook input JSON |
3221| `model` | no | Model to use. Defaults to a fast model |
3222| `timeout` | no | Timeout in seconds. Default: 60 |
3223
3224The response schema is `{ "ok": true }` to allow or `{ "ok": false, "reason": "..." }` to block. On `ok: false`, Claude Code handles an agent hook the way it handles a [prompt hook with `continueOnBlock: true`](#response-schema) on t
3226| :-------- | :------- | :-----------------------------------------------------------------------------
hooks-guide Changed · +5 / -3 lines
from line 179
179179
180180| Matcher | Fires when |
181181| :----------------------- | :------------------------------------------------------------------------------------------------------- |
182| `permission_prompt` | Claude needs you to approve a tool use and you haven't typed for about 6 seconds |
182| `permission_prompt` | Claude needs you to approve a tool use and the prompt has waited about six seconds |
183183| `idle_prompt` | Claude finished responding about 60 seconds ago and you haven't typed since |
184184| `auth_success` | Authentication completes |
185| `elicitation_dialog` | An MCP server opens an elicitation form and you haven't typed for about 6 seconds |
186| `elicitation_url_dialog` | An MCP server asks you to open a browser URL and you haven't typed for about 6 seconds |
185| `elicitation_dialog` | An MCP server opens an elicitation form and you haven't typed for about six seconds |
186| `elicitation_url_dialog` | An MCP server asks you to open a browser URL and you haven't typed for about six seconds |
187187| `elicitation_complete` | An MCP elicitation form is submitted or dismissed |
188188| `elicitation_response` | An MCP elicitation response is sent back to the server |
189189| `agent_needs_input` | A background session starts waiting on your input. Fires only while [agent view](/docs/en/agent-view) is open |
190190| `agent_completed` | A background session finishes or fails. Fires only while [agent view](/docs/en/agent-view) is open |
191
192Claude Code times `permission_prompt` differently in a terminal and in Claude Desktop, the VS Code extension, and other hosts that answer permission requests through the Agent SDK. See [when each notification type fires](/docs/en/hooks#notification) for both timings.
191193
192194The `agent_needs_input` and `agent_completed` matchers require Claude Code v2.1.198 or later.
193195
server-managed-settings Changed · +3 / -17 lines
from line 4
44
55Server-managed settings let organization Owners centrally configure Claude Code from [**Admin Settings > Claude Code > Managed settings**](https://claude.ai/admin-settings/claude-code) in the claude.ai console. Claude Code clients fetch these settings automatically when users authenticate with an organization OAuth login or a directly configured API key, on platforms where server-managed delivery is supported. See [Platform availability](#platform-availability).
66
7This approach is designed for organizations that don't have device management infrastructure in place, or that need to manage settings for users on unmanaged devices.
8
97<Note>
108 Server-managed settings are available for [Claude for Teams](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=server_settings_teams#team-&-enterprise) and [Claude for Enterprise](https://anthropic.com/contact-sales?utm_source=claude_code\&utm_medium=docs\&utm_content=server_settings_enterprise) customers.
119</Note>
from line 75
7775 }
7876 ```
7977
80 To configure the [auto mode](/docs/en/permission-modes#eliminate-prompts-with-auto-mode) classifier so it knows which repos, buckets, and domains your organization trusts:
78 Because hooks execute shell commands, users see a [security approval dialog](#security-approval-dialogs) before they're applied.
8179
82 ```json theme={null}
83 {
84 "autoMode": {
85 "environment": [
86 "Source control: github.example.com/acme-corp and all repos under it",
87 "Trusted cloud buckets: s3://acme-build-artifacts, gs://acme-ml-datasets",
88 "Trusted internal domains: *.corp.example.com"
89 ]
90 }
91 }
92 ```
93
94 Because hooks execute shell commands, users see a [security approval dialog](#security-approval-dialogs) before they're applied. See [Configure auto mode](/docs/en/auto-mode-config) for how the `autoMode` entries affect what the classifier blocks and important warnings about the `environment`, `allow`, `soft_deny`, and `hard_deny` fields.
80 To configure the [auto mode](/docs/en/permission-modes#eliminate-prompts-with-auto-mode) classifier so it knows which repos, buckets, and domains your organization trusts, deliver an `autoMode` block the same way; see [Configure auto mode](/docs/en/auto-mode-config) for how the `autoMode` entries affect what the classifier blocks and important warnings about the `environment`, `allow`, `soft_deny`, and `hard_deny` fields.
9581 </Step>
9682
9783 <Step title="Save and deploy">
settings Changed · +14 / -1 lines
##### Marketplace key aliases
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 328
328328| `spinnerVerbs` | Customize the action verbs shown while a turn is in progress. Set `mode` to `"replace"` to use only your verbs, or `"append"` to add them to the defaults | `{"mode": "append", "verbs": ["Pondering", "Crafting"]}` |
329329| `sshConfigs` | SSH connections to show in the [Desktop](/docs/en/desktop#pre-configure-ssh-connections-for-your-team) environment dropdown. Each entry requires `id`, `name`, and `sshHost`; `sshPort`, `sshIdentityFile`, and `startDirectory` are optional. When set in managed settings, connections are read-only for users. Read from managed and user settings only | `[{"id": "dev-vm", "name": "Dev VM", "sshHost": "[email protected]"}]` |
330330| `statusLine` | Configure a custom status line to display context. The object's optional `padding`, `refreshInterval`, and `hideVimModeIndicator` fields control spacing, periodic re-runs, and whether the built-in vim mode indicator below the prompt is hidden. See [`statusLine` documentation](/docs/en/statusline#manually-configure-a-status-line) | `{"type": "command", "command": "~/.claude/statusline.sh"}` |
331| `strictKnownMarketplaces` | (Managed settings only) Allowlist of plugin marketplace sources. Undefined = no restrictions, empty array = lockdown. Enforced on marketplace add and on plugin install, update, refresh, and auto-update, so a marketplace added before the policy was set cannot be used to fetch plugins. See [Managed marketplace restrictions](/docs/en/plugin-marketplaces#managed-marketplace-restrictions) | `[{ "source": "github", "repo": "acme-corp/plugins" }]` |
331| `strictKnownMarketplaces` | (Managed settings only) Allowlist of plugin marketplace sources. Undefined = no restrictions, empty array = lockdown. Enforced on marketplace add and on plugin install, update, refresh, and auto-update, so a marketplace added before the policy was set cannot be used to fetch plugins. The [`allowedMarketplaces`](#marketplace-key-aliases) alias requires Claude Code v2.1.232 or later. See [Managed marketplace restrictions](/docs/en/plugin-marketplaces#managed-marketplace-restrictions) | `[{ "source": "github", "repo": "acme-corp/plugins" }]` |
332332| `strictPluginOnlyCustomization` | (Managed settings only) Block skills, agents, hooks, and MCP servers from user and project sources, so they can only come from plugins or managed settings. `true` locks all four surfaces; an array locks only the named ones. See [`strictPluginOnlyCustomization`](#strictpluginonlycustomization) | `["skills", "hooks"]` |
333333| `subagentStatusLine` | Configure a custom command that rewrites rows in the subagent task display. See [Subagent status lines](/docs/en/statusline#subagent-status-lines) | `{"type": "command", "command": "~/.claude/subagent-statusline.sh"}` |
334334| `switchModelsOnFlag` | **Default**: `true`. When a [safety classifier flags a request](/docs/en/model-config#automatic-model-fallback), switch to the fallback model automatically and continue the session. Set to `false` to pause instead and choose between switching and editing the prompt. See [Ask before switching](/docs/en/model-config#ask-before-switching). Appears in `/config` as **Switch models when a message is flagged**. Requires Claude Code v2.1.170 or later | `false` |
tools-reference Changed · +11 / -1 lines
### Memory limit on Linux and WSL
from line 182
182182* When the timeout triggers the move, the result reports it explicitly: `Command did not complete within its 120s timeout and was moved to the background`, with the seconds matching the timeout that applied, followed by the task ID and the path of the file the output is being written to.
183183* A `cd`, `pushd`, `popd`, or `chdir` inside a command that is moved to the background never carries over: the result states `Session cwd remains <dir>; directory changes made by the backgrounded command do not apply to subsequent commands.`, so Claude doesn't act on a directory change that didn't happen.
184184
185### Memory limit on Linux and WSL
186
187On Linux and WSL, set [`CLAUDE_CODE_TOOL_MEMORY_LIMIT`](/docs/en/env-vars#variables) to a size such as `4G` to cap the memory that Bash and PowerShell tool commands can use, so one runaway build can't take the memory the rest of the session needs. Requires Claude Code v2.1.233 or later.
188
189* Write the size as a number of bytes or with a `K`, `M`, `G`, or `T` suffix. Set `0`, `off`, `false`, `no`, or `none` to turn the cap off. Claude Code ignores any other value it can't read as a size, such as `4e9`.
190* Claude Code counts all of a session's Bash and PowerShell commands against the one cap, not each command on its own.
191* Claude Code applies the cap with a memory cgroup. When it can't set the cgroup up, commands run without a cap, and the debug log from `claude --debug` says why.
192* After a Bash or PowerShell tool command has turned the cap on, or has turned it off because of an off value or a failed cgroup setup, Claude Code holds that result until you relaunch. To apply a changed or removed value, or a fixed setup, launch `claude` again.
193* When commands can't stay under the cap, the kernel kills a command, and nothing in its result names the cap.
194
185195## Edit tool behavior
186196
187197The Edit tool performs exact string replacement. It takes an `old_string` and a `new_string` and replaces the first with the second. It doesn't use regex or fuzzy matching.
from line 446
436446
437447* HTTP URLs are automatically upgraded to HTTPS.
438448* Large pages are truncated to a fixed character limit before processing.
439* Responses are cached for 15 minutes, so repeated fetches of the same URL return quickly.
449* WebFetch caches each response for 15 minutes by default, so repeated fetches of the same URL return quickly. On Claude Code v2.1.233 or later, set [`CLAUDE_CODE_WEBFETCH_CACHE_TTL_MS`](/docs/en/env-vars#variables) to change how long WebFetch keeps each response.
440450* When a URL redirects to a different host, WebFetch returns a text result that names the original URL and the redirect target instead of following it. Claude then fetches the new URL with a second WebFetch call.
441451* When the extraction step hits an overloaded API, Claude Code retries it with backoff; a fetch that still fails returns an error result. Before v2.1.212, the API error text could reach Claude as if it were the extracted page content.
442452
admin-setup Changed · +0 / -2 lines
from line 62
6262
6363Whichever mechanism you choose, managed values take precedence over user and project settings, apart from a few security-sensitive [exceptions](/docs/en/settings#exceptions-to-managed-settings-precedence). Array settings such as `permissions.allow` and `permissions.deny` merge entries from all sources, so developers can extend managed lists but not remove from them. For `fallbackModel` and `availableModels`, the managed value replaces lower layers rather than merging.
6464
65See [Server-managed settings](/docs/en/server-managed-settings) and [Settings files and precedence](/docs/en/settings#settings-files).
66
6765### WSL sessions in Claude Code Desktop
6866
6967On Windows, [Claude Code Desktop can run Code sessions inside a WSL 2 distribution](/docs/en/desktop-wsl). The session's Claude Code process runs inside the distribution, so it resolves managed settings through the WSL discovery path above: Windows-only sources don't reach it unless `wslInheritsWindowsSettings: true` is deployed.
agent-sdk/session-storage Changed · +1 / -1 lines
from line 279
279279
280280The SDK also seeds the temporary directory with files from your real config directory. What it copies differs by language:
281281
282* **TypeScript**: credentials, `.claude.json`, and your user `settings.json`. From `settings.json` it strips the three keys that misbehave under a temporary config directory: `enabledPlugins`, `extraKnownMarketplaces`, and any `CLAUDE_CONFIG_DIR` in the file's `env` block. Auth configured in settings, such as [`apiKeyHelper`](/docs/en/settings#available-settings), works when you resume from the store. Before Agent SDK v0.3.222, the TypeScript SDK copied only credentials and `.claude.json`.
282* **TypeScript**: credentials, `.claude.json`, and your user `settings.json`. From `settings.json` it strips the keys that misbehave under a temporary config directory: `enabledPlugins`, `extraKnownMarketplaces`, its [`additionalMarketplaces`](/docs/en/settings#extraknownmarketplaces) alias, and any `CLAUDE_CONFIG_DIR` in the file's `env` block. Before Agent SDK v0.3.232, the SDK didn't strip the alias. Auth configured in settings, such as [`apiKeyHelper`](/docs/en/settings#available-settings), works when you resume from the store. Before Agent SDK v0.3.222, the TypeScript SDK copied only credentials and `.claude.json`.
283283* **Python**: credentials and `.claude.json` only, so an app that authenticates through `apiKeyHelper` in your user `settings.json` fails with `Not logged in` when resuming from a store. An `apiKeyHelper` in managed or project settings still works, because Claude Code reads those files from locations that `CLAUDE_CONFIG_DIR` doesn't affect.
284284
285285When the store has nothing for the session, the SDK runs under your real config directory instead, and the outcome depends on which option you passed:
claude-apps-gateway Changed · +0 / -4 lines
from line 69
6969| Private-network address | At `/login`, Claude Code requires the gateway's hostname or IP address to resolve only to private addresses: RFC 1918, link-local, CGNAT `100.64.0.0/10`, IPv6 ULA `fc00::/7`, or loopback. For a gateway you host, any public address is rejected; see the [threat model](/docs/en/claude-apps-gateway-deploy#threat-model-summary) in the deployment guide. The check runs on each resolved IP, so if any address the name resolves to is public, `/login` rejects the URL. If developer machines route HTTPS through a corporate proxy, sign-in also requires the proxy host to resolve to private addresses; if it doesn't, add the gateway host to `NO_PROXY` so the CLI connects directly. |
7070| Linux runtime | The gateway server runs only on the native Linux binary. macOS works for local development. Windows isn't supported as a server platform. |
7171
72The gateway server requires the native `claude` binary; download a pinned release as described in [Install Claude Code](/docs/en/setup). The server uses runtime features that aren't available when Claude Code runs under Node. If you see `requires the native binary` at boot, switch to one of the standalone install methods.
73
7472### Steps
7573
7674<Steps>
from line 388
390388The table covers which Claude Code features work when developers connect through the gateway, and what the gateway server itself supports. Where something isn't supported, the Notes column gives the alternative.
391389
392390The gateway delivers the [`anthropic-beta`](https://platform.claude.com/docs/en/api/beta-headers) values the CLI sends to every upstream, so operators don't maintain a beta allowlist. For Amazon Bedrock, which ignores the header, the gateway moves the values into the request body's `anthropic_beta` field; the other upstreams receive the header as sent.
393
394The CLI's gateway-session beta set omits first-party-only betas and the extended-cache-ttl beta, which is why those rows below show as not available.
395391
396392| Feature | Status | Notes |
397393| -------------------------------------------------------------------------------------------------------------------------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
claude-apps-gateway-on-aws Changed · +1 / -1 lines
from line 502
502502
503503Point `telemetry.forward_to` at an OpenTelemetry collector, such as the [AWS Distro for OpenTelemetry (ADOT) collector](https://aws-otel.github.io/), and export from there to Amazon CloudWatch, Amazon Managed Service for Prometheus, or any OTLP backend.
504504
505Run the collector as its own internal service reachable over `https://`: the gateway accepts plaintext `http://` only for loopback URLs, and even then its [SSRF guard](/docs/en/claude-apps-gateway-deploy#threat-model-summary) blocks loopback connections by default. Unless `CLAUDE_GATEWAY_ALLOW_LOOPBACK=1` is set in the gateway's environment, a sidecar collector on `http://localhost:4318` passes config validation but receives no traffic, with exports failing as `ECONNREFUSED_SSRF` in the gateway logs, and the gateway rejects an IP-literal URL such as `http://127.0.0.1:4318` at boot. That variable relaxes the loopback block for every operator-configured URL, not only telemetry, so prefer the internal-service pattern and reserve the sidecar-plus-flag setup for tasks whose network is otherwise locked down.
505Run the collector as its own internal service reachable over `https://`; the [`telemetry` reference](/docs/en/claude-apps-gateway-config#telemetry) covers the loopback exception and `CLAUDE_GATEWAY_ALLOW_LOOPBACK`.
506506
507507### Gateway logs
508508
claude-apps-gateway-spend-limits Changed · +0 / -2 lines
from line 150
150150| `admin_audit` | The mutation trail | [`admin.audit_retention_days`](/docs/en/claude-apps-gateway-config#admin), default 365 |
151151| `principal_emails` | Each principal's last-seen email, display name, and IdP groups. Contains PII. | [`admin.identity_retention_days`](/docs/en/claude-apps-gateway-config#admin) since last activity, default 90 |
152152
153`identity_retention_days` is deliberately shorter than `spend_retention_months`: a deprovisioned identity stops refreshing and ages out, while its anonymous spend counters remain for year-over-year reporting.
154
155153When a developer leaves, delete any per-user cap via `DELETE /v1/organizations/spend_limits/{id}`; their spend and identity rows age out on the retention windows above. To erase one person immediately, for offboarding or a data subject access request (DSAR), run `DELETE FROM principal_emails WHERE principal = '<sub>'` directly against the gateway database. That removes the only table holding their email, name, and groups. The `spend` and `admin_audit` rows reference the pseudonymous OIDC `sub` only and age out on their own windows.
156154
157155## Related
env-vars Changed · +3 / -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 243
243243| `CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK` | Set to `1` to disable the non-streaming fallback when a streaming request fails mid-stream. Streaming errors propagate to the retry layer instead. Useful when a proxy or gateway causes the fallback to produce duplicate tool execution |
244244| `CLAUDE_CODE_DISABLE_NOTIFICATION_PRESENCE_CHECK` | Set to `1` to send the `PushNotification` tool's desktop notification even while you are typing in or focused on the terminal. By default the tool skips both the desktop notification and the [mobile push](/docs/en/remote-control#mobile-push-notifications) when it detects recent keyboard activity or terminal focus. This variable disables only that local check, so the server can still suppress the mobile push when it detects that you are active. Requires Claude Code v2.1.193 or later |
245245| `CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL` | Set to `1` to disable automatic registration of the official plugin marketplace. Claude Code reads the variable when it is about to register the marketplace, usually during a machine's first interactive launch. If the variable is set at that point, Claude Code skips the registration permanently. Unsetting the variable later doesn't undo the skip. Run `claude plugin marketplace add anthropics/claude-plugins-official` to register the marketplace at any time |
246| `CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS` | Set to `1` to stop Claude Code from running your [`Notification` hooks for unanswered permission requests](/docs/en/hooks#notification) in sessions where Claude Code sends them to the Agent SDK's `canUseTool` callback, which is how Claude Desktop and the VS Code extension host Claude Code. Has no effect in terminal sessions. Requires Claude Code v2.1.233 or later |
246247| `CLAUDE_CODE_DISABLE_POLICY_SKILLS` | Set to `1` to skip loading skills from the system-wide managed skills directory. Useful for container or CI sessions that should not load operator-provisioned skills |
247248| `CLAUDE_CODE_DISABLE_TERMINAL_TITLE` | Set to `1` to disable automatic terminal title updates based on conversation context. In Agent SDK and `claude -p` sessions, this also skips the background small/fast-model request that generates the session title |
248249| `CLAUDE_CODE_DISABLE_THINKING` | Set to `1` to omit the `thinking` parameter from API requests entirely. This is a compatibility option for proxies and gateways that reject the parameter. The variable's behavior is unchanged from earlier versions; on models that think by default, omitting the parameter means the model may still think. To explicitly disable [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) on the Anthropic API, use `MAX_THINKING_TOKENS=0` instead, which is also ineffective on Fable 5 since it cannot have thinking turned off. On [third-party providers](/docs/en/third-party-integrations), `0` likewise omits the parameter, so the two variables behave the same there |
from line 340
339340| `CLAUDE_CODE_SKIP_FAST_MODE_NETWORK_ERRORS` | Set to `1` to treat a failed [fast mode](/docs/en/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways) availability check as available, for networks that block the check's direct request to `api.anthropic.com`. Claude Code still honors a "disabled by your organization" response |
340341| `CLAUDE_CODE_SKIP_FAST_MODE_ORG_CHECK` | Set to `1` to skip the client-side [fast mode](/docs/en/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways) availability check, for proxies that intercept the check's request rather than refuse it. The API still rejects fast mode requests when your organization has fast mode disabled |
341342| `CLAUDE_CODE_SKIP_FOUNDRY_AUTH` | Skip Azure authentication for Microsoft Foundry, for a proxy or gateway that injects its own `Authorization` header. Claude Code sends requests without an Azure credential and preserves the `Authorization` header you supply, for example through `ANTHROPIC_CUSTOM_HEADERS`. Ignored when `ANTHROPIC_FOUNDRY_API_KEY` or `ANTHROPIC_FOUNDRY_AUTH_TOKEN` is set. Before v2.1.203, this variable left the Microsoft Foundry client unable to send requests unless an API key was also set |
342| `CLAUDE_CODE_SKIP_MANTLE_AUTH` | Skip AWS authentication for Amazon Bedrock Mantle (for example, when using an LLM gateway) |
343| `CLAUDE_CODE_SKIP_PROMPT_HISTORY` | Set to `1` to skip writing prompt history and session transcripts to disk. Sessions started with this variable set do not appear in `--resume`, `--continue`, or up-arrow history. Useful for ephemeral scripted sessions
343| `CLAUDE_CODE_SKIP_MANTLE_AUTH` | Skip AWS authentication for Amazon Bedrock Mantle (for example, when using an LLM gateway)
llm-gateway-protocol Changed · +0 / -2 lines
from line 98
9898* Keep the block in its own array entry: the endpoint treats a merged block that starts with the attribution header as attribution in its entirety and drops everything merged into it, including the rest of the system prompt.
9999* If your gateway must reshape system content, set [`CLAUDE_CODE_ATTRIBUTION_HEADER=0`](/docs/en/env-vars) so Claude Code omits the block. Anthropic and the cloud providers' Claude endpoints read the block for attribution, so omit it at the client rather than stripping or moving it in the gateway.
100100
101Requests that reach the endpoint unmodified are unaffected.
102
103101The variable exists for gateway and third-party caching compatibility, not as a privacy control: on a direct connection the full request already goes to the Anthropic API either way. When both of these hold, Claude Code keeps the block on [auto mode](/docs/en/permission-modes#eliminate-prompts-with-auto-mode) classifier requests even when you set the variable to `0`:
104102
105103* The requests go to `api.anthropic.com`, with `ANTHROPIC_BASE_URL` unset or naming that host and no third-party provider selected.
permissions Changed · +1 / -1 lines
from line 435
435435| [Skills](/docs/en/skills) in `.claude/skills/` | Yes, with live reload |
436436| [Command files](/docs/en/skills#where-skills-live) in `.claude/commands/` | Yes. When the added directory and your project both define a command with the same name, Claude Code runs your project's command |
437437| [Subagents](/docs/en/sub-agents) in `.claude/agents/` | Yes |
438| [Settings](/docs/en/settings) in `.claude/settings.json` and `.claude/settings.local.json` | `enabledPlugins` and `extraKnownMarketplaces` keys only |
438| [Settings](/docs/en/settings) in `.claude/settings.json` and `.claude/settings.local.json` | `enabledPlugins` and [`extraKnownMarketplaces`](/docs/en/settings#extraknownmarketplaces) keys only |
439439| [CLAUDE.md](/docs/en/memory) files, `.claude/rules/`, and `CLAUDE.local.md` | Only when `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1` is set. `CLAUDE.local.md` additionally requires the `local` setting source, which is enabled by default |
440440
441441Claude Code discovers output styles from the current working directory and its parents, your user directory at `~/.claude/`, and managed settings. Hooks and other `.claude/settings.json` keys load from the current working directory's `.claude/` folder with no parent-directory fallback, alongside your user `~/.claude/settings.json` and managed settings. `.claude/settings.local.json` loads from the git repository root instead, even when you start Claude Code in a subdirectory; before v2.1.211, it too loaded only from the current working directory. [Agent SDK](/docs/en/agent-sdk/claude-code-features#control-filesystem-settings-with-settingsources) sessions load it from the working directory in all versions.
self-hosted-environments-deploy Changed · +1 / -1 lines
from line 322
322322
323323### Connector traffic leaves your network
324324
325Connector tools, such as GitHub, Slack, Linear, and the other claude.ai connectors, are called from Anthropic's side rather than from your runner, so when a self-hosted session uses a connector, that traffic routes through `api.anthropic.com`, not from inside your network boundary. To keep a connector out of self-hosted sessions, filter it like any other MCP server with the [`allowedMcpServers` and `deniedMcpServers` policy settings](/docs/en/managed-mcp#policy-based-control-with-allowlists-and-denylists), which apply to server-delivered connectors too. An allowlist you deploy for other servers also blocks delivered connectors. To keep connectors available alongside a URL-based allowlist, add entries that match the Anthropic proxy paths for server-delivered MCP servers:
325Anthropic calls connector tools, such as GitHub, Slack, Linear, and the other claude.ai connectors, from its own infrastructure rather than from your runner, so when Claude uses a connector in a self-hosted session, that traffic goes through `api.anthropic.com` rather than originating inside your network boundary. To keep a connector out of self-hosted sessions, filter it like any other MCP server with the [`allowedMcpServers` and `deniedMcpServers` policy settings](/docs/en/managed-mcp#policy-based-control-with-allowlists-and-denylists). Claude Code applies these settings to the connectors Anthropic delivers as well as to the servers you configure, so if you deploy an allowlist for other servers, Claude Code blocks delivered connectors too. To keep connectors available alongside a URL-based allowlist, add entries that match the Anthropic proxy paths for delivered connectors:
326326
327327* `https://api.anthropic.com/v2/ccr-sessions/*`
328328* `https://api.anthropic.com/v1/code/sessions/*`