17```17```
18 18
19<Note>19<Note>
20 SDK 为您的平台捆绑了一个本地 Claude Code 二进制文件，作为可选依赖项，例如 `@anthropic-ai/claude-agent-sdk-darwin-arm64`。您无需单独安装 Claude Code。如果您的包管理器跳过可选依赖项，SDK 会抛出 `Native CLI binary for <platform> not found`；改为将 [`pathToClaudeCodeExecutable`](#options) 设置为单独安装的 `claude` 二进制文件。20 SDK 为您的平台捆绑了一个本地 Claude Code 二进制文件，作为可选依赖项，例如 `@anthropic-ai/claude-agent-sdk-darwin-arm64`。大多数安装无需单独安装 Claude Code。SDK 版本跟踪捆绑的 Claude Code 版本。SDK v0.3.191 捆绑 Claude Code v2.1.191，因此本页面上需要特定 Claude Code 版本的功能需要具有相同补丁号或更高版本的 SDK 版本。如果您的包管理器跳过可选依赖项，SDK 会抛出 `Native CLI binary for <platform>-<arch> not found`；改为将 [`pathToClaudeCodeExecutable`](#options) 设置为单独安装的 `claude` 二进制文件。
21
22 如果您的包管理器不应用 npm 的 `libc` 字段（如 Yarn 1.x 不应用），您会在 Linux 上同时获得 glibc 和 musl 平台包，大约使安装大小翻倍。在 Agent SDK v0.2.141 或更高版本上，SDK 仍然会启动正确的变体。要在容器镜像中回收空间，请删除与您的应用运行的 libc 不匹配的平台包；对于 x64 上的 glibc 运行时，即 `rm -rf node_modules/@anthropic-ai/claude-agent-sdk-linux-x64-musl`。在开发机器上删除是临时的，因为 Yarn 会在下一次依赖项更改时重新安装该包。
21</Note>23</Note>
22 24
23<h3 id="compile-to-a-single-executable">25<h3 id="compile-to-a-single-executable">
24 编译为单个可执行文件26 编译为单个可执行文件
25</h3>27</h3>
26 28
27当您使用 `bun build --compile` 将应用程序编译为单文件可执行文件时，SDK 无法在运行时解析捆绑的 CLI 二进制文件。`require.resolve` 在编译后的可执行文件的 `$bunfs` 虚拟文件系统内不起作用，因此 SDK 会抛出 `Native CLI binary for <platform> not found`。29当您使用 `bun build --compile` 将应用程序编译为单文件可执行文件时，SDK 无法在运行时解析捆绑的 CLI 二进制文件。`require.resolve` 在编译后的可执行文件的 `$bunfs` 虚拟文件系统内不起作用，因此 SDK 会抛出 `Native CLI binary for <platform>-<arch> not found`。
28 30
29要解决此问题，请将平台二进制文件作为文件资产嵌入，在启动时使用 `extractFromBunfs()` 将其提取到真实路径，然后将该路径传递给 [`pathToClaudeCodeExecutable`](#options)。31要解决此问题，请将平台二进制文件作为文件资产嵌入，在启动时使用 `extractFromBunfs()` 将其提取到真实路径，然后将该路径传递给 [`pathToClaudeCodeExecutable`](#options)。
30 32
145 description: string,147 description: string,
146 inputSchema: Schema,148 inputSchema: Schema,
147 handler: (args: InferShape<Schema>, extra: unknown) => Promise<CallToolResult>,149 handler: (args: InferShape<Schema>, extra: unknown) => Promise<CallToolResult>,
148 extras?: { annotations?: ToolAnnotations }150 extras?: { annotations?: ToolAnnotations; searchHint?: string; alwaysLoad?: boolean }
149): SdkMcpToolDefinition<Schema>;151): SdkMcpToolDefinition<Schema>;
150```152```
151 153
154</h4>156</h4>
155 157
156| 参数 | 类型 | 描述 |158| 参数 | 类型 | 描述 |
157| :------------ | :---------------------------------------------------------------- | :--------------------------------- |159| :------------ | :----------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------- |
158| `name` | `string` | 工具的名称 |160| `name` | `string` | 工具的名称 |
159| `description` | `string` | 工具功能的描述 |161| `description` | `string` | 工具功能的描述 |
160| `inputSchema` | `Schema extends AnyZodRawShape` | 定义工具输入参数的 Zod 架构（支持 Zod 3 和 Zod 4） |162| `inputSchema` | `Schema extends AnyZodRawShape` | 定义工具输入参数的 Zod 架构（支持 Zod 3 和 Zod 4） |
161| `handler` | `(args, extra) => Promise<`[`CallToolResult`](#calltoolresult)`>` | 执行工具逻辑的异步函数 |163| `handler` | `(args, extra) => Promise<`[`CallToolResult`](#calltoolresult)`>` | 执行工具逻辑的异步函数 |
162| `extras` | `{ annotations?: `[`ToolAnnotations`](#toolannotations)` }` | 可选的 MCP 工具注释，为客户端提供行为提示 |164| `extras` | `{ annotations?: `[`ToolAnnotations`](#toolannotations)`; searchHint?: string; alwaysLoad?: boolean }` | 可选的 extras。`annotations` 为客户端提供 MCP 行为提示。`searchHint` 是当[工具搜索](/docs/zh-CN/agent-sdk/tool-search)处于活动状态时在延迟工具列表中显示的单行功能短语。`alwaysLoad: true` 将此工具的完整架构保留在初始提示中，而不是延迟它 |
163 165
164<h4 id="toolannotations">166<h4 id="toolannotations">
165 `ToolAnnotations`167 `ToolAnnotations`
200function createSdkMcpServer(options: {202function createSdkMcpServer(options: {
201 name: string;203 name: string;
202 version?: string;204 version?: string;
205 instructions?: string;
203 tools?: Array<SdkMcpToolDefinition<any>>;206 tools?: Array<SdkMcpToolDefinition<any>>;
207 alwaysLoad?: boolean;
208 timeout?: number;
204}): McpSdkServerConfigWithInstance;209}): McpSdkServerConfigWithInstance;
205```210```
206 211
209</h4>214</h4>
210 215
211| 参数 | 类型 | 描述 |216| 参数 | 类型 | 描述 |
212| :---------------- | :---------------------------- | :----------------------------- |217| :--------------------- | :---------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------- |
213| `options.name` | `string` | MCP 服务器的名称 |218| `options.name` | `string` | MCP 服务器的名称 |
214| `options.version` | `string` | 可选版本字符串 |219| `options.version` | `string` | 可选版本字符串 |
220| `options.instructions` | `string` | 可选服务器说明，从 `initialize` 返回并作为 MCP 说明块呈现给模型 |
215| `options.tools` | `Array<SdkMcpToolDefinition>` | 使用 [`tool()`](#tool) 创建的工具定义数组 |221| `options.tools` | `Array<SdkMcpToolDefinition>` | 使用 [`tool()`](#tool) 创建的工具定义数组 |
222| `options.alwaysLoad` | `boolean` | 当为 `true` 时，来自此服务器的每个工具都保留在初始提示中，永远不会在[工具搜索](/docs/zh-CN/agent-sdk/tool-search)后延迟。与 [`tool()`](#tool) 中的每个工具 `alwaysLoad` 结合 |
223| `options.timeout` | `number` | 此服务器的工具调用超时（毫秒）。Claude Code 将其应用于此服务器以代替 [`MCP_TOOL_TIMEOUT`](/docs/zh-CN/env-vars)。传递至少 1000 的整数。Claude Code 忽略其他值。需要 TypeScript Agent SDK v0.3.248 或更高版本 |
216 224
217<h3 id="listsessions">225<h3 id="listsessions">
218 `listSessions()`226 `listSessions()`
296</h4>304</h4>
297 305
298| 属性 | 类型 | 描述 |306| 属性 | 类型 | 描述 |
299| :------------------- | :---------------------- | :------------------------------------------------------------------------------------------------------------------------------------------- |307| :------------------- | :---------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------ |
300| `type` | `"user" \| "assistant"` | 消息角色 |308| `type` | `"user" \| "assistant"` | 消息角色 |
301| `uuid` | `string` | 唯一消息标识符 |309| `uuid` | `string` | 唯一消息标识符 |
302| `session_id` | `string` | 此消息所属的会话 |310| `session_id` | `string` | 此消息所属的会话 |
303| `message` | `unknown` | 来自记录的原始消息有效负载 |311| `message` | `unknown` | 来自记录的原始消息有效负载 |
304| `parent_tool_use_id` | `string \| null` | 对于子代理消息，生成 `Agent` 工具调用的 `tool_use_id`。对于主会话消息和较旧的会话为 `null` |312| `parent_tool_use_id` | `string \| null` | 对于子代理消息，生成 `Agent` 工具调用的 `tool_use_id`。对于主会话消息和较旧的会话为 `null` |
305| `parent_agent_id` | `string \| null` | 对于来自[嵌套子代理](/docs/zh-CN/sub-agents#spawn-nested-subagents)的消息，生成该消息的子代理的 `agentId`。对于主会话消息、来自顶级子代理的消息和较旧的会话为 `null`。需要 Claude Code v2.1.202 或更高版本 |313| `parent_agent_id` | `string \| null` | 对于来自[嵌套子代理](/docs/zh-CN/sub-agents#let-subagents-spawn-their-own-subagents)的消息，生成该消息的子代理的 `agentId`。对于主会话消息、来自顶级子代理的消息和较旧的会话为 `null`。需要 Claude Code v2.1.202 或更高版本 |
306 314
307<h4 id="example-3">315<h4 id="example-3">
308 示例316 示例
404使用与 CLI 相同的合并引擎为给定目录解析有效的 Claude Code 设置，无需生成 Claude CLI。在调用 `query()` 之前使用它来检查 `query()` 调用将看到的配置。412使用与 CLI 相同的合并引擎为给定目录解析有效的 Claude Code 设置，无需生成 Claude CLI。在调用 `query()` 之前使用它来检查 `query()` 调用将看到的配置。
405 413
406<Note>414<Note>
407 此函数处于 alpha 阶段，其 API 在稳定之前可能会更改。它读取 MDM 源，包括 macOS plist 和 Windows HKLM/HKCU，以与 CLI 启动保持一致，但不执行管理员配置的 `policyHelper` 子进程。`permissions.defaultMode` 字段从所有层级（包括项目设置）按原样返回。CLI 在遵守升级权限模式之前应用的信任过滤器不被应用。415 此函数处于 alpha 阶段，其 API 在稳定之前可能会更改。
408</Note>416</Note>
409 417
418快照与实时 `query()` 会话应用的内容不同：
419
420* **`policyHelper`**：`resolveSettings()` 读取 MDM 源，包括 macOS plist 和 Windows HKLM/HKCU，但不执行管理员配置的 `policyHelper` 子进程。
421* **服务器管理的设置**：`resolveSettings()` 不获取[服务器管理的设置](/docs/zh-CN/server-managed-settings#fetch-and-caching-behavior)。将它们作为 `options.serverManagedSettings` 传递以包含它们。
422* **`defaultMode`**：快照从每个层级按原样返回 `permissions.defaultMode`，因此它可以包括项目和本地设置中的 `'auto'` 和 `'bypassPermissions'` 值，[实时会话忽略](/docs/zh-CN/permission-modes#which-mode-a-session-starts-in)这些值。
423
410```typescript theme={null}424```typescript theme={null}
411function resolveSettings(425function resolveSettings(
412 options?: ResolveSettingsOptions426 options?: ResolveSettingsOptions
420`resolveSettings()` 接受单个选项对象。所有字段都是可选的。434`resolveSettings()` 接受单个选项对象。所有字段都是可选的。
421 435
422| 参数 | 类型 | 默认值 | 描述 |436| 参数 | 类型 | 默认值 | 描述 |
423| :------------------------------ | :------------------------------------ | :-------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------- |437| :------------------------------ | :------------------------------------ | :-------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
424| `options.cwd` | `string` | `process.cwd()` | 用于解析项目和本地设置的相对目录 |438| `options.cwd` | `string` | `process.cwd()` | 用于解析项目和本地设置的相对目录 |
425| `options.settingSources` | [`SettingSource`](#settingsource)`[]` | 所有源 | 要加载的文件系统源。传递 `[]` 以跳过用户、项目和本地设置。[端点管理的策略](/docs/zh-CN/settings#settings-files)在所有情况下都会加载。服务器管理的设置取自主机传递的 `serverManagedSettings`，或从 CLI 的磁盘缓存中读取；快照不会从网络获取它们 |439| `options.settingSources` | [`SettingSource`](#settingsource)`[]` | 所有源 | 要加载的文件系统源。传递 `[]` 以跳过用户、项目和本地设置。[端点管理的策略](/docs/zh-CN/managed-settings#delivery-mechanisms)在所有情况下都会加载。`resolveSettings()` 仅当您传递 `options.serverManagedSettings` 时才包括服务器管理的设置 |
426| `options.managedSettings` | `Settings` | `undefined` | 由嵌入主机提供的限制性策略层设置。当存在管理员部署的托管层时被删除；当 [`parentSettingsBehavior`](/docs/zh-CN/settings#available-settings) 为 `"merge"` 时在该层下合并。非限制性密钥（如 `model`）会被静默删除，以便此选项可以加强托管策略但不能放松它 |440| `options.managedSettings` | `Settings` | `undefined` | 由嵌入主机提供的策略层设置。遵循与 [`managedSettings` in `Options`](#options) 相同的规则，除了 `resolveSettings()` 不执行配置的 [`policyHelper`](/docs/zh-CN/settings-reference#policyhelper)，因此快照可以包括实时会话删除的设置 |
427| `options.serverManagedSettings` | `Settings` | `undefined` | 来自 `/api/claude_code/settings` 的服务器托管设置有效负载。非限制性密钥不经过滤地通过 |441| `options.serverManagedSettings` | `Settings` | `undefined` | 来自 `/api/claude_code/settings` 的服务器管理设置有效负载。非限制性密钥不经过滤地通过 |
428 442
429<h4 id="return-type-resolvedsettings">443<h4 id="return-type-resolvedsettings">
430 返回类型：`ResolvedSettings`444 返回类型：`ResolvedSettings`
442 示例456 示例
443</h4>457</h4>
444 458
445下面的示例为项目目录解析设置，并打印控制清理周期的源。459下面的示例为项目目录解析设置并打印控制清理周期的源。在没有设置文件设置 `cleanupPeriodDays` 的机器上，两条打印的行都显示 `undefined` 作为值，这是预期的输出而不是错误。
446 460
447```typescript theme={null}461```typescript theme={null}
448import { resolveSettings } from "@anthropic-ai/claude-agent-sdk";462import { resolveSettings } from "@anthropic-ai/claude-agent-sdk";
467`query()` 函数的配置对象。481`query()` 函数的配置对象。
468 482
469| 属性 | 类型 | 默认值 | 描述 |483| 属性 | 类型 | 默认值 | 描述 |
470| :-------------------------------- | :------------------------------------------------------------------------------------------------------- | :---------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |484| :-------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
471| `abortController` | `AbortController` | `new AbortController()` | 用于取消操作的控制器 |485| `abortController` | `AbortController` | `new AbortController()` | 用于取消操作的控制器 |
472| `additionalDirectories` | `string[]` | `[]` | Claude 可以访问的其他目录 |486| `additionalDirectories` | `string[]` | `[]` | Claude 可以访问的其他目录。SDK 将每个条目作为 `--add-dir` 传递给 Claude Code，因此使用 `project` 设置源时，Claude Code 也会[加载目录的 skills、commands 和 subagents](/docs/zh-CN/permissions#additional-directories-grant-file-access-not-configuration) |
473| `agent` | `string` | `undefined` | 主线程的代理名称。代理必须在 `agents` 选项或设置中定义 |487| `agent` | `string` | `undefined` | 主线程的代理名称。代理必须在 `agents` 选项或设置中定义 |
474| `agents` | `Record<string, [`AgentDefinition`](#agentdefinition)>` | `undefined` | 以编程方式定义子代理 |488| `agents` | `Record<string, [`AgentDefinition`](#agentdefinition)>` | `undefined` | 以编程方式定义 subagents |
475| `agentProgressSummaries` | `boolean` | `false` | 当为 `true` 时，为子代理生成单行进度摘要，并通过 `summary` 字段在 [`task_progress`](#sdktaskprogressmessage) 事件上转发它们。适用于前台和后台子代理 |489| `agentProgressSummaries` | `boolean` | `false` | 当为 `true` 时，为 subagents 生成单行进度摘要，并通过 `summary` 字段在 [`task_progress`](#sdktaskprogressmessage) 事件上转发它们。适用于前台和后台 subagents |
476| `allowDangerouslySkipPermissions` | `boolean` | `false` | 启用绕过权限。使用 `permissionMode: 'bypassPermissions'` 时需要 |490| `allowDangerouslySkipPermissions` | `boolean` | `false` | 启用绕过权限。使用 `permissionMode: 'bypassPermissions'` 时需要 |
477| `allowedTools` | `string[]` | `[]` | 无需提示即可自动批准的工具。这不会将 Claude 限制为仅这些工具；未列出的工具会通过 `permissionMode` 和 `canUseTool` 进行处理。使用 `disallowedTools` 阻止工具。请参阅[权限](/docs/zh-CN/agent-sdk/permissions#allow-and-deny-rules) |491| `allowedTools` | `string[]` | `[]` | 无需提示即可自动批准的工具。这不会将 Claude 限制为仅这些工具。如果您在此处命名[任务跟踪工具](/docs/zh-CN/agent-sdk/todo-tracking#model-availability)之一，Claude Code 也会选择加入会话。其他未列出的工具会通过 `permissionMode` 和 `canUseTool` 进行处理。使用 `disallowedTools` 阻止工具。请参阅[权限](/docs/zh-CN/agent-sdk/permissions#allow-and-deny-rules) |
478| `betas` | [`SdkBeta`](#sdkbeta)`[]` | `[]` | 启用测试功能 |492| `betas` | [`SdkBeta`](#sdkbeta)`[]` | `[]` | 启用测试功能 |
479| `canUseTool` | [`CanUseTool`](#canusetool) | `undefined` | 自定义权限函数，仅在[权限流](/docs/zh-CN/agent-sdk/permissions#how-permissions-are-evaluated)落到提示时调用。不会为 `allowedTools`、allow 规则或 `permissionMode` 自动批准的调用调用。`AskUserQuestion`、connector 工具[您的组织设置为 `ask`](/docs/zh-CN/mcp#organization-controls-on-connector-tools)和标记为 [`requiresUserInteraction`](/docs/zh-CN/mcp#require-approval-for-a-specific-tool) 的 MCP 工具即使您已允许它们也会到达它；在 `dontAsk` 模式下这些会被拒绝。请参阅 [`CanUseTool`](#canusetool) 了解详情 |493| `canUseTool` | [`CanUseTool`](#canusetool) | `undefined` | 自定义权限函数，仅在[权限流](/docs/zh-CN/agent-sdk/permissions#how-permissions-are-evaluated)落到提示时调用。不会为 `allowedTools`、allow 规则或 `permissionMode` 自动批准的调用调用。allow 规则不会预先批准[任何模式都不自动批准的操作](/docs/zh-CN/permission-modes#actions-no-mode-auto-approves)；请参阅[权限如何被评估](/docs/zh-CN/agent-sdk/permissions#how-permissions-are-evaluated)了解哪些到达回调以及在 `dontAsk` 和 `auto` 模式下会发生什么。请参阅 [`CanUseTool`](#canusetool) 了解详情 |
480| `continue` | `boolean` | `false` | 继续最近的对话 |494| `continue` | `boolean` | `false` | 继续最近的对话 |
481| `cwd` | `string` | `process.cwd()` | 当前工作目录 |495| `cwd` | `string` | `process.cwd()` | 当前工作目录 |
482| `debug` | `boolean` | `false` | 为 Claude Code 进程启用调试模式 |496| `debug` | `boolean` | `false` | 为 Claude Code 进程启用调试模式 |
483| `debugFile` | `string` | `undefined` | 将调试日志写入特定文件路径。隐式启用调试模式 |497| `debugFile` | `string` | `undefined` | 将调试日志写入特定文件路径。隐式启用调试模式 |
484| `disallowedTools` | `string[]` | `[]` | 要拒绝的工具。裸名称如 `"Bash"` 会从 Claude 的上下文中移除该工具。作用域规则如 `"Bash(rm *)"` 会保留该工具可用，并在每个权限模式（包括 `bypassPermissions`）中拒绝匹配的调用。请参阅[权限](/docs/zh-CN/agent-sdk/permissions#allow-and-deny-rules) |498| `disallowedTools` | `string[]` | `[]` | 要拒绝的工具。裸名称如 `"Bash"` 会从 Claude 的上下文中移除该工具。作用域规则如 `"Bash(rm *)"` 会保留该工具可用，并在每个权限模式（包括 `bypassPermissions`）中拒绝匹配的调用，针对[按照书写方式](/docs/zh-CN/permissions#bash-rule-limits)的命令。请参阅[权限](/docs/zh-CN/agent-sdk/permissions#allow-and-deny-rules) |
485| `effort` | `'low' \| 'medium' \| 'high' \| 'xhigh' \| 'max'` | 模型默认值 | 控制 Claude 在其响应中投入的努力程度。与自适应思考一起工作以指导思考深度。请参阅[调整努力级别](/docs/zh-CN/model-config#adjust-effort-level) |499| `effort` | `'low' \| 'medium' \| 'high' \| 'xhigh' \| 'max'` | `undefined` | 控制 Claude 在其响应中投入的努力程度。与自适应思考一起工作以指导思考深度。请参阅[调整努力级别](/docs/zh-CN/model-config#adjust-effort-level) |
486| `enableFileCheckpointing` | `boolean` | `false` | 启用文件更改跟踪以进行回滚。请参阅[文件 checkpointing](/docs/zh-CN/agent-sdk/file-checkpointing) |500| `enableFileCheckpointing` | `boolean` | `false` | 启用文件更改跟踪以进行回滚。请参阅[文件 checkpointing](/docs/zh-CN/agent-sdk/file-checkpointing) |
487| `env` | `Record<string, string \| undefined>` | `process.env` | 环境变量。设置此选项时，这会替换子进程环境而不是与 `process.env` 合并，因此请传递 `{ ...process.env, YOUR_VAR: 'value' }` 以保留继承的变量如 `PATH`。请参阅[处理缓慢或停滞的 API 响应](#handle-slow-or-stalled-api-responses)了解此模式的示例，以及[环境变量](/docs/zh-CN/env-vars)了解底层 CLI 读取的变量。设置 `CLAUDE_AGENT_SDK_CLIENT_APP` 以在 User-Agent 标头中标识您的应用 |501| `env` | `Record<string, string \| undefined>` | `process.env` | 环境变量。设置此选项时，这会替换子进程环境而不是与 `process.env` 合并，因此请传递 `{ ...process.env, YOUR_VAR: 'value' }` 以保留继承的变量如 `PATH`。请参阅[处理缓慢或停滞的 API 响应](#handle-slow-or-stalled-api-responses)了解此模式的示例，以及[环境变量](/docs/zh-CN/env-vars)了解底层 CLI 读取的变量。设置 `CLAUDE_AGENT_SDK_CLIENT_APP` 以在 User-Agent 标头中标识您的应用 |
488| `executable` | `'bun' \| 'deno' \| 'node'` | 自动检测 | 要使用的 JavaScript 运行时 |502| `executable` | `'bun' \| 'deno' \| 'node'` | 自动检测 | 要使用的 JavaScript 运行时 |
490| `extraArgs` | `Record<string, string \| null>` | `{}` | 其他参数 |504| `extraArgs` | `Record<string, string \| null>` | `{}` | 其他参数 |
491| `fallbackModel` | `string` | `undefined` | 主模型失败时使用的模型 |505| `fallbackModel` | `string` | `undefined` | 主模型失败时使用的模型 |
492| `forkSession` | `boolean` | `false` | 使用 `resume` 恢复时，分叉到新会话 ID 而不是继续原始会话 |506| `forkSession` | `boolean` | `false` | 使用 `resume` 恢复时，分叉到新会话 ID 而不是继续原始会话 |
493| `forwardSubagentText` | `boolean` | `false` | 转发子代理文本和思考块作为助手和用户消息，并设置 `parent_tool_use_id`，以便消费者可以呈现嵌套记录。默认情况下，仅从子代理发出 `tool_use` 和 `tool_result` 块 |507| `forwardSubagentText` | `boolean` | `false` | 转发 subagent 文本和思考块作为助手和用户消息，并设置 `parent_tool_use_id`，以便消费者可以呈现嵌套记录。没有此选项，Claude Code 会发出 subagent `tool_use` 和 `tool_result` 块，但不会发出文本或思考。来自每个嵌套深度的 subagents 的消息在 Claude Code v2.1.219 及更高版本上转发；在 v2.1.219 之前，仅出现来自深度 1 subagents 的消息 |
494| `hooks` | `Partial<Record<`[`HookEvent`](#hookevent)`, `[`HookCallbackMatcher`](#hookcallbackmatcher)`[]>>` | `{}` | 事件的 Hook 回调 |508| `hooks` | `Partial<Record<`[`HookEvent`](#hookevent)`, `[`HookCallbackMatcher`](#hookcallbackmatcher)`[]>>` | `{}` | 事件的 Hook 回调 |
495| `includeHookEvents` | `boolean` | `false` | 在消息流中包括 hook 生命周期事件，作为 [`SDKHookStartedMessage`](#sdkhookstartedmessage)、[`SDKHookProgressMessage`](#sdkhookprogressmessage) 和 [`SDKHookResponseMessage`](#sdkhookresponsemessage)。`SessionStart` 和 `Setup` hooks 的生命周期事件始终包括在内，不需要此选项 |509| `includeHookEvents` | `boolean` | `false` | 在消息流中包括 hook 生命周期事件，作为 [`SDKHookStartedMessage`](#sdkhookstartedmessage)、[`SDKHookProgressMessage`](#sdkhookprogressmessage) 和 [`SDKHookResponseMessage`](#sdkhookresponsemessage)。`SessionStart` 和 `Setup` hooks 的生命周期事件始终包括在内，不需要此选项。某些 hook 事件，如 `Notification`、`SessionEnd`、`PreCompact` 和 `PostCompact`，即使使用此选项也永远不会产生 `SDKHookStartedMessage`。对于这些事件，Claude Code 仍会在运行超过一秒的命令 hook 产生输出时发出 `SDKHookProgressMessage`，并仅在[在后台运行](/docs/zh-CN/hooks#run-hooks-in-the-background)的 hook 完成时发出 `SDKHookResponseMessage` |
496| `includePartialMessages` | `boolean` | `false` | 包括部分消息事件 |510| `includePartialMessages` | `boolean` | `false` | 包括部分消息事件 |
497| `loadTimeoutMs` | `number` | `60000` | *Alpha.* 每个 `sessionStore.load()` 和 `sessionStore.listSubkeys()` 调用在恢复物化期间的超时时间（以毫秒为单位）。如果适配器未在此窗口内解决，查询将失败而不是挂起。未设置 `sessionStore` 时忽略 |511| `loadTimeoutMs` | `number` | `60000` | *Alpha.* 每个 `sessionStore.load()` 和 `sessionStore.listSubkeys()` 调用在恢复物化期间的超时时间（以毫秒为单位）。如果适配器未在此窗口内解决，查询将失败而不是挂起。未设置 `sessionStore` 时忽略 |
498| `managedSettings` | `Settings` | `undefined` | 由生成的父进程提供的策略层设置。当机器上已存在 IT 控制的托管设置层时删除，除非该管理员选择使用 `parentSettingsBehavior: 'merge'`。无论如何都会过滤为仅限制性键 |512| `managedSettings` | `Settings` | `undefined` | 您的主机进程提供给生成的会话的策略层设置。在具有管理员部署的托管设置的机器上，Claude Code 会忽略这些，除非管理员的最高优先级托管源设置 `parentSettingsBehavior: 'merge'`，并且当 [`policyHelper`](/docs/zh-CN/settings-reference#policyhelper) 提供托管设置时永远不会合并它们。合并的值通过仅限制性过滤器；[限制父设置](/docs/zh-CN/claude-apps-gateway#restrict-parent-settings)涵盖过滤器允许的内容和 `allowManaged*Only` 锁。设置 [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](/docs/zh-CN/env-vars) 的主机有三个键直接从此有效负载读取：其在 Claude Code v2.1.222 或更高版本上的[模型配置](/docs/zh-CN/model-config#restrict-model-selection)、当没有托管源在 v2.1.246 或更高版本上设置它时的 [`modelPricing`](/docs/zh-CN/settings-reference#modelpricing)，以及其在 v2.1.247 或更高版本上的 `ENABLE_TOOL_SEARCH` env 条目 |
499| `maxBudgetUsd` | `number` | `undefined` | 当客户端成本估计达到此 USD 值时停止查询。与 `total_cost_usd` 的相同估计进行比较；请参阅[跟踪成本和使用情况](/docs/zh-CN/agent-sdk/cost-tracking)了解准确性注意事项 |513| `maxBudgetUsd` | `number` | `undefined` | 当客户端成本估计达到此 USD 值时停止查询。与 `total_cost_usd` 的相同估计进行比较；请参阅[跟踪成本和使用情况](/docs/zh-CN/agent-sdk/cost-tracking)了解准确性注意事项 |
500| `maxThinkingTokens` | `number` | `undefined` | *已弃用：* 改用 `thinking`。思考过程的最大令牌数 |514| `maxThinkingTokens` | `number` | `undefined` | *已弃用：* 改用 `thinking`。思考过程的最大令牌数 |
501| `maxTurns` | `number` | `undefined` | 最大代理轮次（工具使用往返） |515| `maxTurns` | `number` | `undefined` | 最大代理轮次（工具使用往返） |
507| `pathToClaudeCodeExecutable` | `string` | 从捆绑的本地二进制文件自动解析 | Claude Code 可执行文件的路径。仅在安装期间跳过可选依赖项或您的平台不在支持的集合中时需要 |521| `pathToClaudeCodeExecutable` | `string` | 从捆绑的本地二进制文件自动解析 | Claude Code 可执行文件的路径。仅在安装期间跳过可选依赖项或您的平台不在支持的集合中时需要 |
508| `permissionMode` | [`PermissionMode`](#permissionmode) | `'default'` | 会话的权限模式 |522| `permissionMode` | [`PermissionMode`](#permissionmode) | `'default'` | 会话的权限模式 |
509| `permissionPromptToolName` | `string` | `undefined` | 权限提示的 MCP 工具名称 |523| `permissionPromptToolName` | `string` | `undefined` | 权限提示的 MCP 工具名称 |
524| `permissionPrompts` | `'host' \| 'none'` | `'host'` | 谁回答权限提示：`'host'` 将它们路由到您的 [`canUseTool`](#canusetool) 回调或 `permissionPromptToolName` 工具，`'none'` [拒绝会提示的调用](/docs/zh-CN/agent-sdk/permissions#how-permissions-are-evaluated)。需要 Claude Code v2.1.259 或更高版本 |
510| `persistSession` | `boolean` | `true` | 当为 `false` 时，禁用会话持久化到磁盘。会话之后无法恢复 |525| `persistSession` | `boolean` | `true` | 当为 `false` 时，禁用会话持久化到磁盘。会话之后无法恢复 |
511| `planModeInstructions` | `string` | `undefined` | Plan Mode 的自定义工作流说明。当 `permissionMode` 为 `'plan'` 时，此字符串替换默认 Plan Mode 工作流正文。CLI 仍然使用只读强制前导和 ExitPlanMode 协议页脚包装它 |526| `planModeInstructions` | `string` | `undefined` | Plan Mode 的自定义工作流说明。当 `permissionMode` 为 `'plan'` 时，此字符串替换默认 Plan Mode 工作流正文。CLI 仍然使用只读强制前导和 ExitPlanMode 协议页脚包装它 |
512| `plugins` | [`SdkPluginConfig`](#sdkpluginconfig)`[]` | `[]` | 从本地路径加载自定义 plugins。请参阅[Plugins](/docs/zh-CN/agent-sdk/plugins)了解详情 |527| `plugins` | [`SdkPluginConfig`](#sdkpluginconfig)`[]` | `[]` | 从本地路径加载自定义 plugins。请参阅[Plugins](/docs/zh-CN/agent-sdk/plugins)了解详情 |
513| `promptSuggestions` | `boolean` | `false` | 启用提示建议。在每个轮次后发出 `prompt_suggestion` 消息，包含预测的下一个用户提示 |528| `promptSuggestions` | `boolean` | `false` | 启用提示建议。在每个轮次后，Claude Code 发出 `prompt_suggestion` 消息，包含预测的下一个用户提示。Claude Code 不会为某些轮次生成建议，例如当您的帐户接近或达到其使用限制时。请参阅[Claude Code 何时跳过建议](/docs/zh-CN/interactive-mode#when-claude-code-skips-suggestions) |
514| `resume` | `string` | `undefined` | 要恢复的会话 ID |529| `resume` | `string` | `undefined` | 要恢复的会话 ID |
530| `resumeDropsTurn` | `string` | `undefined` | 使用 `resumeSessionAt`：截断恢复打算丢弃的轮次的提示 UUID。当丢弃的范围包含任何不可归因于该轮次的内容（例如吸收的排队消息或任务通知）时，Claude Code 会拒绝恢复，并在拒绝消息中命名 `--resume-drops-turn` 标志。仅 Agent SDK 和打印模式恢复读取该对。需要 Claude Code v2.1.223 或更高版本 |
515| `resumeSessionAt` | `string` | `undefined` | 在特定消息 UUID 处恢复会话 |531| `resumeSessionAt` | `string` | `undefined` | 在特定消息 UUID 处恢复会话 |
516| `sandbox` | [`SandboxSettings`](#sandboxsettings) | `undefined` | 以编程方式配置 sandbox 行为。请参阅[Sandbox 设置](#sandboxsettings)了解详情 |532| `sandbox` | [`SandboxSettings`](#sandboxsettings) | `undefined` | 以编程方式配置 sandbox 行为。请参阅[Sandbox 设置](#sandboxsettings)了解详情 |
517| `sessionId` | `string` | 自动生成 | 为会话使用特定的 UUID 而不是自动生成一个 |533| `sessionId` | `string` | 自动生成 | 为会话使用特定的 UUID 而不是自动生成一个 |
518| `sessionStore` | [`SessionStore`](/docs/zh-CN/agent-sdk/session-storage#the-sessionstore-interface) | `undefined` | 将会话记录镜像到外部后端，以便任何主机都可以恢复它们。请参阅[将会话持久化到外部存储](/docs/zh-CN/agent-sdk/session-storage) |534| `sessionStore` | [`SessionStore`](/docs/zh-CN/agent-sdk/session-storage#the-sessionstore-interface) | `undefined` | 将会话记录镜像到外部后端，以便另一个主机可以恢复它们。请参阅[将会话持久化到外部存储](/docs/zh-CN/agent-sdk/session-storage) |
519| `sessionStoreFlush` | `'batched' \| 'eager'` | `'batched'` | *Alpha.* `sessionStore` 的刷新模式。未设置 `sessionStore` 时忽略 |535| `sessionStoreFlush` | `'batched' \| 'eager'` | `'batched'` | *Alpha.* `sessionStore` 的刷新模式。未设置 `sessionStore` 时忽略 |
520| `settings` | `string \| Settings` | `undefined` | 内联[设置](/docs/zh-CN/settings)对象或设置文件的路径。填充[优先级顺序](/docs/zh-CN/settings#settings-precedence)中的标志设置层。使用 [`applyFlagSettings()`](#applyflagsettings) 在运行时更改 |536| `settings` | `string \| Settings` | `undefined` | 内联[设置](/docs/zh-CN/settings)对象或设置文件的路径。填充[优先级顺序](/docs/zh-CN/settings#settings-precedence)中的标志设置层。使用 [`applyFlagSettings()`](#applyflagsettings) 在运行时更改 |
521| `settingSources` | [`SettingSource`](#settingsource)`[]` | CLI 默认值（所有源） | 控制加载哪些文件系统设置。传递 `[]` 以禁用用户、项目和本地设置。[端点管理的策略](/docs/zh-CN/settings#settings-files)无论如何都会加载；当会话使用组织凭证在[符合条件的配置](/docs/zh-CN/server-managed-settings#platform-availability)上进行身份验证时，会获取服务器管理的设置。请参阅[使用 Claude Code 功能](/docs/zh-CN/agent-sdk/claude-code-features#what-settingsources-does-not-control) |537| `settingSources` | [`SettingSource`](#settingsource)`[]` | CLI 默认值（所有源） | 控制加载哪些文件系统设置。传递 `[]` 以禁用用户、项目和本地设置。[端点管理的策略](/docs/zh-CN/managed-settings#delivery-mechanisms)无论如何都会加载；当会话使用组织凭证在[符合条件的配置](/docs/zh-CN/server-managed-settings#platform-availability)上进行身份验证时，会获取服务器管理的设置。请参阅[使用 Claude Code 功能](/docs/zh-CN/agent-sdk/claude-code-features#what-settingsources-does-not-control) |
522| `skills` | `string[] \| 'all'` | `undefined` | 会话可用的 skills。传递 `'all'` 以启用每个发现的 skill，或传递 skill 名称列表。设置后，SDK 会自动将 Skill 工具添加到 `allowedTools`。如果您也传递 `tools`，请在该列表中包含 `'Skill'`。请参阅[Skills](/docs/zh-CN/agent-sdk/skills) |538| `skills` | `string[] \| 'all'` | `undefined` | 会话可用的 skills。传递 `'all'` 以启用每个发现的 skill，或传递 skill 名称列表。仅传递确切名称。在 Agent SDK v0.3.221 或更高版本上，SDK 在启动 Claude Code 进程之前会以错误拒绝格式错误和通配符形式的名称。设置后，SDK 会自动将 Skill 工具添加到 `allowedTools`。如果您也传递 `tools`，请在该列表中包含 `'Skill'`。请参阅[Skills](/docs/zh-CN/agent-sdk/skills) |
523| `spawnClaudeCodeProcess` | `(options: SpawnOptions) => SpawnedProcess` | `undefined` | 用于生成 Claude Code 进程的自定义函数。用于在 VM、容器或远程环境中运行 Claude Code |539| `spawnClaudeCodeProcess` | `(options: SpawnOptions) => SpawnedProcess` | `undefined` | 用于生成 Claude Code 进程的自定义函数。用于在 VM、容器或远程环境中运行 Claude Code |
524| `stderr` | `(data: string) => void` | `undefined` | stderr 输出的回调 |540| `stderr` | `(data: string) => void` | `undefined` | stderr 输出的回调 |
525| `strictMcpConfig` | `boolean` | `false` | 仅使用在 `mcpServers` 中传递的服务器，并忽略项目 `.mcp.json`、用户设置、plugin 提供的 MCP 服务器和[claude.ai connectors](/docs/zh-CN/mcp#use-mcp-servers-from-claude-ai) |541| `strictMcpConfig` | `boolean` | `false` | 仅使用在 `mcpServers` 中传递的服务器，并忽略项目 `.mcp.json`、用户设置、plugin 提供的 MCP 服务器和[claude.ai connectors](/docs/zh-CN/mcp#use-mcp-servers-from-claude-ai) |
526| `systemPrompt` | `string \| { type: 'preset'; preset: 'claude_code'; append?: string; excludeDynamicSections?: boolean }` | `undefined`（最小提示） | 系统提示配置。传递字符串以获取自定义提示，或 `{ type: 'preset', preset: 'claude_code' }` 以使用 Claude Code 的系统提示。使用预设对象形式时，添加 `append` 以使用其他说明扩展它，并设置 `excludeDynamicSections: true` 以将每个会话上下文移到第一条用户消息中，以便[更好地跨机器重用提示缓存](/docs/zh-CN/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines) |542| `systemPrompt` | `string \| string[] \| { type: 'custom'; prompt: string \| string[]; snapshot?: boolean } \| { type: 'preset'; preset: 'claude_code'; append?: string; excludeDynamicSections?: boolean; snapshot?: boolean }` | `undefined`（最小提示） | 系统提示配置。传递字符串以获取自定义提示，或 `{ type: 'preset', preset: 'claude_code' }` 以使用 Claude Code 的系统提示。传递一个字符串数组，其中包含导出的 `SYSTEM_PROMPT_DYNAMIC_BOUNDARY` 常量在静态和每个请求部分之间，以[缓存自定义提示的静态部分](/docs/zh-CN/agent-sdk/modifying-system-prompts#cache-the-static-part-of-a-custom-prompt)。使用预设对象形式时，添加 `append` 以使用其他说明扩展它，并设置 `excludeDynamicSections: true` 以将每个会话上下文移到第一条用户消息中，以便[更好地跨机器重用提示缓存](/docs/zh-CN/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines)。设置 `snapshot: false` 以在每个请求上重建提示，而不是[重用会话在其第一个请求上记录的提示](/docs/zh-CN/agent-sdk/modifying-system-prompts#change-the-prompt-of-an-existing-session)。要在自定义提示上设置 `snapshot`，请传递 `{ type: 'custom', prompt }` 形式。`{ type: 'custom' }` 形式和 `snapshot` 字段需要 TypeScript Agent SDK v0.3.257 或更高版本 |
527| `taskBudget` | `{ total: number }` | `undefined` | *Alpha.* API 端任务预算（以令牌为单位）。设置后，模型会被告知其剩余令牌预算，以便它可以调整工具使用速度并在达到限制前完成 |543| `taskBudget` | `{ total: number }` | `undefined` | *Alpha.* API 端任务预算（以令牌为单位）。设置后，模型会被告知其剩余令牌预算，以便它可以调整工具使用速度并在达到限制前完成 |
528| `thinking` | [`ThinkingConfig`](#thinkingconfig) | 支持的模型为 `{ type: 'adaptive' }` | 控制 Claude 的思考/推理行为。请参阅 [`ThinkingConfig`](#thinkingconfig) 了解选项 |544| `thinking` | [`ThinkingConfig`](#thinkingconfig) | 支持的模型为 `{ type: 'adaptive' }` | 控制 Claude 的思考/推理行为。请参阅 [`ThinkingConfig`](#thinkingconfig) 了解选项 |
529| `title` | `string` | `undefined` | 会话的显示标题。通过 `resume` 或 `continue` 恢复时，恢复的会话的持久化标题优先；使用 [`renameSession()`](#renamesession) 重新标题现有会话 |545| `title` | `string` | `undefined` | 会话的显示标题。通过 `resume` 或 `continue` 恢复时，恢复的会话的持久化标题优先；使用 [`renameSession()`](#renamesession) 重新标题现有会话 |
538CLI 子进程读取多个环境变量，这些变量控制 API 超时和停滞检测。通过 `env` 选项传递它们：554CLI 子进程读取多个环境变量，这些变量控制 API 超时和停滞检测。通过 `env` 选项传递它们：
539 555
540```typescript theme={null}556```typescript theme={null}
557import { query } from "@anthropic-ai/claude-agent-sdk";
558
541const result = query({559const result = query({
542 prompt: "Analyze this code",560 prompt: "Analyze this code",
543 options: {561 options: {
551});569});
552```570```
553 571
554* `API_TIMEOUT_MS`：Anthropic 客户端上的每个请求超时，以毫秒为单位。默认 `600000`。适用于主循环和所有子代理。572* `API_TIMEOUT_MS`：Anthropic 客户端上的每个请求超时，以毫秒为单位。默认 `600000`。适用于主循环和所有 subagents。
555* `CLAUDE_CODE_MAX_RETRIES`：最大 API 重试次数。默认 `10`，上限为 `15`。每次重试都有自己的 `API_TIMEOUT_MS` 窗口，因此最坏情况下的实际时间大约是 `API_TIMEOUT_MS × (CLAUDE_CODE_MAX_RETRIES + 1)` 加上退避。对于需要等待更长时间中断的无人值守运行，设置 `CLAUDE_CODE_RETRY_WATCHDOG=1`：它无限期重试容量错误，从 Claude Code v2.1.199 开始，为其他瞬时错误提高默认值至 `300` 并移除此变量的上限。573* `CLAUDE_CODE_MAX_RETRIES`：最大 API 重试次数。默认 `10`，上限为 `15`。每次重试都有自己的 `API_TIMEOUT_MS` 窗口，因此最坏情况下的实际时间大约是 `API_TIMEOUT_MS × (CLAUDE_CODE_MAX_RETRIES + 1)` 加上退避。对于需要等待更长时间中断的无人值守运行，设置 [`CLAUDE_CODE_RETRY_WATCHDOG=1`](/docs/zh-CN/errors#tune-retry-behavior)：它无限期重试瞬时容量错误，从 Claude Code v2.1.199 开始，为其他瞬时错误提高默认值至 `300` 并移除此变量的上限。
556* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`：使用 `run_in_background` 启动的子代理的停滞监视程序。默认 `600000`。在每个流事件上重置；在停滞时中止子代理，将任务标记为失败，并将错误与任何部分结果一起呈现给父级。不适用于同步子代理。574* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`：subagents 的停滞监视程序。当流监视程序打开时，默认值为 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 加 5 分钟，即 `600000`，除非您提高该变量。当流监视程序关闭时，默认值为 `600000`。在 v2.1.257 之前，默认值始终为 `600000`。
557* `CLAUDE_ENABLE_STREAM_WATCHDOG` 与 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`：当标头已到达但响应正文停止流式传输时中止请求。监视程序对所有提供商默认启用；设置 `CLAUDE_ENABLE_STREAM_WATCHDOG=0` 以禁用它。`CLAUDE_STREAM_IDLE_TIMEOUT_MS` 默认为 `300000` 并被限制为该最小值。中止的请求通过正常重试路径进行。575
576 计时器在每个流事件上重置。在停滞时，Claude Code 中止 subagent 并向父级报告停滞。对于后台 subagent，它也会将任务标记为失败并附加任何部分结果。
577* `CLAUDE_ENABLE_STREAM_WATCHDOG` 与 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`：当标头已到达但响应正文停止流式传输时中止请求的流监视程序。监视程序对所有提供商默认启用；设置 `CLAUDE_ENABLE_STREAM_WATCHDOG=0` 以禁用它。`CLAUDE_STREAM_IDLE_TIMEOUT_MS` 默认为 `300000` 并被限制为该最小值。中止后，[自动重试](/docs/zh-CN/errors#automatic-retries)涵盖 Claude Code 根据响应进度的程度所做的事情。
578
579 当监视程序等待 `ANTHROPIC_BASE_URL` 后面的网关用保活 ping 保持打开的响应时，设置 `includePartialMessages` 的主机继续接收 `ping` [流事件](#sdkpartialassistantmessage)，因此将这些帧读作活跃性而不是在沉默时超时会话。在 v2.1.257 之前，帧在最后一个真实流事件后 5 分钟停止。
558 580
559<h3 id="query-object">581<h3 id="query-object">
560 `Query` 对象582 `Query` 对象
572 setPermissionMode(mode: PermissionMode): Promise<void>;594 setPermissionMode(mode: PermissionMode): Promise<void>;
573 setModel(model?: string): Promise<void>;595 setModel(model?: string): Promise<void>;
574 setMaxThinkingTokens(maxThinkingTokens: number | null): Promise<void>;596 setMaxThinkingTokens(maxThinkingTokens: number | null): Promise<void>;
575 applyFlagSettings(settings: { [K in keyof Settings]?: Settings[K] | null }): Promise<void>;597 applyFlagSettings(settings: {
598 [K in keyof Settings]?: K extends 'effortLevel'
599 ? 'low' | 'medium' | 'high' | 'xhigh' | 'max' | null
600 : Settings[K] | null;
601 }): Promise<void>;
602 updateSettings(
603 source: 'localSettings',
604 settings: Record<string, unknown>,
605 ): Promise<void>;
576 initializationResult(): Promise<SDKControlInitializeResponse>;606 initializationResult(): Promise<SDKControlInitializeResponse>;
577 reinitialize(): Promise<SDKControlInitializeResponse>;607 reinitialize(): Promise<SDKControlInitializeResponse>;
578 supportedCommands(): Promise<SlashCommand[]>;608 supportedCommands(): Promise<SlashCommand[]>;
579 supportedModels(): Promise<ModelInfo[]>;609 supportedModels(): Promise<ModelInfo[]>;
580 supportedAgents(): Promise<AgentInfo[]>;610 supportedAgents(): Promise<AgentInfo[]>;
581 mcpServerStatus(): Promise<McpServerStatus[]>;611 mcpServerStatus(): Promise<McpServerStatus[]>;
612 getContextUsage(opts?: {
613 detail?: 'summary' | 'full';
614 }): Promise<SDKControlGetContextUsageResponse>;
615 readFile(
616 path: string,
617 options?: { maxBytes?: number; encoding?: 'utf-8' | 'base64' }
618 ): Promise<SDKControlReadFileResponse | null>;
619 reloadSkills(): Promise<SDKControlReloadSkillsResponse>;
582 accountInfo(): Promise<AccountInfo>;620 accountInfo(): Promise<AccountInfo>;
583 reconnectMcpServer(serverName: string): Promise<void>;621 reconnectMcpServer(serverName: string): Promise<void>;
584 toggleMcpServer(serverName: string, enabled: boolean): Promise<void>;622 toggleMcpServer(serverName: string, enabled: boolean): Promise<void>;
594</h4>632</h4>
595 633
596| 方法 | 描述 |634| 方法 | 描述 |
597| :------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |635| :------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
598| `interrupt()` | 中断查询。仅在流式输入模式下可用。当 CLI 在 [`SDKSystemMessage.capabilities`](#sdksystemmessage) 中通告 `interrupt_receipt_v1` 功能时，使用列出存活中断的排队消息的 [`SDKControlInterruptResponse`](#sdkcontrolinterruptresponse) 进行解决。在 v2.1.205 之前的 CLI 上解决为 `undefined` |636| `interrupt()` | 中断查询。仅在流式输入模式下可用。当 CLI 在 [`SDKSystemMessage.capabilities`](#sdksystemmessage) 中通告 `interrupt_receipt_v1` 功能时，使用列出中断时待处理的消息的 [`SDKControlInterruptResponse`](#sdkcontrolinterruptresponse) 进行解决。在 v2.1.205 之前的 CLI 上解决为 `undefined` |
599| `rewindFiles(userMessageId, options?)` | 将文件恢复到指定用户消息时的状态。传递 `{ dryRun: true }` 以预览更改。需要 `enableFileCheckpointing: true`。请参阅[文件 checkpointing](/docs/zh-CN/agent-sdk/file-checkpointing) |637| `rewindFiles(userMessageId, options?)` | 将文件恢复到指定用户消息时的状态。传递 `{ dryRun: true }` 以预览更改。需要 `enableFileCheckpointing: true`。请参阅[文件 checkpointing](/docs/zh-CN/agent-sdk/file-checkpointing) |
600| `setPermissionMode()` | 更改权限模式（仅在流式输入模式下可用） |638| `setPermissionMode()` | 更改权限模式（仅在流式输入模式下可用） |
601| `setModel()` | 更改模型（仅在流式输入模式下可用） |639| `setModel()` | 更改模型（仅在流式输入模式下可用）。传递 `undefined` 或字符串 `"default"` 重置为会话默认模型 |
602| `setMaxThinkingTokens()` | *已弃用：* 改用 `thinking` 选项。更改最大思考令牌数。传递 `null` 会将思考重置为会话默认值：清除中期覆盖，对于禁用思考的会话思考保持关闭 |640| `setMaxThinkingTokens()` | *已弃用：* 改用 `thinking` 选项。更改最大思考令牌数。传递 `null` 会将思考重置为会话默认值：清除中期覆盖，对于禁用思考的会话思考保持关闭 |
603| `applyFlagSettings(settings)` | 在运行时将设置合并到会话的标志设置层中（仅在流式输入模式下可用）。请参阅 [`applyFlagSettings()`](#applyflagsettings) |641| `applyFlagSettings(settings)` | 在运行时将设置合并到会话的标志设置层中（仅在流式输入模式下可用）。请参阅 [`applyFlagSettings()`](#applyflagsettings) |
642| `updateSettings(source, settings)` | 将设置合并到项目的本地设置文件 `.claude/settings.local.json` 中；它们在下一个请求时生效。仅接受 `source: 'localSettings'` 和允许列表键集，目前为 `outputStyle`，带有字符串值；不支持删除键。在远程传输和 [`settingSources`](#options) 排除 `local` 的会话中拒绝。需要 TypeScript SDK v0.3.257 或更高版本，它捆绑 Claude Code v2.1.257 |
604| `initializationResult()` | 返回完整的初始化结果，包括支持的命令、模型、帐户信息和输出样式配置 |643| `initializationResult()` | 返回完整的初始化结果，包括支持的命令、模型、帐户信息和输出样式配置 |
605| `reinitialize()` | 重新发送 `initialize` 控制请求到运行的 CLI，并返回新的结果而不是缓存的首次连接结果。在传输间隙后使用它，例如在断开连接后重新连接到会话，以便待处理的权限请求再次到达您的 `canUseTool` 回调。使回调对每个请求 ID 幂等，因为响应丢失的请求会再次分派。需要 Claude Code v2.1.195 或更高版本 |644| `reinitialize()` | 重新发送 `initialize` 控制请求到运行的 CLI，并返回新的结果而不是缓存的首次连接结果。在传输间隙后使用它，例如在断开连接后重新连接到会话，以便待处理的权限请求再次到达您的 `canUseTool` 回调。使回调对每个请求 ID 幂等，因为响应丢失的请求会再次分派。需要 Claude Code v2.1.195 或更高版本 |
606| `supportedCommands()` | 返回可用的 slash commands |645| `supportedCommands()` | 返回可用的 slash commands。从 Agent SDK v0.3.216 开始，列表反映中期命令更改；请参阅 [`SDKCommandsChangedMessage`](#sdkcommandschangedmessage) |
607| `supportedModels()` | 返回具有显示信息的可用模型 |646| `supportedModels()` | 返回具有显示信息的可用模型 |
608| `supportedAgents()` | 返回可用的子代理作为 [`AgentInfo`](#agentinfo)`[]` |647| `supportedAgents()` | 返回可用的 subagents 作为 [`AgentInfo`](#agentinfo)`[]` |
609| `mcpServerStatus()` | 返回连接的 MCP 服务器的状态 |648| `mcpServerStatus()` | 返回连接的 MCP 服务器的状态 |
649| `getContextUsage(opts?)` | 返回 [`SDKControlGetContextUsageResponse`](#sdkcontrolgetcontextusageresponse)，按类别、skill 和工具分解会话的上下文窗口使用情况。使用默认 `detail`，它与 `/context` 在交互式会话中显示的数据相同。[`detail` 选项](#sdkcontrolgetcontextusageresponse)需要 Agent SDK v0.3.257 或更高版本 |
650| `readFile(path, options?)` | 从会话的文件系统读取文件。Claude Code 根据 `cwd` 解析路径；[`readFile()` 可以读取什么](#what-readfile-can-read)列出它提供的文件。传递 `{ maxBytes }` 以更改读取上限（默认 1 MB，上限 10 MB）和 `{ encoding: 'base64' }` 用于二进制文件，如图像。使用 [`SDKControlReadFileResponse`](#sdkcontrolreadfileresponse) 进行解决，或在权限拒绝、文件丢失或传输错误时使用 `null`。需要 TypeScript SDK v0.2.121 或更高版本 |
651| `reloadSkills()` | 从磁盘重新加载 skills，以便您在会话中期添加或编辑的 skills 对运行的会话可用。使用 [`SDKControlReloadSkillsResponse`](#sdkcontrolreloadskillsresponse) 进行解决，列出重新加载后可用的 skills。需要 Agent SDK v0.3.163 或更高版本 |
610| `accountInfo()` | 返回帐户信息 |652| `accountInfo()` | 返回帐户信息 |
611| `reconnectMcpServer(serverName)` | 按名称重新连接 MCP 服务器 |653| `reconnectMcpServer(serverName)` | 按名称重新连接 MCP 服务器。如果名称也匹配设置文件（如 `.mcp.json` 或 `~/.claude.json`）中的条目，Claude Code 会重新连接您通过 [`mcpServers`](#options) 或 `setMcpServers()` 配置的服务器，而不是设置文件条目。该解析顺序需要 Claude Code v2.1.257 或更高版本 |
612| `toggleMcpServer(serverName, enabled)` | 按名称启用或禁用 MCP 服务器 |654| `toggleMcpServer(serverName, enabled)` | 按名称启用或禁用 MCP 服务器，名称解析与 `reconnectMcpServer()` 相同。禁用会断开服务器连接 |
613| `setMcpServers(servers)` | 动态替换此会话的 MCP 服务器集。返回有关添加、删除的服务器和任何错误的信息 |655| `setMcpServers(servers)` | 动态替换此会话的 MCP 服务器集。使用 [`McpSetServersResult`](#mcpsetserversresult) 进行解决，命名添加和删除的服务器以及任何错误 |
614| `streamInput(stream)` | 将输入消息流式传输到查询以进行多轮对话 |656| `streamInput(stream)` | 将输入消息流式传输到查询以进行多轮对话 |
615| `stopTask(taskId)` | 按 ID 停止运行的后台任务 |657| `stopTask(taskId)` | 按 ID 停止运行的后台任务 |
616| `close()` | 关闭查询并终止底层进程。强制结束查询并清理所有资源 |658| `close()` | 关闭查询并终止底层进程。强制结束查询并清理所有资源 |
619 `applyFlagSettings()`661 `applyFlagSettings()`
620</h4>662</h4>
621 663
622在运行的会话上更改任何[设置](/docs/zh-CN/settings)而无需重新启动查询。当没有专用设置器的设置需要在会话中期更改时使用它，例如在代理读取不受信任的输入后收紧 `permissions`。`setModel()` 和 `setPermissionMode()` 是这两个键的专用设置器；`applyFlagSettings()` 是接受任何设置键子集的通用形式，在此处传递 `model` 的行为与 `setModel()` 相同。664在运行的会话上更改[设置](/docs/zh-CN/settings)而无需重新启动查询。当没有专用设置器的设置需要在会话中期更改时使用它，例如在代理读取不受信任的输入后收紧 `permissions`。`setModel()` 和 `setPermissionMode()` 是这两个键的专用设置器；`applyFlagSettings()` 是接受任何设置键子集的通用形式，在此处传递 `model` 的行为与 `setModel()` 相同。
623 665
624仅某些键在会话中期生效：666仅某些键在会话中期生效：
625 667
626* **在下一个轮次应用**：`model`、`effortLevel`、`ultracode`、`permissions`、`hooks`、`skillOverrides`、`fastMode`、`agent`。切换 `agent` 也会在下一个轮次应用该代理的模型覆盖、hooks 和系统提示。668* **在下一个轮次应用**：`effortLevel`、`ultracode`、`permissions`、`hooks`、`skillOverrides`、`fastMode`、`agent`。切换 `agent` 也会在下一个轮次应用该代理的模型覆盖和 hooks。其系统提示在下一个轮次应用，或在[重用记录的系统提示](/docs/zh-CN/agent-sdk/modifying-system-prompts#change-the-prompt-of-an-existing-session)的会话中，一旦会话被压缩。
669* **在当前轮次应用**：`model`。如果您在 Claude 处理轮次时切换 `model`，Claude 已在生成的响应在旧模型上完成，轮次的其余部分（从 Claude Code 对模型进行的下一个调用开始）使用新模型。Subagents 保持自己的模型。在 v2.1.212 之前，中期切换等待下一个轮次。
627* **会话中期无效**：系统提示选项。这些在启动时解决一次，因此运行的会话保持原始值，即使调用成功。要更改它们，请启动新会话。670* **会话中期无效**：系统提示选项。这些在启动时解决一次，因此运行的会话保持原始值，即使调用成功。要更改它们，请启动新会话。
628 671
629`effortLevel` 接受一个[努力级别](/docs/zh-CN/model-config#adjust-effort-level)名称。它也接受 `"ultracode"`，它以 `xhigh` 努力运行会话并打开[ultracode](/docs/zh-CN/workflows#let-claude-decide-with-ultracode)。`Settings` 类型声明 `effortLevel` 不包含该值，因此在 TypeScript 中传递等效的 `{ ultracode: true }`。`ultracode` 值需要 Claude Code v2.1.203 或更高版本，仅由 `applyFlagSettings()` 接受，不由设置文件中的 `effortLevel` 键接受。672`effortLevel` 接受一个[努力级别](/docs/zh-CN/model-config#adjust-effort-level)名称。它也接受 `"ultracode"`，它请求 `xhigh` 努力与[ultracode](/docs/zh-CN/workflows#let-claude-decide-with-ultracode)打开。`applyFlagSettings()` 声明 `effortLevel` 不包含该值，因此在 TypeScript 中传递等效的 `{ ultracode: true }`。`ultracode` 值需要 Claude Code v2.1.203 或更高版本，仅由 `applyFlagSettings()` 接受，不由设置文件中的 `effortLevel` 键接受。
630 673
631这些值被写入标志设置层，这是内联 `query()` 的 `settings` 选项在启动时填充的同一层。标志设置位于[设置优先级顺序](/docs/zh-CN/settings#settings-precedence)的顶部附近：它们覆盖用户、项目和本地设置，只有托管策略设置可以覆盖它们。这与[优先级部分](#settings-precedence)称为编程选项的层相同。674这些值被写入标志设置层，这是内联 `query()` 的 `settings` 选项在启动时填充的同一层。这与[优先级部分](#settings-precedence)称为编程选项的层相同。
632 675
633连续调用浅合并顶级键。第二次调用 `{ permissions: {...} }` 会替换先前调用中的整个 `permissions` 对象，而不是深度合并到其中。要从标志层清除键并回退到较低优先级源，请为该键传递 `null`。传递 `undefined` 无效，因为 JSON 序列化会将其删除。676连续调用浅合并顶级键。第二次调用 `{ permissions: {...} }` 会替换先前调用中的整个 `permissions` 对象，而不是深度合并到其中。要从标志层清除键并回退到较低优先级源，请为该键传递 `null`。传递 `undefined` 无效，因为 JSON 序列化会将其删除。
634 677
637下面的示例在会话中期切换活动模型，然后清除覆盖，以便模型回退到用户或项目设置指定的任何内容。680下面的示例在会话中期切换活动模型，然后清除覆盖，以便模型回退到用户或项目设置指定的任何内容。
638 681
639```typescript theme={null}682```typescript theme={null}
683import { query } from "@anthropic-ai/claude-agent-sdk";
684
640const q = query({ prompt: messageStream });685const q = query({ prompt: messageStream });
641 686
642// 覆盖会话其余部分的模型687// 覆盖会话其余部分的模型
689 models: ModelInfo[];734 models: ModelInfo[];
690 account: AccountInfo;735 account: AccountInfo;
691 fast_mode_state?: "off" | "cooldown" | "on";736 fast_mode_state?: "off" | "cooldown" | "on";
737 fast_mode_disabled_reason?: FastModeDisabledReason;
738 hooks_applied?: boolean;
692};739};
693```740```
694 741
695当客户端向已运行的会话发送 `initialize` 时，控制响应包装器也会携带一个可选的 `pending_permission_requests` 数组。该字段位于响应包装器本身，而不是上面的 `SDKControlInitializeResponse` 有效负载中。每个条目都是一个完整的 `control_request` 消息，具有与会话在运行时为权限请求流式传输的相同 `{ type: "control_request", request_id, request }` 形状。742`hooks_applied` 报告 Claude Code 是否注册了 `initialize` 请求携带的 `hooks`。SDK 在会话启动时发送该请求一次，并在每个 [`reinitialize()`](#query-object) 调用上再次发送。该字段需要 Agent SDK v0.3.238 或更高版本。
743
744当请求不携带 hooks 时，Claude Code 会省略该字段。当请求携带 hooks 时，该值取决于请求是否是会话的第一个初始化，以及对于重复的请求，它如何到达会话：
745
746* `true`：Claude Code 注册了 hooks。会话的第一个初始化返回此值。通过 CLI 的 stdin 发送的重复初始化也返回 `true`。在这种情况下，新请求中的 hooks 替换之前注册的 hooks。
747* `false`：Claude Code 忽略了 hooks。发送到远程会话的重复初始化返回此值，因此加入会话的第二个客户端无法替换第一个客户端注册的 hooks。
748
749在 Agent SDK v0.3.238 之前，响应从不携带该字段，Claude Code 在每个重复初始化上忽略 `hooks`。
696 750
697这些是在客户端连接之前发出的请求，仍在等待回复。SDK 为您读取数组并将每个条目分派到您的 [`canUseTool`](#canusetool) 回调，这与 [`reinitialize()`](#query-object) 在传输间隙后触发的相同重新发送。使用重复的请求 ID 幂等地处理，因为条目可以重复回调已在连接断开前收到的请求。751响应始终报告 `fast_mode_state`，当某些东西阻止[快速模式](/docs/zh-CN/fast-mode)时，`fast_mode_disabled_reason` 携带原因代码，以便您可以解释阻止的状态而不是重新推导可用性。两种行为都需要 Claude Code v2.1.219 或更高版本。在 v2.1.219 之前，当快速模式不可用时响应会省略 `fast_mode_state`，并且从不携带原因。有关原因代码及其含义，请参阅结果消息上的 [`fast_mode_disabled_reason`](#sdkresultmessage)。
752
753成功 `initialize` 的控制响应包装器也携带 `pending_permission_requests` 数组。该字段位于响应包装器本身，而不是上面的 `SDKControlInitializeResponse` 有效负载中。每个条目都是一个完整的 `control_request` 消息，具有与会话在运行时为权限请求流式传输的相同 `{ type: "control_request", request_id, request }` 形状。
754
755该数组列出此 Claude Code 进程已发出且尚未解决的权限请求。SDK 为您读取数组并将每个条目分派到您的 [`canUseTool`](#canusetool) 回调，这与 [`reinitialize()`](#query-object) 在传输间隙后触发的相同重新发送。使用重复的请求 ID 幂等地处理，因为条目可以重复回调已在连接断开前收到的请求。
756
757该数组在成功 `initialize` 响应上始终存在，当此进程没有未解决的权限请求时为空。需要 Claude Code v2.1.268 或更高版本。较早的版本可能会省略该字段，因此如果您自己解析线路协议，请将缺失的字段视为较旧的 CLI，而不是没有待处理的证明。
698 758
699<h3 id="sdkcontrolinterruptresponse">759<h3 id="sdkcontrolinterruptresponse">
700 `SDKControlInterruptResponse`760 `SDKControlInterruptResponse`
705```typescript theme={null}765```typescript theme={null}
706type SDKControlInterruptResponse = {766type SDKControlInterruptResponse = {
707 still_queued: string[];767 still_queued: string[];
768 cancelled?: string[];
708};769};
709```770```
710 771
711`still_queued` 列出存活中断的用户消息的 UUID：仍在队列中的消息，加上已为下一个轮次出队但尚未被中止到达的任何批次。除非您首先取消它，否则每个都作为其自己的轮次在中断后运行。使用收据来决定是否重新发送任何内容；重新发送已列出的消息会产生重复的轮次。772`still_queued` 列出中断时待处理的用户消息的 UUID：仍在队列中的消息，加上 Claude Code 已从队列中取出用于下一个轮次的任何消息。除非您首先取消它，否则每个都在中断后作为其自己的轮次运行。如果您在第一个轮次启动之前中断，Claude Code 会在轮次启动时立即中止该轮次，该轮次中列出的消息不会获得响应。
773
774使用收据来决定是否重新发送任何内容。列出的消息如果您不取消它会进入对话，因此重新发送它会向 Claude 传递两次。
712 775
713使用这些注意事项解释列表：776使用这些注意事项解释列表：
714 777
715* 仅出现已使用 UUID 入队的消息。空数组并不意味着没有其他内容会运行。778* 仅出现已使用 UUID 入队的消息。空数组并不意味着没有其他内容会运行。
716* 仅列出主线程消息。寻址到子代理的消息超出范围。779* 仅列出主线程消息。寻址到 subagent 的消息超出范围。
717* 列表可以包括您的客户端从未发送的 UUID，例如[计划任务](/docs/zh-CN/scheduled-tasks)触发器。忽略您不识别的 UUID，而不是将其视为错误。780* 列表可以包括您的客户端从未发送的 UUID，例如[计划任务](/docs/zh-CN/scheduled-tasks)触发器。忽略您不识别的 UUID，而不是将其视为错误。
718 781
782直接驱动 CLI 控制协议的客户端（而不是通过 `interrupt()`）可以在 `interrupt` 控制请求上设置 `cancel_queued: true`。Claude Code v2.1.219 及更高版本在 [`SDKSystemMessage.capabilities`](#sdksystemmessage) 中通告 `interrupt_cancel_queued_v1` 功能的支持；较早的 CLI 忽略该字段并让排队的消息照常运行。这样的中断也会取消每条否则会在 `still_queued` 下列出的消息：收据在 `cancelled` 下列出它们，`still_queued` 为空，它们都不运行。
783
784`cancelled` 列表与 `still_queued` 具有相同的注意事项。`interrupt()` 方法从不发送 `cancel_queued`，因此它解决的收据不携带 `cancelled`。
785
719收据是在处理中断时拍摄的快照，在干净中断时，它在中断轮次的 [`SDKResultMessage`](#sdkresultmessage) 之前到达。在该结果之后读取收据而不是检查队列：循环立即启动下一个排队的轮次，因此您在结果后检查的队列已经改变。786收据是在处理中断时拍摄的快照，在干净中断时，它在中断轮次的 [`SDKResultMessage`](#sdkresultmessage) 之前到达。在该结果之后读取收据而不是检查队列：循环立即启动下一个排队的轮次，因此您在结果后检查的队列已经改变。
720 787
788<h3 id="sdkcontrolgetcontextusageresponse">
789 `SDKControlGetContextUsageResponse`
790</h3>
791
792[`getContextUsage()`](#query-object) 的返回类型。使用默认 `detail`，这是 Claude Code 在交互式会话中为 `/context` 命令呈现的相同有效负载，因此除了令牌计数外，它还携带显示字段，如 `color` 和 `gridRows`，Claude Code 使用这些字段来绘制 `/context` 使用情况网格。
793
794该方法的可选 `detail` 参数选择 Claude Code 如何计算每个类别。使用默认值 `'full'`，Claude Code 使用令牌计数 API 请求计算每个类别。传递 `{ detail: 'summary' }` 以从最后一个响应的使用情况和本地估计获取答案。没有令牌计数请求出去，每个类别的数字是近似的。`detail` 参数需要 Agent SDK v0.3.257 或更高版本。
795
796当您发送 `/context` 作为提示而不是调用该方法时，Claude Code 会将 [`SDKContextUsage`](#sdkcontextusage) 有效负载附加到传递结果的助手消息的 `context_usage` 字段。该字段需要 Agent SDK v0.3.232 或更高版本。
797
798```typescript theme={null}
799type SDKControlGetContextUsageResponse = {
800 categories: {
801 name: string;
802 tokens: number;
803 color: string;
804 isDeferred?: boolean;
805 }[];
806 totalTokens: number;
807 maxTokens: number;
808 rawMaxTokens: number;
809 percentage: number;
810 gridRows: {
811 color: string;
812 isFilled: boolean;
813 categoryName: string;
814 tokens: number;
815 percentage: number;
816 squareFullness: number;
817 }[][];
818 model: string;
819 memoryFiles: {
820 path: string;
821 type: string;
822 tokens: number;
823 }[];
824 mcpTools: {
825 name: string;
826 serverName: string;
827 tokens: number;
828 isLoaded?: boolean;
829 }[];
830 deferredBuiltinTools?: {
831 name: string;
832 tokens: number;
833 isLoaded: boolean;
834 }[];
835 systemTools?: {
836 name: string;
837 tokens: number;
838 }[];
839 systemPromptSections?: {
840 name: string;
841 tokens: number;
842 }[];
843 agents: {
844 agentType: string;
845 source: string;
846 tokens: number;
847 }[];
848 slashCommands?: {
849 totalCommands: number;
850 includedCommands: number;
851 tokens: number;
852 };
853 skills?: {
854 totalSkills: number;
855 includedSkills: number;
856 tokens: number;
857 skillFrontmatter: {
858 name: string;
859 source: string;
860 tokens: number;
861 }[];
862 };
863 autoCompactThreshold?: number;
864 isAutoCompactEnabled: boolean;
865 messageBreakdown?: {
866 toolCallTokens: number;
867 toolResultTokens: number;
868 attachmentTokens: number;
869 assistantMessageTokens: number;
870 userMessageTokens: number;
871 redirectedContextTokens: number;
872 unattributedTokens: number;
873 toolCallsByType: {
874 name: string;
875 callTokens: number;
876 resultTokens: number;
877 }[];
878 attachmentsByType: {
879 name: string;
880 tokens: number;
881 }[];
882 };
883 apiUsage: {
884 input_tokens: number;
885 output_tokens: number;
886 cache_creation_input_tokens: number;
887 cache_read_input_tokens: number;
888 } | null;
889};
890```
891
892从集合字段读取令牌归属：
893
894* `categories` 保存每个类别的总计。
895* `mcpTools` 和 `agents` 将令牌归属于各个 MCP 工具和 subagents。
896* `memoryFiles` 列出每个加载的内存文件及其成本。
897* `skills.skillFrontmatter` 将 skill 列表的令牌归属于每个包含的 skill。每个 skill 的计数测量每个 skill 的列表条目，因为 Claude Code 实际发送它，这可能比 skill 的完整 frontmatter 更短。比较 `skills.totalSkills` 与 `skills.includedSkills` 以查看每个发现的 skill 是否进入列表。
898
899`totalTokens` 是会话的当前上下文使用情况，`maxTokens` 是针对该使用情况测量的窗口。该窗口是模型的上下文窗口，或当应用一个时的较低自动压缩窗口。`rawMaxTokens` 携带与 `maxTokens` 相同的值，`percentage` 是 `totalTokens` 作为该窗口的四舍五入百分比。
900
901Claude Code 保留可选的 `deferredBuiltinTools`、`systemTools` 和 `systemPromptSections` 诊断未设置，因此即使类型声明它们，也应该期望它们不存在。
902
903<h3 id="sdkcontrolreadfileresponse">
904 `SDKControlReadFileResponse`
905</h3>
906
907[`readFile()`](#query-object) 的返回类型。
908
909```typescript theme={null}
910type SDKControlReadFileResponse = {
911 contents: string;
912 absPath: string;
913 truncated?: boolean;
914 encoding?: 'base64';
915};
916```
917
918`contents` 保存文件文本，或当您请求 `encoding: 'base64'` 时的 base64 数据；响应的 `encoding` 字段在这种情况下设置为 `'base64'`。`absPath` 是解析的绝对路径。当文件长于 `maxBytes` 上限且内容在该限制处被切割时，`truncated` 被设置。
919
920<h4 id="what-readfile-can-read">
921 `readFile()` 可以读取什么
922</h4>
923
924`readFile()` 提供的文件集比 Read 工具更窄：
925
926* 会话的工作目录之一内的常规文件，如 `cwd` 和 `additionalDirectories`
927* Claude Code 自己的一些文件用于会话，如工具结果
928
929Read deny 和 ask 规则仍然阻止匹配的路径，广泛的 Read allow 规则不会向 `readFile()` 打开文件系统的其余部分。对于任何其他内容，调用使用 `null` 进行解决。
930
931<h3 id="sdkcontrolreloadskillsresponse">
932 `SDKControlReloadSkillsResponse`
933</h3>
934
935[`reloadSkills()`](#query-object) 的返回类型。
936
937```typescript theme={null}
938type SDKControlReloadSkillsResponse = {
939 skills: SlashCommand[];
940};
941```
942
943`skills` 列出重新加载后可用的 skills，采用 `supportedCommands()` 返回的相同 [`SlashCommand`](#slashcommand) 形状。
944
721<h3 id="agentdefinition">945<h3 id="agentdefinition">
722 `AgentDefinition`946 `AgentDefinition`
723</h3>947</h3>
724 948
725以编程方式定义的子代理的配置。949以编程方式定义的 subagent 的配置。
726 950
727```typescript theme={null}951```typescript theme={null}
728type AgentDefinition = {952type AgentDefinition = {
744```968```
745 969
746| 字段 | 必需 | 描述 |970| 字段 | 必需 | 描述 |
747| :------------------------------------ | :- | :-------------------------------------------------------------------------------------------------------- |971| :------------------------------------ | :- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
748| `description` | 是 | 何时使用此代理的自然语言描述 |972| `description` | 是 | 何时使用此代理的自然语言描述 |
749| `tools` | 否 | 允许的工具名称数组。如果省略，继承父级的所有工具。要将 Skills 预加载到代理的上下文中，请使用 `skills` 字段而不是在此处列出 `'Skill'` |973| `tools` | 否 | 允许的工具名称数组。如果省略，继承[可用于 subagents 的每个工具](/docs/zh-CN/sub-agents#available-tools)。要将 Skills 预加载到代理的上下文中，请使用 `skills` 字段而不是在此处列出 `'Skill'` |
750| `disallowedTools` | 否 | 要为此代理明确禁止的工具名称数组。也接受 MCP 服务器级别的模式：`mcp__server` 或 `mcp__server__*` 移除该服务器的每个工具，`mcp__*` 移除任何服务器的每个 MCP 工具 |974| `disallowedTools` | 否 | 要为此代理明确禁止的工具名称数组。也接受 MCP 服务器级别的模式：`mcp__server` 或 `mcp__server__*` 移除该服务器的每个工具，`mcp__*` 移除任何服务器的每个 MCP 工具 |
751| `prompt` | 是 | 代理的系统提示 |975| `prompt` | 是 | 代理的系统提示 |
752| `model` | 否 | 此代理的模型覆盖。接受别名，如 `'fable'`、`'opus'`、`'sonnet'`、`'haiku'`、`'inherit'`，或完整的模型 ID。如果省略或 `'inherit'`，使用主模型 |976| `model` | 否 | 此代理的模型覆盖。接受别名，如 `'fable'`、`'opus'`、`'sonnet'`、`'haiku'`、`'inherit'`，或完整的模型 ID。`'inherit'` 使用主模型。当您省略它时，Claude Code 在[subagent 模型顺序](/docs/zh-CN/sub-agents#choose-a-model)中选择模型 |
753| `mcpServers` | 否 | 此代理的 MCP 服务器规范 |977| `mcpServers` | 否 | 此代理的 MCP 服务器规范 |
754| `skills` | 否 | 要预加载到代理上下文中的 skill 名称数组 |978| `skills` | 否 | 要预加载到代理上下文中的 skill 名称数组 |
755| `initialPrompt` | 否 | 当此代理作为主线程代理运行时，自动提交为第一个用户轮次 |979| `initialPrompt` | 否 | 当此代理作为主线程代理运行时，自动提交为第一个用户轮次 |
757| `background` | 否 | 调用时将此代理作为非阻塞后台任务运行 |981| `background` | 否 | 调用时将此代理作为非阻塞后台任务运行 |
758| `memory` | 否 | 此代理的内存源：`'user'`、`'project'` 或 `'local'` |982| `memory` | 否 | 此代理的内存源：`'user'`、`'project'` 或 `'local'` |
759| `effort` | 否 | 此代理的推理努力级别。接受命名级别或整数 |983| `effort` | 否 | 此代理的推理努力级别。接受命名级别或整数 |
760| `permissionMode` | 否 | 此代理内工具执行的权限模式。请参阅 [`PermissionMode`](#permissionmode) |984| `permissionMode` | 否 | 此代理内工具执行的权限模式。[subagent 继承规则](/docs/zh-CN/agent-sdk/permissions#available-modes)决定何时应用。请参阅 [`PermissionMode`](#permissionmode) |
761| `criticalSystemReminder_EXPERIMENTAL` | 否 | 实验性：添加到系统提示的关键提醒 |985| `criticalSystemReminder_EXPERIMENTAL` | 否 | 实验性：添加到系统提示的关键提醒 |
762 986
763<h3 id="agentmcpserverspec">987<h3 id="agentmcpserverspec">
764 `AgentMcpServerSpec`988 `AgentMcpServerSpec`
765</h3>989</h3>
766 990
767指定子代理可用的 MCP 服务器。可以是服务器名称（字符串，引用父级 `mcpServers` 配置中的服务器）或内联服务器配置记录，将服务器名称映射到配置。991指定 subagent 可用的 MCP 服务器。可以是服务器名称（字符串，引用父级 `mcpServers` 配置中的服务器）或内联服务器配置记录，将服务器名称映射到配置。
768 992
769```typescript theme={null}993```typescript theme={null}
770type AgentMcpServerSpec = string | Record<string, McpServerConfigForProcessTransport>;994type AgentMcpServerSpec = string | Record<string, McpServerConfigForProcessTransport>;
783```1007```
784 1008
785| 值 | 描述 | 位置 |1009| 值 | 描述 | 位置 |
786| :---------- | :------------ | :---------------------------- |1010| :---------- | :----------------------------------------- | :---------------------------- |
787| `'user'` | 全局用户设置 | `~/.claude/settings.json` |1011| `'user'` | 全局用户设置 | `~/.claude/settings.json` |
788| `'project'` | 共享项目设置（版本控制） | `.claude/settings.json` |1012| `'project'` | 共享项目设置（版本控制） | `.claude/settings.json` |
789| `'local'` | 本地项目设置（不版本控制） | `.claude/settings.local.json` |1013| `'local'` | 本地项目设置，当 Claude Code 将设置保存到其中时被 gitignored | `.claude/settings.local.json` |
790 1014
791<h4 id="default-behavior">1015<h4 id="default-behavior">
792 默认行为1016 默认行为
793</h4>1017</h4>
794 1018
795当 `settingSources` 被省略或 `undefined` 时，`query()` 加载与 Claude Code CLI 相同的文件系统设置：用户、项目和本地。在所有情况下都会加载[端点管理的策略](/docs/zh-CN/settings#settings-files)；当会话使用组织凭证在[符合条件的配置](/docs/zh-CN/server-managed-settings#platform-availability)上进行身份验证时，会获取服务器管理的设置。请参阅[settingSources 不控制的内容](/docs/zh-CN/agent-sdk/claude-code-features#what-settingsources-does-not-control)了解无论此选项如何都会读取的输入，以及如何禁用它们。1019当 `settingSources` 被省略或 `undefined` 时，`query()` 加载与 Claude Code CLI 相同的文件系统设置：用户、项目和本地。请参阅[settingSources 不控制的内容](/docs/zh-CN/agent-sdk/claude-code-features#what-settingsources-does-not-control)了解无论此选项如何都会读取的输入，以及如何禁用它们。
796 1020
797<h4 id="why-use-settingsources">1021<h4 id="why-use-settingsources">
798 为什么使用 settingSources1022 为什么使用 settingSources
801**禁用文件系统设置：**1025**禁用文件系统设置：**
802 1026
803```typescript theme={null}1027```typescript theme={null}
1028import { query } from "@anthropic-ai/claude-agent-sdk";
1029
804// 不从磁盘加载用户、项目或本地设置1030// 不从磁盘加载用户、项目或本地设置
805const result = query({1031const result = query({
806 prompt: "Analyze this code",1032 prompt: "Analyze this code",
808});1034});
809```1035```
810 1036
811**显式加载所有文件系统设置：**
812
813```typescript theme={null}
814const result = query({
815 prompt: "Analyze this code",
816 options: {
817 settingSources: ["user", "project", "local"] // 加载所有设置
818 }
819});
820```
821
822**仅加载特定设置源：**1037**仅加载特定设置源：**
823 1038
824```typescript theme={null}1039```typescript theme={null}
1040import { query } from "@anthropic-ai/claude-agent-sdk";
1041
825// 仅加载项目设置，忽略用户和本地1042// 仅加载项目设置，忽略用户和本地
826const result = query({1043const result = query({
827 prompt: "Run CI checks",1044 prompt: "Run CI checks",
831});1048});
832```1049```
833 1050
834**测试和 CI 环境：**1051要加载 CLAUDE.md 项目说明，请在 `settingSources` 中包含 `"project"`。请参阅[修改系统提示](/docs/zh-CN/agent-sdk/modifying-system-prompts#claude-md-files-for-project-level-instructions)了解 CLAUDE.md 加载如何与系统提示选项交互。
835
836```typescript theme={null}
837// 通过排除本地设置确保 CI 中的一致行为
838const result = query({
839 prompt: "Run tests",
840 options: {
841 settingSources: ["project"], // 仅团队共享设置
842 permissionMode: "bypassPermissions"
843 }
844});
845```
846
847**仅 SDK 应用程序：**
848
849```typescript theme={null}
850// 以编程方式定义所有内容。
851// 传递 [] 以选择退出文件系统设置源。
852const result = query({
853 prompt: "Review this PR",
854 options: {
855 settingSources: [],
856 agents: {
857 /* ... */
858 },
859 mcpServers: {
860 /* ... */
861 },
862 allowedTools: ["Read", "Grep", "Glob"]
863 }
864});
865```
866
867**加载 CLAUDE.md 项目说明：**
868
869```typescript theme={null}
870// 加载项目设置以包括 CLAUDE.md 文件
871const result = query({
872 prompt: "Add a new feature following project conventions",
873 options: {
874 systemPrompt: {
875 type: "preset",
876 preset: "claude_code" // 使用 Claude Code 的系统提示
877 },
878 settingSources: ["project"], // 从项目目录加载 CLAUDE.md
879 allowedTools: ["Read", "Write", "Edit"]
880 }
881});
882```
883 1052
884<h4 id="settings-precedence">1053<h4 id="settings-precedence">
885 设置优先级1054 设置优先级
901type PermissionMode =1070type PermissionMode =
902 | "default" // 标准权限行为1071 | "default" // 标准权限行为
903 | "acceptEdits" // 自动接受文件编辑1072 | "acceptEdits" // 自动接受文件编辑
904 | "bypassPermissions" // 绕过权限检查；显式询问规则仍然提示1073 | "bypassPermissions" // 绕过权限检查；显式 ask 规则仍然提示
905 | "plan" // Plan Mode - 仅读取工具1074 | "plan" // Plan Mode - 仅读取工具
906 | "dontAsk" // 不提示权限，如果未预先批准则拒绝1075 | "dontAsk" // 不提示权限，如果未预先批准则拒绝
907 | "auto"; // 使用模型分类器批准或拒绝每个工具调用1076 | "auto"; // 模型分类器批准或拒绝权限提示
908```1077```
909 1078
910<h3 id="canusetool">1079<h3 id="canusetool">
915 1084
916该函数是 SDK 替代交互式权限提示：仅当[权限评估流](/docs/zh-CN/agent-sdk/permissions#how-permissions-are-evaluated)解决为提示时才调用它。已由 `allowedTools` 条目、设置 allow 规则或权限模式（如 `acceptEdits` 或 `bypassPermissions`）批准的工具调用永远不会调用它。要限制每个工具调用，请改用 [`PreToolUse` hook](/docs/zh-CN/agent-sdk/hooks)。1085该函数是 SDK 替代交互式权限提示：仅当[权限评估流](/docs/zh-CN/agent-sdk/permissions#how-permissions-are-evaluated)解决为提示时才调用它。已由 `allowedTools` 条目、设置 allow 规则或权限模式（如 `acceptEdits` 或 `bypassPermissions`）批准的工具调用永远不会调用它。要限制每个工具调用，请改用 [`PreToolUse` hook](/docs/zh-CN/agent-sdk/hooks)。
917 1086
918`AskUserQuestion`、标记为 [`requiresUserInteraction`](/docs/zh-CN/mcp#require-approval-for-a-specific-tool) 的 MCP 工具和[您的组织设置为 `ask`](/docs/zh-CN/mcp#organization-controls-on-connector-tools) 的 connector 工具即使 allow 规则匹配也会到达该函数。在 `dontAsk` 模式下这些调用会被拒绝，不调用它。1087[任何模式都不自动批准的操作](/docs/zh-CN/permission-modes#actions-no-mode-auto-approves)不会被 allow 规则预先批准；请参阅[权限如何被评估](/docs/zh-CN/agent-sdk/permissions#how-permissions-are-evaluated)了解哪些到达回调以及在 `dontAsk` 和 `auto` 模式下会发生什么。
919 1088
920```typescript theme={null}1089```typescript theme={null}
921type CanUseTool = (1090type CanUseTool = (
940| `blockedPath` | `string` | 触发权限请求的文件路径（如果适用） |1109| `blockedPath` | `string` | 触发权限请求的文件路径（如果适用） |
941| `decisionReason` | `string` | 解释为什么触发此权限请求 |1110| `decisionReason` | `string` | 解释为什么触发此权限请求 |
942| `toolUseID` | `string` | 此特定工具调用在助手消息中的唯一标识符 |1111| `toolUseID` | `string` | 此特定工具调用在助手消息中的唯一标识符 |
943| `agentID` | `string` | 如果在子代理中运行，子代理的 ID |1112| `agentID` | `string` | 如果在 subagent 中运行，subagent 的 ID |
944| `requestId` | `string` | `control_request` 信封的 `request_id`。您的应用程序在其自己的通道上发送的 `control_response`（例如签名的 HTTP POST）必须回显此值，以便 Claude Code 进程可以将回复与请求匹配 |1113| `requestId` | `string` | `control_request` 信封的 `request_id`。您的应用程序在其自己的通道上发送的 `control_response`（例如签名的 HTTP POST）必须回显此值，以便 Claude Code 进程可以将回复与请求匹配 |
945 1114
946回调通常通过返回 [`PermissionResult`](#permissionresult) 来解决请求，SDK 将其写回其传输作为 `control_response`。仅当您的应用程序已通过其自己的通道为此请求发送 `control_response`（回显 `requestId`）时才返回 `null`；SDK 然后跳过将响应写入其传输。在任何其他情况下返回 `null` 会使工具调用无限期被阻止，因为永远不会发送 `control_response` 且权限提示不会超时。1115回调通常通过返回 [`PermissionResult`](#permissionresult) 来解决请求，SDK 将其写回其传输作为 `control_response`。仅当您的应用程序已通过其自己的通道为此请求发送 `control_response`（回显 `requestId`）时才返回 `null`；SDK 然后跳过将响应写入其传输。在任何其他情况下返回 `null` 会使工具调用无限期被阻止，因为永远不会发送 `control_response` 且权限提示不会超时。
1046type McpSdkServerConfigWithInstance = {1215type McpSdkServerConfigWithInstance = {
1047 type: "sdk";1216 type: "sdk";
1048 name: string;1217 name: string;
1218 timeout?: number;
1049 instance: McpServer;1219 instance: McpServer;
1050};1220};
1051```1221```
1157 message: BetaMessage; // 来自 Anthropic SDK1327 message: BetaMessage; // 来自 Anthropic SDK
1158 parent_tool_use_id: string | null;1328 parent_tool_use_id: string | null;
1159 error?: SDKAssistantMessageError;1329 error?: SDKAssistantMessageError;
1330 aborted?: true;
1331 timestamp?: string;
1332 context_usage?: SDKContextUsage;
1333 user_message_uuid?: string;
1334 user_message_uuids?: string[];
1160};1335};
1161```1336```
1162 1337
1163`message` 字段是来自 Anthropic SDK 的 [`BetaMessage`](https://platform.claude.com/docs/zh-CN/api/messages/create)。它包括 `id`、`content`、`model`、`stop_reason` 和 `usage` 等字段。1338`message` 字段是来自 Anthropic SDK 的 [`BetaMessage`](https://platform.claude.com/docs/zh-CN/api/messages/create)。它包括 `id`、`content`、`model`、`stop_reason` 和 `usage` 等字段。
1164 1339
1165`SDKAssistantMessageError` 是以下之一：`'authentication_failed'`、`'oauth_org_not_allowed'`、`'billing_error'`、`'rate_limit'`、`'overloaded'`、`'invalid_request'`、`'model_not_found'`、`'server_error'`、`'max_output_tokens'` 或 `'unknown'`。`'model_not_found'` 表示所选模型不存在或对您的账户或部署不可用。`'overloaded'` 表示 API 返回了 529 错误，因为服务器处于容量限制，与 `'rate_limit'` 相对，后者是针对您的配额的 429 错误。1340`SDKAssistantMessageError` 是以下之一：`'authentication_failed'`、`'oauth_org_not_allowed'`、`'account_on_hold'`、`'billing_error'`、`'rate_limit'`、`'overloaded'`、`'invalid_request'`、`'model_not_found'`、`'server_error'`、`'max_output_tokens'`、`'cloud_credential_error'` 或 `'unknown'`。其中四个值的含义超出了它们的名称：
1341
1342* `'model_not_found'`：所选模型不存在或对您的账户或部署不可用
1343* `'overloaded'`：API 返回了 529 错误，因为服务器处于容量限制，与 `'rate_limit'` 相对，后者是针对您的配额的 429 错误
1344* `'account_on_hold'`：[您的账户被冻结](/docs/zh-CN/errors#your-account-is-on-hold)
1345* `'cloud_credential_error'`：Claude Code 无法在其运行的机器上获取可用的 AWS 或 Google Cloud 凭证，因此没有请求到达云提供商。通常原因是云登录在该机器上过期或从未完成，尽管暂时无法访问的凭证服务会报告相同的值。请参阅[无法加载 AWS 或 Google Cloud 凭证](/docs/zh-CN/errors#could-not-load-aws-or-google-cloud-credentials)。需要 TypeScript Agent SDK v0.3.267 或更高版本，其中包含 Claude Code v2.1.267
1346
1347当中断或中止在流完成之前截断助手消息时，`aborted` 为 `true`：消息没有 `stop_reason`，内容可能在中间词处结束。该字段在正常完成的消息上不存在。它需要 Agent SDK v0.3.214 或更高版本。
1348
1349Claude Code 在转轮的第一个助手消息上设置 `user_message_uuid` 和 `user_message_uuids`，条件在 [`user_message_uuid`](#user_message_uuid) 中。
1350
1351`timestamp` 是生成消息内容的进程完成内容生成时的 ISO 8601 时间。该值来自该机器的时钟，因此仅用于显示，不要按其排序消息。一个 API 轮次可以产生多个共享 `message.id` 的助手消息，每个都有自己的 `timestamp`。当字段不存在时，回退到您收到消息的时间。
1352
1353`context_usage` 是 `/context` 报告的结构化副本，类型为 [`SDKContextUsage`](#sdkcontextusage)，需要 Agent SDK v0.3.232 或更高版本。当您发送 `/context` 作为提示时，Claude Code 将报告作为助手消息传递，其 `message.content` 包含 markdown 表格，并将 `context_usage` 附加到同一消息。Claude Code 不在任何其他助手消息上设置该字段，早期版本在没有它的情况下传递 `/context` 表格，因此当字段存在时从字段读取分解，当不存在时回退到 markdown 文本。
1166 1354
1167<h3 id="sdkusermessage">1355<h3 id="sdkusermessage">
1168 `SDKUserMessage`1356 `SDKUserMessage`
1190 1378
1191对于 `Agent` 工具，`tool_use_result` 是 [`AgentOutput`](#agent-2)。在 `completed` 结果上，`content` 保存子代理的报告，不包含 Claude Code 附加到 `tool_result` 文本的代理 ID 和使用情况预告片，因此从 `tool_use_result` 呈现而不是解析该文本。1379对于 `Agent` 工具，`tool_use_result` 是 [`AgentOutput`](#agent-2)。在 `completed` 结果上，`content` 保存子代理的报告，不包含 Claude Code 附加到 `tool_result` 文本的代理 ID 和使用情况预告片，因此从 `tool_use_result` 呈现而不是解析该文本。
1192 1380
1381对于其结果包含 `resource_link` 块的 MCP 工具，`tool_use_result` 是一个对象，其中包含 [`SDKMcpResourceLink`](#sdkmcpresourcelink) 条目的 `resourceLinks` 数组。Claude 将每个链接作为 `tool_result` 块中的一行文本接收，因此读取 `resourceLinks` 以呈现服务器返回的文件，而不是解析该文本。Claude Code 在结果没有链接时省略 `resourceLinks`，在来自子代理的结果上省略，每个结果最多保留 50 个链接，一旦数组达到 64 KiB 的序列化 JSON 就停止添加链接。`resourceLinks` 需要 Agent SDK v0.3.257 或更高版本。
1382
1193<h3 id="sdkusermessagereplay">1383<h3 id="sdkusermessagereplay">
1194 `SDKUserMessageReplay`1384 `SDKUserMessageReplay`
1195</h3>1385</h3>
1234 stop_reason: string | null;1424 stop_reason: string | null;
1235 ttft_ms?: number;1425 ttft_ms?: number;
1236 ttft_stream_ms?: number;1426 ttft_stream_ms?: number;
1427 user_message_uuid?: string;
1428 user_message_uuids?: string[];
1429 request_sent_wall_ms?: number;
1430 first_content_frame_ms?: number;
1431 first_stream_post_ms?: number;
1432 first_stream_post_ack_ms?: number;
1433 first_stream_post_wall_ms?: number;
1237 total_cost_usd: number;1434 total_cost_usd: number;
1238 usage: NonNullableUsage;1435 usage: NonNullableUsage;
1239 modelUsage: { [modelName: string]: ModelUsage };1436 modelUsage: { [modelName: string]: ModelUsage };
1240 permission_denials: SDKPermissionDenial[];1437 permission_denials: SDKPermissionDenial[];
1438 queued_turn_count?: number;
1241 structured_output?: unknown;1439 structured_output?: unknown;
1242 deferred_tool_use?: { id: string; name: string; input: Record<string, unknown> };1440 deferred_tool_use?: { id: string; name: string; input: Record<string, unknown> };
1243 terminal_reason?: TerminalReason;1441 terminal_reason?: TerminalReason;
1244 fast_mode_state?: FastModeState;1442 fast_mode_state?: FastModeState;
1443 fast_mode_disabled_reason?: FastModeDisabledReason;
1245 origin?: SDKMessageOrigin;1444 origin?: SDKMessageOrigin;
1246 }1445 }
1247 | {1446 | {
1262 usage: NonNullableUsage;1461 usage: NonNullableUsage;
1263 modelUsage: { [modelName: string]: ModelUsage };1462 modelUsage: { [modelName: string]: ModelUsage };
1264 permission_denials: SDKPermissionDenial[];1463 permission_denials: SDKPermissionDenial[];
1464 queued_turn_count?: number;
1265 errors: string[];1465 errors: string[];
1466 user_message_uuid?: string;
1467 user_message_uuids?: string[];
1266 terminal_reason?: TerminalReason;1468 terminal_reason?: TerminalReason;
1267 fast_mode_state?: FastModeState;1469 fast_mode_state?: FastModeState;
1470 fast_mode_disabled_reason?: FastModeDisabledReason;
1268 origin?: SDKMessageOrigin;1471 origin?: SDKMessageOrigin;
1269 };1472 };
1270```1473```
1274* `api_error_status`：终止对话的 API 错误的 HTTP 状态码。当轮次在没有 API 错误的情况下结束时，该字段不存在或为 `null`。1477* `api_error_status`：终止对话的 API 错误的 HTTP 状态码。当轮次在没有 API 错误的情况下结束时，该字段不存在或为 `null`。
1275* `ttft_ms`：首个令牌的时间（毫秒），在第一个完整的助手消息到达时测量。仅在成功分支上显示。1478* `ttft_ms`：首个令牌的时间（毫秒），在第一个完整的助手消息到达时测量。仅在成功分支上显示。
1276* `ttft_stream_ms`：直到第一个 `message_start` 流事件的时间（毫秒），当响应流打开时。低于 `ttft_ms`；两者之间的差距是流式传输第一条消息所花费的时间。仅在成功分支上显示。1479* `ttft_stream_ms`：直到第一个 `message_start` 流事件的时间（毫秒），当响应流打开时。低于 `ttft_ms`；两者之间的差距是流式传输第一条消息所花费的时间。仅在成功分支上显示。
1480* `user_message_uuid`：此轮次回答的您发送的消息的 `uuid`。请参阅 [`user_message_uuid`](#user_message_uuid) 了解哪些结果携带它。
1481* `user_message_uuids`：Claude Code 在此轮次中回答的您发送的每条消息的 `uuid`。请参阅 [`user_message_uuids`](#user_message_uuids)。
1482* `request_sent_wall_ms`：Claude Code 分派 API 请求时的纪元毫秒，用于与服务器端时间戳的联接。仅与 [`user_message_uuid`](#user_message_uuid) 一起出现，在成功结果上，其中 `is_error` 为 false，轮次发送了 API 请求。
1483* `first_content_frame_ms`：直到第一个 `content_block_start` 或 `content_block_delta` 流事件的时间（毫秒），计算思考块作为内容。仅在成功分支上显示，当 `is_error` 为 false 时。需要 Agent SDK v0.3.260 或更高版本。
1484* `first_stream_post_ms`、`first_stream_post_ack_ms`、`first_stream_post_wall_ms`：上传轮次第一个流事件的时间。Claude Code 仅在它流式传输到 claude.ai 的会话中记录它们，例如[云会话](/docs/zh-CN/claude-code-on-the-web)，`query()` 产生的结果不携带它们。需要 Agent SDK v0.3.260 或更高版本。
1485* `usage`：仅主代理循环。排除子代理和辅助模型调用，在流式输入会话中按轮次。优先使用 `modelUsage` 进行令牌/成本会计。
1486* `modelUsage`：在此 `query()` 调用期间通过查询管道进行的每个模型调用的每模型总计，包括主循环、子代理和内部调用（如压缩和 Workflow 代理）。该管道外的辅助调用（如权限分类器和令牌计数请求）被排除。在流式输入会话中，总计在轮次间累积，因此读取最新结果而不是跨结果求和。请参阅[在流式输入模式中跟踪成本](/docs/zh-CN/agent-sdk/cost-tracking#track-costs-in-streaming-input-mode)了解重置，以及[在会话崩溃后恢复总计](/docs/zh-CN/agent-sdk/cost-tracking#recover-totals-after-a-session-crash)了解零化结果。
1487* `total_cost_usd`：此 `query()` 调用的累积估计成本（美元），涵盖与 `modelUsage` 相同的调用并在相同点重置。这是一个估计值，不是账单声明。请参阅[跟踪成本和使用情况](/docs/zh-CN/agent-sdk/cost-tracking)了解准确性注意事项。
1488* `queued_turn_count`：您发送的带有 `origin: { kind: "human" }` 的消息数量，在 Claude Code 产生结果时仍在等待。请参阅 [`queued_turn_count`](#queued_turn_count) 了解 `0` 和缺失字段告诉您什么。
1277* `terminal_reason`：循环结束的原因。为 `"completed"`、`"max_turns"`、`"tool_deferred"`、`"aborted_streaming"`、`"aborted_tools"`、`"hook_stopped"`、`"stop_hook_prevented"`、`"background_requested"`、`"blocking_limit"`、`"rapid_refill_breaker"`、`"prompt_too_long"`、`"image_error"`、`"model_error"`、`"api_error"`、`"malformed_tool_use_exhausted"`、`"budget_exhausted"`、`"structured_output_retry_exhausted"`、`"tool_deferred_unavailable"` 或 `"turn_setup_failed"` 之一。1489* `terminal_reason`：循环结束的原因。为 `"completed"`、`"max_turns"`、`"tool_deferred"`、`"aborted_streaming"`、`"aborted_tools"`、`"hook_stopped"`、`"stop_hook_prevented"`、`"background_requested"`、`"blocking_limit"`、`"rapid_refill_breaker"`、`"prompt_too_long"`、`"image_error"`、`"model_error"`、`"api_error"`、`"malformed_tool_use_exhausted"`、`"budget_exhausted"`、`"structured_output_retry_exhausted"`、`"tool_deferred_unavailable"` 或 `"turn_setup_failed"` 之一。
1278* `fast_mode_state`：为 `"on"`、`"off"` 或 `"cooldown"` 之一。1490* `fast_mode_state`：为 `"on"`、`"off"` 或 `"cooldown"` 之一。
1491* `fast_mode_disabled_reason`：为什么[快速模式](/docs/zh-CN/fast-mode)现在不可用。当没有任何东西阻止快速模式时不存在，尽管请求仍可能以标准速度运行。在快速模式速率限制后的冷却期间，Claude Code 报告 `fast_mode_state: "cooldown"` 且没有原因代码，并在冷却期过期时重新启用快速模式。需要 Claude Code v2.1.219 或更高版本。
1492
1493使用原因代码在您自己的 UI 中解释为什么快速模式关闭，而不是重新推导可用性。每个代码命名阻止快速模式的检查：
1279 1494
1280`origin` 字段转发触发此结果的用户消息的 [`SDKMessageOrigin`](#sdkmessageorigin)。当后台任务完成且 SDK 注入合成后续轮次时，生成的 `SDKResultMessage` 携带 `origin: { kind: "task-notification" }`。检查此字段以区分回答您的提示的结果与为后台任务后续操作发出的结果，以便您可以路由或抑制后者。对于在任何用户轮次之前发出的结果（例如启动错误），该字段不存在。1495| 原因代码 | 含义 |
1496| ---------------------- | ------------------------------------------------------------------------------------------------------------ |
1497| `free` | 账户没有快速模式所需的付费订阅或使用额度 |
1498| `preference` | 组织已禁用快速模式 |
1499| `extra_usage_disabled` | 账户的使用额度已关闭 |
1500| `network_error` | [可用性检查](/docs/zh-CN/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways)无法到达 `api.anthropic.com` |
1501| `unknown` | Claude Code 无法确定可用性 |
1502| `not_first_party` | 会话使用 Anthropic API 以外的提供商 |
1503| `disabled_by_env` | [`CLAUDE_CODE_DISABLE_FAST_MODE`](/docs/zh-CN/env-vars) 已设置 |
1504| `model_not_allowed` | 快速模式 Opus 模型不在组织的 [`availableModels`](/docs/zh-CN/model-config#restrict-model-selection) 允许列表中 |
1505| `sdk_opt_in_required` | 会话尚未选择加入快速模式：在 [`settings`](#options) 选项中或通过 [`applyFlagSettings()`](#applyflagsettings) 传递 `fastMode: true` |
1506| `pending` | 可用性检查尚未完成 |
1281 1507
1282当 `PreToolUse` hook 返回 `permissionDecision: "defer"` 时，结果具有 `stop_reason: "tool_deferred"` 和 `deferred_tool_use` 携带待处理工具的 `id`、`name` 和 `input`。读取此字段以在您自己的 UI 中显示请求，然后使用相同的 `session_id` 恢复以继续。有关完整的往返过程，请参阅[稍后延迟工具调用](/docs/zh-CN/hooks#defer-a-tool-call-for-later)。1508相同的字段对出现在 [`SDKSystemMessage`](#sdksystemmessage) 和 [`SDKControlInitializeResponse`](#sdkcontrolinitializeresponse) 上，因此您可以在第一个轮次之前读取快速模式状态。
1509
1510`origin` 字段转发触发此结果的用户消息的 [`SDKMessageOrigin`](#sdkmessageorigin)。当 SDK 注入合成后续轮次（例如对于完成的后台任务）时，生成的 `SDKResultMessage` 携带 `origin: { kind: "task-notification" }`。例程的触发器触发和来自您其他会话的服务器验证消息也会到达此类，每个都带有[任务通知子类型](#task-notification-subkinds)中描述的 `subkind`。检查 `kind` 以区分回答您的提示的结果与注入的后续操作，然后再路由或抑制它们。
1511
1512对于在任何用户轮次之前发出的结果（例如启动错误），该字段不存在。
1513
1514当 `PreToolUse` hook 返回 `permissionDecision: "defer"` 时，结果具有 `stop_reason: "tool_deferred"` 和 `deferred_tool_use` 携带待处理工具的 `id`、`name` 和 `input`。读取此字段以在您自己的 UI 中显示请求，然后使用相同的 `session_id` 恢复以继续。请参阅[稍后延迟工具调用](/docs/zh-CN/hooks#defer-a-tool-call-for-later)了解完整的往返过程。
1515
1516<h4 id="user_message_uuid">
1517 `user_message_uuid`
1518</h4>
1519
1520轮次回答的 [`SDKUserMessage`](#sdkusermessage) 的 `uuid`，回显以便您可以将 Claude Code 的回复与您发送的消息匹配。Claude Code 仅在您在消息上设置 uuid 时才回显 `uuid`。该字段在 `SDKUserMessage` 上是可选的，传递给 `query()` 的字符串提示不携带任何。
1521
1522轮次回答的消息取决于轮次如何启动：
1523
1524* **您发送的常规消息**，即没有 `isSynthetic: true` 的消息：轮次在其整个运行中回答该消息。当您紧密发送多条消息时，Claude Code 可以将它们合并为一个轮次，该字段然后仅携带最后一条消息的 `uuid`。要将回复与任何合并的消息匹配，请使用 [`user_message_uuids`](#user_message_uuids)。
1525* **您发送的带有 `isSynthetic: true` 的消息**：轮次最初回答该消息。如果 Claude Code 在工具调用之间拾取您的常规消息，轮次从那时起回答拾取的消息。回显合成消息的 `uuid` 需要 Agent SDK v0.3.265 或更高版本；早期版本在合成轮次上不回显任何内容。
1526* **Claude Code 自己生成的提示**，例如在会话重启后继续中断工作的轮次：轮次最初不回答您的任何消息，其帧不携带回显。如果 Claude Code 在工具调用之间拾取您的常规消息，轮次从那时起回答该消息。拾取回显需要 Agent SDK v0.3.265 或更高版本；早期版本在这些轮次上不回显任何内容。
1527
1528Claude Code 在三种帧上回显回答的消息的 `uuid`：
1529
1530* **结果**：回答您发送的消息的轮次的每个结果。在 Agent SDK v0.3.265 或更高版本上，每个这样的结果都携带它。在 v0.3.265 之前，常规消息启动的轮次的成功结果在轮次未发送 API 请求或以延迟工具调用结束时缺少它。在 v0.3.246 之前，错误结果也缺少它，在 v0.3.216 之前每个结果都缺少它。
1531* **轮次的第一个回复**：第一个[助手消息](#sdkassistantmessage)，或使用 `includePartialMessages` 时第一个[流事件](#sdkpartialassistantmessage)，其 `event.type` 不是 `ping`，因此您可以在结果到达之前绑定回复。当轮次不流式传输任何内容时，Claude Code 改为在第一个助手消息上设置它。第一个回复回显需要 Agent SDK v0.3.246 或更高版本。当轮次回答的消息在中途改变时，改变后的第一个回复也携带该字段，在 Agent SDK v0.3.265 或更高版本上；早期版本在每个轮次的一个回复帧上设置它。
1532* **轮次的每个 [`thinking_tokens`](#sdkthinkingtokensmessage) 帧**：因此您可以将思考进度归属于您发送的消息，而无需等待轮次的第一个回复。需要 Agent SDK v0.3.260 或更高版本。
1533
1534Claude Code 在这些情况下省略该字段：
1535
1536* 除了那些第一个回复之外的回复帧
1537* 子代理帧
1538* 回答没有 `uuid` 的消息的轮次：轮次回答了您发送的没有 uuid 的消息，或 Claude Code 启动了轮次本身并拾取了没有 uuid 的常规消息
1539* 回答您未发送的消息的结果，例如崩溃的工作进程后的零化结果
1540
1541<h4 id="user_message_uuids">
1542 `user_message_uuids`
1543</h4>
1544
1545Claude Code 在此轮次中回答的您发送的每条消息的 `uuid`。当您紧密发送多条消息时，Claude Code 可以将它们合并为一个轮次，`user_message_uuid` 然后仅命名其中的最后一个。要将回复与任何合并的消息匹配，请在此列表中的任何位置查找该消息的 `uuid`。需要 Agent SDK v0.3.259 或更高版本。
1546
1547Claude Code 在携带该字段的每个回复帧和结果上与 `user_message_uuid` 一起设置列表。对于携带 `user_message_uuid` 的完整帧集以及每个需要的版本，请参阅 [`user_message_uuid`](#user_message_uuid)。列表始终包含 `user_message_uuid` 并最多包含 64 个条目。
1548
1549当 Claude Code 在轮次运行时拾取您发送的常规消息时，它将该消息的 `uuid` 添加到结果的列表中。
1550
1551当第一个回复或结果携带 `user_message_uuid` 而没有列表时，它来自较早的 Claude Code 版本，因此回退到单个字段。
1552
1553<h4 id="queued_turn_count">
1554 `queued_turn_count`
1555</h4>
1556
1557您发送的带有 [`origin: { kind: "human" }`](#sdkmessageorigin) 的消息数量，在 Claude Code 产生结果时仍在命令队列中等待。需要 Agent SDK v0.3.242 或更高版本。
1558
1559`0` 和缺失字段告诉您什么：
1560
1561* **`0`**：Claude Code 不计算您发送的没有该 `origin` 的消息，也不计算任务通知，因此轮次仍可能跟随。
1562* **缺失**：Claude Code 在崩溃或致命启动错误后发出的最终结果省略该字段，并且[可能携带零化总计](/docs/zh-CN/agent-sdk/cost-tracking#recover-totals-after-a-session-crash)。
1283 1563
1284<h3 id="sdksystemmessage">1564<h3 id="sdksystemmessage">
1285 `SDKSystemMessage`1565 `SDKSystemMessage`
1306 model: string;1586 model: string;
1307 permissionMode: PermissionMode;1587 permissionMode: PermissionMode;
1308 slash_commands: string[];1588 slash_commands: string[];
1589 terminal_slash_commands?: string[];
1309 output_style: string;1590 output_style: string;
1310 skills: string[];1591 skills: string[];
1311 plugins: { name: string; path: string }[];1592 plugins: { name: string; path: string }[];
1593 fast_mode_state?: FastModeState;
1594 fast_mode_disabled_reason?: FastModeDisabledReason;
1595 effort?: "low" | "medium" | "high" | "xhigh" | "max" | null;
1312 capabilities?: string[];1596 capabilities?: string[];
1313};1597};
1314```1598```
1315 1599
1600`fast_mode_state` 报告会话的[快速模式](/docs/zh-CN/fast-mode)状态。当某些东西阻止快速模式时，`fast_mode_disabled_reason` 命名阻止它的检查；该字段需要 Claude Code v2.1.219 或更高版本。对于原因代码及其含义，请参阅结果消息上的 [`fast_mode_disabled_reason`](#sdkresultmessage)。
1601
1602`terminal_slash_commands` 命名 `slash_commands` 中的条目，其接口绑定到本地终端，例如 `exit`。您可以像 `slash_commands` 中的任何其他条目一样发送它们；该字段存在以便远程或移动客户端可以从其命令菜单中隐藏它们。该字段仅在非空时存在，需要 Agent SDK v0.3.229 或更高版本。
1603
1604* `effort`：[努力级别](/docs/zh-CN/model-config#adjust-effort-level) Claude Code 在会话的下一个请求上发送，或当它不发送任何内容时为 `null`。Claude Code 仅在它发送到[远程控制](/docs/zh-CN/remote-control)客户端的初始化消息上设置该字段，并从您的应用程序读取的初始化消息中省略它。需要 Agent SDK v0.3.234 或更高版本。
1605
1316`capabilities` 数组命名此 CLI 实现的协议行为，因此您可以进行功能检测而不是比较 `claude_code_version` 字符串。这是一个开放集合：忽略您不认识的值，并检查您依赖其行为的特定功能。该字段需要 Claude Code v2.1.205 或更高版本，在较早的 CLI 上不存在。1606`capabilities` 数组命名此 CLI 实现的协议行为，因此您可以进行功能检测而不是比较 `claude_code_version` 字符串。这是一个开放集合：忽略您不认识的值，并检查您依赖其行为的特定功能。该字段需要 Claude Code v2.1.205 或更高版本，在较早的 CLI 上不存在。
1317 1607
1318| 功能 | 含义 |1608| 功能 | 含义 |
1319| ---------------------- | ------------------------------------------------------------------------------------------------------------------ |1609| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1320| `interrupt_receipt_v1` | [`interrupt()`](#query-object) 使用命名存活中断的排队消息的 [`SDKControlInterruptResponse`](#sdkcontrolinterruptresponse) 收据进行解析 |1610| `interrupt_receipt_v1` | [`interrupt()`](#query-object) 使用列出中断到达时待处理消息的 [`SDKControlInterruptResponse`](#sdkcontrolinterruptresponse) 收据进行解析 |
1611| `interrupt_cancel_queued_v1` | `interrupt` 控制请求遵守 `cancel_queued: true`，取消收据在 `still_queued` 下列出的消息，并改为在 `cancelled` 下列出它们。请参阅 [`SDKControlInterruptResponse`](#sdkcontrolinterruptresponse)。需要 Claude Code v2.1.219 或更高版本 |
1321 1612
1322<h3 id="sdkpartialassistantmessage">1613<h3 id="sdkpartialassistantmessage">
1323 `SDKPartialAssistantMessage`1614 `SDKPartialAssistantMessage`
1333 uuid: UUID;1624 uuid: UUID;
1334 session_id: string;1625 session_id: string;
1335 ttft_ms?: number; // 首个令牌的时间（毫秒），仅在 message_start 事件上显示1626 ttft_ms?: number; // 首个令牌的时间（毫秒），仅在 message_start 事件上显示
1627 user_message_uuid?: string;
1628 user_message_uuids?: string[];
1336};1629};
1337```1630```
1338 1631
1632Claude Code 在轮次的第一个非 ping 流事件上设置 `user_message_uuid` 和 `user_message_uuids`，以及当轮次回答的消息改变时，条件在 [`user_message_uuid`](#user_message_uuid) 中。
1633
1339<h3 id="sdkcompactboundarymessage">1634<h3 id="sdkcompactboundarymessage">
1340 `SDKCompactBoundaryMessage`1635 `SDKCompactBoundaryMessage`
1341</h3>1636</h3>
1359 `SDKInformationalMessage`1654 `SDKInformationalMessage`
1360</h3>1655</h3>
1361 1656
1362由循环发出的通用文本横幅。携带非错误状态行、hook 反馈（例如 `UserPromptSubmit` hook 的阻止原因）和命令输出。将 `content` 呈现为给定 `level` 的纯文本。1657由循环发出的通用文本横幅。携带非错误状态行、hook 反馈（例如 `UserPromptSubmit` hook 的阻止原因）和命令输出。在 Claude Code v2.1.227 或更高版本上，hook 的 [`systemMessage`](/docs/zh-CN/hooks#json-output) 可以作为此消息到达，每行前缀为 hook 的名称，例如 `PostToolUse:Bash says:`。hook 的 `systemMessage` 是否作为此消息到达取决于事件。每个[事件的部分](/docs/zh-CN/hooks#hook-events)在 hooks 页面上说明输出如何显示。将 `content` 呈现为给定 `level` 的纯文本。
1363 1658
1364```typescript theme={null}1659```typescript theme={null}
1365type SDKInformationalMessage = {1660type SDKInformationalMessage = {
1412 `SDKPermissionDeniedMessage`1707 `SDKPermissionDeniedMessage`
1413</h3>1708</h3>
1414 1709
1415当权限系统自动拒绝工具调用而不显示交互式提示时发出的流事件。使用它在发生时在您的 UI 中呈现拒绝，而不仅仅观察随后的 `is_error` 工具结果。交互式询问路径通过 [`canUseTool`](#canusetool) 回调单独到达您的应用程序。由 `PreToolUse` hook 发出的拒绝不会通过此事件报告。1710当权限系统拒绝工具调用而不显示交互式提示时发出的流事件。使用它在发生时在您的 UI 中呈现拒绝，而不仅仅观察随后的 `is_error` 工具结果。它报告哪些拒绝取决于运行如何处理权限提示：
1416 1711
1417此事件需要 Claude Code v2.1.136 或更高版本。1712* **使用 [`canUseTool`](#canusetool) 回调**和默认 [`permissionPrompts: 'host'`](#options)：权限提示转到您的回调，此事件报告 Claude Code 自己决定的拒绝，而不调用它。
1713* **都没有**：裸 `-p` 运行，或 `query()` 既不设置 `canUseTool` 也不设置 `permissionPromptToolName`，拒绝任何会提示的工具调用，此事件报告这些拒绝以及 Claude Code 自己决定的拒绝。在 v2.1.223 之前，Claude Code 在没有回调的运行中不发出此事件。
1714* **使用 MCP 提示工具**，使用 `permissionPromptToolName` 或 [`--permission-prompt-tool`](/docs/zh-CN/cli-reference#cli-flags) 标志设置，以及默认 `permissionPrompts: 'host'`：Claude Code 根本不发出此事件，甚至不发出它自己决定的规则拒绝。
1715* **使用 [`permissionPrompts: 'none'`](#options)**：Claude Code 拒绝会提示的调用，即使也设置了 `canUseTool` 或 MCP 提示工具，此事件报告这些拒绝以及 Claude Code 自己决定的拒绝。需要 Claude Code v2.1.259 或更高版本。
1716
1717在每个配置中，此事件跳过在 `PreToolUse` hook 路径上决定的任何拒绝，无论 hook 本身拒绝了调用还是拒绝规则覆盖了 hook 的允许或询问决定。该事件也是尽力而为的：偶尔 Claude Code 记录拒绝而不发出此事件，因此[结果消息](#sdkresultmessage)上的 `permission_denials` 是权威记录。
1418 1718
1419```typescript theme={null}1719```typescript theme={null}
1420type SDKPermissionDeniedMessage = {1720type SDKPermissionDeniedMessage = {
1454};1754};
1455```1755```
1456 1756
1757<h3 id="sdkcontextusage">
1758 `SDKContextUsage`
1759</h3>
1760
1761`/context` 报告的结构化形式，作为 `context_usage` 在传递 `/context` 结果的 [`SDKAssistantMessage`](#sdkassistantmessage) 上携带。Agent SDK v0.3.232 及更高版本导出该类型。与 [`SDKControlGetContextUsageResponse`](#sdkcontrolgetcontextusageresponse) 不同，它仅携带呈现使用情况分解所需的数据，不包含 `color` 和 `gridRows` 等显示字段。
1762
1763```typescript theme={null}
1764type SDKContextUsage = {
1765 model: string;
1766 total_tokens: number;
1767 raw_max_tokens: number;
1768 percentage: number;
1769 over_limit?: {
1770 tokens_over: number;
1771 kind: "hard_limit" | "compaction_window";
1772 };
1773 categories: SDKContextUsageCategory[];
1774 mcp_tools: {
1775 name: string;
1776 server_name: string;
1777 tokens: number;
1778 }[];
1779 memory_files: {
1780 path: string;
1781 type: string;
1782 tokens: number;
1783 }[];
1784 agents: {
1785 agent_type: string;
1786 source: string;
1787 tokens: number;
1788 }[];
1789 skills?: {
1790 name: string;
1791 source: string;
1792 plugin_name?: string;
1793 tokens: number;
1794 }[];
1795};
1796```
1797
1798表格列出了 Claude Code 在每个字段中放入的内容。从 `model` 到 `over_limit` 的字段描述整个会话，集合字段将令牌归属于单个项目。
1799
1800| 字段 | 类型 | 描述 |
1801| ---------------- | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1802| `model` | `string` | Claude Code 计算使用情况的主循环的模型，不是子代理的 |
1803| `total_tokens` | `number` | Claude Code 对使用中令牌的估计。未限制在窗口，因此当会话超过限制时可以超过 `raw_max_tokens` |
1804| `raw_max_tokens` | `number` | 模型的上下文窗口，或较低的[自动压缩窗口](/docs/zh-CN/model-config#context-window-and-auto-compaction)（当适用时），例如您设置的或 Claude Code 应用于某些具有 1M 令牌窗口的模型的 200K 边界。Claude Code 针对此窗口测量 `total_tokens` |
1805| `percentage` | `number` | `total_tokens` 作为 `raw_max_tokens` 的四舍五入百分比，因此当会话超过限制时可以超过 100 |
1806| `over_limit` | `object` | 仅当 `total_tokens` 超过 `raw_max_tokens` 时存在。`tokens_over` 是超过的数量，`kind` 说明 Claude Code 如何解决窗口 |
1807| `categories` | [`SDKContextUsageCategory`](#sdkcontextusagecategory)`[]` | 使用情况按类别分解的每一行一个条目 |
1808| `mcp_tools` | `object[]` | 归属于每个 MCP 工具的令牌，带有其线路名称（例如 `mcp__linear__create_issue`）和其 `server_name` |
1809| `memory_files` | `object[]` | 归属于每个加载的内存文件的令牌，带有其 `path` 和源标签（例如 `Project` 或 `User`）在 `type` 中 |
1810| `agents` | `object[]` | 归属于每个自定义子代理定义的令牌，带有源标识符，例如 `projectSettings`、`userSettings` 或 `plugin`。内置子代理未列出 |
1811| `skills` | `object[]` | 归属于技能列表中每个技能的令牌，带有源标识符，对于插件技能，插件的名称在 `plugin_name` 中。当没有技能贡献令牌时不存在 |
1812
1813`over_limit.kind` 记录 Claude Code 如何解决窗口，而不是 API 是否接受下一个请求：
1814
1815* `hard_limit`：窗口是 Claude Code 认为是模型自己的限制，超过该限制 API 拒绝请求
1816* `compaction_window`：窗口是压缩策略窗口，可能与模型的限制一致，也可能不一致
1817
1818Claude Code 以加法方式演进该类型，添加新数据作为可选字段而不是重塑现有字段。读取您知道的字段并忽略您不认识的任何字段。
1819
1820<h3 id="sdkcontextusagecategory">
1821 `SDKContextUsageCategory`
1822</h3>
1823
1824`/context` 使用情况按类别分解的一行。
1825
1826```typescript theme={null}
1827type SDKContextUsageCategory = {
1828 name: string;
1829 tokens: number;
1830 kind: "used" | "free" | "buffer" | "deferred";
1831};
1832```
1833
1834表格列出了 Claude Code 在行的每个字段中放入的内容。
1835
1836| 字段 | 类型 | 描述 |
1837| -------- | -------- | ----------------------------------------------------------- |
1838| `name` | `string` | 行的显示名称，如 `/context` 打印的那样，例如 `Messages`。按 `kind` 分类行，而不是按名称 |
1839| `tokens` | `number` | 行的令牌计数。行可以携带零令牌 |
1840| `kind` | `string` | 行代表什么：`used`、`free`、`buffer` 或 `deferred` |
1841
1842每个 `kind` 值说明行的令牌是什么：
1843
1844* `used`：占据上下文窗口的内容
1845* `free`：剩余窗口
1846* `buffer`：压缩保留
1847* `deferred`：Claude Code 保留在窗口外的工具模式，从使用情况计算中排除，列出以供了解
1848
1457<h3 id="sdkmessageorigin">1849<h3 id="sdkmessageorigin">
1458 `SDKMessageOrigin`1850 `SDKMessageOrigin`
1459</h3>1851</h3>
1467 | {1859 | {
1468 kind: "peer";1860 kind: "peer";
1469 from: string;1861 from: string;
1862 fromMode?: "bypass" | "prompting";
1470 name?: string;1863 name?: string;
1864 fromSession?: string;
1471 senderTaskId?: string;1865 senderTaskId?: string;
1472 body?: string;1866 body?: string;
1867 verifiedPeerPid?: number;
1868 }
1869 | {
1870 kind: "task-notification";
1871 subkind?: "scheduled-trigger" | "peer-send-message";
1473 }1872 }
1474 | { kind: "task-notification" }
1475 | { kind: "coordinator" }1873 | { kind: "coordinator" }
1476 | { kind: "auto-continuation" };1874 | { kind: "auto-continuation" }
1875 | { kind: "unclassified" };
1477```1876```
1478 1877
1479| `kind` | 含义 |1878| `kind` | 含义 |
1480| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |1879| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1481| `human` | 来自最终用户的直接输入。在用户消息上，缺少的 `origin` 也表示人工输入。 |1880| `human` | 来自最终用户的直接输入。如果您的应用程序将用户键入的内容转发为用户消息，请明确将其 `origin` 设置为 `{ kind: "human" }`：Claude Code 将没有 `origin` 的用户消息视为未归属，并检查需要人工键入提示的内容，例如 [`ultracode` 工作流关键字](/docs/zh-CN/workflows#ask-for-a-workflow-in-your-prompt)，不接受它。在 v2.1.210 之前，Claude Code 将用户消息上缺失的 `origin` 视为人工输入。 |
1482| `channel` | 消息到达[频道](/docs/zh-CN/channels)。`server` 是源 MCP 服务器名称。 |1881| `channel` | 消息到达[频道](/docs/zh-CN/channels)。`server` 是源 MCP 服务器名称。 |
1483| `peer` | 来自另一个代理的消息。对于通过 `SendMessage` 发送到 `main` 的进程内[队友](/docs/zh-CN/agent-teams)，`from` 是队友的名称，`senderTaskId` 是其任务 ID。对于跨会话对等体（例如另一个本地 Claude Code 进程），`from` 是发送者地址，`senderTaskId` 不存在。}`name` 和 `body` 需要 Claude Code v2.1.205 或更高版本。`name` 是发送者的显示名称，由 Claude Code 规范化：它删除 Unicode 控制、格式、代理和行或段落分隔符代码点，然后修剪结果并将其限制为 64 个代码点，并带有省略号。`body` 是解码的消息正文，去除对等信封，与模型看到的字节完全相同。对于队友消息，`body` 始终存在；对于跨会话对等体，仅当轮次恰好是由 Claude Code 形成的一个对等信封时才存在。呈现 `name` 和 `body` 而不是重新解析消息文本。 |1882| `peer` | 来自另一个代理的消息：进程内[队友](/docs/zh-CN/agent-teams)或[跨会话对等体](/docs/zh-CN/cross-session-messaging)，您的另一个 Claude Code 会话。请参阅[对等体来源字段](#peer-origin-fields)了解每个字段的语义和信任模型。 |
1484| `task-notification` | 后台任务完成后注入的合成轮次。请参阅 [`SDKTaskNotificationMessage`](#sdktasknotificationmessage)。 |1883| `task-notification` | 为没有新用户提示的交付注入的合成轮次，例如完成的后台任务；请参阅 [`SDKTaskNotificationMessage`](#sdktasknotificationmessage) 了解该分支。可选的 `subkind` 标记引发通知的内容。请参阅[任务通知子类型](#task-notification-subkinds)。 |
1485| `coordinator` | 来自[代理团队](/docs/zh-CN/agent-teams)中的团队协调员的消息。 |1884| `coordinator` | 来自[代理团队](/docs/zh-CN/agent-teams)中的团队协调员的消息。 |
1486| `auto-continuation` | 当会话在没有新用户输入的情况下继续时注入的合成轮次，例如触发后续提示的命令结果。 |1885| `auto-continuation` | 当会话在没有新用户输入的情况下继续时注入的合成轮次，例如触发后续提示的命令结果。 |
1886| `unclassified` | 其来源无法确定的注入轮次。当 Claude Code 接收带有 `isSynthetic: true` 的 [`SDKUserMessage`](#sdkusermessage) 并无法将其分类为任何其他 `kind` 时，它在消息到达时设置此类型，并将轮次框架给模型作为非用户源，而不是将其视为人工输入。您的应用程序不应设置此值。 |
1887
1888<h3 id="task-notification-subkinds">
1889 任务通知子类型
1890</h3>
1891
1892当 Claude Code 将任务通知传递到会话中时，它仅在 Anthropic 服务器验证该通知来自何处时才在通知的 `origin` 上设置 `subkind`。`subkind` 需要 Claude Code v2.1.213 或更高版本，它采用两个值之一：
1893
1894* `scheduled-trigger`：通知是[例程](/docs/zh-CN/routines)的存储提示，因为例程的触发器之一触发而传递：其计划、其 [API 触发器](/docs/zh-CN/routines#add-an-api-trigger)、其 [GitHub 触发器](/docs/zh-CN/routines#add-a-github-trigger) 或**立即运行**。Claude Code 将这些框架给模型作为会话的分配任务，带有与[其他任务通知携带的通知](#sdktasknotificationmessage)不同的通知。
1895* `peer-send-message`：通知是另一个您的会话使用服务器端 `send_message` 工具发送的消息，[Claude Code on the web](/docs/zh-CN/claude-code-on-the-web) 会话使用该工具相互消息，而不是[跨会话 `SendMessage` 工具](/docs/zh-CN/cross-session-messaging)，Anthropic 服务器验证了两个会话都属于同一私人会话组。需要 Claude Code v2.1.224 或更高版本。服务器未以这种方式验证的 `send_message` 交付没有 subkind。
1896
1897每个其他任务通知都没有 `subkind`。这包括在您自己的机器上触发的[计划任务](/docs/zh-CN/scheduled-tasks)、[PR 活动](/docs/zh-CN/claude-code-on-the-web#how-claude-responds-to-pr-activity)传递到会话中，以及后台事件，例如完成的任务。来自[跨会话 `SendMessage` 工具](/docs/zh-CN/cross-session-messaging)的消息根本不是任务通知：无论它们来自同一机器上的会话还是通过 Anthropic 服务器来自另一台机器，Claude Code 都给它们 `kind: "peer"` 和[对等体来源字段](#peer-origin-fields)。
1898
1899<h3 id="peer-origin-fields">
1900 对等体来源字段
1901</h3>
1902
1903`peer` 来源标识哪个代理发送了消息：进程内[队友](/docs/zh-CN/agent-teams)使用 `SendMessage` 发送到 `main`，或[跨会话对等体](/docs/zh-CN/cross-session-messaging)，您的另一个 Claude Code 会话。跨会话对等体需要 macOS 和 Linux 上的 Claude Code v2.1.224 或更高版本；请参阅[跨会话消息可用性](/docs/zh-CN/cross-session-messaging#availability)了解本机 Windows 要求。跨会话对等体可以在同一机器上运行，或在[您的另一台机器](/docs/zh-CN/cross-session-messaging#message-sessions-on-other-machines)或[Claude Code on the web](/docs/zh-CN/claude-code-on-the-web) 上，当其消息通过远程控制到达时。两种发送者类型填充字段的方式不同：
1904
1905* `from`：队友的名称，或跨会话对等体的发送者地址。对于[单向跨机器消息](/docs/zh-CN/cross-session-messaging#message-sessions-on-other-machines)，发送者没有回复地址，`from` 是 `"unknown"`。该值由发送者创作；`verifiedPeerPid` 是验证的身份。
1906* `fromMode`：发送会话的权限类别，`bypass` 或 `prompting`，由在您的会话之间中继对等消息的主机声明，例如[桌面应用](/docs/zh-CN/desktop#work-across-sessions)。Claude Code 在接收会话中应用[入站控制](/docs/zh-CN/cross-session-messaging#control-inbound-messages)时读取它。需要 Agent SDK v0.3.234 或更高版本。
1907* `senderTaskId`：队友的任务 ID。对于跨会话对等体不存在。
1908* `name`：发送者的显示名称，由 Claude Code 规范化：它删除 Unicode 控制、格式、代理和行或段落分隔符代码点，然后修剪结果并将其限制为 64 个代码点，带有省略号。需要 Claude Code v2.1.205 或更高版本。
1909* `body`：解码的消息正文，去除对等信封，与模型看到的字节完全相同。对于队友消息始终存在；对于跨会话对等体，仅当轮次恰好是由 Claude Code 形成的一个对等信封时才存在。呈现 `name` 和 `body` 而不是重新解析消息文本。需要 Claude Code v2.1.205 或更高版本。
1910* `fromSession`：发送者的主机可打开会话 ID，由发送者的主机设置，以便您的 UI 可以链接回发送会话。像 `from` 一样，它是发送者声称的：仅将其用作导航目标，不要将其视为发送者身份的证明。需要 Claude Code v2.1.216 或更高版本。
1911* `verifiedPeerPid`：连接到此会话的跨会话消息套接字的进程的进程 ID，由内核验证并从连接本身读取，从不从有效负载读取。使用它，而不是 `from`，来标识发送者：`from` 可由任何同用户进程伪造。当 Claude Code 无法验证它时，该字段不存在，例如在 Windows 或非套接字入口上，因此缺失值意味着发送者未验证。对于中继流量，它标识中继而不是消息的作者，进程 ID 是可回收的，因此将其视为来源而不是身份验证令牌。需要 Claude Code v2.1.216 或更高版本。
1487 1912
1488<h2 id="hook-types">1913<h2 id="hook-types">
1489 Hook 类型1914 Hook 类型
1505 | "PostToolBatch"1930 | "PostToolBatch"
1506 | "Notification"1931 | "Notification"
1507 | "UserPromptSubmit"1932 | "UserPromptSubmit"
1933 | "UserPromptExpansion"
1508 | "SessionStart"1934 | "SessionStart"
1509 | "SessionEnd"1935 | "SessionEnd"
1510 | "Stop"1936 | "Stop"
1937 | "StopFailure"
1511 | "SubagentStart"1938 | "SubagentStart"
1512 | "SubagentStop"1939 | "SubagentStop"
1513 | "PreCompact"1940 | "PreCompact"
1941 | "PostCompact"
1942 | "PreModelSwitch"
1943 | "PostModelSwitch"
1514 | "PermissionRequest"1944 | "PermissionRequest"
1945 | "PermissionDenied"
1515 | "Setup"1946 | "Setup"
1516 | "TeammateIdle"1947 | "TeammateIdle"
1948 | "TaskCreated"
1517 | "TaskCompleted"1949 | "TaskCompleted"
1950 | "Elicitation"
1951 | "ElicitationResult"
1518 | "ConfigChange"1952 | "ConfigChange"
1953 | "DirectoryAdded"
1519 | "WorktreeCreate"1954 | "WorktreeCreate"
1520 | "WorktreeRemove"1955 | "WorktreeRemove"
1956 | "InstructionsLoaded"
1957 | "CwdChanged"
1958 | "FileChanged"
1521 | "MessageDisplay";1959 | "MessageDisplay";
1522```1960```
1523 1961
1561 | PostToolUseHookInput1999 | PostToolUseHookInput
1562 | PostToolUseFailureHookInput2000 | PostToolUseFailureHookInput
1563 | PostToolBatchHookInput2001 | PostToolBatchHookInput
2002 | PermissionDeniedHookInput
1564 | NotificationHookInput2003 | NotificationHookInput
1565 | UserPromptSubmitHookInput2004 | UserPromptSubmitHookInput
2005 | UserPromptExpansionHookInput
1566 | SessionStartHookInput2006 | SessionStartHookInput
1567 | SessionEndHookInput2007 | SessionEndHookInput
1568 | StopHookInput2008 | StopHookInput
2009 | StopFailureHookInput
1569 | SubagentStartHookInput2010 | SubagentStartHookInput
1570 | SubagentStopHookInput2011 | SubagentStopHookInput
1571 | PreCompactHookInput2012 | PreCompactHookInput
2013 | PostCompactHookInput
2014 | PreModelSwitchHookInput
2015 | PostModelSwitchHookInput
1572 | PermissionRequestHookInput2016 | PermissionRequestHookInput
1573 | SetupHookInput2017 | SetupHookInput
1574 | TeammateIdleHookInput2018 | TeammateIdleHookInput
2019 | TaskCreatedHookInput
1575 | TaskCompletedHookInput2020 | TaskCompletedHookInput
2021 | ElicitationHookInput
2022 | ElicitationResultHookInput
1576 | ConfigChangeHookInput2023 | ConfigChangeHookInput
2024 | InstructionsLoadedHookInput
2025 | DirectoryAddedHookInput
1577 | WorktreeCreateHookInput2026 | WorktreeCreateHookInput
1578 | WorktreeRemoveHookInput2027 | WorktreeRemoveHookInput
2028 | CwdChangedHookInput
2029 | FileChangedHookInput
1579 | MessageDisplayHookInput;2030 | MessageDisplayHookInput;
1580```2031```
1581 2032
1664};2115};
1665```2116```
1666 2117
2118<h4 id="permissiondeniedhookinput">
2119 `PermissionDeniedHookInput`
2120</h4>
2121
2122```typescript theme={null}
2123type PermissionDeniedHookInput = BaseHookInput & {
2124 hook_event_name: "PermissionDenied";
2125 tool_name: string;
2126 tool_input: unknown;
2127 tool_use_id: string;
2128 reason: string;
2129};
2130```
2131
1667<h4 id="notificationhookinput">2132<h4 id="notificationhookinput">
1668 `NotificationHookInput`2133 `NotificationHookInput`
1669</h4>2134</h4>
1685type UserPromptSubmitHookInput = BaseHookInput & {2150type UserPromptSubmitHookInput = BaseHookInput & {
1686 hook_event_name: "UserPromptSubmit";2151 hook_event_name: "UserPromptSubmit";
1687 prompt: string;2152 prompt: string;
2153 session_title?: string;
2154};
2155```
2156
2157<h4 id="userpromptexpansionhookinput">
2158 `UserPromptExpansionHookInput`
2159</h4>
2160
2161```typescript theme={null}
2162type UserPromptExpansionHookInput = BaseHookInput & {
2163 hook_event_name: "UserPromptExpansion";
2164 expansion_type: "slash_command" | "mcp_prompt";
2165 command_name: string;
2166 command_args: string;
2167 command_source?: string;
2168 prompt: string;
1688};2169};
1689```2170```
1690 2171
1695```typescript theme={null}2176```typescript theme={null}
1696type SessionStartHookInput = BaseHookInput & {2177type SessionStartHookInput = BaseHookInput & {
1697 hook_event_name: "SessionStart";2178 hook_event_name: "SessionStart";
1698 source: "startup" | "resume" | "clear" | "compact";2179 source: "startup" | "resume" | "clear" | "compact" | "fork";
1699 agent_type?: string;2180 agent_type?: string;
1700 model?: string;2181 model?: string;
2182 session_title?: string;
1701};2183};
1702```2184```
1703 2185
1726};2208};
1727```2209```
1728 2210
2211<h4 id="stopfailurehookinput">
2212 `StopFailureHookInput`
2213</h4>
2214
2215```typescript theme={null}
2216type StopFailureHookInput = BaseHookInput & {
2217 hook_event_name: "StopFailure";
2218 error: SDKAssistantMessageError;
2219 error_details?: string;
2220 last_assistant_message?: string;
2221};
2222```
2223
1729<h4 id="subagentstarthookinput">2224<h4 id="subagentstarthookinput">
1730 `SubagentStartHookInput`2225 `SubagentStartHookInput`
1731</h4>2226</h4>
1786};2281};
1787```2282```
1788 2283
2284<h4 id="postcompacthookinput">
2285 `PostCompactHookInput`
2286</h4>
2287
2288```typescript theme={null}
2289type PostCompactHookInput = BaseHookInput & {
2290 hook_event_name: "PostCompact";
2291 trigger: "manual" | "auto";
2292 compact_summary: string;
2293};
2294```
2295
2296<h4 id="premodelswitchhookinput">
2297 `PreModelSwitchHookInput`
2298</h4>
2299
2300在请求的模型切换生效之前触发。`context_tokens` 和之后的字段估计向新模型重新发送对话的成本。有关完整的字段描述和阻止语义，请参阅 [PreModelSwitch](/docs/zh-CN/hooks#premodelswitch)。
2301
2302```typescript theme={null}
2303type PreModelSwitchHookInput = BaseHookInput & {
2304 hook_event_name: "PreModelSwitch";
2305 from_model: string;
2306 to_model: string;
2307 requested_model: string | null;
2308 source: "command" | "picker" | "sdk";
2309 context_tokens: number;
2310 prompt_cache_warm: boolean;
2311 cache_ttl: "5m" | "1h";
2312 estimated_cache_write_usd: number;
2313 pricing: "configured" | "catalog" | "default";
2314};
2315```
2316
2317<h4 id="postmodelswitchhookinput">
2318 `PostModelSwitchHookInput`
2319</h4>
2320
2321在会话的模型更改后触发。它携带与 `PreModelSwitchHookInput` 相同的字段，另外还有两个 `source` 值。请参阅 [PostModelSwitch](/docs/zh-CN/hooks#postmodelswitch)。
2322
2323```typescript theme={null}
2324type PostModelSwitchHookInput = BaseHookInput & {
2325 hook_event_name: "PostModelSwitch";
2326 from_model: string;
2327 to_model: string;
2328 requested_model: string | null;
2329 source: "command" | "picker" | "sdk" | "auto" | "resume";
2330 context_tokens: number;
2331 prompt_cache_warm: boolean;
2332 cache_ttl: "5m" | "1h";
2333 estimated_cache_write_usd: number;
2334 pricing: "configured" | "catalog" | "default";
2335};
2336```
2337
1789<h4 id="permissionrequesthookinput">2338<h4 id="permissionrequesthookinput">
1790 `PermissionRequestHookInput`2339 `PermissionRequestHookInput`
1791</h4>2340</h4>
1823};2372};
1824```2373```
1825 2374
1826<h4 id="taskcompletedhookinput">2375<h4 id="taskcreatedhookinput">
1827 `TaskCompletedHookInput`2376 `TaskCreatedHookInput`
1828</h4>2377</h4>
1829 2378
1830```typescript theme={null}2379```typescript theme={null}
1831type TaskCompletedHookInput = BaseHookInput & {2380type TaskCreatedHookInput = BaseHookInput & {
1832 hook_event_name: "TaskCompleted";2381 hook_event_name: "TaskCreated";
1833 task_id: string;2382 task_id: string;
1834 task_subject: string;2383 task_subject: string;
1835 task_description?: string;2384 task_description?: string;
1839};2388};
1840```2389```
1841 2390
2391<h4 id="taskcompletedhookinput">
2392 `TaskCompletedHookInput`
2393</h4>
2394
2395```typescript theme={null}
2396type TaskCompletedHookInput = BaseHookInput & {
2397 hook_event_name: "TaskCompleted";
2398 task_id: string;
2399 task_subject: string;
2400 task_description?: string;
2401 teammate_name?: string;
2402 /** @deprecated 自 v2.1.178 起已弃用。携带会话派生的团队名称；将被移除。 */
2403 team_name?: string;
2404};
2405```
2406
2407<h4 id="elicitationhookinput">
2408 `ElicitationHookInput`
2409</h4>
2410
2411```typescript theme={null}
2412type ElicitationHookInput = BaseHookInput & {
2413 hook_event_name: "Elicitation";
2414 mcp_server_name: string;
2415 message: string;
2416 mode?: "form" | "url";
2417 url?: string;
2418 elicitation_id?: string;
2419 requested_schema?: Record<string, unknown>;
2420};
2421```
2422
2423<h4 id="elicitationresulthookinput">
2424 `ElicitationResultHookInput`
2425</h4>
2426
2427```typescript theme={null}
2428type ElicitationResultHookInput = BaseHookInput & {
2429 hook_event_name: "ElicitationResult";
2430 mcp_server_name: string;
2431 elicitation_id?: string;
2432 mode?: "form" | "url";
2433 action: "accept" | "decline" | "cancel";
2434 content?: Record<string, unknown>;
2435};
2436```
2437
1842<h4 id="configchangehookinput">2438<h4 id="configchangehookinput">
1843 `ConfigChangeHookInput`2439 `ConfigChangeHookInput`
1844</h4>2440</h4>
1856};2452};
1857```2453```
1858 2454
2455<h4 id="instructionsloadedhookinput">
2456 `InstructionsLoadedHookInput`
2457</h4>
2458
2459```typescript theme={null}
2460type InstructionsLoadedHookInput = BaseHookInput & {
2461 hook_event_name: "InstructionsLoaded";
2462 file_path: string;
2463 memory_type: "User" | "Project" | "Local" | "Managed";
2464 load_reason:
2465 | "session_start"
2466 | "nested_traversal"
2467 | "path_glob_match"
2468 | "include"
2469 | "compact";
2470 globs?: string[];
2471 trigger_file_path?: string;
2472 parent_file_path?: string;
2473};
2474```
2475
2476<h4 id="directoryaddedhookinput">
2477 `DirectoryAddedHookInput`
2478</h4>
2479
2480```typescript theme={null}
2481type DirectoryAddedHookInput = BaseHookInput & {
2482 hook_event_name: "DirectoryAdded";
2483 directory: string;
2484 source: "slash_command" | "register_repo_root";
2485};
2486```
2487
2488`directory` 是被添加的目录的绝对路径。当 `/add-dir` 添加它时，`source` 是 `"slash_command"`，当 SDK 控制请求添加它时，`source` 是 `"register_repo_root"`。
2489
1859<h4 id="worktreecreatehookinput">2490<h4 id="worktreecreatehookinput">
1860 `WorktreeCreateHookInput`2491 `WorktreeCreateHookInput`
1861</h4>2492</h4>
1878};2509};
1879```2510```
1880 2511
2512<h4 id="cwdchangedhookinput">
2513 `CwdChangedHookInput`
2514</h4>
2515
2516```typescript theme={null}
2517type CwdChangedHookInput = BaseHookInput & {
2518 hook_event_name: "CwdChanged";
2519 old_cwd: string;
2520 new_cwd: string;
2521};
2522```
2523
2524<h4 id="filechangedhookinput">
2525 `FileChangedHookInput`
2526</h4>
2527
2528```typescript theme={null}
2529type FileChangedHookInput = BaseHookInput & {
2530 hook_event_name: "FileChanged";
2531 file_path: string;
2532 event: "change" | "add" | "unlink";
2533};
2534```
2535
1881<h4 id="messagedisplayhookinput">2536<h4 id="messagedisplayhookinput">
1882 `MessageDisplayHookInput`2537 `MessageDisplayHookInput`
1883</h4>2538</h4>
1925 stopReason?: string;2580 stopReason?: string;
1926 decision?: "approve" | "block";2581 decision?: "approve" | "block";
1927 systemMessage?: string;2582 systemMessage?: string;
2583 /**
2584 * 一个终端转义序列（例如 OSC 9 / OSC 777 desktop-notification）
2585 * 供 Claude Code 代表您发出。仅允许通知/标题 OSCs
2586 * （0、1、2、9、99、777）和 BEL；包含任何其他内容的值
2587 * 将被整体忽略。仅交互式 CLI 会发出它；SDK 忽略该字段。
2588 */
2589 terminalSequence?: string;
1928 reason?: string;2590 reason?: string;
1929 hookSpecificOutput?:2591 hookSpecificOutput?:
1930 | {2592 | {
1937 | {2599 | {
1938 hookEventName: "UserPromptSubmit";2600 hookEventName: "UserPromptSubmit";
1939 additionalContext?: string;2601 additionalContext?: string;
2602 sessionTitle?: string;
2603 /** 当 decision 为 "block" 时，从阻止消息中省略原始提示。 */
2604 suppressOriginalPrompt?: boolean;
2605 }
2606 | {
2607 hookEventName: "UserPromptExpansion";
2608 additionalContext?: string;
1940 }2609 }
1941 | {2610 | {
1942 hookEventName: "SessionStart";2611 hookEventName: "SessionStart";
1943 additionalContext?: string;2612 additionalContext?: string;
2613 initialUserMessage?: string;
2614 sessionTitle?: string;
2615 watchPaths?: string[];
2616 /**
2617 * SessionStart hooks 完成后重新扫描 skill 和命令目录，
2618 * 以便 hook 安装的 skills 在同一会话中可用。
2619 */
2620 reloadSkills?: boolean;
1944 }2621 }
1945 | {2622 | {
1946 hookEventName: "Setup";2623 hookEventName: "Setup";
1947 additionalContext?: string;2624 additionalContext?: string;
1948 }2625 }
2626 | {
2627 hookEventName: "PreModelSwitch";
2628 /**
2629 * 与 PreToolUse 相同的约定："allow" 继续，"deny" 取消
2630 * 切换，"ask" 要求用户确认。仅交互式会话中的 /model
2631 * 显示该提示；其他所有表面，包括 set_model 请求，
2632 * 将 "ask" 视为拒绝。
2633 */
2634 permissionDecision?: "allow" | "deny" | "ask";
2635 permissionDecisionReason?: string;
2636 }
2637 | {
2638 hookEventName: "PostModelSwitch";
2639 /** 通过新模型服务的下一个请求到达模型。 */
2640 additionalContext?: string;
2641 }
1949 | {2642 | {
1950 hookEventName: "SubagentStart";2643 hookEventName: "SubagentStart";
1951 additionalContext?: string;2644 additionalContext?: string;
1953 | {2646 | {
1954 hookEventName: "PostToolUse";2647 hookEventName: "PostToolUse";
1955 additionalContext?: string;2648 additionalContext?: string;
2649 /**
2650 * 关于此工具调用结果的简短说明，用于自动模式
2651 * 权限分类器。限制为 2000 个字符，在响应同一调用的
2652 * 所有 hooks 之间共享；仅在同步 hook 响应上被接受。
2653 * 不要将不受信任的工具输出复制到其中。
2654 */
2655 classifierContext?: string;
1956 updatedToolOutput?: unknown;2656 updatedToolOutput?: unknown;
1957 /** @deprecated 使用 `updatedToolOutput`，它适用于所有工具。 */2657 /** @deprecated 使用 `updatedToolOutput`，它适用于所有工具。 */
1958 updatedMCPToolOutput?: unknown;2658 updatedMCPToolOutput?: unknown;
1965 hookEventName: "PostToolBatch";2665 hookEventName: "PostToolBatch";
1966 additionalContext?: string;2666 additionalContext?: string;
1967 }2667 }
2668 | {
2669 hookEventName: "Stop";
2670 additionalContext?: string;
2671 }
2672 | {
2673 hookEventName: "SubagentStop";
2674 additionalContext?: string;
2675 }
2676 | {
2677 hookEventName: "PermissionDenied";
2678 retry?: boolean;
2679 }
1968 | {2680 | {
1969 hookEventName: "Notification";2681 hookEventName: "Notification";
1970 additionalContext?: string;2682 additionalContext?: string;
1982 message?: string;2694 message?: string;
1983 interrupt?: boolean;2695 interrupt?: boolean;
1984 };2696 };
2697 }
2698 | {
2699 hookEventName: "Elicitation";
2700 action?: "accept" | "decline" | "cancel";
2701 content?: Record<string, unknown>;
2702 }
2703 | {
2704 hookEventName: "ElicitationResult";
2705 action?: "accept" | "decline" | "cancel";
2706 content?: Record<string, unknown>;
2707 }
2708 | {
2709 hookEventName: "CwdChanged";
2710 watchPaths?: string[];
2711 }
2712 | {
2713 hookEventName: "FileChanged";
2714 watchPaths?: string[];
2715 }
2716 | {
2717 hookEventName: "WorktreeCreate";
2718 worktreePath: string;
2719 }
2720 | {
2721 hookEventName: "MessageDisplay";
2722 /** 用来代替 delta 显示的文本。省略（或返回 delta 不变）以显示原始内容。 */
2723 displayContent?: string;
1985 };2724 };
1986};2725};
1987```2726```
1996 `ToolInputSchemas`2735 `ToolInputSchemas`
1997</h3>2736</h3>
1998 2737
1999所有工具输入类型的联合，从 `@anthropic-ai/claude-agent-sdk` 导出。2738从 `@anthropic-ai/claude-agent-sdk` 导出的工具输入类型的联合；成员包括：
2000 2739
2001```typescript theme={null}2740```typescript theme={null}
2002type ToolInputSchemas =2741type ToolInputSchemas =
2003 | AgentInput2742 | AgentInput
2743 | ArtifactInput
2004 | AskUserQuestionInput2744 | AskUserQuestionInput
2005 | BashInput2745 | BashInput
2006 | TaskOutputInput2746 | CronCreateInput
2747 | CronDeleteInput
2748 | CronListInput
2749 | EnterPlanModeInput
2007 | EnterWorktreeInput2750 | EnterWorktreeInput
2008 | ExitPlanModeInput2751 | ExitPlanModeInput
2752 | ExitWorktreeInput
2009 | FileEditInput2753 | FileEditInput
2010 | FileReadInput2754 | FileReadInput
2011 | FileWriteInput2755 | FileWriteInput
2015 | McpInput2759 | McpInput
2016 | MonitorInput2760 | MonitorInput
2017 | NotebookEditInput2761 | NotebookEditInput
2762 | ProjectsInput
2763 | PushNotificationInput
2764 | ReadMcpResourceDirInput
2018 | ReadMcpResourceInput2765 | ReadMcpResourceInput
2019 | SubscribeMcpResourceInput2766 | RefreshMcpToolsInput
2020 | SubscribePollingInput2767 | RemoteTriggerInput
2768 | REPLInput
2769 | ReportFindingsInput
2770 | ScheduleWakeupInput
2771 | ShowOnboardingRolePickerInput
2021 | TaskCreateInput2772 | TaskCreateInput
2022 | TaskGetInput2773 | TaskGetInput
2023 | TaskListInput2774 | TaskListInput
2775 | TaskOutputInput
2024 | TaskStopInput2776 | TaskStopInput
2025 | TaskUpdateInput2777 | TaskUpdateInput
2026 | TodoWriteInput2778 | TodoWriteInput
2027 | UnsubscribeMcpResourceInput
2028 | UnsubscribePollingInput
2029 | WebFetchInput2779 | WebFetchInput
2030 | WebSearchInput2780 | WebSearchInput
2031 | WorkflowInput;2781 | WorkflowInput;
2035 Agent2785 Agent
2036</h3>2786</h3>
2037 2787
2038**工具名称：** `Agent`（之前为 `Task`，仍然接受作为别名）2788**工具名称：** `Agent`。之前的名称 `Task` 仍然被接受作为别名，[`SDKSystemMessage`](#sdksystemmessage) 初始化消息中的 `tools` 数组目前为了向后兼容仍将此工具列为 `Task`。
2789
2790<Note>
2791 `mode` 字段在 Claude Code v2.1.212 或更高版本上已弃用且被忽略。子代理在父会话的权限模式或其定义的 [`permissionMode`](#agentdefinition) 中运行，[子代理继承规则](/docs/zh-CN/agent-sdk/permissions#available-modes)决定使用哪一个。
2792</Note>
2039 2793
2040```typescript theme={null}2794```typescript theme={null}
2041type AgentInput = {2795type AgentInput = {
2045 model?: "sonnet" | "opus" | "haiku" | "fable";2799 model?: "sonnet" | "opus" | "haiku" | "fable";
2046 run_in_background?: boolean;2800 run_in_background?: boolean;
2047 name?: string;2801 name?: string;
2048 mode?: "acceptEdits" | "auto" | "bypassPermissions" | "default" | "dontAsk" | "plan";2802 team_name?: string; // 已弃用；被忽略
2049 isolation?: "worktree";2803 mode?: "acceptEdits" | "auto" | "bypassPermissions" | "default" | "dontAsk" | "plan"; // 已弃用；被忽略。子代理继承规则决定子代理的权限模式
2804 isolation?: "worktree" | "remote";
2050};2805};
2051```2806```
2052 2807
2066 options: Array<{ label: string; description: string; preview?: string }>;2821 options: Array<{ label: string; description: string; preview?: string }>;
2067 multiSelect: boolean;2822 multiSelect: boolean;
2068 }>;2823 }>;
2824 answers?: Record<string, string>;
2825 annotations?: Record<string, { preview?: string; notes?: string }>;
2826 metadata?: { source?: string };
2069};2827};
2070```2828```
2071 2829
2087};2845};
2088```2846```
2089 2847
2090在持久 shell 会话中执行 bash 命令，支持可选超时和后台执行。2848执行 Bash 命令，支持可选超时和后台执行。工作目录在命令之间保持不变，包括多轮会话后续轮次中运行的命令；shell 状态（如导出的环境变量）不保持。有关哪些目录更改会保持的限制，请参阅[命令之间保持什么](/docs/zh-CN/tools-reference#what-persists-between-commands)。
2091 2849
2092<h3 id="monitor">2850<h3 id="monitor">
2093 Monitor2851 Monitor
2103 protocols?: string[];2861 protocols?: string[];
2104 };2862 };
2105 description: string;2863 description: string;
2106 timeout_ms?: number;2864 timeout_ms: number;
2107 persistent?: boolean;2865 persistent: boolean;
2108};2866};
2109```2867```
2110 2868
2111运行后台源并将每个事件传递给 Claude，以便它可以做出反应而无需轮询：`command` 运行脚本并为每个 stdout 行发出一个事件，`ws` 打开 WebSocket 并为每个文本帧发出一个事件。恰好提供 `command` 或 `ws` 之一。`ws` 源需要 Claude Code v2.1.195 或更高版本。2869运行后台源并将每个事件传递给 Claude，以便它可以做出反应而无需轮询：`command` 运行脚本并为每个 stdout 行发出一个事件，`ws` 打开 WebSocket 并为每个文本帧发出一个事件。恰好提供 `command` 或 `ws` 之一。`ws` 源需要 Claude Code v2.1.195 或更高版本。
2112 2870
2113为会话长度的监视（如日志尾部）设置 `persistent: true`。当 Monitor 运行命令时，它遵循与 Bash 相同的权限规则；WebSocket 监视会单独提示批准。请参阅 [Monitor 工具参考](/docs/zh-CN/tools-reference#monitor-tool)了解行为和提供商可用性。2871为会话长度的监视（如日志尾部）设置 `persistent: true`。当 Monitor 运行命令时，它遵循与 Bash 相同的权限规则；WebSocket 监视会单独提示批准。请参阅 [Monitor 工具参考](/docs/zh-CN/tools-reference#monitor-tool)了解行为和提供商可用性。导出的类型将 `timeout_ms` 和 `persistent` 标记为必需，因为架构填充了它们的默认值 300000 和 `false`；省略它们的调用会验证通过。
2114 2872
2115<h3 id="taskoutput">2873<h3 id="taskoutput">
2116 TaskOutput2874 TaskOutput
2118 2876
2119**工具名称：** `TaskOutput`2877**工具名称：** `TaskOutput`
2120 2878
2879<Note>`TaskOutput` 已弃用；改为在任务的输出文件路径上使用 `Read`。以下架构对于遇到该工具的 hooks 和权限处理程序仍然有效。</Note>
2880
2121```typescript theme={null}2881```typescript theme={null}
2122type TaskOutputInput = {2882type TaskOutputInput = {
2123 task_id: string;2883 task_id: string;
2162 2922
2163从本地文件系统读取文件，包括文本、图像、PDF 和 Jupyter 笔记本。对 PDF 页面范围使用 `pages`（例如，`"1-5"`）。2923从本地文件系统读取文件，包括文本、图像、PDF 和 Jupyter 笔记本。对 PDF 页面范围使用 `pages`（例如，`"1-5"`）。
2164 2924
2925对于 PDF，Claude 在 Read 调用的 `tool_result` 内容中接收文件的内容。返回 `pdf` [输出](#tool-output-types)的读取操作包含一个摘要 `text` 块，后跟一个 `document` 块。返回 `parts` 输出的读取操作包含摘要 `text` 块，后跟每个提取页面的一个块：一个 `image` 块，或当 Claude Code 无法将其呈现为图像时命名该页面的 `text` 块。在 Agent SDK v0.3.242 之前，Claude Code 在工具结果后作为单独的 `user` 消息传递文件的内容。
2926
2165<h3 id="write">2927<h3 id="write">
2166 Write2928 Write
2167</h3>2929</h3>
2206 type?: string;2968 type?: string;
2207 output_mode?: "content" | "files_with_matches" | "count";2969 output_mode?: "content" | "files_with_matches" | "count";
2208 "-i"?: boolean;2970 "-i"?: boolean;
2971 "-o"?: boolean; // 仅打印每行的匹配部分；需要 output_mode: "content"
2209 "-n"?: boolean;2972 "-n"?: boolean;
2210 "-B"?: number;2973 "-B"?: number;
2211 "-A"?: number;2974 "-A"?: number;
2294 script?: string;3057 script?: string;
2295 name?: string;3058 name?: string;
2296 scriptPath?: string;3059 scriptPath?: string;
2297 args?: unknown;3060 args?: unknown; // 任何 JSON 值；发布的类型将其呈现为对象映射
2298 resumeFromRunId?: string;3061 resumeFromRunId?: string;
3062 title?: string; // 被忽略；脚本的 meta 块设置标题
3063 description?: string; // 被忽略；脚本的 meta 块设置描述
2299};3064};
2300```3065```
2301 3066
2305| ----------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |3070| ----------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
2306| `script` | `string` | 内联工作流脚本。必须以 `export const meta = { name, description }` 作为字面量开头，后跟使用 `agent()`、`parallel()`、`pipeline()` 和 `phase()` 的脚本主体。`meta` 中的可选 `phases` 数组在进度视图中将代理分组到命名阶段下 |3071| `script` | `string` | 内联工作流脚本。必须以 `export const meta = { name, description }` 作为字面量开头，后跟使用 `agent()`、`parallel()`、`pipeline()` 和 `phase()` 的脚本主体。`meta` 中的可选 `phases` 数组在进度视图中将代理分组到命名阶段下 |
2307| `name` | `string` | 内置工作流的名称或保存在 `.claude/workflows/` 中的工作流名称。解析为脚本 |3072| `name` | `string` | 内置工作流的名称或保存在 `.claude/workflows/` 中的工作流名称。解析为脚本 |
2308| `scriptPath` | `string` | 磁盘上工作流脚本文件的路径。优先于 `script` 和 `name`。每次调用都会持久化其脚本并在结果中返回路径，因此您可以编辑该文件并使用相同的 `scriptPath` 重新调用以进行迭代 |3073| `scriptPath` | `string` | 磁盘上工作流脚本文件的路径。优先于 `script` 和 `name`。Claude Code 持久化每次调用的脚本并在结果中返回路径，因此您可以编辑该文件并使用相同的 `scriptPath` 重新调用以进行迭代 |
2309| `args` | `unknown` | 输入值，作为全局 `args` 暴露给脚本，用于参数化的命名工作流，例如研究问题或文件路径列表。将数组和对象作为实际 JSON 值传递，而不是作为 JSON 编码的字符串 |3074| `args` | `unknown` | 输入值，作为全局 `args` 暴露给脚本，用于参数化的命名工作流，例如研究问题或文件路径列表。将数组和对象作为实际 JSON 值传递，而不是作为 JSON 编码的字符串 |
2310| `resumeFromRunId` | `string` | 要恢复的先前 `Workflow` 调用的运行 ID。具有未更改输入的已完成 `agent()` 调用返回缓存的结果；只有更改或新的调用才会实时运行。仅限同一会话 |3075| `resumeFromRunId` | `string` | 要恢复的先前 `Workflow` 调用的运行 ID。具有未更改输入的已完成 `agent()` 调用通常返回缓存的结果；其余的实时运行。[暂停后恢复](/docs/zh-CN/workflows#resume-after-a-pause)涵盖哪些已完成的调用会重新运行。仅限同一会话 |
3076| `title` | `string` | 被忽略；脚本的 `meta` 块设置标题 |
3077| `description` | `string` | 被忽略；脚本的 `meta` 块设置描述 |
2311 3078
2312<h3 id="todowrite">3079<h3 id="todowrite">
2313 TodoWrite3080 TodoWrite
2328创建和管理结构化任务列表以跟踪进度。3095创建和管理结构化任务列表以跟踪进度。
2329 3096
2330<Note>3097<Note>
2331 自 TypeScript Agent SDK 0.3.142 起，`TodoWrite` 默认被禁用。改用 `TaskCreate`、`TaskGet`、`TaskUpdate` 和 `TaskList`。请参阅[迁移到 Task 工具](/docs/zh-CN/agent-sdk/todo-tracking#migrate-to-task-tools)以更新您的监视代码，或设置 `CLAUDE_CODE_ENABLE_TASKS=0` 以恢复为 `TodoWrite`。3098 The following tools are available by default only on Claude 3.x models, Opus 4 through 4.7, Sonnet 4 through 4.6, and Haiku 4.5. On every other model, including model IDs Claude Code doesn't recognize, they aren't available unless you opt in:
3099
3100 * `TodoWrite`
3101 * `TaskCreate`
3102 * `TaskGet`
3103 * `TaskUpdate`
3104 * `TaskList`
3105
3106 Wherever the tools are available, Claude Code provides the four Task tools, or `TodoWrite` instead when you set `CLAUDE_CODE_ENABLE_TASKS=0`.
3107
3108 This default set applies in Claude Code v2.1.268 and later, which the TypeScript Agent SDK bundles from v0.3.268.
3109
3110 请参阅[模型可用性](/docs/zh-CN/agent-sdk/todo-tracking#model-availability)以选择加入。
2332</Note>3111</Note>
2333 3112
2334<h3 id="taskcreate">3113<h3 id="taskcreate">
2409 tool: "Bash";3188 tool: "Bash";
2410 prompt: string;3189 prompt: string;
2411 }>;3190 }>;
3191 [k: string]: unknown;
2412};3192};
2413```3193```
2414 3194
2415退出规划模式。`allowedPrompts` 字段已弃用且被忽略；Claude Code 仍然接受它，以便现有调用者和记录验证。在 v2.1.205 之前，它请求基于提示的 Bash 权限以实现计划。3195退出 Plan Mode。`allowedPrompts` 字段已弃用且被忽略；Claude Code 仍然接受它，以便现有调用者和记录验证。在 v2.1.205 之前，它请求基于提示的 Bash 权限以实现计划。
2416 3196
2417<h3 id="listmcpresources">3197<h3 id="listmcpresources">
2418 ListMcpResources3198 ListMcpResources
2458 3238
2459创建并进入临时 git worktree 以进行隔离工作。传递 `path` 以切换到现有 worktree 而不是创建新的。在首次进入时，目标必须是当前存储库的已注册 worktree，或在多存储库工作区中，必须是嵌套在其中的存储库的已注册 worktree；从 worktree 会话内进入时，必须在会话存储库的 `.claude/worktrees/` 下。`name` 和 `path` 互斥。3239创建并进入临时 git worktree 以进行隔离工作。传递 `path` 以切换到现有 worktree 而不是创建新的。在首次进入时，目标必须是当前存储库的已注册 worktree，或在多存储库工作区中，必须是嵌套在其中的存储库的已注册 worktree；从 worktree 会话内进入时，必须在会话存储库的 `.claude/worktrees/` 下。`name` 和 `path` 互斥。
2460 3240
3241<h3 id="exitworktree">
3242 ExitWorktree
3243</h3>
3244
3245**工具名称：** `ExitWorktree`
3246
3247```typescript theme={null}
3248type ExitWorktreeInput = {
3249 action: "keep" | "remove";
3250 discard_changes?: boolean;
3251};
3252```
3253
3254退出当前 git worktree 并返回到原始工作目录。`keep` 操作将 worktree 和分支保留在磁盘上，而 `remove` 删除两者。当删除具有未提交文件或未合并提交的 worktree 时，`discard_changes` 必须为 `true`。
3255
3256<h3 id="enterplanmode">
3257 EnterPlanMode
3258</h3>
3259
3260**工具名称：** `EnterPlanMode`
3261
3262```typescript theme={null}
3263type EnterPlanModeInput = {};
3264```
3265
3266进入 Plan Mode，Claude 在其中研究并呈现计划，然后再进行更改。
3267
3268<h3 id="croncreate">
3269 CronCreate
3270</h3>
3271
3272**工具名称：** `CronCreate`
3273
3274```typescript theme={null}
3275type CronCreateInput = {
3276 cron: string;
3277 prompt: string;
3278 recurring?: boolean;
3279 durable?: boolean;
3280};
3281```
3282
3283在本地时间的 5 字段 cron 计划上安排提示运行。将 `recurring` 设置为 `false` 以在下一个匹配时仅触发一次。作业默认为会话范围：启动新对话会清除它们，使用 `--resume` 或 `--continue` 恢复会恢复尚未过期的作业。请参阅[计划任务](/docs/zh-CN/scheduled-tasks)。
3284
3285将 `durable` 设置为 `true` 请求持久化到 `.claude/scheduled_tasks.json`，以便作业在重启后继续存在。持久化调度并非在每个会话中都可用：当不可用时，Claude Code 接受 `durable: true` 但创建仅会话的作业。读取输出的 `durable` 字段以查看作业是否已持久化。
3286
3287<h3 id="crondelete">
3288 CronDelete
3289</h3>
3290
3291**工具名称：** `CronDelete`
3292
3293```typescript theme={null}
3294type CronDeleteInput = {
3295 id: string;
3296};
3297```
3298
3299按从 `CronCreate` 返回的 ID 删除计划的 cron 作业。
3300
3301<h3 id="cronlist">
3302 CronList
3303</h3>
3304
3305**工具名称：** `CronList`
3306
3307```typescript theme={null}
3308type CronListInput = {};
3309```
3310
3311列出计划的 cron 作业：来自 `.claude/scheduled_tasks.json` 的持久化作业和来自当前会话的仅会话作业。
3312
3313<h3 id="schedulewakeup">
3314 ScheduleWakeup
3315</h3>
3316
3317**工具名称：** `ScheduleWakeup`
3318
3319```typescript theme={null}
3320type ScheduleWakeupInput = {
3321 delaySeconds?: number;
3322 reason?: string;
3323 prompt?: string;
3324 noop?: boolean;
3325 stop?: boolean;
3326};
3327```
3328
3329安排一次性唤醒，在延迟后触发给定的提示。此工具支持自定步调的 `/loop` 命令。运行时将 `delaySeconds` 限制在 60 到 3600 秒之间。除非 `stop` 为 true，否则 `delaySeconds`、`reason`、`prompt` 和 `noop` 字段是必需的。`noop: true` 报告没有任何更改的唤醒。设置 `stop: true` 取消待处理的唤醒并结束自定步调的 `/loop`。`stop` 字段需要 Claude Code v2.1.202 或更高版本。请参阅[工具参考中的 ScheduleWakeup 行](/docs/zh-CN/tools-reference)。
3330
3331<h3 id="remotetrigger">
3332 RemoteTrigger
3333</h3>
3334
3335**工具名称：** `RemoteTrigger`
3336
3337```typescript theme={null}
3338type RemoteTriggerInput = {
3339 action:
3340 | "list"
3341 | "get"
3342 | "create"
3343 | "update"
3344 | "run"
3345 | "create_webhook_trigger"
3346 | "list_runs"
3347 | "get_run_log";
3348 trigger_id?: string;
3349 session_id?: string;
3350 cursor?: string;
3351 body?: {
3352 [k: string]: unknown;
3353 };
3354};
3355```
3356
3357管理[例程](/docs/zh-CN/routines)，即在云中托管的计划和触发的 Claude Code 运行。此工具支持 `/schedule` 命令。`trigger_id` 对于 `get`、`update`、`run` 和 `list_runs` 操作是必需的。`body` 对于 `create`、`update` 和 `create_webhook_trigger` 是必需的，对于 `run` 是可选的。
3358
3359`create_webhook_trigger` 将事件源附加到现有例程，例如触发它的 [GitHub 事件](/docs/zh-CN/routines#add-a-github-trigger)。`body` 命名源、事件和要触发的例程。需要 Claude Code v2.1.225 或更高版本。
3360
3361`list_runs` 列出例程的最近运行，`get_run_log` 读取一个运行的日志。`session_id` 从 `list_runs` 结果命名要读取的运行，`cursor` 分页浏览任一操作的结果。两个操作都需要 Claude Code v2.1.227 或更高版本。
3362
3363此工具仅在会话使用启用了例程的计划的 claude.ai 账户进行身份验证时可用，当您的组织的策略禁用[网络上的 Claude Code](/docs/zh-CN/claude-code-on-the-web) 时不存在。在 Claude Code v2.1.227 或更高版本上，当所有者为组织[关闭例程](/docs/zh-CN/routines#routines-are-disabled-by-your-organizations-policy)时，该工具也不存在。在 v2.1.227 之前，仅关闭例程切换的会话仍然显示该工具，服务器拒绝其调用。
3364
3365<h3 id="pushnotification">
3366 PushNotification
3367</h3>
3368
3369**工具名称：** `PushNotification`
3370
3371```typescript theme={null}
3372type PushNotificationInput = {
3373 message: string;
3374 status: "proactive";
3375};
3376```
3377
3378向用户发送主动推送通知。将 `message` 保持在 200 个字符以下，因为移动操作系统会截断较长的文本。请参阅[工具参考中的 PushNotification 行](/docs/zh-CN/tools-reference)了解提供商可用性；推送传递通过 Anthropic 托管的基础设施进行，该基础设施无法从 Amazon Bedrock、AWS 上的 Claude Platform、Google Cloud 的 Agent Platform 或 Microsoft Foundry 访问。
3379
3380<h3 id="repl">
3381 REPL
3382</h3>
3383
3384**工具名称：** `REPL`
3385
3386```typescript theme={null}
3387type REPLInput = {
3388 code: string;
3389 description?: string;
3390 timeout?: number;
3391};
3392```
3393
3394在持久 REPL 中执行 JavaScript 代码。状态在调用之间保持，并支持顶级 await。`timeout` 以毫秒为单位，默认为 30000，最大为 600000。
3395
3396这些类型已导出，但除非您在 [`env` 选项](#options)中设置 `CLAUDE_CODE_REPL=1`，否则该工具在 SDK 会话中处于关闭状态。它还需要本机安装程序提供的基于 Bun 的 `claude` 可执行文件。
3397
3398<h3 id="reportfindings">
3399 ReportFindings
3400</h3>
3401
3402**工具名称：** `ReportFindings`
3403
3404```typescript theme={null}
3405type ReportFindingsInput = {
3406 level?: "low" | "medium" | "high" | "xhigh" | "max";
3407 findings: Array<{
3408 file: string;
3409 line?: number;
3410 summary: string;
3411 failure_scenario: string;
3412 short_summary?: string;
3413 category?: string;
3414 verdict?: "CONFIRMED" | "PLAUSIBLE";
3415 outcome?: "fixed" | "skipped" | "no_change_needed";
3416 }>;
3417};
3418```
3419
3420将代码审查发现报告为结构化列表，以便 Claude Code 可以呈现它们而不是将其打印为文本。`level` 是审查运行的工作量级别。发现按最严重优先排序，每次调用最多 32 个，当没有发现存活时数组为空。需要 Claude Code v2.1.196 或更高版本。
3421
3422每个发现包含这些字段：
3423
3424* `file`：发现所在的存储库相对路径。可选的 `line` 是它锚定到的 1 索引行。
3425* `summary`：缺陷的单句陈述。`failure_scenario` 描述导致错误输出或崩溃的具体输入和状态。
3426* `short_summary`：可选的最多 60 个字符的压缩标签，用于紧凑显示。需要 Claude Code v2.1.212 或更高版本。
3427* `category`：可选的发现类型的短 kebab-case slug，例如 `correctness` 或 `test-coverage`。需要 Claude Code v2.1.199 或更高版本。
3428* `verdict`：在验证通过运行时设置；在仅内联审查中不存在。
3429* `outcome`：仅在应用修复后重新报告时设置。
3430
3431<h3 id="artifact">
3432 Artifact
3433</h3>
3434
3435**工具名称：** `Artifact`
3436
3437```typescript theme={null}
3438type ArtifactInput = {
3439 action?: "publish" | "list";
3440 file_path?: string;
3441 favicon?: string;
3442 limit?: number;
3443 scope?: "mine" | "shared" | "all";
3444 title?: string;
3445 description?: string;
3446 label?: string;
3447 url?: string;
3448 force?: boolean;
3449 capabilities?: Record<string, unknown>;
3450 contract?: "latest" | string;
3451};
3452```
3453
3454将本地 `.html` 或 `.md` 文件发布为托管的 artifact 页面，或列出用户发布的 artifacts。省略 `action` 或传递 `"publish"` 以发布 `file_path`，这对于发布操作是必需的，以及 `favicon`，一个或两个标记 artifact 在用户库中的表情符号。当 HTML 文件没有 `<title>` 标签时，`title` 在浏览器标签和库中命名发布的页面。`url` 针对现有 artifact 以就地更新，而不是创建新的。
3455
3456`force` 是最后手段的覆盖，丢弃另一个会话发布的较新版本。在冲突时，失败的发布返回较新的内容；Claude 将其更改合并到该内容上，或重新读取 artifact，然后再次发布。仅当用户明确要求丢弃该版本时才传递 `force`。
3457
3458传递 `"list"` 以枚举用户发布的 artifacts；仅 `limit` 和 `scope` 可能伴随它。`scope` 默认为 `"mine"`，列出用户拥有的 artifacts；`"shared"` 列出其他人与用户共享的 artifacts，`"all"` 列出两者。
3459
3460* `capabilities`：发布的页面使用的运行时功能，由功能名称键入，例如[页面可能调用的连接器](/docs/zh-CN/artifacts#pull-live-data-with-mcp-connectors)。artifact 服务验证声明并拒绝命名账户无法使用的功能或给予一个无效配置的发布。传递 `{}` 以清除存储的声明，在重新部署时省略字段以保留它。需要 Agent SDK v0.3.235 或更高版本。
3461* `contract`：发布的页面运行的运行时版本。省略它以保留 artifact 的当前版本，传递 `"latest"` 以升级，或传递特定版本以固定或回滚。需要 Agent SDK v0.3.235 或更高版本。
3462
3463这些类型已导出，但该工具在 Agent SDK 会话中默认处于关闭状态。发布还需要 [artifacts 可用性表](/docs/zh-CN/artifacts#availability)中的每个条件，使用 API 密钥进行身份验证的会话不满足这些条件。
3464
3465<h3 id="projects">
3466 Projects
3467</h3>
3468
3469**工具名称：** `Projects`
3470
3471```typescript theme={null}
3472type ProjectsInput = {
3473 method:
3474 | "project_info"
3475 | "project_read"
3476 | "project_search"
3477 | "project_write"
3478 | "project_delete";
3479 path?: string;
3480 content?: string;
3481 local_path?: string;
3482 present_to_user?: boolean;
3483 query?: string;
3484 n?: number;
3485};
3486```
3487
3488读取和写入附加到会话的 claude.ai Project。在 `method` 上分派：
3489
3490* `project_info`：返回项目元数据和文档列表。
3491* `project_read`：按 `path` 读取一个文档。
3492* `project_search`：使用 `query` 查询项目的知识库。`n` 限制命中数并默认为 5。
3493* `project_write`：从 `content`（包含内联文本）或 `local_path`（命名工作目录内的文件）中的恰好一个在 `path` 处创建或替换文档。`present_to_user: true` 将写入的文档标记为用户需要看到的可交付成果。
3494* `project_delete`：按 `path` 删除文档。
3495
3496<h3 id="readmcpresourcedir">
3497 ReadMcpResourceDir
3498</h3>
3499
3500**工具名称：** `ReadMcpResourceDirTool`
3501
3502```typescript theme={null}
3503type ReadMcpResourceDirInput = {
3504 server: string;
3505 uri: string;
3506};
3507```
3508
3509列出 MCP 服务器上目录资源的直接子项。仅可用于已声明支持目录列表的服务器；列表不是递归的。目录列表并非在每个会话中都启用：当关闭时，调用返回空的 `resources` 列表，`error` 字段报告目录列表未启用。
3510
3511<h3 id="refreshmcptools">
3512 RefreshMcpTools
3513</h3>
3514
3515**工具名称：** `RefreshMcpTools`
3516
3517```typescript theme={null}
3518type RefreshMcpToolsInput = {
3519 server?: string; // 仅刷新此服务器；省略以刷新所有连接的服务器
3520};
3521```
3522
3523重新查询连接的 MCP 服务器的工具列表并应用任何更改。这些类型已导出，但 Claude Code 仅在您在 [`env` 选项](#options)中设置 `CLAUDE_CODE_ENABLE_REFRESH_MCP_TOOLS=1` 时注册该工具，并且仅在至少有一个 MCP 服务器的会话中。需要 Claude Code v2.1.211 或更高版本。
3524
3525<h3 id="showonboardingrolepicker">
3526 ShowOnboardingRolePicker
3527</h3>
3528
3529**工具名称：** `ShowOnboardingRolePicker`
3530
3531```typescript theme={null}
3532type ShowOnboardingRolePickerInput = {};
3533```
3534
3535在 Cowork 入职期间呈现可点击的角色选择器芯片行，以便用户可以选择其角色并获得匹配的插件安装。不需要参数；角色列表由客户端定义。调用会阻塞直到用户响应。
3536
3537<h3 id="mcpinput">
3538 McpInput
3539</h3>
3540
3541**工具名称：** 形式为 `mcp__<server>__<tool>` 的动态 MCP 工具名称
3542
3543```typescript theme={null}
3544type McpInput = {
3545 [k: string]: unknown;
3546};
3547```
3548
3549MCP 工具参数是开放对象：每个服务器定义自己的参数，因此类型对字段名称或值不施加任何约束。请查阅服务器自己的工具架构以了解特定工具接受的字段。
3550
2461<h2 id="tool-output-types">3551<h2 id="tool-output-types">
2462 工具输出类型3552 工具输出类型
2463</h2>3553</h2>
2468 `ToolOutputSchemas`3558 `ToolOutputSchemas`
2469</h3>3559</h3>
2470 3560
2471所有工具输出类型的联合。3561从 `@anthropic-ai/claude-agent-sdk` 导出的工具输出类型的联合；成员包括：
2472 3562
2473```typescript theme={null}3563```typescript theme={null}
2474type ToolOutputSchemas =3564type ToolOutputSchemas =
2475 | AgentOutput3565 | AgentOutput
3566 | ArtifactOutput
2476 | AskUserQuestionOutput3567 | AskUserQuestionOutput
2477 | BashOutput3568 | BashOutput
3569 | CronCreateOutput
3570 | CronDeleteOutput
3571 | CronListOutput
3572 | EnterPlanModeOutput
2478 | EnterWorktreeOutput3573 | EnterWorktreeOutput
2479 | ExitPlanModeOutput3574 | ExitPlanModeOutput
3575 | ExitWorktreeOutput
2480 | FileEditOutput3576 | FileEditOutput
2481 | FileReadOutput3577 | FileReadOutput
2482 | FileWriteOutput3578 | FileWriteOutput
2483 | GlobOutput3579 | GlobOutput
2484 | GrepOutput3580 | GrepOutput
2485 | ListMcpResourcesOutput3581 | ListMcpResourcesOutput
3582 | McpOutput
2486 | MonitorOutput3583 | MonitorOutput
2487 | NotebookEditOutput3584 | NotebookEditOutput
3585 | ProjectsOutput
3586 | PushNotificationOutput
3587 | ReadMcpResourceDirOutput
2488 | ReadMcpResourceOutput3588 | ReadMcpResourceOutput
3589 | RefreshMcpToolsOutput
3590 | RemoteTriggerOutput
3591 | REPLOutput
3592 | ReportFindingsOutput
3593 | ScheduleWakeupOutput
3594 | ShowOnboardingRolePickerOutput
2489 | TaskCreateOutput3595 | TaskCreateOutput
2490 | TaskGetOutput3596 | TaskGetOutput
2491 | TaskListOutput3597 | TaskListOutput
2501 Agent3607 Agent
2502</h3>3608</h3>
2503 3609
2504**工具名称：** `Agent`（之前为 `Task`，仍然接受作为别名）3610**工具名称：** `Agent`。之前的名称 `Task` 仍然被接受作为别名，[`SDKSystemMessage`](#sdksystemmessage) 初始化消息中的 `tools` 数组目前为了向后兼容仍将此工具列为 `Task`。
2505 3611
2506```typescript theme={null}3612```typescript theme={null}
2507type AgentOutput =3613type AgentOutput =
2511 agentType?: string;3617 agentType?: string;
2512 content: Array<{ type: "text"; text: string; citations?: unknown[] | null }>;3618 content: Array<{ type: "text"; text: string; citations?: unknown[] | null }>;
2513 resolvedModel?: string;3619 resolvedModel?: string;
3620 modelsUsed?: string[];
2514 totalToolUseCount: number;3621 totalToolUseCount: number;
2515 totalDurationMs: number;3622 totalDurationMs: number;
2516 totalTokens: number;3623 totalTokens: number;
2531 inference_geo?: string | null;3638 inference_geo?: string | null;
2532 speed?: string | null;3639 speed?: string | null;
2533 iterations?: unknown;3640 iterations?: unknown;
3641 output_tokens_details?: {
3642 thinking_tokens?: number | null;
3643 } | null;
2534 };3644 };
2535 toolStats?: {3645 toolStats?: {
2536 readCount: number;3646 readCount: number;
2552 agentId: string;3662 agentId: string;
2553 description: string;3663 description: string;
2554 resolvedModel?: string;3664 resolvedModel?: string;
3665 modelsUsed?: string[];
2555 prompt: string;3666 prompt: string;
2556 outputFile: string;3667 outputFile: string;
2557 canReadOutputFile?: boolean;3668 canReadOutputFile?: boolean;
2568 3679
2569返回来自子代理的结果。在 `status` 字段上进行区分：`"completed"` 表示已完成的任务，`"async_launched"` 表示后台任务，`"remote_launched"` 表示 Claude Code 分派到远程云会话的任务，其中 `sessionUrl` 链接到该会话，`taskId` 标识它。3680返回来自子代理的结果。在 `status` 字段上进行区分：`"completed"` 表示已完成的任务，`"async_launched"` 表示后台任务，`"remote_launched"` 表示 Claude Code 分派到远程云会话的任务，其中 `sessionUrl` 链接到该会话，`taskId` 标识它。
2570 3681
2571`completed` 和 `async_launched` 变体上的 `resolvedModel` 字段命名子代理实际运行的模型，当应用 [`availableModels`](/docs/zh-CN/model-config#restrict-model-selection) 或其他覆盖时，该模型可能与请求的 `model` 输入不同。此字段需要 Claude Code v2.1.174 或更高版本。3682在 `completed` 变体上，`resolvedModel` 命名子代理启动时所用的模型，当应用 [`availableModels`](/docs/zh-CN/model-config#restrict-model-selection) 或其他覆盖时，该模型可能与请求的 `model` 输入不同。此字段需要 Claude Code v2.1.174 或更高版本。在 `async_launched` 上，它命名任务移至后台时使用的模型。
3683
3684`modelsUsed` 列出子代理使用的模型，按顺序。该字段仅在发生中途交换时出现，当运行交换回某个模型时，该模型会再次出现。在 `async_launched` 上，该列表涵盖后台处理前使用的模型。`modelsUsed` 和 `resolvedModel` 的后台处理行为都需要 Claude Code v2.1.212 或更高版本。
3685
3686如果 Claude Code [保留了子代理的隔离 worktree](/docs/zh-CN/worktrees#isolate-subagents-with-worktrees)，`completed` 结果上的 `worktreePath` 是找到它的位置。`worktreeBranch` 是其分支，当 Claude Code 使用 git 创建 worktree 时出现。
2572 3687
2573在 `completed` 变体上，当子代理在隔离的 git worktree 中运行时，`worktreePath` 被设置，`worktreeBranch` 在 Claude Code 创建该 worktree 时命名其分支。`usage.service_tier` 携带 API 为子代理的请求报告的服务层字符串。3688Claude Code 从子代理的最终 API 请求而不是整个运行中填充 `usage` 和 `totalTokens`，因此 `usage.service_tier` 是 API 在该请求上报告的服务层字符串。当存在时，`usage.output_tokens_details.thinking_tokens` 是该请求的输出令牌中属于思考令牌的数量。`output_tokens_details` 字段需要 TypeScript SDK v0.3.228 或更高版本，该版本包含 Claude Code v2.1.228。
3689
3690`usage.output_tokens_details` 在含义上与 [`Usage.output_tokens_details`](#usage) 匹配，范围限于该最终请求，但其每个级别都是可选的。保护对象和字段，例如 `usage.output_tokens_details?.thinking_tokens ?? 0`，而不是直接读取它。
2574 3691
2575在 v2.1.207 之前，发布的类型更窄。它省略了 `worktreePath`、`worktreeBranch`、`citations`、`toolStats.frameCount` 和 `inference_geo`、`speed` 和 `iterations` 使用字段，并将 `service_tier` 类型化为 `"standard" | "priority" | "batch"`。类型标记为可选的字段可能在早期版本记录的结果中不存在。3692在 v2.1.207 之前，发布的类型更窄。它省略了 `worktreePath`、`worktreeBranch`、`citations`、`toolStats.frameCount` 和 `inference_geo`、`speed` 和 `iterations` 使用字段，并将 `service_tier` 类型化为 `"standard" | "priority" | "batch"`。类型标记为可选的字段可能在早期版本记录的结果中不存在。
2576 3693
2590 }>;3707 }>;
2591 answers: Record<string, string>;3708 answers: Record<string, string>;
2592 response?: string;3709 response?: string;
3710 annotations?: Record<string, { preview?: string; notes?: string }>;
3711 afkTimeoutMs?: number;
2593};3712};
2594```3713```
2595 3714
2610 isImage?: boolean;3729 isImage?: boolean;
2611 backgroundTaskId?: string;3730 backgroundTaskId?: string;
2612 backgroundedByUser?: boolean;3731 backgroundedByUser?: boolean;
3732 timedOutAfterMs?: number;
3733 backgroundCwdHint?: string;
3734 backgroundEndsWithFinalResponse?: true;
2613 dangerouslyDisableSandbox?: boolean;3735 dangerouslyDisableSandbox?: boolean;
2614 returnCodeInterpretation?: string;3736 returnCodeInterpretation?: string;
3737 noOutputExpected?: boolean;
2615 structuredContent?: unknown[];3738 structuredContent?: unknown[];
2616 persistedOutputPath?: string;3739 persistedOutputPath?: string;
2617 persistedOutputSize?: number;3740 persistedOutputSize?: number;
3741 staleReadFileStateHint?: string;
3742 ghRateLimitHint?: string;
3743 gitOperation?: {
3744 commit?: { sha: string; kind: "committed" | "amended" | "cherry-picked"; branch?: string };
3745 push?: { branch: string };
3746 branch?: { ref: string; action: "merged" | "rebased" };
3747 pr?: {
3748 number: number;
3749 url?: string;
3750 action: "created" | "edited" | "merged" | "commented" | "closed" | "reopened" | "ready" | "draft" | "auto-merge-enabled" | "auto-merge-disabled";
3751 };
3752 };
2618};3753};
2619```3754```
2620 3755
2621返回命令输出，stdout/stderr 分开。后台命令包括 `backgroundTaskId`。3756`stdout`、`stderr` 和 `backgroundTaskId` 字段携带：
3757
3758| 字段 | 它携带的内容 |
3759| ------------------ | -------------------------------------- |
3760| `stdout` | 命令的 stdout 和 stderr，合并为一个交错流 |
3761| `stderr` | 工具本身添加的通知，例如 shell 工作目录重置，不是命令的 stderr |
3762| `backgroundTaskId` | 对于后台命令存在 |
3763
3764`timedOutAfterMs` 是超时时间（以毫秒为单位），当命令达到其超时并移至后台而不是显式启动时设置。`backgroundCwdHint` 在后台命令包含目录更改内置命令（如 `cd`、`pushd`、`popd` 或 `chdir`）时设置，并注意会话工作目录未更改。两个字段都需要 Claude Code v2.1.210 或更高版本。
3765
3766当在前台运行的子代理拥有后台命令时，Claude Code 在该子代理给出最终响应时终止该命令。Claude Code 在此类命令上将 `backgroundEndsWithFinalResponse` 设置为 `true`，并在命令存活该轮时省略该字段，如主对话或后台子代理启动的命令那样。该字段需要 Claude Code v2.1.227 或更高版本。
3767
3768Claude Code 将 `gitOperation.commit.branch` 设置为 git 提交摘要行中命名的分支，对于在分离 HEAD 上进行的提交则省略它。该字段需要 Agent SDK v0.3.227 或更高版本。Claude Code 将 `gh pr reopen` 命令报告为 `reopened` PR 操作，这需要 Agent SDK v0.3.234 或更高版本。
2622 3769
2623<h3 id="monitor-2">3770<h3 id="monitor-2">
2624 Monitor3771 Monitor
2647 filePath: string;3794 filePath: string;
2648 oldString: string;3795 oldString: string;
2649 newString: string;3796 newString: string;
2650 originalFile: string;3797 originalFile: string | null;
2651 structuredPatch: Array<{3798 structuredPatch: Array<{
2652 oldStart: number;3799 oldStart: number;
2653 oldLines: number;3800 oldLines: number;
2664 deletions: number;3811 deletions: number;
2665 changes: number;3812 changes: number;
2666 patch: string;3813 patch: string;
3814 repository?: string | null;
2667 };3815 };
2668};3816};
2669```3817```
2686 numLines: number;3834 numLines: number;
2687 startLine: number;3835 startLine: number;
2688 totalLines: number;3836 totalLines: number;
3837 /** True when a whole-file read was auto-paginated because it exceeded the token cap (the content is a partial first page). */
3838 truncatedByTokenCap?: boolean;
2689 };3839 };
2690 }3840 }
2691 | {3841 | {
2725 count: number;3875 count: number;
2726 outputDir: string;3876 outputDir: string;
2727 };3877 };
3878 /** Document page number of the first extracted page; labels the page images in the tool_result content. */
3879 firstPage?: number;
3880 /** In-process only: the page-image bytes are delivered as image blocks in the tool_result content and aren't retained on the emitted tool_use_result, so this key is absent there. */
3881 pages?: {
3882 base64: string;
3883 mediaType: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
3884 error?: string;
3885 }[];
3886 }
3887 | {
3888 type: "file_unchanged";
3889 file: {
3890 filePath: string;
3891 };
3892 /** Set when the dedup matched a startup-seeded entry (CLAUDE.md / nested memory) rather than a prior Read tool_result. */
3893 source?: "seeded";
2728 };3894 };
2729```3895```
2730 3896
2756 deletions: number;3922 deletions: number;
2757 changes: number;3923 changes: number;
2758 patch: string;3924 patch: string;
3925 repository?: string | null;
2759 };3926 };
3927 userModified?: boolean;
2760};3928};
2761```3929```
2762 3930
2763返回写入结果，包含结构化差异信息。3931返回写入结果，包含结构化差异信息。`originalFile` 和 `structuredPatch` 持有的内容取决于写入：
3932
3933* 对于新创建的文件，`originalFile` 为 null，`structuredPatch` 为空
3934* 在覆盖时，`originalFile` 携带之前的内容，除非该内容大于约 10 MB：Claude Code 则跳过差异并返回 `originalFile` null 和 `structuredPatch` 空
3935* 当写入未更改任何内容或差异超时时，`structuredPatch` 也为空
2764 3936
2765<h3 id="glob-2">3937<h3 id="glob-2">
2766 Glob3938 Glob
2774 numFiles: number;3946 numFiles: number;
2775 filenames: string[];3947 filenames: string[];
2776 truncated: boolean;3948 truncated: boolean;
3949 totalMatches?: number;
3950 countIsComplete?: boolean;
2777};3951};
2778```3952```
2779 3953
2780返回与 glob 模式匹配的文件路径，按修改时间排序。3954返回与 glob 模式匹配的文件路径，按修改时间排序。
2781 3955
3956`totalMatches` 和 `countIsComplete` 需要 Claude Code v2.1.191 或更高版本。`totalMatches` 报告截断前的匹配文件数。当 `countIsComplete` 为 false 时，`totalMatches` 是一个下界，因为底层搜索截断了其自己的输出。
3957
2782<h3 id="grep-2">3958<h3 id="grep-2">
2783 Grep3959 Grep
2784</h3>3960</h3>
2793 content?: string;3969 content?: string;
2794 numLines?: number;3970 numLines?: number;
2795 numMatches?: number;3971 numMatches?: number;
3972 totalFiles?: number;
3973 totalLines?: number;
2796 appliedLimit?: number;3974 appliedLimit?: number;
2797 appliedOffset?: number;3975 appliedOffset?: number;
2798};3976};
2799```3977```
2800 3978
2801返回搜索结果。形状因 `mode` 而异：文件列表、带匹配的内容或匹配计数。3979返回搜索结果。形状因 `mode` 而异：文件列表、带匹配的内容或匹配计数。在 `count` 模式下，`numFiles` 和 `numMatches` 是完整结果集上的总计，不是分页切片。在 v2.1.208 之前，截断列出条目的 `head_limit` 或 `offset` 也会截断这些总计。
3980
3981`totalFiles` 需要 Claude Code v2.1.208 或更高版本，并在 `files_with_matches` 模式下报告 `head_limit` 和 `offset` 分页前的总结果数。`totalLines` 需要 Claude Code v2.1.210 或更高版本，并在 `content` 模式下报告分页前的总行数。
2802 3982
2803<h3 id="taskstop-2">3983<h3 id="taskstop-2">
2804 TaskStop3984 TaskStop
2826```typescript theme={null}4006```typescript theme={null}
2827type NotebookEditOutput = {4007type NotebookEditOutput = {
2828 new_source: string;4008 new_source: string;
4009 old_source?: string;
2829 cell_id?: string;4010 cell_id?: string;
2830 cell_type: "code" | "markdown";4011 cell_type: "code" | "markdown";
2831 language: string;4012 language: string;
2853 result: string;4034 result: string;
2854 durationMs: number;4035 durationMs: number;
2855 url: string;4036 url: string;
4037 artifactRead?: {
4038 slug: string;
4039 ver?: string;
4040 seeded?: false;
4041 };
2856};4042};
2857```4043```
2858 4044
2859返回获取的内容，包含 HTTP 状态和元数据。4045返回获取的内容，包含 HTTP 状态和元数据。
2860 4046
4047`artifactRead` 是 Claude Code 自己的工件读取记录，仅当 Claude 获取会话可以发布的工件时出现。Claude Code 在会话恢复时读取它回来，以便稍后的发布基于正确的版本；您的代码不需要对其采取行动。`slug` 命名工件，`ver` 是读取记录的版本，当它未记录任何内容时不存在，`seeded: false` 标记其完整源未到达 Claude 的读取。`seeded` 字段需要 Agent SDK v0.3.239 或更高版本。
4048
2861<h3 id="websearch-2">4049<h3 id="websearch-2">
2862 WebSearch4050 WebSearch
2863</h3>4051</h3>
2875 | string4063 | string
2876 >;4064 >;
2877 durationSeconds: number;4065 durationSeconds: number;
4066 searchCount?: number;
2878};4067};
2879```4068```
2880 4069
2888 4077
2889```typescript theme={null}4078```typescript theme={null}
2890type WorkflowOutput = {4079type WorkflowOutput = {
2891 status: "async_launched";4080 status: "async_launched" | "remote_launched";
2892 taskId: string;4081 taskId: string;
4082 taskType?: "local_workflow" | "remote_agent";
4083 workflowName?: string;
2893 runId?: string;4084 runId?: string;
2894 summary?: string;4085 summary?: string;
2895 transcriptDir?: string;4086 transcriptDir?: string;
2896 scriptPath?: string;4087 scriptPath?: string;
4088 sessionUrl?: string; // set when the workflow launched as a remote session
4089 warning?: string;
2897 error?: string;4090 error?: string;
2898};4091};
2899```4092```
2901在工具接受调用后立即返回。最终结果稍后作为任务完成到达。在将运行视为已启动之前检查 `error`：脚本如果语法检查失败，会返回 `status: "async_launched"` 并设置 `error`，且永远不会运行。4094在工具接受调用后立即返回。最终结果稍后作为任务完成到达。在将运行视为已启动之前检查 `error`：脚本如果语法检查失败，会返回 `status: "async_launched"` 并设置 `error`，且永远不会运行。
2902 4095
2903| 字段 | 类型 | 描述 |4096| 字段 | 类型 | 描述 |
2904| --------------- | ------------------ | ---------------------------------------------------- |4097| --------------- | --------------------------------------- | ----------------------------------------------------------------------------------- |
2905| `status` | `"async_launched"` | 工具接受了调用。这是该字段唯一的值 |4098| `status` | `"async_launched" \| "remote_launched"` | 工具接受了调用。`"async_launched"` 用于进程内运行，`"remote_launched"` 用于分派到远程会话而不是在进程内运行的运行 |
2906| `taskId` | `string` | 运行的后台任务标识符 |4099| `taskId` | `string` | 运行的后台任务标识符 |
2907| `runId` | `string` | 工作流运行标识符，用于在后续调用中作为 `resumeFromRunId` 传递 |4100| `taskType` | `"local_workflow" \| "remote_agent"` | 已注册后台任务的任务类型，与 `status` 分支匹配 |
4101| `workflowName` | `string` | 工作流脚本中的 `meta.name` |
4102| `runId` | `string` | 工作流运行标识符，用于在后续调用中作为 `resumeFromRunId` 传递。对于 `remote_launched` 运行不存在，其中云会话 URL 是恢复句柄 |
2908| `summary` | `string` | 工作流功能的单行描述 |4103| `summary` | `string` | 工作流功能的单行描述 |
2909| `transcriptDir` | `string` | 执行期间写入子代理转录的目录 |4104| `transcriptDir` | `string` | 执行期间写入子代理转录的目录 |
2910| `scriptPath` | `string` | 此运行的持久化工作流脚本的路径。编辑它并作为 `scriptPath` 传回以重新运行而无需重新发送脚本 |4105| `scriptPath` | `string` | 此运行的持久化工作流脚本的路径。编辑它并作为 `scriptPath` 传回以重新运行而无需重新发送脚本 |
2911| `error` | `string` | 当脚本语法检查失败时设置。存在时，尽管 `async_launched` 状态，运行未启动 |4106| `sessionUrl` | `string` | 云会话 URL，当 `status` 为 `"remote_launched"` 时设置 |
4107| `warning` | `string` | 非阻塞性提示，例如本地 git 状态与云会话将克隆的推送分支不同 |
4108| `error` | `string` | 当脚本语法检查失败时设置。存在时，尽管启动状态，运行未启动 |
2912 4109
2913<h3 id="todowrite-2">4110<h3 id="todowrite-2">
2914 TodoWrite4111 TodoWrite
2934返回之前和更新的任务列表。4131返回之前和更新的任务列表。
2935 4132
2936<Note>4133<Note>
2937 自 TypeScript Agent SDK 0.3.142 起，`TodoWrite` 默认被禁用。改用 `TaskCreate`、`TaskGet`、`TaskUpdate` 和 `TaskList`。请参阅[迁移到 Task 工具](/docs/zh-CN/agent-sdk/todo-tracking#migrate-to-task-tools)更新您的监视代码，或设置 `CLAUDE_CODE_ENABLE_TASKS=0` 以恢复为 `TodoWrite`。4134 The following tools are available by default only on Claude 3.x models, Opus 4 through 4.7, Sonnet 4 through 4.6, and Haiku 4.5. On every other model, including model IDs Claude Code doesn't recognize, they aren't available unless you opt in:
4135
4136 * `TodoWrite`
4137 * `TaskCreate`
4138 * `TaskGet`
4139 * `TaskUpdate`
4140 * `TaskList`
4141
4142 Wherever the tools are available, Claude Code provides the four Task tools, or `TodoWrite` instead when you set `CLAUDE_CODE_ENABLE_TASKS=0`.
4143
4144 This default set applies in Claude Code v2.1.268 and later, which the TypeScript Agent SDK bundles from v0.3.268.
4145
4146 请参阅[模型可用性](/docs/zh-CN/agent-sdk/todo-tracking#model-availability)以选择加入。
2938</Note>4147</Note>
2939 4148
2940<h3 id="taskcreate-2">4149<h3 id="taskcreate-2">
3028 isAgent: boolean;4237 isAgent: boolean;
3029 filePath?: string;4238 filePath?: string;
3030 hasTaskTool?: boolean;4239 hasTaskTool?: boolean;
4240 planWasEdited?: boolean;
3031 awaitingLeaderApproval?: boolean;4241 awaitingLeaderApproval?: boolean;
3032 requestId?: string;4242 requestId?: string;
3033};4243};
3065 uri: string;4275 uri: string;
3066 mimeType?: string;4276 mimeType?: string;
3067 text?: string;4277 text?: string;
4278 blobSavedTo?: string;
3068 }>;4279 }>;
4280 error?: string;
3069};4281};
3070```4282```
3071 4283
3087 4299
3088返回有关 git worktree 的信息。4300返回有关 git worktree 的信息。
3089 4301
4302<h3 id="exitworktree-2">
4303 ExitWorktree
4304</h3>
4305
4306**工具名称：** `ExitWorktree`
4307
4308```typescript theme={null}
4309type ExitWorktreeOutput = {
4310 action: "keep" | "remove";
4311 originalCwd: string;
4312 worktreePath: string;
4313 worktreeBranch?: string;
4314 tmuxSessionName?: string;
4315 discardedFiles?: number;
4316 discardedCommits?: number;
4317 message: string;
4318};
4319```
4320
4321返回采取的操作和有关退出的 worktree 的详细信息。
4322
4323<h3 id="enterplanmode-2">
4324 EnterPlanMode
4325</h3>
4326
4327**工具名称：** `EnterPlanMode`
4328
4329```typescript theme={null}
4330type EnterPlanModeOutput = {
4331 message: string;
4332};
4333```
4334
4335返回进入规划模式的确认。
4336
4337<h3 id="croncreate-2">
4338 CronCreate
4339</h3>
4340
4341**工具名称：** `CronCreate`
4342
4343```typescript theme={null}
4344type CronCreateOutput = {
4345 id: string;
4346 humanSchedule: string;
4347 recurring: boolean;
4348 durable?: boolean; // true when persisted to .claude/scheduled_tasks.json; false when session-only
4349};
4350```
4351
4352返回作业 ID 和计划的人类可读描述。
4353
4354<h3 id="crondelete-2">
4355 CronDelete
4356</h3>
4357
4358**工具名称：** `CronDelete`
4359
4360```typescript theme={null}
4361type CronDeleteOutput = {
4362 id: string;
4363};
4364```
4365
4366返回已删除作业的 ID。
4367
4368<h3 id="cronlist-2">
4369 CronList
4370</h3>
4371
4372**工具名称：** `CronList`
4373
4374```typescript theme={null}
4375type CronListOutput = {
4376 jobs: {
4377 id: string;
4378 cron: string;
4379 humanSchedule: string;
4380 prompt: string;
4381 recurring?: boolean;
4382 durable?: boolean;
4383 }[];
4384};
4385```
4386
4387返回计划的 cron 作业：来自 `.claude/scheduled_tasks.json` 的持久作业和来自当前会话的仅会话作业。仅会话作业携带 `durable: false`；从磁盘读取的作业省略该字段。
4388
4389<h3 id="schedulewakeup-2">
4390 ScheduleWakeup
4391</h3>
4392
4393**工具名称：** `ScheduleWakeup`
4394
4395```typescript theme={null}
4396type ScheduleWakeupOutput = {
4397 scheduledFor: number;
4398 clampedDelaySeconds: number;
4399 wasClamped: boolean;
4400 stopped?: boolean;
4401 cancelledWakeups?: number;
4402};
4403```
4404
4405返回唤醒将触发的时间作为纪元毫秒时间戳、实际使用的延迟以及请求的延迟是否被限制。`stopped` 字段在调用以 `stop: true` 结束循环时为 `true`。它需要 Claude Code v2.1.202 或更高版本。`cancelledWakeups` 字段计算 `stop: true` 调用取消了多少待处理唤醒。值为 0 表示没有待处理，重复 `/loop` cron 不会被 `stop: true` 取消。它需要 Claude Code v2.1.206 或更高版本。
4406
4407<h3 id="remotetrigger-2">
4408 RemoteTrigger
4409</h3>
4410
4411**工具名称：** `RemoteTrigger`
4412
4413```typescript theme={null}
4414type RemoteTriggerOutput = {
4415 status: number;
4416 json: string;
4417 summary?: string;
4418};
4419```
4420
4421返回触发操作的 API 响应状态和正文。
4422
4423<h3 id="pushnotification-2">
4424 PushNotification
4425</h3>
4426
4427**工具名称：** `PushNotification`
4428
4429```typescript theme={null}
4430type PushNotificationOutput = {
4431 message: string;
4432 pushSent?: boolean;
4433 localSent?: boolean;
4434 disabledReason?: "config_off" | "user_present" | "no_transport";
4435 sentAt?: string;
4436};
4437```
4438
4439返回传递详细信息，包括是否发送了推送或本地通知以及跳过传递的原因。
4440
4441<h3 id="repl-2">
4442 REPL
4443</h3>
4444
4445**工具名称：** `REPL`
4446
4447```typescript theme={null}
4448type REPLOutput = {
4449 code: string;
4450 result: {
4451 [k: string]: unknown;
4452 };
4453 stdout: string;
4454 stderr: string;
4455 error?: string;
4456 registeredTools?: string[];
4457 images?: {
4458 base64: string;
4459 mediaType: string;
4460 }[];
4461 documents?: {
4462 base64: string;
4463 }[];
4464};
4465```
4466
4467返回执行结果、捕获的控制台输出以及内部 `Read` 调用显示的任何图像或文档。
4468
4469<h3 id="reportfindings-2">
4470 ReportFindings
4471</h3>
4472
4473**工具名称：** `ReportFindings`
4474
4475```typescript theme={null}
4476type ReportFindingsOutput = {
4477 count: number;
4478 level?: "low" | "medium" | "high" | "xhigh" | "max";
4479 findings: Array<{
4480 file: string;
4481 line?: number;
4482 summary: string;
4483 failure_scenario: string;
4484 short_summary?: string;
4485 category?: string;
4486 verdict?: "CONFIRMED" | "PLAUSIBLE";
4487 outcome?: "fixed" | "skipped" | "no_change_needed";
4488 }>;
4489};
4490```
4491
4492返回报告的发现数、审查运行的工作量级别以及为结果正文回显的发现。需要 Claude Code v2.1.196 或更高版本。回显的 `short_summary` 字段需要 Claude Code v2.1.212 或更高版本。
4493
4494<h3 id="artifact-2">
4495 Artifact
4496</h3>
4497
4498**工具名称：** `Artifact`
4499
4500```typescript theme={null}
4501type ArtifactOutput =
4502 | {
4503 url: string;
4504 path: string;
4505 title?: string;
4506 version?: string;
4507 capabilities?: unknown;
4508 stored?: {
4509 contract: string;
4510 capabilities?: Record<string, unknown>;
4511 };
4512 warnings?: string[];
4513 contract?: string;
4514 updated?: boolean;
4515 liveSubscription?: string;
4516 }
4517 | {
4518 artifacts: Array<{
4519 title: string;
4520 url: string;
4521 updatedAt?: string;
4522 rel?: "mine" | "shared";
4523 }>;
4524 truncated?: boolean;
4525 scope?: "shared" | "all";
4526 };
4527```
4528
4529返回已发布页面的 `url` 和为发布操作发布的本地 `path`，当发布重新部署现有工件时 `updated` 设置为 true，`warnings` 携带任何发布时建议。列表操作返回 `artifacts` 行，当存在比请求限制更多的工件时 `truncated` 设置。在范围不是 `"mine"` 的列表上，每行携带 `rel` 标记用户是否拥有工件或与他们共享，输出的 `scope` 记录哪个非默认范围产生了列表；两者在默认列表上不存在。
4530
4531<h3 id="projects-2">
4532 Projects
4533</h3>
4534
4535**工具名称：** `Projects`
4536
4537```typescript theme={null}
4538type ProjectsOutput =
4539 | {
4540 method: "project_info";
4541 notice?: string;
4542 name: string;
4543 description: string;
4544 instructions: string;
4545 docs: Array<{ path: string; created_at: string | null }>;
4546 files?: Array<{
4547 path: string;
4548 file_kind: string;
4549 created_at: string | null;
4550 }>;
4551 sync_sources?: Array<{
4552 type: string | null;
4553 config: Record<string, unknown>;
4554 }>;
4555 knowledge: {
4556 knowledge_size: number;
4557 max_knowledge_size: number;
4558 };
4559 }
4560 | {
4561 method: "project_read";
4562 notice?: string;
4563 path: string;
4564 file_kind?: string;
4565 content?: string;
4566 local_file?: string;
4567 created_at: string | null;
4568 }
4569 | {
4570 method: "project_search";
4571 notice?: string;
4572 rag: boolean;
4573 hits?: Array<{ name?: string; doc_uuid?: string; text?: string }>;
4574 docs?: string[];
4575 }
4576 | {
4577 method: "project_write";
4578 notice?: string;
4579 path: string;
4580 doc_uuid: string;
4581 replaced: boolean;
4582 present_to_user?: boolean;
4583 local_path?: string;
4584 }
4585 | {
4586 method: "project_delete";
4587 notice?: string;
4588 path: string;
4589 deleted: boolean;
4590 };
4591```
4592
4593在 `method` 字段上进行区分，镜像输入。`project_read` 在 `content` 中内联返回小文本文档，并将较大的文档写入 `local_file` 路径；`project_search` 当项目的索引可用时返回 RAG `hits` 且 `rag: true`，否则回退到 `docs` 路径列表。
4594
4595<h3 id="readmcpresourcedir-2">
4596 ReadMcpResourceDir
4597</h3>
4598
4599**工具名称：** `ReadMcpResourceDirTool`
4600
4601```typescript theme={null}
4602type ReadMcpResourceDirOutput = {
4603 resources: Array<{
4604 uri: string;
4605 name: string;
4606 mimeType?: string;
4607 }>;
4608 error?: string;
4609};
4610```
4611
4612返回目录资源的直接子项。子目录显示为 mimeType `"inode/directory"`；`error` 在服务器无法列出目录时携带人类可读的消息。
4613
4614<h3 id="refreshmcptools-2">
4615 RefreshMcpTools
4616</h3>
4617
4618**工具名称：** `RefreshMcpTools`
4619
4620```typescript theme={null}
4621type RefreshMcpToolsOutput = Array<{
4622 server: string;
4623 status: "refreshed" | "error" | "not_connected";
4624 toolCount?: number; // tools now available from this server
4625 added?: string[]; // tool names this refresh added
4626 removed?: string[]; // tool names this refresh removed
4627 error?: string; // why the refresh failed or the server was unavailable
4628}>;
4629```
4630
4631返回每个服务器一个条目：`refreshed` 表示重新查询的工具列表已应用，`error` 表示重新查询失败且保留了之前的工具集，`not_connected` 表示服务器没有实时连接来查询。
4632
4633<h3 id="showonboardingrolepicker-2">
4634 ShowOnboardingRolePicker
4635</h3>
4636
4637**工具名称：** `ShowOnboardingRolePicker`
4638
4639```typescript theme={null}
4640type ShowOnboardingRolePickerOutput = {
4641 role?: string;
4642 dismissed?: boolean;
4643};
4644```
4645
4646返回用户的选择：当他们选择角色芯片或输入一个时为 `role`，当他们关闭选择器时为 `dismissed: true`。空对象表示用户批准了调用而未选择角色。
4647
4648<h3 id="mcpoutput">
4649 McpOutput
4650</h3>
4651
4652**工具名称：** 形式为 `mcp__<server>__<tool>` 的动态 MCP 工具名称
4653
4654```typescript theme={null}
4655type McpOutput =
4656 | string
4657 | {
4658 type: string;
4659 [k: string]: unknown;
4660 }[]
4661 | {
4662 [k: string]: unknown;
4663 };
4664```
4665
4666MCP 工具结果作为字符串或内容块数组返回，取决于服务器。导出类型中的尾部纯对象分支是架构生成工件：SDK 不返回裸对象，因为服务器的结构化输出在返回前被序列化为 JSON 字符串。在运行时值也可能是 `undefined`，尽管导出的类型不对此建模。
4667
3090<h2 id="permission-types">4668<h2 id="permission-types">
3091 权限类型4669 权限类型
3092</h2>4670</h2>
3174 `ApiKeySource`4752 `ApiKeySource`
3175</h3>4753</h3>
3176 4754
4755会话请求的 API 密钥来源，在 [`SDKSystemMessage`](#sdksystemmessage) 初始化消息上报告为 `apiKeySource`。
4756
3177```typescript theme={null}4757```typescript theme={null}
3178type ApiKeySource = "user" | "project" | "org" | "temporary" | "oauth";4758type ApiKeySource =
4759 | "ANTHROPIC_API_KEY"
4760 | "apiKeyHelper"
4761 | "/login managed key"
4762 | "none"
4763 | "user"
4764 | "project"
4765 | "org"
4766 | "temporary"
4767 | "oauth";
3179```4768```
3180 4769
4770Claude Code 报告以下四个值之一：
4771
4772| 值 | 使用中的密钥 |
4773| -------------------- | --------------------------------------------------------------------------------------------------- |
4774| `ANTHROPIC_API_KEY` | `ANTHROPIC_API_KEY` 环境变量中的密钥 |
4775| `apiKeyHelper` | 您的 [`apiKeyHelper`](/docs/zh-CN/settings-reference#apikeyhelper) 命令返回的密钥 |
4776| `/login managed key` | 当您使用 [Claude Console 账户](/docs/zh-CN/authentication#claude-console-authentication) 登录时 Claude Code 存储的密钥 |
4777| `none` | 没有 API 密钥。会话以其他方式进行身份验证，例如 claude.ai 登录、bearer 令牌或云提供商 |
4778
4779Agent SDK v0.3.234 及更高版本在类型中列出这四个值。该类型还保留 `user`、`project`、`org`、`temporary` 和 `oauth`，以便旧代码仍然可以编译，Claude Code 不报告它们。
4780
3181<h3 id="sdkbeta">4781<h3 id="sdkbeta">
3182 `SdkBeta`4782 `SdkBeta`
3183</h3>4783</h3>
3184 4784
3185可通过 `betas` 选项启用的可用测试功能。请参阅 [Beta 标头](https://platform.claude.com/docs/zh-CN/api/beta-headers)了解更多信息。4785可通过 `betas` 选项启用的可用测试功能。请参阅 [Beta 标头](https://platform.claude.com/docs/en/api/beta-headers) 了解更多信息。
3186 4786
3187```typescript theme={null}4787```typescript theme={null}
3188type SdkBeta = "context-1m-2025-08-07";4788type SdkBeta = "context-1m-2025-08-07";
3189```4789```
3190 4790
3191<Warning>4791<Warning>
3192 `context-1m-2025-08-07` beta 自 2026 年 4 月 30 日起已停用。使用 Claude Sonnet 4.5 或 Sonnet 4 传递此值无效，超过标准 200k 令牌上下文窗口的请求返回错误。要使用 1M 令牌上下文窗口，请迁移到 [Claude Sonnet 5、Claude Sonnet 4.6、Claude Opus 4.6、Claude Opus 4.7 或 Claude Opus 4.8](https://platform.claude.com/docs/zh-CN/about-claude/models/overview)，它们以标准定价包括 1M 上下文，无需 beta 标头。4792 `context-1m-2025-08-07` beta 自 2026 年 4 月 30 日起已停用。使用 Claude Sonnet 4.5 或 Sonnet 4 传递此值无效，超过标准 200k 令牌上下文窗口的请求返回错误。要使用 1M 令牌上下文窗口，请迁移到 [Claude Opus 5、Claude Sonnet 5、Claude Sonnet 4.6、Claude Opus 4.6、Claude Opus 4.7 或 Claude Opus 4.8](https://platform.claude.com/docs/en/about-claude/models/overview)，它们以标准定价包括 1M 上下文，无需 beta 标头。
3193</Warning>4793</Warning>
3194 4794
3195<h3 id="slashcommand">4795<h3 id="slashcommand">
3196 `SlashCommand`4796 `SlashCommand`
3197</h3>4797</h3>
3198 4798
3199有关可用 slash command 的信息。4799有关可用命令的信息。
3200 4800
3201```typescript theme={null}4801```typescript theme={null}
3202type SlashCommand = {4802type SlashCommand = {
3254```4854```
3255 4855
3256| 字段 | 类型 | 描述 |4856| 字段 | 类型 | 描述 |
3257| :------------ | :-------------------- | :------------------------------------------ |4857| :------------ | :-------------------- | :----------------------------------------------------------------------------------------------------------------------- |
3258| `name` | `string` | 代理类型标识符（例如，`"Explore"`、`"general-purpose"`） |4858| `name` | `string` | 代理类型标识符（例如，`"Explore"`、`"general-purpose"`） |
3259| `description` | `string` | 何时使用此代理的描述 |4859| `description` | `string` | 何时使用此代理的描述 |
3260| `model` | `string \| undefined` | 此代理使用的模型别名。如果省略，继承父级的模型 |4860| `model` | `string \| undefined` | 此代理使用的模型：别名或模型 ID，或 `'inherit'` 表示父级的模型。当为 `undefined` 时，Claude Code 按照 [子代理模型顺序](/docs/zh-CN/sub-agents#choose-a-model) 选择模型 |
3261 4861
3262<h3 id="mcpserverstatus">4862<h3 id="mcpserverstatus">
3263 `McpServerStatus`4863 `McpServerStatus`
3303 | McpClaudeAIProxyServerConfig;4903 | McpClaudeAIProxyServerConfig;
3304```4904```
3305 4905
3306请参阅 [`McpServerConfig`](#mcpserverconfig)了解每种传输类型的详情。4906请参阅 [`McpServerConfig`](#mcpserverconfig) 了解每种传输类型的详情。
3307 4907
3308<h3 id="accountinfo">4908<h3 id="accountinfo">
3309 `AccountInfo`4909 `AccountInfo`
3331type ModelUsage = {4931type ModelUsage = {
3332 inputTokens: number;4932 inputTokens: number;
3333 outputTokens: number;4933 outputTokens: number;
4934 thinkingTokens?: number;
3334 cacheReadInputTokens: number;4935 cacheReadInputTokens: number;
3335 cacheCreationInputTokens: number;4936 cacheCreationInputTokens: number;
3336 webSearchRequests: number;4937 webSearchRequests: number;
3337 costUSD: number;4938 costUSD: number;
3338 contextWindow: number;4939 contextWindow: number;
3339 maxOutputTokens: number;4940 maxOutputTokens: number;
4941 canonicalModel?: string;
4942 provider?: string;
4943 costBasis?: 'list' | 'managed' | 'unknown';
3340};4944};
3341```4945```
3342 4946
4947`thinkingTokens` 计算此模型生成的思考令牌。`outputTokens` 已包括它们，因此不要将两者相加。该字段在运行在记录它的 Claude Code 版本上的轮次之前不存在，因此在早期版本上开始的已恢复会话报告部分计数。`thinkingTokens` 需要 Agent SDK v0.3.257 或更高版本。
4948
4949字段 `canonicalModel` 和 `provider` 需要 Claude Code v2.1.218 或更高版本。`canonicalModel` 是定价查询使用的规范模型 ID；它可能与键入条目的原始模型字符串不同，例如当该字符串是提供商特定的 ID 或别名时。
4950
4951`provider` 命名为模型提供服务的 API 后端，例如 `firstParty`、`bedrock`、`vertex`、`foundry`、`anthropicAws`、`mantle` 或 `gateway`。
4952
4953`costBasis` 命名为模型最新请求定价的价格表：`list` 表示列表价格，`managed` 表示 [`modelPricing`](/docs/zh-CN/settings-reference#modelpricing) 表，或 `unknown` 当两者都不匹配模型 ID 时。该字段需要 Claude Code v2.1.246 或更高版本。
4954
3343<h3 id="configscope">4955<h3 id="configscope">
3344 `ConfigScope`4956 `ConfigScope`
3345</h3>4957</h3>
3381 speed: "standard" | "fast" | null;4993 speed: "standard" | "fast" | null;
3382 inference_geo: string | null;4994 inference_geo: string | null;
3383 iterations: BetaIterationsUsage | null;4995 iterations: BetaIterationsUsage | null;
4996 output_tokens_details: BetaOutputTokensDetails | null;
3384};4997};
3385```4998```
3386 4999
3387`BetaServerToolUsage` 和 `BetaIterationsUsage` 在 `@anthropic-ai/sdk` 中定义。5000`BetaServerToolUsage`、`BetaIterationsUsage` 和 `BetaOutputTokensDetails` 在 `@anthropic-ai/sdk` 中定义。
5001
5002`output_tokens_details` 按类别分解计费输出。它目前包含一个字段 `thinking_tokens: number`，计算模型生成的输出令牌作为内部推理，包括思考块分隔符。`output_tokens_details` 字段需要 TypeScript SDK v0.3.228 或更高版本，它捆绑了 Claude Code v2.1.228。
5003
5004* **计费**：读取分解以进行观察，而不是计费。`output_tokens` 保持权威总数，`output_tokens - thinking_tokens` 近似非推理输出。
5005* **计数涵盖的内容**：模型生成的原始推理，可能比响应体中返回的思考文本更长。API 通过重新标记化该原始文本来计算它，因此它可能与模型的精确生成计数相差几个令牌。
5006* **流式传输**：在流式助手消息上，此分解与 `output_tokens` 一样是 `message_start` 占位符，不包含真实计数，因此从结果消息的 `usage` 读取它，如 [从结果消息读取输出令牌](/docs/zh-CN/agent-sdk/cost-tracking#read-output-tokens-from-the-result-message) 所述。在结果消息上，当模型或提供商不报告分解时，`thinking_tokens` 读取 `0`。
5007* **`null` 情况**：`output_tokens_details` 本身在 Claude Code 合成的助手消息上为 `null`，例如 API 错误消息。
3388 5008
3389<h3 id="calltoolresult">5009<h3 id="calltoolresult">
3390 `CallToolResult`5010 `CallToolResult`
3403};5023};
3404```5024```
3405 5025
5026<h3 id="sdkmcpresourcelink">
5027 `SDKMcpResourceLink`
5028</h3>
5029
5030MCP 工具按引用返回的一个文件。Claude Code 从工具结果中的 `resource_link` 块构建每个条目，并将列表作为 `resourceLinks` 在 [`SDKUserMessage.tool_use_result`](#sdkusermessage) 上传递，或在调用在后台完成时作为 `resource_links` 在 [`SDKTaskNotificationMessage`](#sdktasknotificationmessage) 上传递。需要 Agent SDK v0.3.257 或更高版本。
5031
5032```typescript theme={null}
5033type SDKMcpResourceLink = {
5034 uri: string;
5035 name: string;
5036 title?: string;
5037 description?: string;
5038 mimeType?: string;
5039 size?: number;
5040 annotations?: Record<string, unknown>;
5041};
5042```
5043
5044Claude Code 删除其 `uri` 或 `name` 不是字符串的块，并省略其值不是列出类型的可选字段。
5045
5046| 字段 | 类型 | 描述 |
5047| :------------ | :------------------------------------- | :------------------ |
5048| `uri` | `string` | 资源的 URI，如服务器返回的那样 |
5049| `name` | `string` | 服务器给资源的名称 |
5050| `title` | `string \| undefined` | 显示标题，当服务器设置时 |
5051| `description` | `string \| undefined` | 描述，当服务器设置时 |
5052| `mimeType` | `string \| undefined` | MIME 类型，当服务器设置时 |
5053| `size` | `number \| undefined` | 大小（以字节为单位），当服务器设置时 |
5054| `annotations` | `Record<string, unknown> \| undefined` | 块的 MCP 注释对象，当服务器设置时 |
5055
3406<h3 id="thinkingconfig">5056<h3 id="thinkingconfig">
3407 `ThinkingConfig`5057 `ThinkingConfig`
3408</h3>5058</h3>
3418 | { type: "disabled" }; // 无扩展思考5068 | { type: "disabled" }; // 无扩展思考
3419```5069```
3420 5070
3421可选的 `display` 字段控制思考文本是否以 `"summarized"` 或 `"omitted"` 形式返回。在 Claude Opus 4.7 及更高版本上，API 默认值为 `"omitted"`，因此设置 `"summarized"` 以在 `thinking` 块中接收思考内容。5071可选的 `display` 字段控制思考文本是否以 `"summarized"` 或 `"omitted"` 形式返回。在 Claude Opus 4.7 及更高版本上，API 默认值为 `"omitted"`，因此设置 `"summarized"` 以在 `thinking` 块中接收思考内容。Claude Code 不会将 `display` 发送到 Amazon Bedrock 或 Google Cloud 的 Agent Platform，因此在这些提供商上，即使您将 `display` 设置为 `"summarized"`，Opus 4.7 及更高版本也会返回空 `thinking` 块。
3422 5072
3423<h3 id="spawnedprocess">5073<h3 id="spawnedprocess">
3424 `SpawnedProcess`5074 `SpawnedProcess`
3487};5137};
3488```5138```
3489 5139
5140当您调用 `setMcpServers()` 时，Claude Code 应用这些规则：
5141
5142* **调用未命名的服务器**：Claude Code 保持插件提供的服务器运行。需要 Agent SDK v0.3.210 或更高版本。
5143* **调用命名的服务器**：除了 CLI 在启动时启动的内置服务器外，Claude Code 仅当其配置与您传递的配置不同时才替换运行中的服务器。
5144* **CLI 在启动时启动的内置服务器**：如果调用命名了一个，Claude Code 删除该条目并在 `errors` 中报告它。
5145
5146承诺在新添加的 stdio、HTTP 和 SSE 服务器连接或失败后解决，因此来自已连接服务器的工具在下一轮可用。
5147
5148`added` 列出 Claude Code 添加或替换的服务器，无论它们是否连接。未能连接的服务器同时出现在 `added` 和 `errors` 中，失败文本在 `errors` 下，`failed` 行在 [`mcpServerStatus()`](#methods) 中。在 Claude Code v2.1.257 之前，其连接尝试抛出的服务器仅在 `errors` 下报告。
5149
3490<h3 id="rewindfilesresult">5150<h3 id="rewindfilesresult">
3491 `RewindFilesResult`5151 `RewindFilesResult`
3492</h3>5152</h3>
3500 filesChanged?: string[];5160 filesChanged?: string[];
3501 insertions?: number;5161 insertions?: number;
3502 deletions?: number;5162 deletions?: number;
5163 skippedLinks?: number;
3503};5164};
3504```5165```
3505 5166
5167`skippedLinks` 计算跟踪路径，倒带拒绝恢复或删除以确保链接安全：跟踪路径处的符号链接、硬链接或其他非常规文件，不再解析到检查点时指向的位置的父目录，或无法安全读取的备份。该字段需要 Claude Code v2.1.216 或更高版本。使用 `rewindFiles(userMessageId, { dryRun: true })` 的预览调用永远不会设置它。
5168
3506<h3 id="sdkstatusmessage">5169<h3 id="sdkstatusmessage">
3507 `SDKStatusMessage`5170 `SDKStatusMessage`
3508</h3>5171</h3>
3524 `SDKTaskNotificationMessage`5187 `SDKTaskNotificationMessage`
3525</h3>5188</h3>
3526 5189
3527后台任务完成、失败或停止时的通知。后台任务包括 `run_in_background` Bash 命令、[Monitor](#monitor) 监视和后台子代理。5190后台任务完成、失败或停止时的通知。后台任务包括 `run_in_background` Bash 命令、[Monitor](#monitor) 监视和后台子代理。对于 `ambient` 字段，请参阅 [`SDKTaskStartedMessage`](#sdktaskstartedmessage)，它定义了它及其版本要求。
3528 5191
3529```typescript theme={null}5192```typescript theme={null}
3530type SDKTaskNotificationMessage = {5193type SDKTaskNotificationMessage = {
3535 status: "completed" | "failed" | "stopped";5198 status: "completed" | "failed" | "stopped";
3536 output_file: string;5199 output_file: string;
3537 summary: string;5200 summary: string;
5201 ambient?: boolean;
3538 usage?: {5202 usage?: {
3539 total_tokens: number;5203 total_tokens: number;
3540 tool_uses: number;5204 tool_uses: number;
3541 duration_ms: number;5205 duration_ms: number;
3542 };5206 };
5207 resource_links?: SDKMcpResourceLink[];
3543 uuid: UUID;5208 uuid: UUID;
3544 session_id: string;5209 session_id: string;
3545};5210};
3546```5211```
3547 5212
5213当 Claude Code [将长 MCP 工具调用移到后台](/docs/zh-CN/mcp#automatic-backgrounding-of-long-tool-calls) 时，该调用的 `tool_result` 块仅保存占位符，调用的真实结果在此通知中到达。使用 `tool_use_id` 将通知与调用匹配。在 `completed` 通知上，`resource_links` 列出工具按引用返回的文件作为 [`SDKMcpResourceLink`](#sdkmcpresourcelink) 条目，具有与 [`tool_use_result.resourceLinks`](#sdkusermessage) 相同的 50 链接和 64 KiB 限制。Claude Code 在结果没有链接时省略 `resource_links`，以及在不是 MCP 工具调用的任务的通知上。`resource_links` 需要 Agent SDK v0.3.257 或更高版本。
5214
5215Claude Code 在发送给模型的每个任务通知前面加上通知，除了带有 [`scheduled-trigger` 子类型](#task-notification-subkinds) 的传递外，它们改为携带分配任务框架。通知说明没有发生人类输入，因此模型不会将通知视为用户指令或批准。
5216
5217要检测任务通知轮次，请在 [`SDKUserMessage`](#sdkusermessage) 或 [`SDKResultMessage`](#sdkresultmessage) 上检查 `origin.kind === "task-notification"`，而不是匹配通知文本。如果您需要知道是什么引发了它，请从同一字段读取 `subkind`。在 v2.1.205 之前，Claude Code 在会话空闲时到达的通知上省略了通知。
5218
3548<h3 id="sdktoolusesummarymessage">5219<h3 id="sdktoolusesummarymessage">
3549 `SDKToolUseSummaryMessage`5220 `SDKToolUseSummaryMessage`
3550</h3>5221</h3>
3639 parent_tool_use_id: string | null;5310 parent_tool_use_id: string | null;
3640 elapsed_time_seconds: number;5311 elapsed_time_seconds: number;
3641 task_id?: string;5312 task_id?: string;
5313 heartbeat?: boolean;
5314 subagent_type?: string;
5315 subagent_retry?: {
5316 agent_id: string;
5317 attempt: number;
5318 max_retries: number;
5319 retry_delay_ms: number;
5320 error_status: number | null;
5321 error_category: string;
5322 };
3642 uuid: UUID;5323 uuid: UUID;
3643 session_id: string;5324 session_id: string;
3644};5325};
3645```5326```
3646 5327
5328当工具调用在主对话中运行时，Claude Code 每 30 秒发出一条 `tool_progress` 消息，其中 `heartbeat: true`。每个心跳都包含工具名称和经过的秒数，因此您可以区分长时间运行的调用和停滞的会话。Claude Code 不为子代理内的工具调用发出心跳。`heartbeat` 字段需要 Agent SDK v0.3.214 或更高版本。在 v2.1.257 之前，Claude Code 也不为前台 Agent 工具调用发出心跳。
5329
5330在除心跳外的 Agent 工具的 `tool_progress` 消息上，`subagent_type` 命名运行中的子代理类型，例如 `general-purpose`。`subagent_retry` 在该子代理等待 API 错误退避（例如速率限制或过载）时出现，每个重试尝试一条消息。两个字段都需要 Agent SDK v0.3.214 或更高版本。
5331
5332要从 `subagent_retry` 呈现重试指示器：
5333
5334* 按 `parent_tool_use_id` 跟踪指示器，这对每个子代理是唯一的。`tool_use_id` 由来自一个助手轮次的并行子代理共享，因此按它跟踪会让一个子代理的更新清除另一个的指示器。
5335* 当同一 `parent_tool_use_id` 的后续 `tool_progress` 到达时清除指示器，既不包含 `subagent_retry` 也不包含 `heartbeat: true`，或当工具的结果消息到达时。带有 `heartbeat: true` 的帧仅报告活跃性，因此当一个到达时保持指示器。`attempt` 可能在持续重试下超过 `max_retries`，因此不要从计数器派生清除。
5336* 将 `error_category` 视为选择您自己的消息文本的令牌，而不是显示文本。值为 `rate_limit`、`overloaded`、`authentication_failed`、`server_error`、`cloud_credential_error` 和 `unknown`。处理您不识别的值的方式与处理 `unknown` 的方式相同，因为后续版本可以添加值。
5337
3647<h3 id="sdkauthstatusmessage">5338<h3 id="sdkauthstatusmessage">
3648 `SDKAuthStatusMessage`5339 `SDKAuthStatusMessage`
3649</h3>5340</h3>
3665 `SDKTaskStartedMessage`5356 `SDKTaskStartedMessage`
3666</h3>5357</h3>
3667 5358
3668当后台任务开始时发出。`task_type` 字段对于后台 Bash 命令和 [Monitor](#monitor) 监视为 `"local_bash"`，对于子代理为 `"local_agent"`，或 `"remote_agent"`。5359当任务开始时发出。`task_type` 字段对于 Bash 命令和 [Monitor](#monitor) 监视为 `"local_bash"`，对于子代理为 `"local_agent"`，或 `"remote_agent"`。
3669 5360
3670```typescript theme={null}5361```typescript theme={null}
3671type SDKTaskStartedMessage = {5362type SDKTaskStartedMessage = {
3675 tool_use_id?: string;5366 tool_use_id?: string;
3676 description: string;5367 description: string;
3677 task_type?: string;5368 task_type?: string;
5369 is_backgrounded?: boolean;
5370 spawn_depth?: number;
5371 ambient?: boolean;
3678 uuid: UUID;5372 uuid: UUID;
3679 session_id: string;5373 session_id: string;
3680};5374};
3681```5375```
3682 5376
5377对于不是会话工作一部分的任务，`ambient` 为 `true`，例如 Claude Code 为其自身操作运行的任务。实时更新监视器也是环境的，包括用户要求的监视器。从活动指示器中排除环境任务。该字段需要 Agent SDK v0.3.247 或更高版本。
5378
5379`ambient` 也出现在 [`SDKTaskNotificationMessage`](#sdktasknotificationmessage) 和 [`SDKBackgroundTasksChangedMessage`](#sdkbackgroundtaskschangedmessage) 条目上。
5380
5381`is_backgrounded` 和 `spawn_depth` 描述 Claude Code 如何启动任务。两个字段都需要 Agent SDK v0.3.238 或更高版本。
5382
5383* `is_backgrounded`：Claude Code 在 `"local_agent"` 和 `"local_bash"` 任务上设置它。`true` 表示任务在后台运行。`false` 表示任务在前台运行，启动它的工具调用保持阻止，直到任务完成或移到后台。
5384* `spawn_depth`：Claude Code 仅在 `"local_agent"` 任务上设置它。主线程生成的子代理的深度为 `1`。深度 `1` 子代理生成的子代理的深度为 `2`，以此类推。
5385
5386[已恢复的子代理](/docs/zh-CN/agent-sdk/subagents#resume-subagents) 始终报告 `is_backgrounded: true`，因为 Claude Code 在后台运行每个已恢复的子代理。当前台任务稍后移到后台时，Claude Code 在 [`task_updated`](#sdktaskupdatedmessage) 消息中报告新的 `is_backgrounded` 值，而不是发送第二个 `task_started`。
5387
3683<h3 id="sdktaskprogressmessage">5388<h3 id="sdktaskprogressmessage">
3684 `SDKTaskProgressMessage`5389 `SDKTaskProgressMessage`
3685</h3>5390</h3>
3734 `SDKBackgroundTasksChangedMessage`5439 `SDKBackgroundTasksChangedMessage`
3735</h3>5440</h3>
3736 5441
3737每当实时后台任务集发生变化时发出：任务启动、完成、被杀死，或前台代理被后台化。`tasks` 数组是完整的实时集。用每个有效负载替换任何缓存的集，而不是配对 `task_started` 和 `task_notification` 事件，以便下一个成员资格变化纠正您错过的任何事件。5442每当实时后台任务集发生变化时发出：任务启动、完成、被杀死，前台代理被后台化，或任务的 `description` 或 `ambient` 字段发生变化。
5443
5444`tasks` 数组是完整的实时集。用每个有效负载替换任何缓存的集，而不是配对 `task_started` 和 `task_notification` 事件，以便下一个成员资格变化纠正您错过的任何事件。
3738 5445
3739相对于这些每个任务事件的顺序是未指定的，因此不要关联这两个流。5446相对于这些每个任务事件的顺序是未指定的，因此不要关联这两个流。
3740 5447
3741启动时不发出任何内容。每当会话的 CLI 进程启动或重新启动时重置为空集，并让下一个成员资格变化重新填充它。5448启动时不发出任何内容。每当会话的 CLI 进程启动或重新启动时重置为空集，并让下一个成员资格变化重新填充它。
3742 5449
5450当您向运行中的会话发送重复的 `initialize` 控制请求时，例如在传输间隙后使用 [`reinitialize()`](#query-object)，Claude Code 在响应后跟随当前实时集的快照，即使它为空。因此，重新连接的主机可以了解正在运行的内容，而无需等待下一个成员资格变化。在 Agent SDK v0.3.239 之前，Claude Code 在重复 `initialize` 后没有发送快照。
5451
3743需要 Claude Code v2.1.203 或更高版本。5452需要 Claude Code v2.1.203 或更高版本。
3744 5453
3745```typescript theme={null}5454```typescript theme={null}
3750 task_id: string;5459 task_id: string;
3751 task_type: string;5460 task_type: string;
3752 description: string;5461 description: string;
5462 ambient?: boolean;
3753 }[];5463 }[];
3754 uuid: UUID;5464 uuid: UUID;
3755 session_id: string;5465 session_id: string;
3760 `SDKThinkingTokensMessage`5470 `SDKThinkingTokensMessage`
3761</h3>5471</h3>
3762 5472
3763在 Claude 生成思考块（包括编辑过的块）时发出，携带迄今为止生成的思考令牌的运行估计。`estimated_tokens` 是当前思考块的运行总计，`estimated_tokens_delta` 是此帧携带的增量。将其用于进度显示。顶级代理循环的最终计数是结果消息的 `usage.output_tokens`，它[不包括子代理令牌](/docs/zh-CN/agent-sdk/cost-tracking#get-the-total-cost-of-a-query)；使用 [`modelUsage`](#modelusage) 进行整树会计。5473在 Claude 生成思考块（包括编辑过的块）时发出。`estimated_tokens` 是迄今为止在当前块中生成的思考令牌的运行估计，`estimated_tokens_delta` 是此帧携带的增量。将这些估计用于进度显示。
5474
5475当模型或提供商报告分解时，顶级代理循环的最终计数是结果消息的 [`usage.output_tokens_details.thinking_tokens`](#usage)，它[不包括子代理令牌](/docs/zh-CN/agent-sdk/cost-tracking#get-the-total-cost-of-a-query)。
3764 5476
3765需要 Claude Code v2.1.153 或更高版本。5477需要 Claude Code v2.1.153 或更高版本。
3766 5478
3770 subtype: "thinking_tokens";5482 subtype: "thinking_tokens";
3771 estimated_tokens: number;5483 estimated_tokens: number;
3772 estimated_tokens_delta: number;5484 estimated_tokens_delta: number;
5485 user_message_uuid?: string;
3773 uuid: UUID;5486 uuid: UUID;
3774 session_id: string;5487 session_id: string;
3775};5488};
3821 `SDKLocalCommandOutputMessage`5534 `SDKLocalCommandOutputMessage`
3822</h3>5535</h3>
3823 5536
3824来自本地 slash command 的输出（例如，`/voice` 或 `/usage`）。在记录中显示为助手样式的文本。5537Claude Code 不发出此消息类型。当您发送命令（例如 `/context` 或 `/usage`）作为提示时，其输出作为 [`SDKAssistantMessage`](#sdkassistantmessage) 到达。
3825 5538
3826```typescript theme={null}5539```typescript theme={null}
3827type SDKLocalCommandOutputMessage = {5540type SDKLocalCommandOutputMessage = {
3837 `SDKCommandsChangedMessage`5550 `SDKCommandsChangedMessage`
3838</h3>5551</h3>
3839 5552
3840当可用命令集在会话中期发生变化时发出，例如当代理进入子目录时发现技能。`commands` 数组是完整的更新列表，因此用此有效负载替换任何缓存的命令列表。再次调用 `supportedCommands()` 不等同：该方法返回在初始化时捕获的快照，不反映会话中期的变化。5553当可用命令集在会话中期发生变化时发出，例如当代理进入子目录时发现技能。`commands` 数组是完整的更新列表，因此用此有效负载替换任何缓存的命令列表。在此消息后调用 [`supportedCommands()`](#query-object) 返回相同的更新列表，因为该方法跟踪最新推送；这需要 Agent SDK v0.3.216 或更高版本。在早期 SDK 版本中，`supportedCommands()` 返回在初始化时捕获的快照，永远不反映会话中期的变化。
3841 5554
3842```typescript theme={null}5555```typescript theme={null}
3843type SDKCommandsChangedMessage = {5556type SDKCommandsChangedMessage = {
3853 `SDKPromptSuggestionMessage`5566 `SDKPromptSuggestionMessage`
3854</h3>5567</h3>
3855 5568
3856当启用 `promptSuggestions` 时在每个轮次后发出。包含预测的下一个用户提示。5569当启用 [`promptSuggestions`](#options) 且 Claude Code 为该轮次生成了建议时，在轮次后发出。包含预测的下一个用户提示。对于未获得任何建议的轮次，请参阅 [当 Claude Code 跳过建议时](/docs/zh-CN/interactive-mode#when-claude-code-skips-suggestions)。
3857 5570
3858```typescript theme={null}5571```typescript theme={null}
3859type SDKPromptSuggestionMessage = {5572type SDKPromptSuggestionMessage = {
3868 `SDKConversationResetMessage`5581 `SDKConversationResetMessage`
3869</h3>5582</h3>
3870 5583
3871当会话的对话被替换而不结束会话时发出，例如在 `/clear` 之后、在计划模式退出时或当新对话启动时。在 `new_conversation_id` 下挂载空记录，并丢弃任何缓存的会话标题。5584当会话的对话被替换而不结束会话时发出。在 `query()` 调用中，仅 `/clear` 及其别名产生此消息。在 `new_conversation_id` 下挂载空记录，并丢弃任何缓存的会话标题。
3872 5585
3873```typescript theme={null}5586```typescript theme={null}
3874type SDKConversationResetMessage = {5587type SDKConversationResetMessage = {
3891class AbortError extends Error {}5604class AbortError extends Error {}
3892```5605```
3893 5606
5607`AbortError` 是 SDK 的类型化 API 中唯一的错误类。其他失败，例如 Claude Code 进程退出或无法启动，使用没有 SDK 类可匹配的错误拒绝消息迭代。[故障排除](/docs/zh-CN/agent-sdk/troubleshooting) 按消息键入这些错误，每个都有原因和修复。
5608
3894<h2 id="sandbox-configuration">5609<h2 id="sandbox-configuration">
3895 沙箱配置5610 沙箱配置
3896</h2>5611</h2>
3917```5632```
3918 5633
3919| 属性 | 类型 | 默认值 | 描述 |5634| 属性 | 类型 | 默认值 | 描述 |
3920| :-------------------------- | :---------------------------------------------------- | :---------- | :------------------------------------------------------------------------------------------------------------------------------ |5635| :-------------------------- | :---------------------------------------------------- | :---------- | :------------------------------------------------------------------------------------------------------------------------------------------------------ |
3921| `enabled` | `boolean` | `false` | 为命令执行启用沙箱模式 |5636| `enabled` | `boolean` | `false` | 为命令执行启用沙箱模式 |
3922| `failIfUnavailable` | `boolean` | `true` | 如果 `enabled` 为 `true` 但沙箱无法启动，则在启动时停止。设置为 `false` 以回退到沙箱外执行，并在 stderr 上显示警告 |5637| `failIfUnavailable` | `boolean` | `true` | 如果 `enabled` 为 `true` 但沙箱无法启动，则在启动时停止。设置为 `false` 以回退到沙箱外执行，并在 stderr 上显示警告 |
3923| `autoAllowBashIfSandboxed` | `boolean` | `true` | 启用沙箱时自动批准 bash 命令 |5638| `autoAllowBashIfSandboxed` | `boolean` | `true` | 启用沙箱时自动批准 bash 命令 |
3925| `allowUnsandboxedCommands` | `boolean` | `true` | 允许模型请求在沙箱外运行命令。当为 `true` 时，模型可以在工具输入中设置 `dangerouslyDisableSandbox`，这会回退到[权限系统](#permissions-fallback-for-unsandboxed-commands) |5640| `allowUnsandboxedCommands` | `boolean` | `true` | 允许模型请求在沙箱外运行命令。当为 `true` 时，模型可以在工具输入中设置 `dangerouslyDisableSandbox`，这会回退到[权限系统](#permissions-fallback-for-unsandboxed-commands) |
3926| `network` | [`SandboxNetworkConfig`](#sandboxnetworkconfig) | `undefined` | 网络特定的沙箱配置 |5641| `network` | [`SandboxNetworkConfig`](#sandboxnetworkconfig) | `undefined` | 网络特定的沙箱配置 |
3927| `filesystem` | [`SandboxFilesystemConfig`](#sandboxfilesystemconfig) | `undefined` | 用于读/写限制的文件系统特定沙箱配置 |5642| `filesystem` | [`SandboxFilesystemConfig`](#sandboxfilesystemconfig) | `undefined` | 用于读/写限制的文件系统特定沙箱配置 |
3928| `ignoreViolations` | `Record<string, string[]>` | `undefined` | 违规类别到要忽略的模式的映射（例如，`{ file: ['/tmp/*'], network: ['localhost'] }`） |5643| `ignoreViolations` | `Record<string, string[]>` | `undefined` | 命令子字符串或 `*` 的映射（用于每个命令）到要忽略的违规文本的子字符串，例如 `{ "*": ['/etc/hosts'] }`；请参阅 [`sandbox.ignoreViolations`](/docs/zh-CN/settings-reference#sandbox-ignoreviolations) |
3929| `enableWeakerNestedSandbox` | `boolean` | `false` | 为兼容性启用较弱的嵌套沙箱 |5644| `enableWeakerNestedSandbox` | `boolean` | `false` | 为兼容性启用较弱的嵌套沙箱 |
3930| `ripgrep` | `{ command: string; args?: string[] }` | `undefined` | 沙箱环境中的自定义 ripgrep 二进制配置 |5645| `ripgrep` | `{ command: string; args?: string[] }` | `undefined` | 沙箱环境中的自定义 ripgrep 二进制配置 |
3931 5646
3965```5680```
3966 5681
3967<Warning>5682<Warning>
3968 **Unix socket 安全性：** `allowUnixSockets` 选项可以授予对强大系统服务的访问权限。例如，允许 `/var/run/docker.sock` 实际上通过 Docker API 授予对主机系统的完全访问权限，绕过沙箱隔离。仅允许严格必要的 Unix sockets 并了解每个的安全含义。5683 **Unix socket 安全性：** `allowUnixSockets` 选项可以授予对系统服务的访问权限，这些服务可能会到达沙箱外。例如，允许 `/var/run/docker.sock` 实际上通过 Docker API 授予对主机系统的完全访问权限，绕过沙箱隔离。仅允许严格必要的 Unix sockets 并了解每个的安全含义。
3969</Warning>5684</Warning>
3970 5685
3971<h3 id="sandboxnetworkconfig">5686<h3 id="sandboxnetworkconfig">
3978type SandboxNetworkConfig = {5693type SandboxNetworkConfig = {
3979 allowedDomains?: string[];5694 allowedDomains?: string[];
3980 deniedDomains?: string[];5695 deniedDomains?: string[];
5696 strictAllowlist?: boolean;
3981 allowManagedDomainsOnly?: boolean;5697 allowManagedDomainsOnly?: boolean;
3982 allowLocalBinding?: boolean;5698 allowLocalBinding?: boolean;
3983 allowUnixSockets?: string[];5699 allowUnixSockets?: string[];
3988```5704```
3989 5705
3990| 属性 | 类型 | 默认值 | 描述 |5706| 属性 | 类型 | 默认值 | 描述 |
3991| :------------------------ | :--------- | :---------- | :----------------------------------------------------------------------------------------------------------------------- |5707| :------------------------ | :--------- | :---------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
3992| `allowedDomains` | `string[]` | `[]` | 沙箱进程可以访问的域名 |5708| `allowedDomains` | `string[]` | `[]` | 沙箱进程可以访问的域名 |
3993| `deniedDomains` | `string[]` | `[]` | 沙箱进程无法访问的域名。优先于 `allowedDomains` |5709| `deniedDomains` | `string[]` | `[]` | 沙箱进程无法访问的域名。优先于 `allowedDomains` |
3994| `allowManagedDomainsOnly` | `boolean` | `false` | 仅限管理设置。在[管理设置](/docs/zh-CN/permissions#managed-settings)中设置时，仅遵守来自管理设置的 `allowedDomains` 条目，来自用户、项目或本地设置的条目被忽略。通过 SDK 选项设置时无效 |5710| `strictAllowlist` | `boolean` | `false` | 拒绝沙箱化命令访问[网络允许列表](/docs/zh-CN/sandboxing#network-isolation)之外的主机，而不是提示。仅对沙箱化命令强制执行；WebFetch 等进程内工具不受其限制。仅从用户、托管或 CLI `--settings` 设置中遵守；项目设置被忽略。需要 Claude Code v2.1.219 或更高版本 |
5711| `allowManagedDomainsOnly` | `boolean` | `false` | 仅限管理设置。在[管理设置](/docs/zh-CN/managed-settings)中设置时，仅遵守来自管理设置的 `allowedDomains` 条目和来自管理设置的 `WebFetch(domain:...)` 允许规则，来自用户、项目或本地设置的允许条目被忽略。通过 SDK 选项设置时无效 |
3995| `allowLocalBinding` | `boolean` | `false` | 允许进程绑定到本地端口（例如，用于开发服务器） |5712| `allowLocalBinding` | `boolean` | `false` | 允许进程绑定到本地端口（例如，用于开发服务器） |
3996| `allowUnixSockets` | `string[]` | `[]` | 进程可以访问的 Unix socket 路径（例如，Docker socket） |5713| `allowUnixSockets` | `string[]` | `[]` | 进程可以访问的 Unix socket 路径（例如，Docker socket） |
3997| `allowAllUnixSockets` | `boolean` | `false` | 允许访问所有 Unix sockets |5714| `allowAllUnixSockets` | `boolean` | `false` | 允许访问所有 Unix sockets |
4026 沙箱外命令的权限回退5743 沙箱外命令的权限回退
4027</h3>5744</h3>
4028 5745
4029启用 `allowUnsandboxedCommands` 时，模型可以通过在工具输入中设置 `dangerouslyDisableSandbox: true` 来请求在沙箱外运行命令。这些请求回退到现有权限系统，意味着您的 `canUseTool` 处理程序被调用，允许您实现自定义授权逻辑。在下面的示例中，`isCommandAuthorized` 代表您定义的授权检查。5746当 `allowUnsandboxedCommands` 启用时，模型可以通过在工具输入中设置 `dangerouslyDisableSandbox: true` 来请求在沙箱外运行命令。这些请求回退到现有权限系统，意味着您的 `canUseTool` 处理程序被调用，允许您实现自定义授权逻辑。在下面的示例中，`isCommandAuthorized` 代表您定义的授权检查。
4030
4031<Note>
4032 **`excludedCommands` vs `allowUnsandboxedCommands`：**
4033
4034 * `excludedCommands`：始终自动绕过沙箱的命令的静态列表（例如，`['docker']`）。模型对此无法控制。
4035 * `allowUnsandboxedCommands`：让模型在运行时通过在工具输入中设置 `dangerouslyDisableSandbox: true` 来决定是否请求沙箱外执行。
4036</Note>
4037 5747
4038```typescript theme={null}5748```typescript theme={null}
4039import { query } from "@anthropic-ai/claude-agent-sdk";5749import { query } from "@anthropic-ai/claude-agent-sdk";
4068}5778}
4069```5779```
4070 5780
4071此模式使您能够：
4072
4073* **审计模型请求：** 记录模型何时请求沙箱外执行
4074* **实现允许列表：** 仅允许特定命令在沙箱外运行
4075* **添加批准工作流：** 需要对特权操作进行明确授权
4076
4077<Warning>5781<Warning>
4078 使用 `dangerouslyDisableSandbox: true` 运行的命令具有完整的系统访问权限。确保您的 `canUseTool` 处理程序仔细验证这些请求。5782 使用 `dangerouslyDisableSandbox: true` 运行的命令具有完整的系统访问权限。确保您的 `canUseTool` 处理程序仔细验证这些请求。
4079 5783
4080 如果 `permissionMode` 设置为 `bypassPermissions` 且 `allowUnsandboxedCommands` 启用，模型可以自主执行沙箱外的命令，无需任何批准提示（显式的 [`ask` 规则](/docs/zh-CN/agent-sdk/permissions#how-permissions-are-evaluated)仍会强制执行一个）。此组合实际上允许模型以静默方式逃离沙箱隔离。5784 如果 `permissionMode` 设置为 `bypassPermissions` 且 `allowUnsandboxedCommands` 启用，模型可以自主执行沙箱外的命令，无需批准提示，除了[操作无模式自动批准的操作](/docs/zh-CN/permission-modes#actions-no-mode-auto-approves)。此组合实际上允许模型以静默方式逃离沙箱隔离。
4081</Warning>5785</Warning>
4082 5786
4083<h2 id="see-also">5787<h2 id="see-also">
