Documentation 2026-05-04 22:58 UTC to 2026-05-05 23:00 UTC

47 47 

48As the loop runs, the SDK yields a stream of messages. Each message carries a type that tells you what stage of the loop it came from. The five core types are:48As the loop runs, the SDK yields a stream of messages. Each message carries a type that tells you what stage of the loop it came from. The five core types are:

49 49 

50* **`SystemMessage`:** session lifecycle events. The `subtype` field distinguishes them: `"init"` is the first message (session metadata), and `"compact_boundary"` fires after [compaction](#automatic-compaction). In TypeScript, the compact boundary is its own [`SDKCompactBoundaryMessage`](/en/agent-sdk/typescript#sdk-compact-boundary-message) type rather than a subtype of `SDKSystemMessage`.50* **`SystemMessage`:** session lifecycle events. The `subtype` field distinguishes them: `"init"` is the first message (session metadata), and `"compact_boundary"` fires after [compaction](#automatic-compaction). In TypeScript, the compact boundary is its own [`SDKCompactBoundaryMessage`](/en/agent-sdk/typescript#sdkcompactboundarymessage) type rather than a subtype of `SDKSystemMessage`.

51* **`AssistantMessage`:** emitted after each Claude response, including the final text-only one. Contains text content blocks and tool call blocks from that turn.51* **`AssistantMessage`:** emitted after each Claude response, including the final text-only one. Contains text content blocks and tool call blocks from that turn.

52* **`UserMessage`:** emitted after each tool execution with the tool result content sent back to Claude. Also emitted for any user inputs you stream mid-loop.52* **`UserMessage`:** emitted after each tool execution with the tool result content sent back to Claude. Also emitted for any user inputs you stream mid-loop.

53* **`StreamEvent`:** only emitted when partial messages are enabled. Contains raw API streaming events (text deltas, tool input chunks). See [Stream responses](/en/agent-sdk/streaming-output).53* **`StreamEvent`:** only emitted when partial messages are enabled. Contains raw API streaming events (text deltas, tool input chunks). See [Stream responses](/en/agent-sdk/streaming-output).

141 141 

142When Claude requests multiple tool calls in a single turn, both SDKs can run them concurrently or sequentially depending on the tool. Read-only tools (like `Read`, `Glob`, `Grep`, and MCP tools marked as read-only) can run concurrently. Tools that modify state (like `Edit`, `Write`, and `Bash`) run sequentially to avoid conflicts.142When Claude requests multiple tool calls in a single turn, both SDKs can run them concurrently or sequentially depending on the tool. Read-only tools (like `Read`, `Glob`, `Grep`, and MCP tools marked as read-only) can run concurrently. Tools that modify state (like `Edit`, `Write`, and `Bash`) run sequentially to avoid conflicts.

143 143 

144Custom tools default to sequential execution. To enable parallel execution for a custom tool, mark it as read-only in its annotations: `readOnly` in [TypeScript](/en/agent-sdk/typescript#tool) or `readOnlyHint` in [Python](/en/agent-sdk/python#tool).144Custom tools default to sequential execution. To enable parallel execution for a custom tool, set `readOnlyHint` in its annotations. Both the [TypeScript](/en/agent-sdk/typescript#tool) and [Python](/en/agent-sdk/python#tool) SDKs use this field name from the MCP SDK.

145 145 

146## Control how the loop runs146## Control how the loop runs

147 147 

148You can limit how many turns the loop takes, how much it costs, how deeply Claude reasons, and whether tools require approval before running. All of these are fields on [`ClaudeAgentOptions`](/en/agent-sdk/python#claude-agent-options) (Python) / [`Options`](/en/agent-sdk/typescript#options) (TypeScript).148You can limit how many turns the loop takes, how much it costs, how deeply Claude reasons, and whether tools require approval before running. All of these are fields on [`ClaudeAgentOptions`](/en/agent-sdk/python#claudeagentoptions) (Python) / [`Options`](/en/agent-sdk/typescript#options) (TypeScript).

149 149 

150### Turns and budget150### Turns and budget

151 151 

154| Max turns (`max_turns` / `maxTurns`) | Maximum tool-use round trips | No limit |154| Max turns (`max_turns` / `maxTurns`) | Maximum tool-use round trips | No limit |

155| Max budget (`max_budget_usd` / `maxBudgetUsd`) | Maximum cost before stopping | No limit |155| Max budget (`max_budget_usd` / `maxBudgetUsd`) | Maximum cost before stopping | No limit |

156 156 

157When either limit is hit, the SDK returns a `ResultMessage` with a corresponding error subtype (`error_max_turns` or `error_max_budget_usd`). See [Handle the result](#handle-the-result) for how to check these subtypes and [`ClaudeAgentOptions`](/en/agent-sdk/python#claude-agent-options) / [`Options`](/en/agent-sdk/typescript#options) for syntax.157When either limit is hit, the SDK returns a `ResultMessage` with a corresponding error subtype (`error_max_turns` or `error_max_budget_usd`). See [Handle the result](#handle-the-result) for how to check these subtypes and [`ClaudeAgentOptions`](/en/agent-sdk/python#claudeagentoptions) / [`Options`](/en/agent-sdk/typescript#options) for syntax.

158 158 

159### Effort level159### Effort level

160 160 

174 `effort` trades latency and token cost for reasoning depth within each response. [Extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) is a separate feature that produces visible chain-of-thought blocks in the output. They are independent: you can set `effort: "low"` with extended thinking enabled, or `effort: "max"` without it.174 `effort` trades latency and token cost for reasoning depth within each response. [Extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) is a separate feature that produces visible chain-of-thought blocks in the output. They are independent: you can set `effort: "low"` with extended thinking enabled, or `effort: "max"` without it.

175</Note>175</Note>

176 176 

177Use lower effort for agents doing simple, well-scoped tasks (like listing files or running a single grep) to reduce cost and latency. `effort` is set at the top-level `query()` options, not per-subagent.177Use lower effort for agents doing simple, well-scoped tasks (like listing files or running a single grep) to reduce cost and latency. Set `effort` in the top-level `query()` options for the whole session, or per subagent with the `effort` field on [`AgentDefinition`](/en/agent-sdk/subagents#agentdefinition-configuration) to override the session level.

178 178 

179### Permission mode179### Permission mode

180 180 

184| :------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |184| :------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

185| `"default"` | Tools not covered by allow rules trigger your approval callback; no callback means deny |185| `"default"` | Tools not covered by allow rules trigger your approval callback; no callback means deny |

186| `"acceptEdits"` | Auto-approves file edits and common filesystem commands (`mkdir`, `touch`, `mv`, `cp`, etc.); other Bash commands follow default rules |186| `"acceptEdits"` | Auto-approves file edits and common filesystem commands (`mkdir`, `touch`, `mv`, `cp`, etc.); other Bash commands follow default rules |

187| `"plan"` | No tool execution; Claude produces a plan for review |187| `"plan"` | Read-only tools run; Claude explores and produces a plan without editing your source files |

188| `"dontAsk"` | Never prompts. Tools pre-approved by [permission rules](/en/settings#permission-settings) run, everything else is denied |188| `"dontAsk"` | Never prompts. Tools pre-approved by [permission rules](/en/settings#permission-settings) run, everything else is denied |

189| `"auto"` (TypeScript only) | Uses a model classifier to approve or deny each tool call. See [Auto mode](/en/permission-modes#eliminate-prompts-with-auto-mode) for availability and behavior |189| `"auto"` (TypeScript only) | Uses a model classifier to approve or deny each tool call. See [Auto mode](/en/permission-modes#eliminate-prompts-with-auto-mode) for availability and behavior |

190| `"bypassPermissions"` | Runs all allowed tools without asking. Cannot be used when running as root on Unix. Use only in isolated environments where the agent's actions cannot affect systems you care about |190| `"bypassPermissions"` | Runs all allowed tools without asking. Cannot be used when running as root on Unix. Use only in isolated environments where the agent's actions cannot affect systems you care about |

244A few strategies for long-running agents:244A few strategies for long-running agents:

245 245 

246* **Use subagents for subtasks.** Each subagent starts with a fresh conversation (no prior message history, though it does load its own system prompt and project-level context like CLAUDE.md). It does not see the parent's turns, and only its final response returns to the parent as a tool result. The main agent's context grows by that summary, not by the full subtask transcript. See [What subagents inherit](/en/agent-sdk/subagents#what-subagents-inherit) for details.246* **Use subagents for subtasks.** Each subagent starts with a fresh conversation (no prior message history, though it does load its own system prompt and project-level context like CLAUDE.md). It does not see the parent's turns, and only its final response returns to the parent as a tool result. The main agent's context grows by that summary, not by the full subtask transcript. See [What subagents inherit](/en/agent-sdk/subagents#what-subagents-inherit) for details.

247* **Be selective with tools.** Every tool definition takes context space. Use the `tools` field on [`AgentDefinition`](/en/agent-sdk/subagents#agent-definition-configuration) to scope subagents to the minimum set they need, and use [MCP tool search](/en/agent-sdk/mcp#mcp-tool-search) to load tools on demand instead of preloading all of them.247* **Be selective with tools.** Every tool definition takes context space. Use the `tools` field on [`AgentDefinition`](/en/agent-sdk/subagents#agentdefinition-configuration) to scope subagents to the minimum set they need, and use [MCP tool search](/en/agent-sdk/mcp#mcp-tool-search) to load tools on demand instead of preloading all of them.

248* **Watch MCP server costs.** Each MCP server adds all its tool schemas to every request. A few servers with many tools can consume significant context before the agent does any work. The `ToolSearch` tool can help by loading tools on-demand instead of preloading all of them. See [MCP tool search](/en/agent-sdk/mcp#mcp-tool-search) for configuration.248* **Watch MCP server costs.** Each MCP server adds all its tool schemas to every request. A few servers with many tools can consume significant context before the agent does any work. The `ToolSearch` tool can help by loading tools on-demand instead of preloading all of them. See [MCP tool search](/en/agent-sdk/mcp#mcp-tool-search) for configuration.

249* **Use lower effort for routine tasks.** Set [effort](#effort-level) to `"low"` for agents that only need to read files or list directories. This reduces token usage and cost.249* **Use lower effort for routine tasks.** Set [effort](#effort-level) to `"low"` for agents that only need to read files or list directories. This reduces token usage and cost.

250 250 

259See [Session management](/en/agent-sdk/sessions) for the full guide on resume, continue, and fork patterns.259See [Session management](/en/agent-sdk/sessions) for the full guide on resume, continue, and fork patterns.

260 260 

261<Note>261<Note>

262 In Python, `ClaudeSDKClient` handles session IDs automatically across multiple calls. See the [Python SDK reference](/en/agent-sdk/python#choosing-between-query-and-claude-sdk-client) for details.262 In Python, `ClaudeSDKClient` handles session IDs automatically across multiple calls. See the [Python SDK reference](/en/agent-sdk/python#choosing-between-query-and-claudesdkclient) for details.

263</Note>263</Note>

264 264 

265## Handle the result265## Handle the result

276 276 

277The `result` field (the final text output) is only present on the `success` variant, so always check the subtype before reading it. All result subtypes carry `total_cost_usd`, `usage`, `num_turns`, and `session_id` so you can track cost and resume even after errors. In Python, `total_cost_usd` and `usage` are typed as optional and may be `None` on some error paths, so guard before formatting them. See [Tracking costs and usage](/en/agent-sdk/cost-tracking) for details on interpreting the `usage` fields.277The `result` field (the final text output) is only present on the `success` variant, so always check the subtype before reading it. All result subtypes carry `total_cost_usd`, `usage`, `num_turns`, and `session_id` so you can track cost and resume even after errors. In Python, `total_cost_usd` and `usage` are typed as optional and may be `None` on some error paths, so guard before formatting them. See [Tracking costs and usage](/en/agent-sdk/cost-tracking) for details on interpreting the `usage` fields.

278 278 

279The result also includes a `stop_reason` field (`string | null` in TypeScript, `str | None` in Python) indicating why the model stopped generating on its final turn. Common values are `end_turn` (model finished normally), `max_tokens` (hit the output token limit), and `refusal` (the model declined the request). On error result subtypes, `stop_reason` carries the value from the last assistant response before the loop ended. To detect refusals, check `stop_reason === "refusal"` (TypeScript) or `stop_reason == "refusal"` (Python). See [`SDKResultMessage`](/en/agent-sdk/typescript#sdk-result-message) (TypeScript) or [`ResultMessage`](/en/agent-sdk/python#result-message) (Python) for the full type.279The result also includes a `stop_reason` field (`string | null` in TypeScript, `str | None` in Python) indicating why the model stopped generating on its final turn. Common values are `end_turn` (model finished normally), `max_tokens` (hit the output token limit), and `refusal` (the model declined the request). On error result subtypes, `stop_reason` carries the value from the last assistant response before the loop ended. To detect refusals, check `stop_reason === "refusal"` (TypeScript) or `stop_reason == "refusal"` (Python). See [`SDKResultMessage`](/en/agent-sdk/typescript#sdkresultmessage) (TypeScript) or [`ResultMessage`](/en/agent-sdk/python#resultmessage) (Python) for the full type.

280 280 

281## Hooks281## Hooks

282 282 

14 14 

15## Control filesystem settings with settingSources15## Control filesystem settings with settingSources

16 16 

17The setting sources option ([`setting_sources`](/en/agent-sdk/python#claude-agent-options) in Python, [`settingSources`](/en/agent-sdk/typescript#setting-source) in TypeScript) controls which filesystem-based settings the SDK loads. Pass an explicit list to opt in to specific sources, or pass an empty array to disable user, project, and local settings.17The setting sources option ([`setting_sources`](/en/agent-sdk/python#claudeagentoptions) in Python, [`settingSources`](/en/agent-sdk/typescript#settingsource) in TypeScript) controls which filesystem-based settings the SDK loads. Pass an explicit list to opt in to specific sources, or pass an empty array to disable user, project, and local settings.

18 18 

19This example loads both user-level and project-level settings by setting `settingSources` to `["user", "project"]`:19This example loads both user-level and project-level settings by setting `settingSources` to `["user", "project"]`:

20 20 

65 ```65 ```

66</CodeGroup>66</CodeGroup>

67 67 

68Each source loads settings from a specific location, where `<cwd>` is the working directory you pass via the `cwd` option (or the process's current directory if unset). For the full type definition, see [`SettingSource`](/en/agent-sdk/typescript#setting-source) (TypeScript) or [`SettingSource`](/en/agent-sdk/python#setting-source) (Python).68Each source loads settings from a specific location, where `<cwd>` is the working directory you pass via the `cwd` option, or the process's current directory if unset. For the full type definition, see [`SettingSource`](/en/agent-sdk/typescript#settingsource) (TypeScript) or [`SettingSource`](/en/agent-sdk/python#settingsource) (Python).

69 69 

70| Source | What it loads | Location |70| Source | What it loads | Location |

71| :---------- | :---------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------- |71| :---------- | :---------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------- |

31 31 

32Cost tracking depends on understanding how the SDK scopes usage data:32Cost tracking depends on understanding how the SDK scopes usage data:

33 33 

34* **`query()` call:** one invocation of the SDK's `query()` function. A single call can involve multiple steps (Claude responds, uses tools, gets results, responds again). Each call produces one [`result`](/en/agent-sdk/typescript#sdk-result-message) message at the end.34* **`query()` call:** one invocation of the SDK's `query()` function. A single call can involve multiple steps (Claude responds, uses tools, gets results, responds again). Each call produces one [`result`](/en/agent-sdk/typescript#sdkresultmessage) message at the end.

35* **Step:** a single request/response cycle within a `query()` call. Each step produces assistant messages with token usage.35* **Step:** a single request/response cycle within a `query()` call. Each step produces assistant messages with token usage.

36* **Session:** a series of `query()` calls linked by a session ID (using the `resume` option). Each `query()` call within a session reports its own cost independently.36* **Session:** a series of `query()` calls linked by a session ID (using the `resume` option). Each `query()` call within a session reports its own cost independently.

37 37 

45 </Step>45 </Step>

46 46 

47 <Step title="The result message provides the cumulative estimate">47 <Step title="The result message provides the cumulative estimate">

48 When the `query()` call completes, the SDK emits a result message with `total_cost_usd` and cumulative `usage`. This is available in both TypeScript ([`SDKResultMessage`](/en/agent-sdk/typescript#sdk-result-message)) and Python ([`ResultMessage`](/en/agent-sdk/python#result-message)). If you make multiple `query()` calls (for example, in a multi-turn session), each result only reflects the cost of that individual call. If you only need the estimated total, you can ignore the per-step usage and read this single value.48 When the `query()` call completes, the SDK emits a result message with `total_cost_usd` and cumulative `usage`. This is available in both TypeScript ([`SDKResultMessage`](/en/agent-sdk/typescript#sdkresultmessage)) and Python ([`ResultMessage`](/en/agent-sdk/python#resultmessage)). If you make multiple `query()` calls (for example, in a multi-turn session), each result only reflects the cost of that individual call. If you only need the estimated total, you can ignore the per-step usage and read this single value.

49 </Step>49 </Step>

50</Steps>50</Steps>

51 51 

52## Get the total cost of a query52## Get the total cost of a query

53 53 

54The result message ([TypeScript](/en/agent-sdk/typescript#sdk-result-message), [Python](/en/agent-sdk/python#result-message)) marks the end of the agent loop for a `query()` call. It includes `total_cost_usd`, the cumulative estimated cost across all steps in that call. This works for both success and error results. If you use sessions to make multiple `query()` calls, each result only reflects the cost of that individual call.54The result message ([TypeScript](/en/agent-sdk/typescript#sdkresultmessage), [Python](/en/agent-sdk/python#resultmessage)) marks the end of the agent loop for a `query()` call. It includes `total_cost_usd`, the cumulative estimated cost across all steps in that call. This works for both success and error results. If you use sessions to make multiple `query()` calls, each result only reflects the cost of that individual call.

55 55 

56The following examples iterate over the message stream from a `query()` call and print the total cost when the `result` message arrives:56The following examples iterate over the message stream from a `query()` call and print the total cost when the `result` message arrives:

57 57 

83 83 

84## Track per-step and per-model usage84## Track per-step and per-model usage

85 85 

86The examples in this section use TypeScript field names. In Python, the equivalent fields are [`AssistantMessage.usage`](/en/agent-sdk/python#assistant-message) and `AssistantMessage.message_id` for per-step usage, and [`ResultMessage.model_usage`](/en/agent-sdk/python#result-message) for per-model breakdowns.86The examples in this section use TypeScript field names. In Python, the equivalent fields are [`AssistantMessage.usage`](/en/agent-sdk/python#assistantmessage) and `AssistantMessage.message_id` for per-step usage, and [`ResultMessage.model_usage`](/en/agent-sdk/python#resultmessage) for per-model breakdowns.

87 87 

88### Track per-step usage88### Track per-step usage

89 89 

122 122 

123### Break down usage per model123### Break down usage per model

124 124 

125The result message includes [`modelUsage`](/en/agent-sdk/typescript#model-usage), a map of model name to per-model token counts and cost. This is useful when you run multiple models (for example, Haiku for subagents and Opus for the main agent) and want to see where tokens are going.125The result message includes [`modelUsage`](/en/agent-sdk/typescript#modelusage), a map of model name to per-model token counts and cost. This is useful when you run multiple models (for example, Haiku for subagents and Opus for the main agent) and want to see where tokens are going.

126 126 

127The following example runs a query and prints the cost and token breakdown for each model used:127The following example runs a query and prints the cost and token breakdown for each model used:

128 128 

223* `cache_creation_input_tokens`: tokens used to create new cache entries (charged at a higher rate than standard input tokens).223* `cache_creation_input_tokens`: tokens used to create new cache entries (charged at a higher rate than standard input tokens).

224* `cache_read_input_tokens`: tokens read from existing cache entries (charged at a reduced rate).224* `cache_read_input_tokens`: tokens read from existing cache entries (charged at a reduced rate).

225 225 

226Track these separately from `input_tokens` to understand caching savings. In TypeScript, these fields are typed on the [`Usage`](/en/agent-sdk/typescript#usage) object. In Python, they appear as keys in the [`ResultMessage.usage`](/en/agent-sdk/python#result-message) dict (for example, `message.usage.get("cache_read_input_tokens", 0)`).226Track these separately from `input_tokens` to understand caching savings. In TypeScript, these fields are typed on the [`Usage`](/en/agent-sdk/typescript#usage) object. In Python, they appear as keys in the [`ResultMessage.usage`](/en/agent-sdk/python#resultmessage) dict (for example, `message.usage.get("cache_read_input_tokens", 0)`).

227 227 

228### Extend the prompt cache TTL to one hour228### Extend the prompt cache TTL to one hour

229 229 

34 * `content` (required): an array of result blocks, each with a `type` of `"text"`, `"image"`, or `"resource"`. See [Return images and resources](#return-images-and-resources) for non-text blocks.34 * `content` (required): an array of result blocks, each with a `type` of `"text"`, `"image"`, or `"resource"`. See [Return images and resources](#return-images-and-resources) for non-text blocks.

35 * `isError` (optional): set to `true` to signal a tool failure so Claude can react to it. See [Handle errors](#handle-errors).35 * `isError` (optional): set to `true` to signal a tool failure so Claude can react to it. See [Handle errors](#handle-errors).

36 36 

37After defining a tool, wrap it in a server with [`createSdkMcpServer`](/en/agent-sdk/typescript#create-sdk-mcp-server) (TypeScript) or [`create_sdk_mcp_server`](/en/agent-sdk/python#create-sdk-mcp-server) (Python). The server runs in-process inside your application, not as a separate process.37After defining a tool, wrap it in a server with [`createSdkMcpServer`](/en/agent-sdk/typescript#createsdkmcpserver) (TypeScript) or [`create_sdk_mcp_server`](/en/agent-sdk/python#create_sdk_mcp_server) (Python). The server runs in-process inside your application, not as a separate process.

38 38 

39### Weather tool example39### Weather tool example

40 40 

306 ```306 ```

307</CodeGroup>307</CodeGroup>

308 308 

309See `ToolAnnotations` in the [TypeScript](/en/agent-sdk/typescript#tool-annotations) or [Python](/en/agent-sdk/python#tool-annotations) reference.309See `ToolAnnotations` in the [TypeScript](/en/agent-sdk/typescript#toolannotations) or [Python](/en/agent-sdk/python#toolannotations) reference.

310 310 

311## Control tool access311## Control tool access

312 312 

24 </Step>24 </Step>

25 25 

26 <Step title="The SDK collects registered hooks">26 <Step title="The SDK collects registered hooks">

27 The SDK checks for hooks registered for that event type. This includes callback hooks you pass in `options.hooks` and shell command hooks from settings files when the corresponding [`settingSources`](/en/agent-sdk/typescript#setting-source) or [`setting_sources`](/en/agent-sdk/python#setting-source) entry is enabled, which it is for default `query()` options.27 The SDK checks for hooks registered for that event type. This includes callback hooks you pass in `options.hooks` and shell command hooks from settings files when the corresponding [`settingSources`](/en/agent-sdk/typescript#settingsource) or [`setting_sources`](/en/agent-sdk/python#settingsource) entry is enabled, which it is for default `query()` options.

28 </Step>28 </Step>

29 29 

30 <Step title="Matchers filter which hooks run">30 <Step title="Matchers filter which hooks run">

225 225 

226Every hook callback receives three arguments:226Every hook callback receives three arguments:

227 227 

228* **Input data:** a typed object containing event details. Each hook type has its own input shape (for example, `PreToolUseHookInput` includes `tool_name` and `tool_input`, while `NotificationHookInput` includes `message`). See the full type definitions in the [TypeScript](/en/agent-sdk/typescript#hook-input) and [Python](/en/agent-sdk/python#hook-input) SDK references.228* **Input data:** a typed object containing event details. Each hook type has its own input shape (for example, `PreToolUseHookInput` includes `tool_name` and `tool_input`, while `NotificationHookInput` includes `message`). See the full type definitions in the [TypeScript](/en/agent-sdk/typescript#hookinput) and [Python](/en/agent-sdk/python#hookinput) SDK references.

229 * All hook inputs share `session_id`, `cwd`, and `hook_event_name`.229 * All hook inputs share `session_id`, `cwd`, and `hook_event_name`.

230 * `agent_id` and `agent_type` are populated when the hook fires inside a subagent. In TypeScript, these are on the base hook input and available to all hook types. In Python, they are on `PreToolUse`, `PostToolUse`, and `PostToolUseFailure` only.230 * `agent_id` and `agent_type` are populated when the hook fires inside a subagent. In TypeScript, these are on the base hook input and available to all hook types. In Python, they are on `PreToolUse`, `PostToolUse`, and `PostToolUseFailure` only.

231* **Tool use ID** (`str | None` / `string | undefined`): correlates `PreToolUse` and `PostToolUse` events for the same tool call.231* **Tool use ID** (`str | None` / `string | undefined`): correlates `PreToolUse` and `PostToolUse` events for the same tool call.

238* **Top-level fields** control the conversation: `systemMessage` injects a message into the conversation visible to the model, and `continue` (`continue_` in Python) determines whether the agent keeps running after this hook.238* **Top-level fields** control the conversation: `systemMessage` injects a message into the conversation visible to the model, and `continue` (`continue_` in Python) determines whether the agent keeps running after this hook.

239* **`hookSpecificOutput`** controls the current operation. The fields inside depend on the hook event type. For `PreToolUse` hooks, this is where you set `permissionDecision` (`"allow"`, `"deny"`, or `"ask"`), `permissionDecisionReason`, and `updatedInput`. In the TypeScript SDK, `permissionDecision` also accepts `"defer"` to end the query and [resume later](/en/hooks#defer-a-tool-call-for-later); this value is not available in the Python SDK. For `PostToolUse` hooks, you can set `additionalContext` to append information to the tool result, or `updatedToolOutput` to replace the tool's output entirely before Claude sees it.239* **`hookSpecificOutput`** controls the current operation. The fields inside depend on the hook event type. For `PreToolUse` hooks, this is where you set `permissionDecision` (`"allow"`, `"deny"`, or `"ask"`), `permissionDecisionReason`, and `updatedInput`. In the TypeScript SDK, `permissionDecision` also accepts `"defer"` to end the query and [resume later](/en/hooks#defer-a-tool-call-for-later); this value is not available in the Python SDK. For `PostToolUse` hooks, you can set `additionalContext` to append information to the tool result, or `updatedToolOutput` to replace the tool's output entirely before Claude sees it.

240 240 

241Return `{}` to allow the operation without changes. SDK callback hooks use the same JSON output format as [Claude Code shell command hooks](/en/hooks#json-output), which documents every field and event-specific option. For the SDK type definitions, see the [TypeScript](/en/agent-sdk/typescript#sync-hook-json-output) and [Python](/en/agent-sdk/python#sync-hook-json-output) SDK references.241Return `{}` to allow the operation without changes. SDK callback hooks use the same JSON output format as [Claude Code shell command hooks](/en/hooks#json-output), which documents every field and event-specific option. For the SDK type definitions, see the [TypeScript](/en/agent-sdk/typescript#synchookjsonoutput) and [Python](/en/agent-sdk/python#synchookjsonoutput) SDK references.

242 242 

243<Note>243<Note>

244 When multiple hooks or permission rules apply, **deny** takes priority over **defer**, which takes priority over **ask**, which takes priority over **allow**. If any hook returns `deny`, the operation is blocked regardless of other hooks.244 When multiple hooks or permission rules apply, **deny** takes priority over **defer**, which takes priority over **ask**, which takes priority over **allow**. If any hook returns `deny`, the operation is blocked regardless of other hooks.

417 ```417 ```

418</CodeGroup>418</CodeGroup>

419 419 

420### Chain multiple hooks420### Register multiple hooks

421 421 

422Hooks execute in the order they appear in the array. Keep each hook focused on a single responsibility and chain multiple hooks for complex logic:422When an event fires, all matching hooks run in parallel. For permission decisions, the most restrictive result wins: a single `deny` blocks the tool call regardless of what the other hooks return. Because completion order is non-deterministic, write each hook to act independently rather than relying on another hook having run first.

423 

424The example below registers three independent checks for every tool call:

423 425 

424<CodeGroup>426<CodeGroup>

425 ```python Python theme={null}427 ```python Python theme={null}

426 options = ClaudeAgentOptions(428 options = ClaudeAgentOptions(

427 hooks={429 hooks={

428 "PreToolUse": [430 "PreToolUse": [

429 HookMatcher(hooks=[rate_limiter]), # First: check rate limits431 HookMatcher(hooks=[authorization_check]),

430 HookMatcher(hooks=[authorization_check]), # Second: verify permissions432 HookMatcher(hooks=[input_validator]),

431 HookMatcher(hooks=[input_sanitizer]), # Third: sanitize inputs433 HookMatcher(hooks=[audit_logger]),

432 HookMatcher(hooks=[audit_logger]), # Last: log the action

433 ]434 ]

434 }435 }

435 )436 )

439 const options = {440 const options = {

440 hooks: {441 hooks: {

441 PreToolUse: [442 PreToolUse: [

442 { hooks: [rateLimiter] }, // First: check rate limits443 { hooks: [authorizationCheck] },

443 { hooks: [authorizationCheck] }, // Second: verify permissions444 { hooks: [inputValidator] },

444 { hooks: [inputSanitizer] }, // Third: sanitize inputs445 { hooks: [auditLogger] }

445 { hooks: [auditLogger] } // Last: log the action

446 ]446 ]

447 }447 }

448 };448 };

489 489 

490### Track subagent activity490### Track subagent activity

491 491 

492Use `SubagentStop` hooks to monitor when subagents finish their work. See the full input type in the [TypeScript](/en/agent-sdk/typescript#hook-input) and [Python](/en/agent-sdk/python#hook-input) SDK references. This example logs a summary each time a subagent completes:492Use `SubagentStop` hooks to monitor when subagents finish their work. See the full input type in the [TypeScript](/en/agent-sdk/typescript#hookinput) and [Python](/en/agent-sdk/python#hookinput) SDK references. This example logs a summary each time a subagent completes:

493 493 

494<CodeGroup>494<CodeGroup>

495 ```python Python theme={null}495 ```python Python theme={null}

727* Check that your matcher pattern matches the tool name exactly727* Check that your matcher pattern matches the tool name exactly

728* Ensure the hook is under the correct event type in `options.hooks`728* Ensure the hook is under the correct event type in `options.hooks`

729* For non-tool hooks like `Stop` and `SubagentStop`, matchers match against different fields (see [matcher patterns](/en/hooks#matcher-patterns))729* For non-tool hooks like `Stop` and `SubagentStop`, matchers match against different fields (see [matcher patterns](/en/hooks#matcher-patterns))

730* Hooks may not fire when the agent hits the [`max_turns`](/en/agent-sdk/python#claude-agent-options) limit because the session ends before hooks can execute730* Hooks may not fire when the agent hits the [`max_turns`](/en/agent-sdk/python#claudeagentoptions) limit because the session ends before hooks can execute

731 731 

732### Matcher not filtering as expected732### Matcher not filtering as expected

733 733 

775 775 

776### Session hooks not available in Python776### Session hooks not available in Python

777 777 

778`SessionStart` and `SessionEnd` can be registered as SDK callback hooks in TypeScript, but are not available in the Python SDK (`HookEvent` omits them). In Python, they are only available as [shell command hooks](/en/hooks#hook-events) defined in settings files (for example, `.claude/settings.json`). To load shell command hooks from your SDK application, include the appropriate setting source with [`setting_sources`](/en/agent-sdk/python#setting-source) or [`settingSources`](/en/agent-sdk/typescript#setting-source):778`SessionStart` and `SessionEnd` can be registered as SDK callback hooks in TypeScript, but are not available in the Python SDK (`HookEvent` omits them). In Python, they are only available as [shell command hooks](/en/hooks#hook-events) defined in settings files (for example, `.claude/settings.json`). To load shell command hooks from your SDK application, include the appropriate setting source with [`setting_sources`](/en/agent-sdk/python#settingsource) or [`settingSources`](/en/agent-sdk/typescript#settingsource):

779 779 

780<CodeGroup>780<CodeGroup>

781 ```python Python theme={null}781 ```python Python theme={null}

18 18 

19For security and isolation, the SDK should run inside a sandboxed container environment. This provides process isolation, resource limits, network control, and ephemeral filesystems.19For security and isolation, the SDK should run inside a sandboxed container environment. This provides process isolation, resource limits, network control, and ephemeral filesystems.

20 20 

21The SDK also supports [programmatic sandbox configuration](/en/agent-sdk/typescript#sandbox-settings) for command execution.21The SDK also supports [programmatic sandbox configuration](/en/agent-sdk/typescript#sandboxsettings) for command execution.

22 22 

23### System Requirements23### System Requirements

24 24 

135## Next Steps135## Next Steps

136 136 

137* [Secure Deployment](/en/agent-sdk/secure-deployment) - Network controls, credential management, and isolation hardening137* [Secure Deployment](/en/agent-sdk/secure-deployment) - Network controls, credential management, and isolation hardening

138* [TypeScript SDK - Sandbox Settings](/en/agent-sdk/typescript#sandbox-settings) - Configure sandbox programmatically138* [TypeScript SDK - Sandbox Settings](/en/agent-sdk/typescript#sandboxsettings) - Configure sandbox programmatically

139* [Sessions Guide](/en/agent-sdk/sessions) - Learn about session management139* [Sessions Guide](/en/agent-sdk/sessions) - Learn about session management

140* [Permissions](/en/agent-sdk/permissions) - Configure tool permissions140* [Permissions](/en/agent-sdk/permissions) - Configure tool permissions

141* [Cost Tracking](/en/agent-sdk/cost-tracking) - Monitor API usage141* [Cost Tracking](/en/agent-sdk/cost-tracking) - Monitor API usage

205 205 

206**Why this changed:** Provides better control and isolation for SDK applications. You can now build agents with custom behavior without inheriting Claude Code's CLI-focused instructions.206**Why this changed:** Provides better control and isolation for SDK applications. You can now build agents with custom behavior without inheriting Claude Code's CLI-focused instructions.

207 207 

208### Settings Sources No Longer Loaded by Default208### Settings sources default

209 209 

210**What changed:** The SDK no longer reads from filesystem settings (CLAUDE.md, settings.json, slash commands, etc.) by default.210This default was briefly changed in v0.1.0 and then reverted, so no migration action is needed.

211 211 

212**Migration:**212**Current behavior:** Omitting `settingSources` on `query()` loads user, project, and local filesystem settings, matching the CLI. This includes `~/.claude/settings.json`, `.claude/settings.json`, `.claude/settings.local.json`, CLAUDE.md files, and custom commands.

213 

214To run isolated from filesystem settings, pass an empty array:

213 215 

214<CodeGroup>216<CodeGroup>

215 ```typescript TypeScript theme={null}217 ```typescript TypeScript theme={null}

216 // BEFORE (v0.0.x) - Loaded all settings automatically

217 const result = query({ prompt: "Hello" });

218 // Would read from:

219 // - ~/.claude/settings.json (user)

220 // - .claude/settings.json (project)

221 // - .claude/settings.local.json (local)

222 // - CLAUDE.md files

223 // - Custom slash commands

224 

225 // AFTER (v0.1.0) - No settings loaded by default

226 // To get the old behavior:

227 const result = query({218 const result = query({

228 prompt: "Hello",219 prompt: "Hello",

229 options: {220 options: {

230 settingSources: ["user", "project", "local"]221 settingSources: [] // No filesystem settings loaded

231 }222 }

232 });223 });

233 224 

241 ```232 ```

242 233 

243 ```python Python theme={null}234 ```python Python theme={null}

244 # BEFORE (v0.0.x) - Loaded all settings automatically

245 async for message in query(prompt="Hello"):

246 print(message)

247 # Would read from:

248 # - ~/.claude/settings.json (user)

249 # - .claude/settings.json (project)

250 # - .claude/settings.local.json (local)

251 # - CLAUDE.md files

252 # - Custom slash commands

253 

254 # AFTER (v0.1.0) - No settings loaded by default

255 # To get the old behavior:

256 from claude_agent_sdk import query, ClaudeAgentOptions235 from claude_agent_sdk import query, ClaudeAgentOptions

257 236 

258 async for message in query(237 async for message in query(

259 prompt="Hello",238 prompt="Hello",

260 options=ClaudeAgentOptions(setting_sources=["user", "project", "local"]),239 options=ClaudeAgentOptions(setting_sources=[]), # No filesystem settings loaded

261 ):240 ):

262 print(message)241 print(message)

263 242 

272 ```251 ```

273</CodeGroup>252</CodeGroup>

274 253 

275**Why this changed:** Ensures SDK applications have predictable behavior independent of local filesystem configurations. This is especially important for:254Isolation is especially important for CI/CD pipelines, deployed applications, test environments, and multi-tenant systems where local customizations should not leak in.

276 255 

277* **CI/CD environments** - Consistent behavior without local customizations256<Note>

278* **Deployed applications** - No dependency on filesystem settings257 SDK v0.1.0 briefly defaulted to no settings loaded; this was reverted in subsequent releases. Python SDK 0.1.59 and earlier treated an empty list the same as omitting the option, so upgrade before relying on `setting_sources=[]`. See [What settingSources does not control](/en/agent-sdk/claude-code-features#what-settingsources-does-not-control) for inputs that are read even when `settingSources` is `[]`.

279* **Testing** - Isolated test environments258</Note>

280* **Multi-tenant systems** - Prevent settings leakage between users

281 

282<Warning>

283 Current SDK releases have reverted this default for `query()`: omitting the option once again loads user, project, and local settings, matching the CLI. Pass `settingSources: []` in TypeScript or `setting_sources=[]` in Python if your application depends on the isolated behavior described above. Python SDK 0.1.59 and earlier treated an empty list the same as omitting the option, so upgrade before relying on `setting_sources=[]`. See [What settingSources does not control](/en/agent-sdk/claude-code-features#what-settingsources-does-not-control) for inputs that are read even when `settingSources` is `[]`.

284</Warning>

285 259 

286## Why the Rename?260## Why the Rename?

287 261 

194 ```194 ```

195</CodeGroup>195</CodeGroup>

196 196 

197## Attribute actions to your end users

198 

199The CLI attaches [identity attributes](/en/monitoring-usage#standard-attributes) to every event based on the credential it uses to call Anthropic. When you build an application that serves many end users from one deployment, these attributes identify your service's credential, not the end user on whose behalf the agent acted.

200 

201To make tool calls and MCP activity attributable to your application's end users, inject end-user identity as resource attributes on each `query()` call. Percent-encode values before interpolating them, since `OTEL_RESOURCE_ATTRIBUTES` [reserves commas, spaces, and equals signs](/en/monitoring-usage#multi-team-organization-support). The following example attaches the requesting user and tenant to every span and event from one request:

202 

203<CodeGroup>

204 ```python Python theme={null}

205 from urllib.parse import quote

206 

207 options = ClaudeAgentOptions(

208 env={

209 # ... exporter configuration ...

210 "OTEL_RESOURCE_ATTRIBUTES": f"enduser.id={quote(request.user_id)},tenant.id={quote(request.tenant_id)}",

211 },

212 )

213 ```

214 

215 ```typescript TypeScript theme={null}

216 const options = {

217 env: {

218 ...process.env,

219 // ... exporter configuration ...

220 OTEL_RESOURCE_ATTRIBUTES: `enduser.id=${encodeURIComponent(request.userId)},tenant.id=${encodeURIComponent(request.tenantId)}`,

221 },

222 };

223 ```

224</CodeGroup>

225 

226With end-user identity attached, the `tool_decision`, `tool_result`, `mcp_server_connection`, and `permission_mode_changed` events become a per-user audit trail you can forward to a Security Information and Event Management (SIEM) platform. See [Audit security events](/en/monitoring-usage#audit-security-events) in the Monitoring reference for the full list of security-relevant events and the attributes each one carries.

227 

197## Control sensitive data in exports228## Control sensitive data in exports

198 229 

199Telemetry is structural by default. Durations, model names, and tool names are recorded on every span; token counts are recorded when the underlying API request returns usage data, so spans for failed or aborted requests may omit them. The content your agent reads and writes is not recorded by default. These opt-in variables add content to the exported data:230Telemetry is structural by default. Durations, model names, and tool names are recorded on every span; token counts are recorded when the underlying API request returns usage data, so spans for failed or aborted requests may omit them. The content your agent reads and writes is not recorded by default. These opt-in variables add content to the exported data:

18 18 

19<Steps>19<Steps>

20 <Step title="Hooks">20 <Step title="Hooks">

21 Run [hooks](/en/agent-sdk/hooks) first, which can allow, deny, or continue to the next step21 Run [hooks](/en/agent-sdk/hooks) first. A hook can deny the call outright or pass it on. A hook that returns `allow` does not skip the deny and ask rules below; those are evaluated regardless of the hook result.

22 </Step>22 </Step>

23 23 

24 <Step title="Deny rules">24 <Step title="Deny rules">

38 </Step>38 </Step>

39</Steps>39</Steps>

40 40 

41<img src="https://mintcdn.com/claude-code/gvy2DIUELtNA8qD3/images/agent-sdk/permissions-flow.svg?fit=max&auto=format&n=gvy2DIUELtNA8qD3&q=85&s=0ccd63043a9ffc2a34d863602e043f72" alt="Permission evaluation flow diagram" width="920" height="260" data-path="images/agent-sdk/permissions-flow.svg" />41<img src="https://mintcdn.com/claude-code/FEspvVUyRuaWjm0s/images/agent-sdk/permissions-flow.svg?fit=max&auto=format&n=FEspvVUyRuaWjm0s&q=85&s=a1759b0cf4541281a9fdd8f5348228e8" alt="Permission evaluation flow diagram" width="920" height="260" data-path="images/agent-sdk/permissions-flow.svg" />

42 42 

43This page focuses on **allow and deny rules** and **permission modes**. For the other steps:43This page focuses on **allow and deny rules** and **permission modes**. For the other steps:

44 44 

83| `dontAsk` | Deny instead of prompting | Anything not pre-approved by `allowed_tools` or rules is denied; `canUseTool` is never called |83| `dontAsk` | Deny instead of prompting | Anything not pre-approved by `allowed_tools` or rules is denied; `canUseTool` is never called |

84| `acceptEdits` | Auto-accept file edits | File edits and [filesystem operations](#accept-edits-mode-acceptedits) (`mkdir`, `rm`, `mv`, etc.) are automatically approved |84| `acceptEdits` | Auto-accept file edits | File edits and [filesystem operations](#accept-edits-mode-acceptedits) (`mkdir`, `rm`, `mv`, etc.) are automatically approved |

85| `bypassPermissions` | Bypass all permission checks | All tools run without permission prompts (use with caution) |85| `bypassPermissions` | Bypass all permission checks | All tools run without permission prompts (use with caution) |

86| `plan` | Planning mode | No tool execution; Claude plans without making changes |86| `plan` | Planning mode | Read-only tools run; Claude analyzes and plans without editing your source files |

87| `auto` (TypeScript only) | Model-classified approvals | A model classifier approves or denies each tool call. See [Auto mode](/en/permission-modes#eliminate-prompts-with-auto-mode) for availability |87| `auto` (TypeScript only) | Model-classified approvals | A model classifier approves or denies each tool call. See [Auto mode](/en/permission-modes#eliminate-prompts-with-auto-mode) for availability |

88 88 

89<Warning>89<Warning>

145 <CodeGroup>145 <CodeGroup>

146 ```python Python theme={null}146 ```python Python theme={null}

147 import asyncio147 import asyncio

148 from claude_agent_sdk import query, ClaudeAgentOptions148 from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions

149 149 

150 150 

151 async def main():151 async def main():

152 q = query(152 async with ClaudeSDKClient(

153 prompt="Help me refactor this code",

154 options=ClaudeAgentOptions(153 options=ClaudeAgentOptions(

155 permission_mode="default", # Start in default mode154 permission_mode="default", # Start in default mode

156 ),

157 )155 )

156 ) as client:

157 await client.query("Help me refactor this code")

158 158 

159 # Change mode dynamically mid-session159 # Change mode dynamically mid-session

160 await q.set_permission_mode("acceptEdits")160 await client.set_permission_mode("acceptEdits")

161 161 

162 # Process messages with the new permission mode162 # Process messages with the new permission mode

163 async for message in q:163 async for message in client.receive_response():

164 if hasattr(message, "result"):164 if hasattr(message, "result"):

165 print(message.result)165 print(message.result)

166 166 

229 229 

230#### Plan mode (`plan`)230#### Plan mode (`plan`)

231 231 

232Prevents tool execution entirely. Claude can analyze code and create plans but cannot make changes. Claude may use `AskUserQuestion` to clarify requirements before finalizing the plan. See [Handle approvals and user input](/en/agent-sdk/user-input#handle-clarifying-questions) for handling these prompts.232Restricts Claude to read-only tools. Claude can read files and run read-only shell commands to explore the codebase but does not edit your source files. Claude may use `AskUserQuestion` to clarify requirements before finalizing the plan. See [Handle approvals and user input](/en/agent-sdk/user-input#handle-clarifying-questions) for handling these prompts.

233 233 

234**Use when:** you want Claude to propose changes without executing them, such as during code review or when you need to approve changes before they're made.234**Use when:** you want Claude to propose changes without executing them, such as during code review or when you need to approve changes before they're made.

235 235 

113#### Parameters113#### Parameters

114 114 

115| Parameter | Type | Description |115| Parameter | Type | Description |

116| :------------- | :----------------------------------------------- | :------------------------------------------------------------------ |116| :------------- | :---------------------------------------------- | :------------------------------------------------------------------ |

117| `name` | `str` | Unique identifier for the tool |117| `name` | `str` | Unique identifier for the tool |

118| `description` | `str` | Human-readable description of what the tool does |118| `description` | `str` | Human-readable description of what the tool does |

119| `input_schema` | `type \| dict[str, Any]` | Schema defining the tool's input parameters (see below) |119| `input_schema` | `type \| dict[str, Any]` | Schema defining the tool's input parameters (see below) |

120| `annotations` | [`ToolAnnotations`](#tool-annotations)` \| None` | Optional MCP tool annotations providing behavioral hints to clients |120| `annotations` | [`ToolAnnotations`](#toolannotations)` \| None` | Optional MCP tool annotations providing behavioral hints to clients |

121 121 

122#### Input schema options122#### Input schema options

123 123 

267| `first_prompt` | `str \| None` | First meaningful user prompt in the session |267| `first_prompt` | `str \| None` | First meaningful user prompt in the session |

268| `git_branch` | `str \| None` | Git branch at the end of the session |268| `git_branch` | `str \| None` | Git branch at the end of the session |

269| `cwd` | `str \| None` | Working directory for the session |269| `cwd` | `str \| None` | Working directory for the session |

270| `tag` | `str \| None` | User-set session tag (see [`tag_session()`](#tag-session)) |270| `tag` | `str \| None` | User-set session tag (see [`tag_session()`](#tag_session)) |

271| `created_at` | `int \| None` | Session creation time in milliseconds since epoch |271| `created_at` | `int \| None` | Session creation time in milliseconds since epoch |

272 272 

273#### Example273#### Example

343| `session_id` | `str` | required | UUID of the session to look up |343| `session_id` | `str` | required | UUID of the session to look up |

344| `directory` | `str \| None` | `None` | Project directory path. When omitted, searches all project directories |344| `directory` | `str \| None` | `None` | Project directory path. When omitted, searches all project directories |

345 345 

346Returns [`SDKSessionInfo`](#return-type-sdk-session-info), or `None` if the session is not found.346Returns [`SDKSessionInfo`](#return-type-sdksessioninfo), or `None` if the session is not found.

347 347 

348#### Example348#### Example

349 349 

381 381 

382#### Example382#### Example

383 383 

384Rename the most recent session so it's easier to find later. The new title appears in [`SDKSessionInfo.custom_title`](#return-type-sdk-session-info) on subsequent reads.384Rename the most recent session so it's easier to find later. The new title appears in [`SDKSessionInfo.custom_title`](#return-type-sdksessioninfo) on subsequent reads.

385 385 

386```python theme={null}386```python theme={null}

387from claude_agent_sdk import list_sessions, rename_session387from claude_agent_sdk import list_sessions, rename_session

476| `set_permission_mode(mode)` | Change the permission mode for the current session |476| `set_permission_mode(mode)` | Change the permission mode for the current session |

477| `set_model(model)` | Change the model for the current session. Pass `None` to reset to default |477| `set_model(model)` | Change the model for the current session. Pass `None` to reset to default |

478| `rewind_files(user_message_id)` | Restore files to their state at the specified user message. Requires `enable_file_checkpointing=True`. See [File checkpointing](/en/agent-sdk/file-checkpointing) |478| `rewind_files(user_message_id)` | Restore files to their state at the specified user message. Requires `enable_file_checkpointing=True`. See [File checkpointing](/en/agent-sdk/file-checkpointing) |

479| `get_mcp_status()` | Get the status of all configured MCP servers. Returns [`McpStatusResponse`](#mcp-status-response) |479| `get_mcp_status()` | Get the status of all configured MCP servers. Returns [`McpStatusResponse`](#mcpstatusresponse) |

480| `reconnect_mcp_server(server_name)` | Retry connecting to an MCP server that failed or was disconnected |480| `reconnect_mcp_server(server_name)` | Retry connecting to an MCP server that failed or was disconnected |

481| `toggle_mcp_server(server_name, enabled)` | Enable or disable an MCP server mid-session. Disabling removes its tools |481| `toggle_mcp_server(server_name, enabled)` | Enable or disable an MCP server mid-session. Disabling removes its tools |

482| `stop_task(task_id)` | Stop a running background task. A [`TaskNotificationMessage`](#task-notification-message) with status `"stopped"` follows in the message stream |482| `stop_task(task_id)` | Stop a running background task. A [`TaskNotificationMessage`](#tasknotificationmessage) with status `"stopped"` follows in the message stream |

483| `get_server_info()` | Get server information including session ID and capabilities |483| `get_server_info()` | Get server information including session ID and capabilities |

484| `disconnect()` | Disconnect from Claude |484| `disconnect()` | Disconnect from Claude |

485 485 

791 effort: Literal["low", "medium", "high", "max"] | None = None791 effort: Literal["low", "medium", "high", "max"] | None = None

792 enable_file_checkpointing: bool = False792 enable_file_checkpointing: bool = False

793 session_store: SessionStore | None = None793 session_store: SessionStore | None = None

794 session_store_flush: SessionStoreFlushMode = "batched"

794```795```

795 796 

796| Property | Type | Default | Description |797| Property | Type | Default | Description |

797| :---------------------------- | :------------------------------------------------------------------------------------- | :--------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |798| :---------------------------- | :------------------------------------------------------------------------------------ | :--------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

798| `tools` | `list[str] \| ToolsPreset \| None` | `None` | Tools configuration. Use `{"type": "preset", "preset": "claude_code"}` for Claude Code's default tools |799| `tools` | `list[str] \| ToolsPreset \| None` | `None` | Tools configuration. Use `{"type": "preset", "preset": "claude_code"}` for Claude Code's default tools |

799| `allowed_tools` | `list[str]` | `[]` | Tools to auto-approve without prompting. This does not restrict Claude to only these tools; unlisted tools fall through to `permission_mode` and `can_use_tool`. Use `disallowed_tools` to block tools. See [Permissions](/en/agent-sdk/permissions#allow-and-deny-rules) |800| `allowed_tools` | `list[str]` | `[]` | Tools to auto-approve without prompting. This does not restrict Claude to only these tools; unlisted tools fall through to `permission_mode` and `can_use_tool`. Use `disallowed_tools` to block tools. See [Permissions](/en/agent-sdk/permissions#allow-and-deny-rules) |

800| `system_prompt` | `str \| SystemPromptPreset \| None` | `None` | System prompt configuration. Pass a string for custom prompt, or use `{"type": "preset", "preset": "claude_code"}` for Claude Code's system prompt. Add `"append"` to extend the preset |801| `system_prompt` | `str \| SystemPromptPreset \| None` | `None` | System prompt configuration. Pass a string for custom prompt, or use `{"type": "preset", "preset": "claude_code"}` for Claude Code's system prompt. Add `"append"` to extend the preset |

808| `enable_file_checkpointing` | `bool` | `False` | Enable file change tracking for rewinding. See [File checkpointing](/en/agent-sdk/file-checkpointing) |809| `enable_file_checkpointing` | `bool` | `False` | Enable file change tracking for rewinding. See [File checkpointing](/en/agent-sdk/file-checkpointing) |

809| `model` | `str \| None` | `None` | Claude model to use |810| `model` | `str \| None` | `None` | Claude model to use |

810| `fallback_model` | `str \| None` | `None` | Fallback model to use if the primary model fails |811| `fallback_model` | `str \| None` | `None` | Fallback model to use if the primary model fails |

811| `betas` | `list[SdkBeta]` | `[]` | Beta features to enable. See [`SdkBeta`](#sdk-beta) for available options |812| `betas` | `list[SdkBeta]` | `[]` | Beta features to enable. See [`SdkBeta`](#sdkbeta) for available options |

812| `output_format` | `dict[str, Any] \| None` | `None` | Output format for structured responses (e.g., `{"type": "json_schema", "schema": {...}}`). See [Structured outputs](/en/agent-sdk/structured-outputs) for details |813| `output_format` | `dict[str, Any] \| None` | `None` | Output format for structured responses (e.g., `{"type": "json_schema", "schema": {...}}`). See [Structured outputs](/en/agent-sdk/structured-outputs) for details |

813| `permission_prompt_tool_name` | `str \| None` | `None` | MCP tool name for permission prompts |814| `permission_prompt_tool_name` | `str \| None` | `None` | MCP tool name for permission prompts |

814| `cwd` | `str \| Path \| None` | `None` | Current working directory |815| `cwd` | `str \| Path \| None` | `None` | Current working directory |

820| `max_buffer_size` | `int \| None` | `None` | Maximum bytes when buffering CLI stdout |821| `max_buffer_size` | `int \| None` | `None` | Maximum bytes when buffering CLI stdout |

821| `debug_stderr` | `Any` | `sys.stderr` | *Deprecated* - File-like object for debug output. Use `stderr` callback instead |822| `debug_stderr` | `Any` | `sys.stderr` | *Deprecated* - File-like object for debug output. Use `stderr` callback instead |

822| `stderr` | `Callable[[str], None] \| None` | `None` | Callback function for stderr output from CLI |823| `stderr` | `Callable[[str], None] \| None` | `None` | Callback function for stderr output from CLI |

823| `can_use_tool` | [`CanUseTool`](#can-use-tool) ` \| None` | `None` | Tool permission callback function. See [Permission types](#can-use-tool) for details |824| `can_use_tool` | [`CanUseTool`](#canusetool) ` \| None` | `None` | Tool permission callback function. See [Permission types](#canusetool) for details |

824| `hooks` | `dict[HookEvent, list[HookMatcher]] \| None` | `None` | Hook configurations for intercepting events |825| `hooks` | `dict[HookEvent, list[HookMatcher]] \| None` | `None` | Hook configurations for intercepting events |

825| `user` | `str \| None` | `None` | User identifier |826| `user` | `str \| None` | `None` | User identifier |

826| `include_partial_messages` | `bool` | `False` | Include partial message streaming events. When enabled, [`StreamEvent`](#stream-event) messages are yielded |827| `include_partial_messages` | `bool` | `False` | Include partial message streaming events. When enabled, [`StreamEvent`](#streamevent) messages are yielded |

827| `fork_session` | `bool` | `False` | When resuming with `resume`, fork to a new session ID instead of continuing the original session |828| `fork_session` | `bool` | `False` | When resuming with `resume`, fork to a new session ID instead of continuing the original session |

828| `agents` | `dict[str, AgentDefinition] \| None` | `None` | Programmatically defined subagents |829| `agents` | `dict[str, AgentDefinition] \| None` | `None` | Programmatically defined subagents |

829| `plugins` | `list[SdkPluginConfig]` | `[]` | Load custom plugins from local paths. See [Plugins](/en/agent-sdk/plugins) for details |830| `plugins` | `list[SdkPluginConfig]` | `[]` | Load custom plugins from local paths. See [Plugins](/en/agent-sdk/plugins) for details |

830| `sandbox` | [`SandboxSettings`](#sandbox-settings) ` \| None` | `None` | Configure sandbox behavior programmatically. See [Sandbox settings](#sandbox-settings) for details |831| `sandbox` | [`SandboxSettings`](#sandboxsettings) ` \| None` | `None` | Configure sandbox behavior programmatically. See [Sandbox settings](#sandboxsettings) for details |

831| `setting_sources` | `list[SettingSource] \| None` | `None` (CLI defaults: all sources) | Control which filesystem settings to load. Pass `[]` to disable user, project, and local settings. Managed policy settings load regardless. See [Use Claude Code features](/en/agent-sdk/claude-code-features#what-settingsources-does-not-control) |832| `setting_sources` | `list[SettingSource] \| None` | `None` (CLI defaults: all sources) | Control which filesystem settings to load. Pass `[]` to disable user, project, and local settings. Managed policy settings load regardless. See [Use Claude Code features](/en/agent-sdk/claude-code-features#what-settingsources-does-not-control) |

832| `max_thinking_tokens` | `int \| None` | `None` | *Deprecated* - Maximum tokens for thinking blocks. Use `thinking` instead |833| `max_thinking_tokens` | `int \| None` | `None` | *Deprecated* - Maximum tokens for thinking blocks. Use `thinking` instead |

833| `thinking` | [`ThinkingConfig`](#thinking-config) ` \| None` | `None` | Controls extended thinking behavior. Takes precedence over `max_thinking_tokens` |834| `thinking` | [`ThinkingConfig`](#thinkingconfig) ` \| None` | `None` | Controls extended thinking behavior. Takes precedence over `max_thinking_tokens` |

834| `effort` | `Literal["low", "medium", "high", "max"] \| None` | `None` | Effort level for thinking depth |835| `effort` | `Literal["low", "medium", "high", "max"] \| None` | `None` | Effort level for thinking depth |

835| `session_store` | [`SessionStore`](/en/agent-sdk/session-storage#the-session-store-interface) ` \| None` | `None` | Mirror session transcripts to an external backend so any host can resume them. See [Persist sessions to external storage](/en/agent-sdk/session-storage) |836| `session_store` | [`SessionStore`](/en/agent-sdk/session-storage#the-sessionstore-interface) ` \| None` | `None` | Mirror session transcripts to an external backend so any host can resume them. See [Persist sessions to external storage](/en/agent-sdk/session-storage) |

837| `session_store_flush` | `Literal["batched", "eager"]` | `"batched"` | When to flush mirrored transcript entries to `session_store`. `"batched"` flushes once per turn or when the buffer fills; `"eager"` triggers a background flush after every frame. Ignored when `session_store` is `None` |

836 838 

837### `OutputFormat`839### `OutputFormat`

838 840 

1031| `maxTurns` | No | Maximum number of agentic turns before the agent stops |1033| `maxTurns` | No | Maximum number of agentic turns before the agent stops |

1032| `background` | No | Run this agent as a non-blocking background task when invoked |1034| `background` | No | Run this agent as a non-blocking background task when invoked |

1033| `effort` | No | Reasoning effort level for this agent. Accepts a named level or an integer |1035| `effort` | No | Reasoning effort level for this agent. Accepts a named level or an integer |

1034| `permissionMode` | No | Permission mode for tool execution within this agent. See [`PermissionMode`](#permission-mode) |1036| `permissionMode` | No | Permission mode for tool execution within this agent. See [`PermissionMode`](#permissionmode) |

1035 1037 

1036<Note>1038<Note>

1037 `AgentDefinition` field names use camelCase, such as `disallowedTools`, `permissionMode`, and `maxTurns`. These names map directly to the wire format shared with the TypeScript SDK. This differs from `ClaudeAgentOptions`, which uses Python snake\_case for the equivalent top-level fields such as `disallowed_tools` and `permission_mode`. Because `AgentDefinition` is a dataclass, passing a snake\_case keyword raises a `TypeError` at construction time.1039 `AgentDefinition` field names use camelCase, such as `disallowedTools`, `permissionMode`, and `maxTurns`. These names map directly to the wire format shared with the TypeScript SDK. This differs from `ClaudeAgentOptions`, which uses Python snake\_case for the equivalent top-level fields such as `disallowed_tools` and `permission_mode`. Because `AgentDefinition` is a dataclass, passing a snake\_case keyword raises a `TypeError` at construction time.

1045PermissionMode = Literal[1047PermissionMode = Literal[

1046 "default", # Standard permission behavior1048 "default", # Standard permission behavior

1047 "acceptEdits", # Auto-accept file edits1049 "acceptEdits", # Auto-accept file edits

1048 "plan", # Planning mode - no execution1050 "plan", # Planning mode - read-only tools only

1049 "dontAsk", # Deny anything not pre-approved instead of prompting1051 "dontAsk", # Deny anything not pre-approved instead of prompting

1050 "bypassPermissions", # Bypass all permission checks (use with caution)1052 "bypassPermissions", # Bypass all permission checks (use with caution)

1051]1053]

1081```1083```

1082 1084 

1083| Field | Type | Description |1085| Field | Type | Description |

1084| :------------ | :----------------------- | :----------------------------------------- |1086| :------------ | :----------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

1085| `signal` | `Any \| None` | Reserved for future abort signal support |1087| `signal` | `Any \| None` | Reserved for future abort signal support |

1086| `suggestions` | `list[PermissionUpdate]` | Permission update suggestions from the CLI |1088| `suggestions` | `list[PermissionUpdate]` | Permission update suggestions from the CLI. Bash prompts include a suggestion with the `localSettings` destination, so returning it in `updated_permissions` writes the rule to `.claude/settings.local.json` and persists across sessions. |

1087 1089 

1088### `PermissionResult`1090### `PermissionResult`

1089 1091 

1289 1291 

1290### `McpServerStatusConfig`1292### `McpServerStatusConfig`

1291 1293 

1292The configuration of an MCP server as reported by [`get_mcp_status()`](#methods). This is the union of all [`McpServerConfig`](#mcp-server-config) transport variants plus an output-only `claudeai-proxy` variant for servers proxied through claude.ai.1294The configuration of an MCP server as reported by [`get_mcp_status()`](#methods). This is the union of all [`McpServerConfig`](#mcpserverconfig) transport variants plus an output-only `claudeai-proxy` variant for servers proxied through claude.ai.

1293 1295 

1294```python theme={null}1296```python theme={null}

1295McpServerStatusConfig = (1297McpServerStatusConfig = (

1301)1303)

1302```1304```

1303 1305 

1304`McpSdkServerConfigStatus` is the serializable form of [`McpSdkServerConfig`](#mcp-sdk-server-config) with only `type` (`"sdk"`) and `name` (`str`) fields; the in-process `instance` is omitted. `McpClaudeAIProxyServerConfig` has `type` (`"claudeai-proxy"`), `url` (`str`), and `id` (`str`) fields.1306`McpSdkServerConfigStatus` is the serializable form of [`McpSdkServerConfig`](#mcpsdkserverconfig) with only `type` (`"sdk"`) and `name` (`str`) fields; the in-process `instance` is omitted. `McpClaudeAIProxyServerConfig` has `type` (`"claudeai-proxy"`), `url` (`str`), and `id` (`str`) fields.

1305 1307 

1306### `McpStatusResponse`1308### `McpStatusResponse`

1307 1309 

1314 1316 

1315### `McpServerStatus`1317### `McpServerStatus`

1316 1318 

1317Status of a connected MCP server, contained in [`McpStatusResponse`](#mcp-status-response).1319Status of a connected MCP server, contained in [`McpStatusResponse`](#mcpstatusresponse).

1318 1320 

1319```python theme={null}1321```python theme={null}

1320class McpServerStatus(TypedDict):1322class McpServerStatus(TypedDict):

1328```1330```

1329 1331 

1330| Field | Type | Description |1332| Field | Type | Description |

1331| :----------- | :-------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |1333| :----------- | :----------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

1332| `name` | `str` | Server name |1334| `name` | `str` | Server name |

1333| `status` | `str` | One of `"connected"`, `"failed"`, `"needs-auth"`, `"pending"`, or `"disabled"` |1335| `status` | `str` | One of `"connected"`, `"failed"`, `"needs-auth"`, `"pending"`, or `"disabled"` |

1334| `serverInfo` | `dict` (optional) | Server name and version (`{"name": str, "version": str}`) |1336| `serverInfo` | `dict` (optional) | Server name and version (`{"name": str, "version": str}`) |

1335| `error` | `str` (optional) | Error message if the server failed to connect |1337| `error` | `str` (optional) | Error message if the server failed to connect |

1336| `config` | [`McpServerStatusConfig`](#mcp-server-status-config) (optional) | Server configuration. Same shape as [`McpServerConfig`](#mcp-server-config) (stdio, SSE, HTTP, or SDK), plus a `claudeai-proxy` variant for servers connected through claude.ai |1338| `config` | [`McpServerStatusConfig`](#mcpserverstatusconfig) (optional) | Server configuration. Same shape as [`McpServerConfig`](#mcpserverconfig) (stdio, SSE, HTTP, or SDK), plus a `claudeai-proxy` variant for servers connected through claude.ai |

1337| `scope` | `str` (optional) | Configuration scope |1339| `scope` | `str` (optional) | Configuration scope |

1338| `tools` | `list` (optional) | Tools provided by this server, each with `name`, `description`, and `annotations` fields |1340| `tools` | `list` (optional) | Tools provided by this server, each with `name`, `description`, and `annotations` fields |

1339 1341 

1416```1418```

1417 1419 

1418| Field | Type | Description |1420| Field | Type | Description |

1419| :------------------- | :------------------------------------------------------------- | :------------------------------------------------------------------------------ |1421| :------------------- | :----------------------------------------------------------- | :----------------------------------------------------------------------------- |

1420| `content` | `list[ContentBlock]` | List of content blocks in the response |1422| `content` | `list[ContentBlock]` | List of content blocks in the response |

1421| `model` | `str` | Model that generated the response |1423| `model` | `str` | Model that generated the response |

1422| `parent_tool_use_id` | `str \| None` | Tool use ID if this is a nested response |1424| `parent_tool_use_id` | `str \| None` | Tool use ID if this is a nested response |

1423| `error` | [`AssistantMessageError`](#assistant-message-error) ` \| None` | Error type if the response encountered an error |1425| `error` | [`AssistantMessageError`](#assistantmessageerror) ` \| None` | Error type if the response encountered an error |

1424| `usage` | `dict[str, Any] \| None` | Per-message token usage (same keys as [`ResultMessage.usage`](#result-message)) |1426| `usage` | `dict[str, Any] \| None` | Per-message token usage (same keys as [`ResultMessage.usage`](#resultmessage)) |

1425| `message_id` | `str \| None` | API message ID. Multiple messages from one turn share the same ID |1427| `message_id` | `str \| None` | API message ID. Multiple messages from one turn share the same ID |

1426 1428 

1427### `AssistantMessageError`1429### `AssistantMessageError`

1481| `cache_creation_input_tokens` | `int` | Tokens used to create new cache entries. |1483| `cache_creation_input_tokens` | `int` | Tokens used to create new cache entries. |

1482| `cache_read_input_tokens` | `int` | Tokens read from existing cache entries. |1484| `cache_read_input_tokens` | `int` | Tokens read from existing cache entries. |

1483 1485 

1484The `model_usage` dict maps model names to per-model usage. The inner dict keys use camelCase because the value is passed through unmodified from the underlying CLI process, matching the TypeScript [`ModelUsage`](/en/agent-sdk/typescript#model-usage) type:1486The `model_usage` dict maps model names to per-model usage. The inner dict keys use camelCase because the value is passed through unmodified from the underlying CLI process, matching the TypeScript [`ModelUsage`](/en/agent-sdk/typescript#modelusage) type:

1485 1487 

1486| Key | Type | Description |1488| Key | Type | Description |

1487| -------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------- |1489| -------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------- |

1527```1529```

1528 1530 

1529| Field | Type | Description |1531| Field | Type | Description |

1530| :---------------- | :---------------------------------- | :----------------------- |1532| :---------------- | :-------------------------------- | :----------------------- |

1531| `rate_limit_info` | [`RateLimitInfo`](#rate-limit-info) | Current rate limit state |1533| `rate_limit_info` | [`RateLimitInfo`](#ratelimitinfo) | Current rate limit state |

1532| `uuid` | `str` | Unique event identifier |1534| `uuid` | `str` | Unique event identifier |

1533| `session_id` | `str` | Session identifier |1535| `session_id` | `str` | Session identifier |

1534 1536 

1535### `RateLimitInfo`1537### `RateLimitInfo`

1536 1538 

1537Rate limit state carried by [`RateLimitEvent`](#rate-limit-event).1539Rate limit state carried by [`RateLimitEvent`](#ratelimitevent).

1538 1540 

1539```python theme={null}1541```python theme={null}

1540RateLimitStatus = Literal["allowed", "allowed_warning", "rejected"]1542RateLimitStatus = Literal["allowed", "allowed_warning", "rejected"]

1812 1814 

1813Parameters:1815Parameters:

1814 1816 

1815* `input`: Strongly-typed hook input with discriminated unions based on `hook_event_name` (see [`HookInput`](#hook-input))1817* `input`: Strongly-typed hook input with discriminated unions based on `hook_event_name` (see [`HookInput`](#hookinput))

1816* `tool_use_id`: Optional tool use identifier (for tool-related hooks)1818* `tool_use_id`: Optional tool use identifier (for tool-related hooks)

1817* `context`: Hook context with additional information1819* `context`: Hook context with additional information

1818 1820 

1819Returns a [`HookJSONOutput`](#hook-json-output) that may contain:1821Returns a [`HookJSONOutput`](#hookjsonoutput) that may contain:

1820 1822 

1821* `decision`: `"block"` to block the action1823* `decision`: `"block"` to block the action

1822* `systemMessage`: System message to add to the transcript1824* `systemMessage`: System message to add to the transcript

3109```3111```

3110 3112 

3111| Property | Type | Default | Description |3113| Property | Type | Default | Description |

3112| :-------------------------- | :------------------------------------------------------ | :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |3114| :-------------------------- | :---------------------------------------------------- | :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

3113| `enabled` | `bool` | `False` | Enable sandbox mode for command execution |3115| `enabled` | `bool` | `False` | Enable sandbox mode for command execution |

3114| `autoAllowBashIfSandboxed` | `bool` | `True` | Auto-approve bash commands when sandbox is enabled |3116| `autoAllowBashIfSandboxed` | `bool` | `True` | Auto-approve bash commands when sandbox is enabled |

3115| `excludedCommands` | `list[str]` | `[]` | Commands that always bypass sandbox restrictions (e.g., `["docker"]`). These run unsandboxed automatically without model involvement |3117| `excludedCommands` | `list[str]` | `[]` | Commands that always bypass sandbox restrictions (e.g., `["docker"]`). These run unsandboxed automatically without model involvement |

3116| `allowUnsandboxedCommands` | `bool` | `True` | Allow the model to request running commands outside the sandbox. When `True`, the model can set `dangerouslyDisableSandbox` in tool input, which falls back to the [permissions system](#permissions-fallback-for-unsandboxed-commands) |3118| `allowUnsandboxedCommands` | `bool` | `True` | Allow the model to request running commands outside the sandbox. When `True`, the model can set `dangerouslyDisableSandbox` in tool input, which falls back to the [permissions system](#permissions-fallback-for-unsandboxed-commands) |

3117| `network` | [`SandboxNetworkConfig`](#sandbox-network-config) | `None` | Network-specific sandbox configuration |3119| `network` | [`SandboxNetworkConfig`](#sandboxnetworkconfig) | `None` | Network-specific sandbox configuration |

3118| `ignoreViolations` | [`SandboxIgnoreViolations`](#sandbox-ignore-violations) | `None` | Configure which sandbox violations to ignore |3120| `ignoreViolations` | [`SandboxIgnoreViolations`](#sandboxignoreviolations) | `None` | Configure which sandbox violations to ignore |

3119| `enableWeakerNestedSandbox` | `bool` | `False` | Enable a weaker nested sandbox for compatibility |3121| `enableWeakerNestedSandbox` | `bool` | `False` | Enable a weaker nested sandbox for compatibility |

3120 3122 

3121#### Example usage3123#### Example usage

173 173 

1742. **`prompt`**: what you want Claude to do. Claude figures out which tools to use based on the task.1742. **`prompt`**: what you want Claude to do. Claude figures out which tools to use based on the task.

175 175 

1763. **`options`**: configuration for the agent. This example uses `allowedTools` to pre-approve `Read`, `Edit`, and `Glob`, and `permissionMode: "acceptEdits"` to auto-approve file changes. Other options include `systemPrompt`, `mcpServers`, and more. See all options for [Python](/en/agent-sdk/python#claude-agent-options) or [TypeScript](/en/agent-sdk/typescript#options).1763. **`options`**: configuration for the agent. This example uses `allowedTools` to pre-approve `Read`, `Edit`, and `Glob`, and `permissionMode: "acceptEdits"` to auto-approve file changes. Other options include `systemPrompt`, `mcpServers`, and more. See all options for [Python](/en/agent-sdk/python#claudeagentoptions) or [TypeScript](/en/agent-sdk/typescript#options).

177 177 

178The `async for` loop keeps running as Claude thinks, calls tools, observes results, and decides what to do next. Each iteration yields a message: Claude's reasoning, a tool call, a tool result, or the final outcome. The SDK handles the orchestration (tool execution, context management, retries) so you just consume the stream. The loop ends when Claude finishes the task or hits an error.178The `async for` loop keeps running as Claude thinks, calls tools, observes results, and decides what to do next. Each iteration yields a message: Claude's reasoning, a tool call, a tool result, or the final outcome. The SDK handles the orchestration (tool execution, context management, retries) so you just consume the stream. The loop ends when Claude finishes the task or hits an error.

179 179 

31 31 

32### Continue, resume, and fork32### Continue, resume, and fork

33 33 

34Continue, resume, and fork are option fields you set on `query()` ([`ClaudeAgentOptions`](/en/agent-sdk/python#claude-agent-options) in Python, [`Options`](/en/agent-sdk/typescript#options) in TypeScript).34Continue, resume, and fork are option fields you set on `query()` ([`ClaudeAgentOptions`](/en/agent-sdk/python#claudeagentoptions) in Python, [`Options`](/en/agent-sdk/typescript#options) in TypeScript).

35 35 

36**Continue** and **resume** both pick up an existing session and add to it. The difference is how they find that session:36**Continue** and **resume** both pick up an existing session and add to it. The difference is how they find that session:

37 37 

46 46 

47### Python: `ClaudeSDKClient`47### Python: `ClaudeSDKClient`

48 48 

49[`ClaudeSDKClient`](/en/agent-sdk/python#claude-sdk-client) handles session IDs internally. Each call to `client.query()` automatically continues the same session. Call [`client.receive_response()`](/en/agent-sdk/python#claude-sdk-client) to iterate over the messages for the current query. The client must be used as an async context manager.49[`ClaudeSDKClient`](/en/agent-sdk/python#claudesdkclient) handles session IDs internally. Each call to `client.query()` automatically continues the same session. Call [`client.receive_response()`](/en/agent-sdk/python#claudesdkclient) to iterate over the messages for the current query. The client must be used as an async context manager.

50 50 

51This example runs two queries against the same `client`. The first asks the agent to analyze a module; the second asks it to refactor that module. Because both calls go through the same client instance, the second query has full context from the first without any explicit `resume` or session ID:51This example runs two queries against the same `client`. The first asks the agent to analyze a module; the second asks it to refactor that module. Because both calls go through the same client instance, the second query has full context from the first without any explicit `resume` or session ID:

52 52 

96asyncio.run(main())96asyncio.run(main())

97```97```

98 98 

99See the [Python SDK reference](/en/agent-sdk/python#choosing-between-query-and-claude-sdk-client) for details on when to use `ClaudeSDKClient` vs the standalone `query()` function.99See the [Python SDK reference](/en/agent-sdk/python#choosing-between-query-and-claudesdkclient) for details on when to use `ClaudeSDKClient` vs the standalone `query()` function.

100 100 

101### TypeScript: `continue: true`101### TypeScript: `continue: true`

102 102 

139 139 

140### Capture the session ID140### Capture the session ID

141 141 

142Resume and fork require a session ID. Read it from the `session_id` field on the result message ([`ResultMessage`](/en/agent-sdk/python#result-message) in Python, [`SDKResultMessage`](/en/agent-sdk/typescript#sdk-result-message) in TypeScript), which is present on every result regardless of success or error. In TypeScript the ID is also available earlier as a direct field on the init `SystemMessage`; in Python it's nested inside `SystemMessage.data`.142Resume and fork require a session ID. Read it from the `session_id` field on the result message ([`ResultMessage`](/en/agent-sdk/python#resultmessage) in Python, [`SDKResultMessage`](/en/agent-sdk/typescript#sdkresultmessage) in TypeScript), which is present on every result regardless of success or error. In TypeScript the ID is also available earlier as a direct field on the init `SystemMessage`; in Python it's nested inside `SystemMessage.data`.

143 143 

144<CodeGroup>144<CodeGroup>

145 ```python Python theme={null}145 ```python Python theme={null}

312* **Move the session file.** Persist `~/.claude/projects/<encoded-cwd>/<session-id>.jsonl` from the first run and restore it to the same path on the new host before calling `resume`. The `cwd` must match.312* **Move the session file.** Persist `~/.claude/projects/<encoded-cwd>/<session-id>.jsonl` from the first run and restore it to the same path on the new host before calling `resume`. The `cwd` must match.

313* **Don't rely on session resume.** Capture the results you need (analysis output, decisions, file diffs) as application state and pass them into a fresh session's prompt. This is often more robust than shipping transcript files around.313* **Don't rely on session resume.** Capture the results you need (analysis output, decisions, file diffs) as application state and pass them into a fresh session's prompt. This is often more robust than shipping transcript files around.

314 314 

315Both SDKs expose functions for enumerating sessions on disk and reading their messages: [`listSessions()`](/en/agent-sdk/typescript#list-sessions) and [`getSessionMessages()`](/en/agent-sdk/typescript#get-session-messages) in TypeScript, [`list_sessions()`](/en/agent-sdk/python#list-sessions) and [`get_session_messages()`](/en/agent-sdk/python#get-session-messages) in Python. Use them to build custom session pickers, cleanup logic, or transcript viewers.315Both SDKs expose functions for enumerating sessions on disk and reading their messages: [`listSessions()`](/en/agent-sdk/typescript#listsessions) and [`getSessionMessages()`](/en/agent-sdk/typescript#getsessionmessages) in TypeScript, [`list_sessions()`](/en/agent-sdk/python#list_sessions) and [`get_session_messages()`](/en/agent-sdk/python#get_session_messages) in Python. Use them to build custom session pickers, cleanup logic, or transcript viewers.

316 316 

317Both SDKs also expose functions for looking up and mutating individual sessions: [`get_session_info()`](/en/agent-sdk/python#get-session-info), [`rename_session()`](/en/agent-sdk/python#rename-session), and [`tag_session()`](/en/agent-sdk/python#tag-session) in Python, and [`getSessionInfo()`](/en/agent-sdk/typescript#get-session-info), [`renameSession()`](/en/agent-sdk/typescript#rename-session), and [`tagSession()`](/en/agent-sdk/typescript#tag-session) in TypeScript. Use them to organize sessions by tag or give them human-readable titles.317Both SDKs also expose functions for looking up and mutating individual sessions: [`get_session_info()`](/en/agent-sdk/python#get_session_info), [`rename_session()`](/en/agent-sdk/python#rename_session), and [`tag_session()`](/en/agent-sdk/python#tag_session) in Python, and [`getSessionInfo()`](/en/agent-sdk/typescript#getsessioninfo), [`renameSession()`](/en/agent-sdk/typescript#renamesession), and [`tagSession()`](/en/agent-sdk/typescript#tagsession) in TypeScript. Use them to organize sessions by tag or give them human-readable titles.

318 318 

319## Related resources319## Related resources

320 320 

321* [How the agent loop works](/en/agent-sdk/agent-loop): Understand turns, messages, and context accumulation within a session321* [How the agent loop works](/en/agent-sdk/agent-loop): Understand turns, messages, and context accumulation within a session

322* [File checkpointing](/en/agent-sdk/file-checkpointing): Track and revert file changes across sessions322* [File checkpointing](/en/agent-sdk/file-checkpointing): Track and revert file changes across sessions

323* [Python `ClaudeAgentOptions`](/en/agent-sdk/python#claude-agent-options): Full session option reference for Python323* [Python `ClaudeAgentOptions`](/en/agent-sdk/python#claudeagentoptions): Full session option reference for Python

324* [TypeScript `Options`](/en/agent-sdk/typescript#options): Full session option reference for TypeScript324* [TypeScript `Options`](/en/agent-sdk/typescript#options): Full session option reference for TypeScript

233 ```233 ```

234</CodeGroup>234</CodeGroup>

235 235 

236For more details on `settingSources`/`setting_sources`, see the [TypeScript SDK reference](/en/agent-sdk/typescript#setting-source) or [Python SDK reference](/en/agent-sdk/python#setting-source).236For more details on `settingSources`/`setting_sources`, see the [TypeScript SDK reference](/en/agent-sdk/typescript#settingsource) or [Python SDK reference](/en/agent-sdk/python#settingsource).

237 237 

238**Check working directory**: The SDK loads Skills relative to the `cwd` option. Ensure it points to a directory containing `.claude/skills/`:238**Check working directory**: The SDK loads Skills relative to the `cwd` option. Ensure it points to a directory containing `.claude/skills/`:

239 239 

93 ```typescript TypeScript theme={null}93 ```typescript TypeScript theme={null}

94 type SDKPartialAssistantMessage = {94 type SDKPartialAssistantMessage = {

95 type: "stream_event";95 type: "stream_event";

96 event: RawMessageStreamEvent; // From Anthropic SDK96 event: BetaRawMessageStreamEvent; // From Anthropic SDK

97 parent_tool_use_id: string | null;97 parent_tool_use_id: string | null;

98 uuid: UUID;98 uuid: UUID;

99 session_id: string;99 session_id: string;

15 15 

16You can create subagents in three ways:16You can create subagents in three ways:

17 17 

18* **Programmatically**: use the `agents` parameter in your `query()` options ([TypeScript](/en/agent-sdk/typescript#agent-definition), [Python](/en/agent-sdk/python#agent-definition))18* **Programmatically**: use the `agents` parameter in your `query()` options ([TypeScript](/en/agent-sdk/typescript#agentdefinition), [Python](/en/agent-sdk/python#agentdefinition))

19* **Filesystem-based**: define agents as markdown files in `.claude/agents/` directories (see [defining subagents as files](/en/sub-agents))19* **Filesystem-based**: define agents as markdown files in `.claude/agents/` directories (see [defining subagents as files](/en/sub-agents))

20* **Built-in general-purpose**: Claude can invoke the built-in `general-purpose` subagent at any time via the Agent tool without you defining anything20* **Built-in general-purpose**: Claude can invoke the built-in `general-purpose` subagent at any time via the Agent tool without you defining anything

21 21 

174| `effort` | `'low' \| 'medium' \| 'high' \| 'xhigh' \| 'max' \| number` | No | Reasoning effort level for this agent |174| `effort` | `'low' \| 'medium' \| 'high' \| 'xhigh' \| 'max' \| number` | No | Reasoning effort level for this agent |

175| `permissionMode` | `PermissionMode` | No | Permission mode for tool execution within this agent |175| `permissionMode` | `PermissionMode` | No | Permission mode for tool execution within this agent |

176 176 

177In the Python SDK, these field names use camelCase to match the wire format. See the [`AgentDefinition` reference](/en/agent-sdk/python#agent-definition) for details.177In the Python SDK, these field names use camelCase to match the wire format. See the [`AgentDefinition` reference](/en/agent-sdk/python#agentdefinition) for details.

178 178 

179<Note>179<Note>

180 Subagents cannot spawn their own subagents. Don't include `Agent` in a subagent's `tools` array.180 Subagents cannot spawn their own subagents. Don't include `Agent` in a subagent's `tools` array.

57 ```57 ```

58 58 

59 ```python Python theme={null}59 ```python Python theme={null}

60 from claude_agent_sdk import query, AssistantMessage, ToolUseBlock60 from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ToolUseBlock

61 61 

62 async for message in query(62 async for message in query(

63 prompt="Optimize my React app performance and track progress with todos",63 prompt="Optimize my React app performance and track progress with todos",

64 options={"max_turns": 15},64 options=ClaudeAgentOptions(max_turns=15),

65 ):65 ):

66 # Todo updates are reflected in the message stream66 # Todo updates are reflected in the message stream

67 if isinstance(message, AssistantMessage):67 if isinstance(message, AssistantMessage):

132 ```132 ```

133 133 

134 ```python Python theme={null}134 ```python Python theme={null}

135 from claude_agent_sdk import query, AssistantMessage, ToolUseBlock135 from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ToolUseBlock

136 from typing import List, Dict136 from typing import List, Dict

137 137 

138 138 

167 print(f"{i + 1}. {icon} {text}")167 print(f"{i + 1}. {icon} {text}")

168 168 

169 async def track_query(self, prompt: str):169 async def track_query(self, prompt: str):

170 async for message in query(prompt=prompt, options={"max_turns": 20}):170 async for message in query(prompt=prompt, options=ClaudeAgentOptions(max_turns=20)):

171 if isinstance(message, AssistantMessage):171 if isinstance(message, AssistantMessage):

172 for block in message.content:172 for block in message.content:

173 if isinstance(block, ToolUseBlock) and block.name == "TodoWrite":173 if isinstance(block, ToolUseBlock) and block.name == "TodoWrite":

41#### Parameters41#### Parameters

42 42 

43| Parameter | Type | Description |43| Parameter | Type | Description |

44| :-------- | :---------------------------------------------------------------- | :---------------------------------------------------------------- |44| :-------- | :--------------------------------------------------------------- | :---------------------------------------------------------------- |

45| `prompt` | `string \| AsyncIterable<`[`SDKUserMessage`](#sdkuser-message)`>` | The input prompt as a string or async iterable for streaming mode |45| `prompt` | `string \| AsyncIterable<`[`SDKUserMessage`](#sdkusermessage)`>` | The input prompt as a string or async iterable for streaming mode |

46| `options` | [`Options`](#options) | Optional configuration object (see Options type below) |46| `options` | [`Options`](#options) | Optional configuration object (see Options type below) |

47 47 

48#### Returns48#### Returns

49 49 

50Returns a [`Query`](#query-object) object that extends `AsyncGenerator<`[`SDKMessage`](#sdk-message)`, void>` with additional methods.50Returns a [`Query`](#query-object) object that extends `AsyncGenerator<`[`SDKMessage`](#sdkmessage)`, void>` with additional methods.

51 51 

52### `startup()`52### `startup()`

53 53 

54Pre-warms the CLI subprocess by spawning it and completing the initialize handshake before a prompt is available. The returned [`WarmQuery`](#warm-query) handle accepts a prompt later and writes it to an already-ready process, so the first `query()` call resolves without paying subprocess spawn and initialization cost inline.54Pre-warms the CLI subprocess by spawning it and completing the initialize handshake before a prompt is available. The returned [`WarmQuery`](#warmquery) handle accepts a prompt later and writes it to an already-ready process, so the first `query()` call resolves without paying subprocess spawn and initialization cost inline.

55 55 

56```typescript theme={null}56```typescript theme={null}

57function startup(params?: {57function startup(params?: {

69 69 

70#### Returns70#### Returns

71 71 

72Returns a `Promise<`[`WarmQuery`](#warm-query)`>` that resolves once the subprocess has spawned and completed its initialize handshake.72Returns a `Promise<`[`WarmQuery`](#warmquery)`>` that resolves once the subprocess has spawned and completed its initialize handshake.

73 73 

74#### Example74#### Example

75 75 

104#### Parameters104#### Parameters

105 105 

106| Parameter | Type | Description |106| Parameter | Type | Description |

107| :------------ | :------------------------------------------------------------------ | :------------------------------------------------------------------------------ |107| :------------ | :---------------------------------------------------------------- | :------------------------------------------------------------------------------ |

108| `name` | `string` | The name of the tool |108| `name` | `string` | The name of the tool |

109| `description` | `string` | A description of what the tool does |109| `description` | `string` | A description of what the tool does |

110| `inputSchema` | `Schema extends AnyZodRawShape` | Zod schema defining the tool's input parameters (supports both Zod 3 and Zod 4) |110| `inputSchema` | `Schema extends AnyZodRawShape` | Zod schema defining the tool's input parameters (supports both Zod 3 and Zod 4) |

111| `handler` | `(args, extra) => Promise<`[`CallToolResult`](#call-tool-result)`>` | Async function that executes the tool logic |111| `handler` | `(args, extra) => Promise<`[`CallToolResult`](#calltoolresult)`>` | Async function that executes the tool logic |

112| `extras` | `{ annotations?: `[`ToolAnnotations`](#tool-annotations)` }` | Optional MCP tool annotations providing behavioral hints to clients |112| `extras` | `{ annotations?: `[`ToolAnnotations`](#toolannotations)` }` | Optional MCP tool annotations providing behavioral hints to clients |

113 113 

114#### `ToolAnnotations`114#### `ToolAnnotations`

115 115 

186| `firstPrompt` | `string \| undefined` | First meaningful user prompt in the session |186| `firstPrompt` | `string \| undefined` | First meaningful user prompt in the session |

187| `gitBranch` | `string \| undefined` | Git branch at the end of the session |187| `gitBranch` | `string \| undefined` | Git branch at the end of the session |

188| `cwd` | `string \| undefined` | Working directory for the session |188| `cwd` | `string \| undefined` | Working directory for the session |

189| `tag` | `string \| undefined` | User-set session tag (see [`tagSession()`](#tag-session)) |189| `tag` | `string \| undefined` | User-set session tag (see [`tagSession()`](#tagsession)) |

190| `createdAt` | `number \| undefined` | Creation time in milliseconds since epoch, from the first entry's timestamp |190| `createdAt` | `number \| undefined` | Creation time in milliseconds since epoch, from the first entry's timestamp |

191 191 

192#### Example192#### Example

270| `sessionId` | `string` | required | UUID of the session to look up |270| `sessionId` | `string` | required | UUID of the session to look up |

271| `options.dir` | `string` | `undefined` | Project directory path. When omitted, searches all project directories |271| `options.dir` | `string` | `undefined` | Project directory path. When omitted, searches all project directories |

272 272 

273Returns [`SDKSessionInfo`](#return-type-sdk-session-info), or `undefined` if the session is not found.273Returns [`SDKSessionInfo`](#return-type-sdksessioninfo), or `undefined` if the session is not found.

274 274 

275### `renameSession()`275### `renameSession()`

276 276 

323| `abortController` | `AbortController` | `new AbortController()` | Controller for cancelling operations |323| `abortController` | `AbortController` | `new AbortController()` | Controller for cancelling operations |

324| `additionalDirectories` | `string[]` | `[]` | Additional directories Claude can access |324| `additionalDirectories` | `string[]` | `[]` | Additional directories Claude can access |

325| `agent` | `string` | `undefined` | Agent name for the main thread. The agent must be defined in the `agents` option or in settings |325| `agent` | `string` | `undefined` | Agent name for the main thread. The agent must be defined in the `agents` option or in settings |

326| `agents` | `Record<string, [`AgentDefinition`](#agent-definition)>` | `undefined` | Programmatically define subagents |326| `agents` | `Record<string, [`AgentDefinition`](#agentdefinition)>` | `undefined` | Programmatically define subagents |

327| `allowDangerouslySkipPermissions` | `boolean` | `false` | Enable bypassing permissions. Required when using `permissionMode: 'bypassPermissions'` |327| `allowDangerouslySkipPermissions` | `boolean` | `false` | Enable bypassing permissions. Required when using `permissionMode: 'bypassPermissions'` |

328| `allowedTools` | `string[]` | `[]` | Tools to auto-approve without prompting. This does not restrict Claude to only these tools; unlisted tools fall through to `permissionMode` and `canUseTool`. Use `disallowedTools` to block tools. See [Permissions](/en/agent-sdk/permissions#allow-and-deny-rules) |328| `allowedTools` | `string[]` | `[]` | Tools to auto-approve without prompting. This does not restrict Claude to only these tools; unlisted tools fall through to `permissionMode` and `canUseTool`. Use `disallowedTools` to block tools. See [Permissions](/en/agent-sdk/permissions#allow-and-deny-rules) |

329| `betas` | [`SdkBeta`](#sdk-beta)`[]` | `[]` | Enable beta features |329| `betas` | [`SdkBeta`](#sdkbeta)`[]` | `[]` | Enable beta features |

330| `canUseTool` | [`CanUseTool`](#can-use-tool) | `undefined` | Custom permission function for tool usage |330| `canUseTool` | [`CanUseTool`](#canusetool) | `undefined` | Custom permission function for tool usage |

331| `continue` | `boolean` | `false` | Continue the most recent conversation |331| `continue` | `boolean` | `false` | Continue the most recent conversation |

332| `cwd` | `string` | `process.cwd()` | Current working directory |332| `cwd` | `string` | `process.cwd()` | Current working directory |

333| `debug` | `boolean` | `false` | Enable debug mode for the Claude Code process |333| `debug` | `boolean` | `false` | Enable debug mode for the Claude Code process |

341| `extraArgs` | `Record<string, string \| null>` | `{}` | Additional arguments |341| `extraArgs` | `Record<string, string \| null>` | `{}` | Additional arguments |

342| `fallbackModel` | `string` | `undefined` | Model to use if primary fails |342| `fallbackModel` | `string` | `undefined` | Model to use if primary fails |

343| `forkSession` | `boolean` | `false` | When resuming with `resume`, fork to a new session ID instead of continuing the original session |343| `forkSession` | `boolean` | `false` | When resuming with `resume`, fork to a new session ID instead of continuing the original session |

344| `hooks` | `Partial<Record<`[`HookEvent`](#hook-event)`, `[`HookCallbackMatcher`](#hook-callback-matcher)`[]>>` | `{}` | Hook callbacks for events |344| `hooks` | `Partial<Record<`[`HookEvent`](#hookevent)`, `[`HookCallbackMatcher`](#hookcallbackmatcher)`[]>>` | `{}` | Hook callbacks for events |

345| `includePartialMessages` | `boolean` | `false` | Include partial message events |345| `includePartialMessages` | `boolean` | `false` | Include partial message events |

346| `maxBudgetUsd` | `number` | `undefined` | Stop the query when the client-side cost estimate reaches this USD value. Compared against the same estimate as `total_cost_usd`; see [Track cost and usage](/en/agent-sdk/cost-tracking) for accuracy caveats |346| `maxBudgetUsd` | `number` | `undefined` | Stop the query when the client-side cost estimate reaches this USD value. Compared against the same estimate as `total_cost_usd`; see [Track cost and usage](/en/agent-sdk/cost-tracking) for accuracy caveats |

347| `maxThinkingTokens` | `number` | `undefined` | *Deprecated:* Use `thinking` instead. Maximum tokens for thinking process |347| `maxThinkingTokens` | `number` | `undefined` | *Deprecated:* Use `thinking` instead. Maximum tokens for thinking process |

348| `maxTurns` | `number` | `undefined` | Maximum agentic turns (tool-use round trips) |348| `maxTurns` | `number` | `undefined` | Maximum agentic turns (tool-use round trips) |

349| `mcpServers` | `Record<string, [`McpServerConfig`](#mcp-server-config)>` | `{}` | MCP server configurations |349| `mcpServers` | `Record<string, [`McpServerConfig`](#mcpserverconfig)>` | `{}` | MCP server configurations |

350| `model` | `string` | Default from CLI | Claude model to use |350| `model` | `string` | Default from CLI | Claude model to use |

351| `outputFormat` | `{ type: 'json_schema', schema: JSONSchema }` | `undefined` | Define output format for agent results. See [Structured outputs](/en/agent-sdk/structured-outputs) for details |351| `outputFormat` | `{ type: 'json_schema', schema: JSONSchema }` | `undefined` | Define output format for agent results. See [Structured outputs](/en/agent-sdk/structured-outputs) for details |

352| `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 |352| `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 |

353| `permissionMode` | [`PermissionMode`](#permission-mode) | `'default'` | Permission mode for the session |353| `permissionMode` | [`PermissionMode`](#permissionmode) | `'default'` | Permission mode for the session |

354| `permissionPromptToolName` | `string` | `undefined` | MCP tool name for permission prompts |354| `permissionPromptToolName` | `string` | `undefined` | MCP tool name for permission prompts |

355| `persistSession` | `boolean` | `true` | When `false`, disables session persistence to disk. Sessions cannot be resumed later |355| `persistSession` | `boolean` | `true` | When `false`, disables session persistence to disk. Sessions cannot be resumed later |

356| `plugins` | [`SdkPluginConfig`](#sdk-plugin-config)`[]` | `[]` | Load custom plugins from local paths. See [Plugins](/en/agent-sdk/plugins) for details |356| `plugins` | [`SdkPluginConfig`](#sdkpluginconfig)`[]` | `[]` | Load custom plugins from local paths. See [Plugins](/en/agent-sdk/plugins) for details |

357| `promptSuggestions` | `boolean` | `false` | Enable prompt suggestions. Emits a `prompt_suggestion` message after each turn with a predicted next user prompt |357| `promptSuggestions` | `boolean` | `false` | Enable prompt suggestions. Emits a `prompt_suggestion` message after each turn with a predicted next user prompt |

358| `resume` | `string` | `undefined` | Session ID to resume |358| `resume` | `string` | `undefined` | Session ID to resume |

359| `resumeSessionAt` | `string` | `undefined` | Resume session at a specific message UUID |359| `resumeSessionAt` | `string` | `undefined` | Resume session at a specific message UUID |

360| `sandbox` | [`SandboxSettings`](#sandbox-settings) | `undefined` | Configure sandbox behavior programmatically. See [Sandbox settings](#sandbox-settings) for details |360| `sandbox` | [`SandboxSettings`](#sandboxsettings) | `undefined` | Configure sandbox behavior programmatically. See [Sandbox settings](#sandboxsettings) for details |

361| `sessionId` | `string` | Auto-generated | Use a specific UUID for the session instead of auto-generating one |361| `sessionId` | `string` | Auto-generated | Use a specific UUID for the session instead of auto-generating one |

362| `sessionStore` | [`SessionStore`](/en/agent-sdk/session-storage#the-session-store-interface) | `undefined` | Mirror session transcripts to an external backend so any host can resume them. See [Persist sessions to external storage](/en/agent-sdk/session-storage) |362| `sessionStore` | [`SessionStore`](/en/agent-sdk/session-storage#the-sessionstore-interface) | `undefined` | Mirror session transcripts to an external backend so any host can resume them. See [Persist sessions to external storage](/en/agent-sdk/session-storage) |

363| `settingSources` | [`SettingSource`](#setting-source)`[]` | CLI defaults (all sources) | Control which filesystem settings to load. Pass `[]` to disable user, project, and local settings. Managed policy settings load regardless. See [Use Claude Code features](/en/agent-sdk/claude-code-features#what-settingsources-does-not-control) |363| `settingSources` | [`SettingSource`](#settingsource)`[]` | CLI defaults (all sources) | Control which filesystem settings to load. Pass `[]` to disable user, project, and local settings. Managed policy settings load regardless. See [Use Claude Code features](/en/agent-sdk/claude-code-features#what-settingsources-does-not-control) |

364| `spawnClaudeCodeProcess` | `(options: SpawnOptions) => SpawnedProcess` | `undefined` | Custom function to spawn the Claude Code process. Use to run Claude Code in VMs, containers, or remote environments |364| `spawnClaudeCodeProcess` | `(options: SpawnOptions) => SpawnedProcess` | `undefined` | Custom function to spawn the Claude Code process. Use to run Claude Code in VMs, containers, or remote environments |

365| `stderr` | `(data: string) => void` | `undefined` | Callback for stderr output |365| `stderr` | `(data: string) => void` | `undefined` | Callback for stderr output |

366| `strictMcpConfig` | `boolean` | `false` | Enforce strict MCP validation |366| `strictMcpConfig` | `boolean` | `false` | Enforce strict MCP validation |

367| `systemPrompt` | `string \| { type: 'preset'; preset: 'claude_code'; append?: string; excludeDynamicSections?: boolean }` | `undefined` (minimal prompt) | System prompt configuration. Pass a string for custom prompt, or `{ type: 'preset', preset: 'claude_code' }` to use Claude Code's system prompt. When using the preset object form, add `append` to extend it with additional instructions, and set `excludeDynamicSections: true` to move per-session context into the first user message for [better prompt-cache reuse across machines](/en/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines) |367| `systemPrompt` | `string \| { type: 'preset'; preset: 'claude_code'; append?: string; excludeDynamicSections?: boolean }` | `undefined` (minimal prompt) | System prompt configuration. Pass a string for custom prompt, or `{ type: 'preset', preset: 'claude_code' }` to use Claude Code's system prompt. When using the preset object form, add `append` to extend it with additional instructions, and set `excludeDynamicSections: true` to move per-session context into the first user message for [better prompt-cache reuse across machines](/en/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines) |

368| `thinking` | [`ThinkingConfig`](#thinking-config) | `{ type: 'adaptive' }` for supported models | Controls Claude's thinking/reasoning behavior. See [`ThinkingConfig`](#thinking-config) for options |368| `thinking` | [`ThinkingConfig`](#thinkingconfig) | `{ type: 'adaptive' }` for supported models | Controls Claude's thinking/reasoning behavior. See [`ThinkingConfig`](#thinkingconfig) for options |

369| `toolConfig` | [`ToolConfig`](#tool-config) | `undefined` | Configuration for built-in tool behavior. See [`ToolConfig`](#tool-config) for details |369| `toolConfig` | [`ToolConfig`](#toolconfig) | `undefined` | Configuration for built-in tool behavior. See [`ToolConfig`](#toolconfig) for details |

370| `tools` | `string[] \| { type: 'preset'; preset: 'claude_code' }` | `undefined` | Tool configuration. Pass an array of tool names or use the preset to get Claude Code's default tools |370| `tools` | `string[] \| { type: 'preset'; preset: 'claude_code' }` | `undefined` | Tool configuration. Pass an array of tool names or use the preset to get Claude Code's default tools |

371 371 

372### `Query` object372### `Query` object

410| `initializationResult()` | Returns the full initialization result including supported commands, models, account info, and output style configuration |410| `initializationResult()` | Returns the full initialization result including supported commands, models, account info, and output style configuration |

411| `supportedCommands()` | Returns available slash commands |411| `supportedCommands()` | Returns available slash commands |

412| `supportedModels()` | Returns available models with display info |412| `supportedModels()` | Returns available models with display info |

413| `supportedAgents()` | Returns available subagents as [`AgentInfo`](#agent-info)`[]` |413| `supportedAgents()` | Returns available subagents as [`AgentInfo`](#agentinfo)`[]` |

414| `mcpServerStatus()` | Returns status of connected MCP servers |414| `mcpServerStatus()` | Returns status of connected MCP servers |

415| `accountInfo()` | Returns account information |415| `accountInfo()` | Returns account information |

416| `reconnectMcpServer(serverName)` | Reconnect an MCP server by name |416| `reconnectMcpServer(serverName)` | Reconnect an MCP server by name |

493| `background` | No | Run this agent as a non-blocking background task when invoked |493| `background` | No | Run this agent as a non-blocking background task when invoked |

494| `memory` | No | Memory source for this agent: `'user'`, `'project'`, or `'local'` |494| `memory` | No | Memory source for this agent: `'user'`, `'project'`, or `'local'` |

495| `effort` | No | Reasoning effort level for this agent. Accepts a named level or an integer |495| `effort` | No | Reasoning effort level for this agent. Accepts a named level or an integer |

496| `permissionMode` | No | Permission mode for tool execution within this agent. See [`PermissionMode`](#permission-mode) |496| `permissionMode` | No | Permission mode for tool execution within this agent. See [`PermissionMode`](#permissionmode) |

497| `criticalSystemReminder_EXPERIMENTAL` | No | Experimental: Critical reminder added to the system prompt |497| `criticalSystemReminder_EXPERIMENTAL` | No | Experimental: Critical reminder added to the system prompt |

498 498 

499### `AgentMcpServerSpec`499### `AgentMcpServerSpec`

626 | "default" // Standard permission behavior626 | "default" // Standard permission behavior

627 | "acceptEdits" // Auto-accept file edits627 | "acceptEdits" // Auto-accept file edits

628 | "bypassPermissions" // Bypass all permission checks628 | "bypassPermissions" // Bypass all permission checks

629 | "plan" // Planning mode - no execution629 | "plan" // Planning mode - read-only tools only

630 | "dontAsk" // Don't prompt for permissions, deny if not pre-approved630 | "dontAsk" // Don't prompt for permissions, deny if not pre-approved

631 | "auto"; // Use a model classifier to approve or deny each tool call631 | "auto"; // Use a model classifier to approve or deny each tool call

632```632```

651```651```

652 652 

653| Option | Type | Description |653| Option | Type | Description |

654| :--------------- | :------------------------------------------- | :--------------------------------------------------------------------------- |654| :--------------- | :------------------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

655| `signal` | `AbortSignal` | Signaled if the operation should be aborted |655| `signal` | `AbortSignal` | Signaled if the operation should be aborted |

656| `suggestions` | [`PermissionUpdate`](#permission-update)`[]` | Suggested permission updates so the user is not prompted again for this tool |656| `suggestions` | [`PermissionUpdate`](#permissionupdate)`[]` | Suggested permission updates so the user is not prompted again for this tool. Bash prompts include a suggestion with the `localSettings` [destination](#permissionupdatedestination), so returning it in `updatedPermissions` writes the rule to `.claude/settings.local.json` and persists across sessions. |

657| `blockedPath` | `string` | The file path that triggered the permission request, if applicable |657| `blockedPath` | `string` | The file path that triggered the permission request, if applicable |

658| `decisionReason` | `string` | Explains why this permission request was triggered |658| `decisionReason` | `string` | Explains why this permission request was triggered |

659| `toolUseID` | `string` | Unique identifier for this specific tool call within the assistant message |659| `toolUseID` | `string` | Unique identifier for this specific tool call within the assistant message |

2379 | McpClaudeAIProxyServerConfig;2379 | McpClaudeAIProxyServerConfig;

2380```2380```

2381 2381 

2382See [`McpServerConfig`](#mcp-server-config) for details on each transport type.2382See [`McpServerConfig`](#mcpserverconfig) for details on each transport type.

2383 2383 

2384### `AccountInfo`2384### `AccountInfo`

2385 2385 

2825```2825```

2826 2826 

2827| Property | Type | Default | Description |2827| Property | Type | Default | Description |

2828| :-------------------------- | :------------------------------------------------------ | :---------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |2828| :-------------------------- | :---------------------------------------------------- | :---------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

2829| `enabled` | `boolean` | `false` | Enable sandbox mode for command execution |2829| `enabled` | `boolean` | `false` | Enable sandbox mode for command execution |

2830| `autoAllowBashIfSandboxed` | `boolean` | `true` | Auto-approve bash commands when sandbox is enabled |2830| `autoAllowBashIfSandboxed` | `boolean` | `true` | Auto-approve bash commands when sandbox is enabled |

2831| `excludedCommands` | `string[]` | `[]` | Commands that always bypass sandbox restrictions (e.g., `['docker']`). These run unsandboxed automatically without model involvement |2831| `excludedCommands` | `string[]` | `[]` | Commands that always bypass sandbox restrictions (e.g., `['docker']`). These run unsandboxed automatically without model involvement |

2832| `allowUnsandboxedCommands` | `boolean` | `true` | Allow the model to request running commands outside the sandbox. When `true`, the model can set `dangerouslyDisableSandbox` in tool input, which falls back to the [permissions system](#permissions-fallback-for-unsandboxed-commands) |2832| `allowUnsandboxedCommands` | `boolean` | `true` | Allow the model to request running commands outside the sandbox. When `true`, the model can set `dangerouslyDisableSandbox` in tool input, which falls back to the [permissions system](#permissions-fallback-for-unsandboxed-commands) |

2833| `network` | [`SandboxNetworkConfig`](#sandbox-network-config) | `undefined` | Network-specific sandbox configuration |2833| `network` | [`SandboxNetworkConfig`](#sandboxnetworkconfig) | `undefined` | Network-specific sandbox configuration |

2834| `filesystem` | [`SandboxFilesystemConfig`](#sandbox-filesystem-config) | `undefined` | Filesystem-specific sandbox configuration for read/write restrictions |2834| `filesystem` | [`SandboxFilesystemConfig`](#sandboxfilesystemconfig) | `undefined` | Filesystem-specific sandbox configuration for read/write restrictions |

2835| `ignoreViolations` | `Record<string, string[]>` | `undefined` | Map of violation categories to patterns to ignore (e.g., `{ file: ['/tmp/*'], network: ['localhost'] }`) |2835| `ignoreViolations` | `Record<string, string[]>` | `undefined` | Map of violation categories to patterns to ignore (e.g., `{ file: ['/tmp/*'], network: ['localhost'] }`) |

2836| `enableWeakerNestedSandbox` | `boolean` | `false` | Enable a weaker nested sandbox for compatibility |2836| `enableWeakerNestedSandbox` | `boolean` | `false` | Enable a weaker nested sandbox for compatibility |

2837| `ripgrep` | `{ command: string; args?: string[] }` | `undefined` | Custom ripgrep binary configuration for sandbox environments |2837| `ripgrep` | `{ command: string; args?: string[] }` | `undefined` | Custom ripgrep binary configuration for sandbox environments |

54Once you've passed a `canUseTool` callback in your query options, it fires when Claude wants to use a tool that isn't auto-approved. Your callback receives three arguments:54Once you've passed a `canUseTool` callback in your query options, it fires when Claude wants to use a tool that isn't auto-approved. Your callback receives three arguments:

55 55 

56| Argument | Description |56| Argument | Description |

57| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |57| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

58| `toolName` | The name of the tool Claude wants to use (e.g., `"Bash"`, `"Write"`, `"Edit"`) |58| `toolName` | The name of the tool Claude wants to use (e.g., `"Bash"`, `"Write"`, `"Edit"`) |

59| `input` | The parameters Claude is passing to the tool. Contents vary by tool. |59| `input` | The parameters Claude is passing to the tool. Contents vary by tool. |

60| `options` (TS) / `context` (Python) | Additional context including optional `suggestions` (proposed `PermissionUpdate` entries to avoid re-prompting) and a cancellation signal. In TypeScript, `signal` is an `AbortSignal`; in Python, the signal field is reserved for future use. See [`ToolPermissionContext`](/en/agent-sdk/python#tool-permission-context) for Python. |60| `options` (TS) / `context` (Python) | Additional context including optional `suggestions` (proposed `PermissionUpdate` entries to avoid re-prompting) and a cancellation signal. In TypeScript, `signal` is an `AbortSignal`; in Python, the signal field is reserved for future use. See [`ToolPermissionContext`](/en/agent-sdk/python#toolpermissioncontext) for Python. |

61 61 

62The `input` object contains tool-specific parameters. Common examples:62The `input` object contains tool-specific parameters. Common examples:

63 63 

68| `Edit` | `file_path`, `old_string`, `new_string` |68| `Edit` | `file_path`, `old_string`, `new_string` |

69| `Read` | `file_path`, `offset`, `limit` |69| `Read` | `file_path`, `offset`, `limit` |

70 70 

71See the SDK reference for complete input schemas: [Python](/en/agent-sdk/python#tool-input-output-types) | [TypeScript](/en/agent-sdk/typescript#tool-input-types).71See the SDK reference for complete input schemas: [Python](/en/agent-sdk/python#tool-input%2Foutput-types) | [TypeScript](/en/agent-sdk/typescript#tool-input-types).

72 72 

73You can display this information to the user so they can decide whether to allow or reject the action, then return the appropriate response.73You can display this information to the user so they can decide whether to allow or reject the action, then return the appropriate response.

74 74 

807 807 

808* [Configure permissions](/en/agent-sdk/permissions): set up permission modes and rules808* [Configure permissions](/en/agent-sdk/permissions): set up permission modes and rules

809* [Control execution with hooks](/en/agent-sdk/hooks): run custom code at key points in the agent lifecycle809* [Control execution with hooks](/en/agent-sdk/hooks): run custom code at key points in the agent lifecycle

810* [TypeScript SDK reference](/en/agent-sdk/typescript#can-use-tool): full canUseTool API documentation810* [TypeScript SDK reference](/en/agent-sdk/typescript#canusetool): full canUseTool API documentation

113 113 

114Claude Code securely manages your authentication credentials:114Claude Code securely manages your authentication credentials:

115 115 

116* **Storage location**: on macOS, credentials are stored in the encrypted macOS Keychain. On Linux and Windows, credentials are stored in `~/.claude/.credentials.json`, or under `$CLAUDE_CONFIG_DIR` if that variable is set. On Linux, the file is written with mode `0600`; on Windows, it inherits the access controls of your user profile directory.116* **Storage location**:

117 * On macOS, credentials are stored in the encrypted macOS Keychain.

118 * On Linux, credentials are stored in `~/.claude/.credentials.json` with file mode `0600`.

119 * On Windows, credentials are stored in `%USERPROFILE%\.claude\.credentials.json` and inherit the access controls of your user profile directory, which restricts the file to your user account by default.

120 * If you've set the `CLAUDE_CONFIG_DIR` environment variable on Linux or Windows, the `.credentials.json` file lives under that directory instead.

117* **Supported authentication types**: Claude.ai credentials, Claude API credentials, Azure Auth, Bedrock Auth, and Vertex Auth.121* **Supported authentication types**: Claude.ai credentials, Claude API credentials, Azure Auth, Bedrock Auth, and Vertex Auth.

118* **Custom credential scripts**: the [`apiKeyHelper`](/en/settings#available-settings) setting can be configured to run a shell script that returns an API key.122* **Custom credential scripts**: the [`apiKeyHelper`](/en/settings#available-settings) setting can be configured to run a shell script that returns an API key.

119* **Refresh intervals**: by default, `apiKeyHelper` is called after 5 minutes or on HTTP 401 response. Set `CLAUDE_CODE_API_KEY_HELPER_TTL_MS` environment variable for custom refresh intervals.123* **Refresh intervals**: by default, `apiKeyHelper` is called after 5 minutes or on HTTP 401 response. Set `CLAUDE_CODE_API_KEY_HELPER_TTL_MS` environment variable for custom refresh intervals.

7> Use channels to push messages, alerts, and webhooks into your Claude Code session from an MCP server. Forward CI results, chat messages, and monitoring events so Claude can react while you're away.7> Use channels to push messages, alerts, and webhooks into your Claude Code session from an MCP server. Forward CI results, chat messages, and monitoring events so Claude can react while you're away.

8 8 

9<Note>9<Note>

10 Channels are in [research preview](#research-preview) and require Claude Code v2.1.80 or later. They require claude.ai login. Console and API key authentication is not supported. Team and Enterprise organizations must [explicitly enable them](#enterprise-controls).10 Channels are in [research preview](#research-preview) and require Claude Code v2.1.80 or later. They require Anthropic authentication through claude.ai or a Console API key, and are not available on Amazon Bedrock, Google Vertex AI, or Microsoft Foundry. Team and Enterprise organizations must [explicitly enable them](#enterprise-controls).

11</Note>11</Note>

12 12 

13A channel is an MCP server that pushes events into your running Claude Code session, so Claude can react to things that happen while you're not at the terminal. Channels can be two-way: Claude reads the event and replies back through the same channel, like a chat bridge. Events only arrive while the session is open, so for an always-on setup you run Claude in a background process or persistent terminal.13A channel is an MCP server that pushes events into your running Claude Code session, so Claude can react to things that happen while you're not at the terminal. Channels can be two-way: Claude reads the event and replies back through the same channel, like a chat bridge. Events only arrive while the session is open, so for an always-on setup you run Claude in a background process or persistent terminal.

23* [Supported channels](#supported-channels): Telegram, Discord, and iMessage setup23* [Supported channels](#supported-channels): Telegram, Discord, and iMessage setup

24* [Install and run a channel](#quickstart) with fakechat, a localhost demo24* [Install and run a channel](#quickstart) with fakechat, a localhost demo

25* [Who can push messages](#security): sender allowlists and how you pair25* [Who can push messages](#security): sender allowlists and how you pair

26* [Enable channels for your organization](#enterprise-controls) on Team and Enterprise26* [Enable channels for your organization](#enterprise-controls) if you manage a Team, Enterprise, or Console org

27* [How channels compare](#how-channels-compare) to web sessions, Slack, MCP, and Remote Control27* [How channels compare](#how-channels-compare) to web sessions, Slack, MCP, and Remote Control

28 28 

29To build your own channel, see the [Channels reference](/en/channels-reference).29To build your own channel, see the [Channels reference](/en/channels-reference).

225 225 

226To try the fakechat demo, you'll need:226To try the fakechat demo, you'll need:

227 227 

228* Claude Code [installed and authenticated](/en/quickstart#step-1-install-claude-code) with a claude.ai account228* Claude Code [installed and authenticated](/en/quickstart#step-1-install-claude-code) with a claude.ai account or a Claude Console API key

229* [Bun](https://bun.sh) installed. The pre-built channel plugins are Bun scripts. Check with `bun --version`; if that fails, [install Bun](https://bun.sh/docs/installation).229* [Bun](https://bun.sh) installed. The pre-built channel plugins are Bun scripts. Check with `bun --version`; if that fails, [install Bun](https://bun.sh/docs/installation).

230* **Team/Enterprise users**: your organization admin must [enable channels](#enterprise-controls) in managed settings230* **Team, Enterprise, or managed Console org**: your admin must [enable channels](#enterprise-controls) in managed settings

231 231 

232<Steps>232<Steps>

233 <Step title="Install the fakechat channel plugin">233 <Step title="Install the fakechat channel plugin">

280 280 

281iMessage works differently: texting yourself bypasses the gate automatically, and you add other contacts by handle with `/imessage:access allow`.281iMessage works differently: texting yourself bypasses the gate automatically, and you add other contacts by handle with `/imessage:access allow`.

282 282 

283On top of that, you control which servers are enabled each session with `--channels`, and on Team and Enterprise plans your organization controls availability with [`channelsEnabled`](#enterprise-controls).283On top of that, you control which servers are enabled each session with `--channels`, and your organization controls availability with [`channelsEnabled`](#enterprise-controls) on claude.ai Team and Enterprise plans and on Console organizations that deploy managed settings.

284 284 

285Being in `.mcp.json` isn't enough to push messages: a server also has to be named in `--channels`.285Being in `.mcp.json` isn't enough to push messages: a server also has to be named in `--channels`.

286 286 

288 288 

289## Enterprise controls289## Enterprise controls

290 290 

291On Team and Enterprise plans, channels are off by default. Admins control availability through two [managed settings](/en/settings) that users cannot override:291Admins control availability through two [managed settings](/en/settings) that users cannot override. The default depends on how you authenticate:

292 

293* **claude.ai Team and Enterprise**: channels are blocked until an admin enables them.

294* **Anthropic Console with API key authentication**: channels are permitted by default. You only need this setting if your organization deploys managed settings.

295 

296In all cases, no channel runs until a user opts it in for the session with `--channels`.

292 297 

293| Setting | Purpose | When not configured |298| Setting | Purpose | When not configured |

294| :---------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------- |299| :---------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

295| `channelsEnabled` | Master switch. Must be `true` for any channel to deliver messages. Set via the [claude.ai Admin console](https://claude.ai/admin-settings/claude-code) toggle or directly in managed settings. Blocks all channels including the development flag when off. | Channels blocked |300| `channelsEnabled` | Master switch. Must be `true` for any channel to deliver messages. Set via the [claude.ai Admin console](https://claude.ai/admin-settings/claude-code) toggle or directly in managed settings. Blocks all channels including the development flag when off. | claude.ai Team and Enterprise: channels blocked. Console: channels allowed unless your organization deploys managed settings, in which case channels are blocked until this key is set |

296| `allowedChannelPlugins` | Which plugins can register once channels are enabled. Replaces the Anthropic-maintained list when set. Only applies when `channelsEnabled` is `true`. | Anthropic default list applies |301| `allowedChannelPlugins` | Which plugins can register once channels are enabled. Replaces the Anthropic-maintained list when set. Only applies when `channelsEnabled` is `true`. | Anthropic default list applies |

297 302 

298Pro and Max users without an organization skip these checks entirely: channels are available and users opt in per session with `--channels`.303Pro and Max users without an organization skip these checks entirely: channels are available and users opt in per session with `--channels`.

7> Build an MCP server that pushes webhooks, alerts, and chat messages into a Claude Code session. Reference for the channel contract: capability declaration, notification events, reply tools, sender gating, and permission relay.7> Build an MCP server that pushes webhooks, alerts, and chat messages into a Claude Code session. Reference for the channel contract: capability declaration, notification events, reply tools, sender gating, and permission relay.

8 8 

9<Note>9<Note>

10 Channels are in [research preview](/en/channels#research-preview) and require Claude Code v2.1.80 or later. They require claude.ai login. Console and API key authentication is not supported. Team and Enterprise organizations must [explicitly enable them](/en/channels#enterprise-controls).10 Channels are in [research preview](/en/channels#research-preview) and require Claude Code v2.1.80 or later. Team and Enterprise organizations must [explicitly enable them](/en/channels#enterprise-controls).

11</Note>11</Note>

12 12 

13A channel is an MCP server that pushes events into a Claude Code session so Claude can react to things happening outside the terminal.13A channel is an MCP server that pushes events into a Claude Code session so Claude can react to things happening outside the terminal.

138 138 

139 When Claude Code starts, it reads your MCP config, spawns your `webhook.ts` as a subprocess, and the HTTP listener starts automatically on the port you configured (8788 in this example). You don't need to run the server yourself.139 When Claude Code starts, it reads your MCP config, spawns your `webhook.ts` as a subprocess, and the HTTP listener starts automatically on the port you configured (8788 in this example). You don't need to run the server yourself.

140 140 

141 If you see "blocked by org policy," your Team or Enterprise admin needs to [enable channels](/en/channels#enterprise-controls) first.141 If you see "blocked by org policy," your organization admin needs to [enable channels](/en/channels#enterprise-controls) first.

142 142 

143 In a separate terminal, simulate a webhook by sending an HTTP POST with a message to your server. This example sends a CI failure alert to port 8788 (or whichever port you configured):143 In a separate terminal, simulate a webhook by sending an HTTP POST with a message to your server. This example sends a CI failure alert to port 8788 (or whichever port you configured):

144 144 

185 185 

186If the script exits non-zero, the session fails to start. Append `|| true` to non-critical commands to avoid blocking the session on an intermittent install failure.186If the script exits non-zero, the session fails to start. Append `|| true` to non-critical commands to avoid blocking the session on an intermittent install failure.

187 187 

188Keep the script's total runtime under roughly five minutes so the [environment cache](#environment-caching) can build. Run independent installs in parallel with `&` and `wait`. If a single download won't fit in the five-minute limit, move it to a [SessionStart hook](#setup-scripts-vs-sessionstart-hooks) that launches it in the background.

189 

188<Note>190<Note>

189 Setup scripts that install packages need network access to reach registries. The default **Trusted** network access allows connections to [common package registries](#default-allowed-domains) including npm, PyPI, RubyGems, and crates.io. Scripts will fail to install packages if your environment uses **None** network access.191 Setup scripts that install packages need network access to reach registries. The default **Trusted** network access allows connections to [common package registries](#default-allowed-domains) including npm, PyPI, RubyGems, and crates.io. Scripts will fail to install packages if your environment uses **None** network access.

190</Note>192</Note>

83| `--output-format` | Specify output format for print mode (options: `text`, `json`, `stream-json`) | `claude -p "query" --output-format json` |83| `--output-format` | Specify output format for print mode (options: `text`, `json`, `stream-json`) | `claude -p "query" --output-format json` |

84| `--permission-mode` | Begin in a specified [permission mode](/en/permission-modes). Accepts `default`, `acceptEdits`, `plan`, `auto`, `dontAsk`, or `bypassPermissions`. Overrides `defaultMode` from settings files | `claude --permission-mode plan` |84| `--permission-mode` | Begin in a specified [permission mode](/en/permission-modes). Accepts `default`, `acceptEdits`, `plan`, `auto`, `dontAsk`, or `bypassPermissions`. Overrides `defaultMode` from settings files | `claude --permission-mode plan` |

85| `--permission-prompt-tool` | Specify an MCP tool to handle permission prompts in non-interactive mode | `claude -p --permission-prompt-tool mcp_auth_tool "query"` |85| `--permission-prompt-tool` | Specify an MCP tool to handle permission prompts in non-interactive mode | `claude -p --permission-prompt-tool mcp_auth_tool "query"` |

86| `--plugin-dir` | Load plugins from a directory for this session only. Each flag takes one path. Repeat the flag for multiple directories: `--plugin-dir A --plugin-dir B` | `claude --plugin-dir ./my-plugins` |86| `--plugin-dir` | Load a plugin from a directory or `.zip` archive for this session only. Each flag takes one path. Repeat the flag for multiple plugins: `--plugin-dir A --plugin-dir B.zip` | `claude --plugin-dir ./my-plugin` |

87| `--print`, `-p` | Print response without interactive mode (see [Agent SDK documentation](/en/agent-sdk/overview) for programmatic usage details) | `claude -p "query"` |87| `--print`, `-p` | Print response without interactive mode (see [Agent SDK documentation](/en/agent-sdk/overview) for programmatic usage details) | `claude -p "query"` |

88| `--remote` | Create a new [web session](/en/claude-code-on-the-web) on claude.ai with the provided task description | `claude --remote "Fix the login bug"` |88| `--remote` | Create a new [web session](/en/claude-code-on-the-web) on claude.ai with the provided task description | `claude --remote "Fix the login bug"` |

89| `--remote-control`, `--rc` | Start an interactive session with [Remote Control](/en/remote-control#start-a-remote-control-session) enabled so you can also control it from claude.ai or the Claude app. Optionally pass a name for the session | `claude --remote-control "My Project"` |89| `--remote-control`, `--rc` | Start an interactive session with [Remote Control](/en/remote-control#start-a-remote-control-session) enabled so you can also control it from claude.ai or the Claude app. Optionally pass a name for the session | `claude --remote-control "My Project"` |

29| `/chrome` | Configure [Claude in Chrome](/en/chrome) settings |29| `/chrome` | Configure [Claude in Chrome](/en/chrome) settings |

30| `/claude-api [migrate\|managed-agents-onboard]` | **[Skill](/en/skills#bundled-skills).** Load Claude API reference material for your project's language (Python, TypeScript, Java, Go, Ruby, C#, PHP, or cURL) and Managed Agents reference. Covers tool use, streaming, batches, structured outputs, and common pitfalls. Also activates automatically when your code imports `anthropic` or `@anthropic-ai/sdk`. Run `/claude-api migrate` to upgrade existing Claude API code to a newer model: Claude asks which files to scan and which model to target, then updates model IDs, thinking configuration, and other parameters that changed between versions. Run `/claude-api managed-agents-onboard` for an interactive walkthrough that creates a new Managed Agent from scratch |30| `/claude-api [migrate\|managed-agents-onboard]` | **[Skill](/en/skills#bundled-skills).** Load Claude API reference material for your project's language (Python, TypeScript, Java, Go, Ruby, C#, PHP, or cURL) and Managed Agents reference. Covers tool use, streaming, batches, structured outputs, and common pitfalls. Also activates automatically when your code imports `anthropic` or `@anthropic-ai/sdk`. Run `/claude-api migrate` to upgrade existing Claude API code to a newer model: Claude asks which files to scan and which model to target, then updates model IDs, thinking configuration, and other parameters that changed between versions. Run `/claude-api managed-agents-onboard` for an interactive walkthrough that creates a new Managed Agent from scratch |

31| `/clear` | Start a new conversation with empty context. The previous conversation stays available in `/resume`. To free up context while continuing the same conversation, use `/compact` instead. Aliases: `/reset`, `/new` |31| `/clear` | Start a new conversation with empty context. The previous conversation stays available in `/resume`. To free up context while continuing the same conversation, use `/compact` instead. Aliases: `/reset`, `/new` |

32| `/color [color\|default]` | Set the prompt bar color for the current session. Available colors: `red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink`, `cyan`. Use `default` to reset. When [Remote Control](/en/remote-control) is connected, the color syncs to claude.ai/code |32| `/color [color\|default]` | Set the prompt bar color for the current session. Available colors: `red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink`, `cyan`. Use `default` to reset, or run with no argument to pick a random color. When [Remote Control](/en/remote-control) is connected, the color syncs to claude.ai/code |

33| `/compact [instructions]` | Free up context by summarizing the conversation so far. Optionally pass focus instructions for the summary. See [how compaction handles rules, skills, and memory files](/en/context-window#what-survives-compaction) |33| `/compact [instructions]` | Free up context by summarizing the conversation so far. Optionally pass focus instructions for the summary. See [how compaction handles rules, skills, and memory files](/en/context-window#what-survives-compaction) |

34| `/config` | Open the [Settings](/en/settings) interface to adjust theme, model, [output style](/en/output-styles), and other preferences. Alias: `/settings` |34| `/config` | Open the [Settings](/en/settings) interface to adjust theme, model, [output style](/en/output-styles), and other preferences. Alias: `/settings` |

35| `/context` | Visualize current context usage as a colored grid. Shows optimization suggestions for context-heavy tools, memory bloat, and capacity warnings |35| `/context` | Visualize current context usage as a colored grid. Shows optimization suggestions for context-heavy tools, memory bloat, and capacity warnings |

46| `/fast [on\|off]` | Toggle [fast mode](/en/fast-mode) on or off |46| `/fast [on\|off]` | Toggle [fast mode](/en/fast-mode) on or off |

47| `/feedback [report]` | Submit feedback about Claude Code. Alias: `/bug` |47| `/feedback [report]` | Submit feedback about Claude Code. Alias: `/bug` |

48| `/fewer-permission-prompts` | **[Skill](/en/skills#bundled-skills).** Scan your transcripts for common read-only Bash and MCP tool calls, then add a prioritized allowlist to project `.claude/settings.json` to reduce permission prompts |48| `/fewer-permission-prompts` | **[Skill](/en/skills#bundled-skills).** Scan your transcripts for common read-only Bash and MCP tool calls, then add a prioritized allowlist to project `.claude/settings.json` to reduce permission prompts |

49| `/focus` | Toggle the focus view, which shows only your last prompt, a one-line tool-call summary with edit diffstats, and the final response. The selection persists across sessions. Only available in [fullscreen rendering](/en/fullscreen) |49| `/focus` | Toggle the focus view, which shows only your last prompt, a one-line tool-call summary with edit diffstats, and the final response. The selection persists across sessions; set [`viewMode`](/en/settings#available-settings) in settings to override it. Only available in [fullscreen rendering](/en/fullscreen) |

50| `/heapdump` | Write a JavaScript heap snapshot and a memory breakdown to `~/Desktop`, or your home directory on Linux without a Desktop folder, for diagnosing high memory usage. See [troubleshooting](/en/troubleshooting#high-cpu-or-memory-usage) |50| `/heapdump` | Write a JavaScript heap snapshot and a memory breakdown to `~/Desktop`, or your home directory on Linux without a Desktop folder, for diagnosing high memory usage. See [troubleshooting](/en/troubleshooting#high-cpu-or-memory-usage) |

51| `/help` | Show help and available commands |51| `/help` | Show help and available commands |

52| `/hooks` | View [hook](/en/hooks) configurations for tool events |52| `/hooks` | View [hook](/en/hooks) configurations for tool events |

91| `/statusline` | Configure Claude Code's [status line](/en/statusline). Describe what you want, or run without arguments to auto-configure from your shell prompt |91| `/statusline` | Configure Claude Code's [status line](/en/statusline). Describe what you want, or run without arguments to auto-configure from your shell prompt |

92| `/stickers` | Order Claude Code stickers |92| `/stickers` | Order Claude Code stickers |

93| `/tasks` | List and manage background tasks. Also available as `/bashes` |93| `/tasks` | List and manage background tasks. Also available as `/bashes` |

94| `/team-onboarding` | Generate a team onboarding guide from your Claude Code usage history. Claude analyzes your sessions, commands, and MCP server usage from the past 30 days and produces a markdown guide a teammate can paste as a first message to get set up quickly |94| `/team-onboarding` | Generate a team onboarding guide from your Claude Code usage history. Claude analyzes your sessions, commands, and MCP server usage from the past 30 days and produces a markdown guide a teammate can paste as a first message to get set up quickly. For claude.ai subscribers on Pro, Max, Team, and Enterprise plans, also returns a share link teammates can open directly in Claude Code |

95| `/teleport` | Pull a [Claude Code on the web](/en/claude-code-on-the-web#from-web-to-terminal) session into this terminal: opens a picker, then fetches the branch and conversation. Also available as `/tp`. Requires a claude.ai subscription |95| `/teleport` | Pull a [Claude Code on the web](/en/claude-code-on-the-web#from-web-to-terminal) session into this terminal: opens a picker, then fetches the branch and conversation. Also available as `/tp`. Requires a claude.ai subscription |

96| `/terminal-setup` | Configure terminal keybindings for Shift+Enter and other shortcuts. Only visible in terminals that need it, like VS Code, Cursor, Windsurf, Alacritty, or Zed |96| `/terminal-setup` | Configure terminal keybindings for Shift+Enter and other shortcuts. Only visible in terminals that need it, like VS Code, Cursor, Windsurf, Alacritty, or Zed |

97| `/theme` | Change the color theme. Includes an `auto` option that matches your terminal's light or dark background, light and dark variants, colorblind-accessible (daltonized) themes, ANSI themes that use your terminal's color palette, and any [custom themes](/en/terminal-config#create-a-custom-theme) from `~/.claude/themes/` or plugins. Select **New custom theme…** to create one |97| `/theme` | Change the color theme. Includes an `auto` option that matches your terminal's light or dark background, light and dark variants, colorblind-accessible (daltonized) themes, ANSI themes that use your terminal's color palette, and any [custom themes](/en/terminal-config#create-a-custom-theme) from `~/.claude/themes/` or plugins. Select **New custom theme…** to create one |

67 67 

68The diagram below shows how Claude Code connects to external services during installation and normal operation. Solid lines indicate required connections, while dashed lines represent optional or user-initiated data flows.68The diagram below shows how Claude Code connects to external services during installation and normal operation. Solid lines indicate required connections, while dashed lines represent optional or user-initiated data flows.

69 69 

70<img src="https://mintcdn.com/claude-code/YcBW2H7CArGcduPb/images/claude-code-data-flow.svg?fit=max&auto=format&n=YcBW2H7CArGcduPb&q=85&s=b600a89f84fc86f9ff7be00a466c0635" alt="Diagram showing Claude Code's external connections: install/update connects to the distribution server, and user requests connect to Anthropic services including Console auth, public-api, and optionally Statsig, Sentry, and bug reporting" width="720" height="520" data-path="images/claude-code-data-flow.svg" />70<img src="https://mintcdn.com/claude-code/RcOyXc06Ja8cuvMZ/images/claude-code-data-flow.svg?fit=max&auto=format&n=RcOyXc06Ja8cuvMZ&q=85&s=b5be40abf333defe984993af89546c19" alt="Diagram showing Claude Code's external connections: install/update connects to the distribution server, and user requests connect to Anthropic services including Console auth, public-api, and optionally metrics, Sentry, and bug reporting" width="720" height="520" data-path="images/claude-code-data-flow.svg" />

71 71 

72Claude Code runs locally. To interact with the LLM, Claude Code sends data over the network. This data includes all user prompts and model outputs, encrypted in transit via TLS 1.2+. Claude Code is compatible with most popular VPNs and LLM proxies.72Claude Code runs locally. To interact with the LLM, Claude Code sends data over the network. This data includes all user prompts and model outputs, encrypted in transit via TLS 1.2+. Claude Code is compatible with most popular VPNs and LLM proxies.

73 73 

95 95 

96## Telemetry services96## Telemetry services

97 97 

98Claude Code connects from users' machines to the Statsig service to log operational metrics such as latency, reliability, and usage patterns. This logging does not include any code or file paths. Data is encrypted in transit using TLS and at rest using 256-bit AES encryption. Read more in the [Statsig security documentation](https://www.statsig.com/trust/security). To opt out of Statsig telemetry, set the `DISABLE_TELEMETRY` environment variable.98Claude Code connects from users' machines to Anthropic to log operational metrics such as latency, reliability, and usage patterns. This logging does not include any code or file paths. Data is encrypted in transit and at rest. To opt out of telemetry, set the `DISABLE_TELEMETRY` environment variable.

99 99 

100Claude Code connects from users' machines to Sentry for operational error logging. The data is encrypted in transit using TLS and at rest using 256-bit AES encryption. Read more in the [Sentry security documentation](https://sentry.io/security/). To opt out of error logging, set the `DISABLE_ERROR_REPORTING` environment variable.100Claude Code connects from users' machines to Sentry for operational error logging. The data is encrypted in transit using TLS and at rest using 256-bit AES encryption. Read more in the [Sentry security documentation](https://sentry.io/security/). To opt out of error logging, set the `DISABLE_ERROR_REPORTING` environment variable.

101 101 

107 107 

108| Service | Claude API | Vertex API | Bedrock API | Foundry API |108| Service | Claude API | Vertex API | Bedrock API | Foundry API |

109| ------------------------------------ | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |109| ------------------------------------ | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |

110| **Statsig (Metrics)** | Default on.<br />`DISABLE_TELEMETRY=1` to disable. | Default off.<br />`CLAUDE_CODE_USE_VERTEX` must be 1. | Default off.<br />`CLAUDE_CODE_USE_BEDROCK` must be 1. | Default off.<br />`CLAUDE_CODE_USE_FOUNDRY` must be 1. |110| **Anthropic (Metrics)** | Default on.<br />`DISABLE_TELEMETRY=1` to disable. | Default off.<br />`CLAUDE_CODE_USE_VERTEX` must be 1. | Default off.<br />`CLAUDE_CODE_USE_BEDROCK` must be 1. | Default off.<br />`CLAUDE_CODE_USE_FOUNDRY` must be 1. |

111| **Sentry (Errors)** | Default on.<br />`DISABLE_ERROR_REPORTING=1` to disable. | Default off.<br />`CLAUDE_CODE_USE_VERTEX` must be 1. | Default off.<br />`CLAUDE_CODE_USE_BEDROCK` must be 1. | Default off.<br />`CLAUDE_CODE_USE_FOUNDRY` must be 1. |111| **Sentry (Errors)** | Default on.<br />`DISABLE_ERROR_REPORTING=1` to disable. | Default off.<br />`CLAUDE_CODE_USE_VERTEX` must be 1. | Default off.<br />`CLAUDE_CODE_USE_BEDROCK` must be 1. | Default off.<br />`CLAUDE_CODE_USE_FOUNDRY` must be 1. |

112| **Claude API (`/feedback` reports)** | Default on.<br />`DISABLE_FEEDBACK_COMMAND=1` to disable. | Default off.<br />`CLAUDE_CODE_USE_VERTEX` must be 1. | Default off.<br />`CLAUDE_CODE_USE_BEDROCK` must be 1. | Default off.<br />`CLAUDE_CODE_USE_FOUNDRY` must be 1. |112| **Claude API (`/feedback` reports)** | Default on.<br />`DISABLE_FEEDBACK_COMMAND=1` to disable. | Default off.<br />`CLAUDE_CODE_USE_VERTEX` must be 1. | Default off.<br />`CLAUDE_CODE_USE_BEDROCK` must be 1. | Default off.<br />`CLAUDE_CODE_USE_FOUNDRY` must be 1. |

113| **Session quality surveys** | Default on.<br />`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY=1` to disable. | Default on.<br />`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY=1` to disable. | Default on.<br />`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY=1` to disable. | Default on.<br />`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY=1` to disable. |113| **Session quality surveys** | Default on.<br />`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY=1` to disable. | Default on.<br />`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY=1` to disable. | Default on.<br />`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY=1` to disable. | Default on.<br />`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY=1` to disable. |

115 115 

116All environment variables can be checked into `settings.json` (see [settings reference](/en/settings)).116All environment variables can be checked into `settings.json` (see [settings reference](/en/settings)).

117 117 

118As of v2.1.126, when a host platform sets `CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`, Statsig metrics default to on for Vertex, Bedrock, and Foundry, and follow the standard `DISABLE_TELEMETRY` opt-out. Sentry error reporting and `/feedback` reports remain off by default on those providers.118As of v2.1.126, when a host platform sets `CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`, metrics default to on for Vertex, Bedrock, and Foundry, and follow the standard `DISABLE_TELEMETRY` opt-out. Sentry error reporting and `/feedback` reports remain off by default on those providers.

119 119 

120### WebFetch domain safety check120### WebFetch domain safety check

121 121 

284 284 

285Click **+ New session** in the sidebar, or press **Cmd+N** on macOS or **Ctrl+N** on Windows, to work on multiple tasks in parallel. Press **Ctrl+Tab** and **Ctrl+Shift+Tab** to cycle through sessions in the sidebar. For Git repositories, each session gets its own isolated copy of your project using [Git worktrees](/en/worktrees), so changes in one session don't affect other sessions until you commit them.285Click **+ New session** in the sidebar, or press **Cmd+N** on macOS or **Ctrl+N** on Windows, to work on multiple tasks in parallel. Press **Ctrl+Tab** and **Ctrl+Shift+Tab** to cycle through sessions in the sidebar. For Git repositories, each session gets its own isolated copy of your project using [Git worktrees](/en/worktrees), so changes in one session don't affect other sessions until you commit them.

286 286 

287To view two sessions at once, hold **Cmd** on macOS or **Ctrl** on Windows and click a session in the sidebar. The session opens in a second pane alongside the one you already have open. While the split is active, clicking another sidebar session replaces whichever pane has focus. Press **Cmd+\\** on macOS or **Ctrl+\\** on Windows to close the focused pane and return to a single session.

288 

287Worktrees are stored in `<project-root>/.claude/worktrees/` by default. You can change this to a custom directory in Settings → Claude Code under "Worktree location". You can also set a branch prefix that gets prepended to every worktree branch name, which is useful for keeping Claude-created branches organized. To remove a worktree when you're done, hover over the session in the sidebar and click the archive icon. To have sessions archive themselves when their pull request merges or closes, turn on **Auto-archive after PR merge or close** in Settings → Claude Code. Auto-archive only applies to local sessions that have finished running.289Worktrees are stored in `<project-root>/.claude/worktrees/` by default. You can change this to a custom directory in Settings → Claude Code under "Worktree location". You can also set a branch prefix that gets prepended to every worktree branch name, which is useful for keeping Claude-created branches organized. To remove a worktree when you're done, hover over the session in the sidebar and click the archive icon. To have sessions archive themselves when their pull request merges or closes, turn on **Auto-archive after PR merge or close** in Settings → Claude Code. Auto-archive only applies to local sessions that have finished running.

288 290 

289To include gitignored files like `.env` in new worktrees, create a [`.worktreeinclude` file](/en/worktrees#copy-gitignored-files-into-worktrees) in your project root.291To include gitignored files like `.env` in new worktrees, create a [`.worktreeinclude` file](/en/worktrees#copy-gitignored-files-into-worktrees) in your project root.

60| `CLAUDE_CODE_ATTRIBUTION_HEADER` | Set to `0` to omit the attribution block (client version and prompt fingerprint) from the start of the system prompt. Disabling it improves prompt-cache hit rates when routing through an [LLM gateway](/en/llm-gateway). Anthropic API caching is unaffected |60| `CLAUDE_CODE_ATTRIBUTION_HEADER` | Set to `0` to omit the attribution block (client version and prompt fingerprint) from the start of the system prompt. Disabling it improves prompt-cache hit rates when routing through an [LLM gateway](/en/llm-gateway). Anthropic API caching is unaffected |

61| `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | Set the context capacity in tokens used for auto-compaction calculations. Defaults to the model's context window: 200K for standard models or 1M for [extended context](/en/model-config#extended-context) models. Use a lower value like `500000` on a 1M model to treat the window as 500K for compaction purposes. The value is capped at the model's actual context window. `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` is applied as a percentage of this value. Setting this variable decouples the compaction threshold from the status line's `used_percentage`, which always uses the model's full context window |61| `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | Set the context capacity in tokens used for auto-compaction calculations. Defaults to the model's context window: 200K for standard models or 1M for [extended context](/en/model-config#extended-context) models. Use a lower value like `500000` on a 1M model to treat the window as 500K for compaction purposes. The value is capped at the model's actual context window. `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` is applied as a percentage of this value. Setting this variable decouples the compaction threshold from the status line's `used_percentage`, which always uses the model's full context window |

62| `CLAUDE_CODE_AUTO_CONNECT_IDE` | Override automatic [IDE connection](/en/vs-code). By default, Claude Code connects automatically when launched inside a supported IDE's integrated terminal. Set to `false` to prevent this. Set to `true` to force a connection attempt when auto-detection fails, such as when tmux obscures the parent terminal |62| `CLAUDE_CODE_AUTO_CONNECT_IDE` | Override automatic [IDE connection](/en/vs-code). By default, Claude Code connects automatically when launched inside a supported IDE's integrated terminal. Set to `false` to prevent this. Set to `true` to force a connection attempt when auto-detection fails, such as when tmux obscures the parent terminal |

63| `CLAUDE_CODE_CERT_STORE` | Comma-separated list of CA certificate sources for TLS connections. `bundled` is the Mozilla CA set shipped with Claude Code. `system` is the operating system trust store. Default is `bundled,system`. The native binary distribution is required for system store integration. On the Node.js runtime, only the bundled set is used regardless of this value |63| `CLAUDE_CODE_CERT_STORE` | Comma-separated list of CA certificate sources for TLS connections. `bundled` is the Mozilla CA set shipped with Claude Code. `system` is the operating system trust store. Default is `bundled,system` |

64| `CLAUDE_CODE_CLIENT_CERT` | Path to client certificate file for mTLS authentication |64| `CLAUDE_CODE_CLIENT_CERT` | Path to client certificate file for mTLS authentication |

65| `CLAUDE_CODE_CLIENT_KEY` | Path to client private key file for mTLS authentication |65| `CLAUDE_CODE_CLIENT_KEY` | Path to client private key file for mTLS authentication |

66| `CLAUDE_CODE_CLIENT_KEY_PASSPHRASE` | Passphrase for encrypted CLAUDE\_CODE\_CLIENT\_KEY (optional) |66| `CLAUDE_CODE_CLIENT_KEY_PASSPHRASE` | Passphrase for encrypted CLAUDE\_CODE\_CLIENT\_KEY (optional) |

181| `DISABLE_PROMPT_CACHING_HAIKU` | Set to `1` to disable prompt caching for Haiku models |181| `DISABLE_PROMPT_CACHING_HAIKU` | Set to `1` to disable prompt caching for Haiku models |

182| `DISABLE_PROMPT_CACHING_OPUS` | Set to `1` to disable prompt caching for Opus models |182| `DISABLE_PROMPT_CACHING_OPUS` | Set to `1` to disable prompt caching for Opus models |

183| `DISABLE_PROMPT_CACHING_SONNET` | Set to `1` to disable prompt caching for Sonnet models |183| `DISABLE_PROMPT_CACHING_SONNET` | Set to `1` to disable prompt caching for Sonnet models |

184| `DISABLE_TELEMETRY` | Set to `1` to opt out of Statsig telemetry (note that Statsig events do not include user data like code, file paths, or bash commands) |184| `DISABLE_TELEMETRY` | Set to `1` to opt out of telemetry. Telemetry events do not include user data like code, file paths, or bash commands |

185| `DISABLE_UPDATES` | Set to `1` to block all updates including manual `claude update` and `claude install`. Stricter than `DISABLE_AUTOUPDATER`. Use when distributing Claude Code through your own channels and users should not self-update |185| `DISABLE_UPDATES` | Set to `1` to block all updates including manual `claude update` and `claude install`. Stricter than `DISABLE_AUTOUPDATER`. Use when distributing Claude Code through your own channels and users should not self-update |

186| `DISABLE_UPGRADE_COMMAND` | Set to `1` to hide the `/upgrade` command |186| `DISABLE_UPGRADE_COMMAND` | Set to `1` to hide the `/upgrade` command |

187| `ENABLE_CLAUDEAI_MCP_SERVERS` | Set to `false` to disable [claude.ai MCP servers](/en/mcp#use-mcp-servers-from-claude-ai) in Claude Code. Enabled by default for logged-in users |187| `ENABLE_CLAUDEAI_MCP_SERVERS` | Set to `false` to disable [claude.ai MCP servers](/en/mcp#use-mcp-servers-from-claude-ai) in Claude Code. Enabled by default for logged-in users |

198| `MAX_STRUCTURED_OUTPUT_RETRIES` | Number of times to retry when the model's response fails validation against the [`--json-schema`](/en/cli-reference#cli-flags) in non-interactive mode (the `-p` flag). Defaults to 5 |198| `MAX_STRUCTURED_OUTPUT_RETRIES` | Number of times to retry when the model's response fails validation against the [`--json-schema`](/en/cli-reference#cli-flags) in non-interactive mode (the `-p` flag). Defaults to 5 |

199| `MAX_THINKING_TOKENS` | Override the [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) token budget. The ceiling is the model's [max output tokens](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison) minus one. Set to `0` to disable thinking entirely. On models with [adaptive reasoning](/en/model-config#adjust-effort-level), the budget is ignored unless adaptive reasoning is disabled via `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` |199| `MAX_THINKING_TOKENS` | Override the [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) token budget. The ceiling is the model's [max output tokens](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison) minus one. Set to `0` to disable thinking entirely. On models with [adaptive reasoning](/en/model-config#adjust-effort-level), the budget is ignored unless adaptive reasoning is disabled via `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` |

200| `MCP_CLIENT_SECRET` | OAuth client secret for MCP servers that require [pre-configured credentials](/en/mcp#use-pre-configured-oauth-credentials). Avoids the interactive prompt when adding a server with `--client-secret` |200| `MCP_CLIENT_SECRET` | OAuth client secret for MCP servers that require [pre-configured credentials](/en/mcp#use-pre-configured-oauth-credentials). Avoids the interactive prompt when adding a server with `--client-secret` |

201| `MCP_CONNECTION_NONBLOCKING` | Set to `true` in non-interactive mode (`-p`) to skip the MCP connection wait entirely. Useful for scripted pipelines where MCP tools are not needed. Without this variable, the first query waits up to 5 seconds for `--mcp-config` server connections |201| `MCP_CONNECTION_NONBLOCKING` | Set to `true` in non-interactive mode (`-p`) to skip the MCP connection wait entirely. Useful for scripted pipelines where MCP tools are not needed. Without this variable, the first query waits up to 5 seconds for `--mcp-config` server connections. Servers configured with [`alwaysLoad: true`](/en/mcp#exempt-a-server-from-deferral) always block startup regardless of this variable, since their tools must be present when the first prompt is built |

202| `MCP_OAUTH_CALLBACK_PORT` | Fixed port for the OAuth redirect callback, as an alternative to `--callback-port` when adding an MCP server with [pre-configured credentials](/en/mcp#use-pre-configured-oauth-credentials) |202| `MCP_OAUTH_CALLBACK_PORT` | Fixed port for the OAuth redirect callback, as an alternative to `--callback-port` when adding an MCP server with [pre-configured credentials](/en/mcp#use-pre-configured-oauth-credentials) |

203| `MCP_REMOTE_SERVER_CONNECTION_BATCH_SIZE` | Maximum number of remote MCP servers (HTTP/SSE) to connect in parallel during startup (default: 20) |203| `MCP_REMOTE_SERVER_CONNECTION_BATCH_SIZE` | Maximum number of remote MCP servers (HTTP/SSE) to connect in parallel during startup (default: 20) |

204| `MCP_SERVER_CONNECTION_BATCH_SIZE` | Maximum number of local MCP servers (stdio) to connect in parallel during startup (default: 3) |204| `MCP_SERVER_CONNECTION_BATCH_SIZE` | Maximum number of local MCP servers (stdio) to connect in parallel during startup (default: 3) |

307* Ensure your firewall allows the hosts listed in [Network access requirements](/en/network-config#network-access-requirements)307* Ensure your firewall allows the hosts listed in [Network access requirements](/en/network-config#network-access-requirements)

308* Intermittent failures are [retried automatically](#automatic-retries); persistent failures point to a local network issue308* Intermittent failures are [retried automatically](#automatic-retries); persistent failures point to a local network issue

309 309 

310If `curl` succeeds but Claude Code still fails, the cause is usually something between Node.js and the network rather than the network itself:310If `curl` succeeds but Claude Code still fails, the cause is usually something between the runtime and the network rather than the network itself:

311 311 

312* On Linux and WSL, check `/etc/resolv.conf` for an unreachable nameserver. WSL in particular can inherit a broken resolver from the host.312* On Linux and WSL, check `/etc/resolv.conf` for an unreachable nameserver. WSL in particular can inherit a broken resolver from the host.

313* On macOS, a VPN client that was disconnected or uninstalled can leave a tunnel interface or routing rule behind. Check `ifconfig` for stale `utun` interfaces and remove the VPN's network extension in System Settings.313* On macOS, a VPN client that was disconnected or uninstalled can leave a tunnel interface or routing rule behind. Check `ifconfig` for stale `utun` interfaces and remove the VPN's network extension in System Settings.

315 315 

316### SSL certificate errors316### SSL certificate errors

317 317 

318A proxy or security appliance on your network is intercepting TLS traffic with its own certificate, and Node.js does not trust it.318A proxy or security appliance on your network is intercepting TLS traffic with its own certificate, and Claude Code does not trust it.

319 319 

320```text theme={null}320```text theme={null}

321Unable to connect to API: SSL certificate verification failed. Check your proxy or corporate SSL certificates321Unable to connect to API: SSL certificate verification failed. Check your proxy or corporate SSL certificates

324 324 

325**What to do:**325**What to do:**

326 326 

327* Export your organization's CA bundle and point Node at it with `NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.pem`327* Export your organization's CA bundle and point Claude Code at it with `NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.pem`

328* See [Network configuration](/en/network-config#custom-ca-certificates) for full setup instructions328* See [Network configuration](/en/network-config#custom-ca-certificates) for full setup instructions

329* Do not set `NODE_TLS_REJECT_UNAUTHORIZED=0`, which disables certificate validation entirely329* Do not set `NODE_TLS_REJECT_UNAUTHORIZED=0`, which disables certificate validation entirely

330 330 

71 * **Subagents** are isolated workers that run separately from your main conversation71 * **Subagents** are isolated workers that run separately from your main conversation

72 72 

73 | Aspect | Skill | Subagent |73 | Aspect | Skill | Subagent |