TypeScript SDK 参考：其他类型与沙盒配置

本页是 TypeScript Agent SDK 参考的最后一部分：不属于前几页的辅助类型、其余的系统消息类型，以及沙盒配置。

其他类型

ApiKeySource

会话请求的 API key 来自哪里，作为 SDKSystemMessage init 消息上的 apiKeySource 报告。

type ApiKeySource =
  | "ANTHROPIC_API_KEY"
  | "apiKeyHelper"
  | "/login managed key"
  | "none"
  | "user"
  | "project"
  | "org"
  | "temporary"
  | "oauth";

Claude Code 报告四个值之一：ANTHROPIC_API_KEY——ANTHROPIC_API_KEY 环境变量里的 key；apiKeyHelper——你的 apiKeyHelper 命令返回的 key；/login managed key——你用 Claude Console 账号登录时 Claude Code 存储的 key；none——没有 API key，会话以另一种方式认证，如 claude.ai 登录、bearer 令牌或云提供商。Agent SDK v0.3.234 及以上在类型里列出这四个值；类型还保留 user、project、org、temporary 和 oauth，使旧代码仍能编译，Claude Code 不会报告它们。

SdkBeta

可通过 betas 选项启用的 beta 功能。

type SdkBeta = "context-1m-2025-08-07";

注意：context-1m-2025-08-07 beta 已于 2026 年 4 月 30 日退役。对 Claude Sonnet 4.5 或 Sonnet 4 传入该值没有效果，超过标准 200k token 上下文窗口的请求会返回错误；要用 1M token 的上下文窗口，需迁移到支持它的模型。

SlashCommand

可用命令的信息。

type SlashCommand = {
  name: string;
  description: string;
  argumentHint: string;
  aliases?: string[];
  builtin?: boolean;
};

builtin 在命令是 Claude Code 自己的、键入 /name 就会运行它时为 true；用户、项目、插件或 MCP 服务器定义的命令，以及被它们按名字替换的内置命令，该字段不存在。

ModelInfo

可用模型的信息。

type ModelInfo = {
  value: string;
  resolvedModel?: string;
  displayName: string;
  description: string;
  supportsEffort?: boolean;
  supportedEffortLevels?: ("low" | "medium" | "high" | "xhigh" | "max")[];
  supportsAdaptiveThinking?: boolean;
  supportsFastMode?: boolean;
  supportsAutoMode?: boolean;
};

AgentInfo

可通过 Agent 工具调用的可用子智能体的信息。

type AgentInfo = {
  name: string;
  description: string;
  model?: string;
};

McpServerProvenance

为 mcp__* 工具提供服务的 MCP 服务器，以及该服务器的定义来自哪里。PreToolUse、PostToolUse、PostToolUseFailure、PermissionRequest 和 PermissionDenied 的 hook 输入把它作为 mcp_server 携带，CanUseTool 选项把它作为 mcpServer 携带；不来自 MCP 服务器的工具两者都省略。

type McpServerProvenance = {
  name: string;
  source: string;
};

source 取下列值之一，该集合是开放的，所以要把你不认识的值当作已配置的来源，绝不当作 sdk：sdk——你的应用注册的进程内服务器，只有 SDK 宿主应用能注册，所以已配置的服务器无论叫什么名字都从不报告 sdk；plugin——插件提供的服务器，其 name 是带范围的 plugin:<plugin-name>:<server-name> 形式；配置范围——user、project、local、dynamic、managed、enterprise、claudeai 或 agent，.mcp.json 里的服务器报告 project，你的应用在 mcpServers 选项里传入的服务器（进程内 SDK 服务器除外）报告 dynamic。信任决定要基于 source，不要基于 name 或 mcp__<server>__ 工具名前缀；对 sdk 之外的任何来源，name 都是不受信任的文本，显示前要转义。McpServerProvenance 及携带它的字段需要 Agent SDK v0.3.274 及以上。

McpServerStatus

已连接 MCP 服务器的状态。

type McpServerStatus = {
  name: string;
  status: "connected" | "failed" | "needs-auth" | "pending" | "disabled";
  serverInfo?: {
    name: string;
    version: string;
  };
  error?: string;
  config?: McpServerStatusConfig;
  scope?: string;
  source?: string;
  tools?: {
    name: string;
    description?: string;
    annotations?: {
      readOnly?: boolean;
      destructive?: boolean;
      openWorld?: boolean;
    };
    _meta?: Record<string, unknown>;
  }[];
};

source 说明服务器的定义来自哪里，取值和信任规则与 McpServerProvenance 的 source 相同；该字段需要 Agent SDK v0.3.274 及以上，更早的版本上不存在。tools 条目上的 _meta 携带该工具 _meta 里的 MCP Apps 成员，使你的应用能找到要用 readMcpResource() 渲染的 ui:// 资源；Claude Code 透传 ui 对象和已弃用的扁平 ui/resourceUri 字符串，并扣留其他所有键。

McpServerStatusConfig

mcpServerStatus() 报告的 MCP 服务器配置，是所有 MCP 服务器传输类型的联合。

type McpServerStatusConfig =
  | McpStdioServerConfig
  | McpSSEServerConfig
  | McpHttpServerConfig
  | McpSdkServerConfig
  | McpClaudeAIProxyServerConfig;

AccountInfo

已认证用户的账号信息。

type AccountInfo = {
  email?: string;
  organization?: string;
  subscriptionType?: string;
  tokenSource?: string;
  apiKeySource?: string;
};

ModelUsage

结果消息里返回的按模型用量统计。costUSD 是客户端估算（账单注意事项见「跟踪成本与用量」）。

type ModelUsage = {
  inputTokens: number;
  outputTokens: number;
  thinkingTokens?: number;
  cacheReadInputTokens: number;
  cacheCreationInputTokens: number;
  webSearchRequests: number;
  costUSD: number;
  contextWindow: number;
  maxOutputTokens: number;
  canonicalModel?: string;
  provider?: string;
  costBasis?: 'list' | 'managed' | 'unknown';
};

thinkingTokens 统计该模型生成的思考 token；outputTokens 已经包含它们，所以不要把两者相加；在某个轮次于记录它的 Claude Code 版本上运行之前，该字段不存在，所以从较早版本开始的已恢复会话报告的是部分计数（thinkingTokens 需要 Agent SDK v0.3.257 及以上）。canonicalModel 和 provider 字段需要 Claude Code v2.1.218 及以上：canonicalModel 是价格查找使用的规范模型 ID，它可能与作为条目键的原始模型字符串不同，例如该字符串是提供商专有 ID 或别名时；provider 点名服务该模型的 API 后端，如 firstParty、bedrock、vertex、foundry、anthropicAws、mantle 或 gateway。costBasis 点名为模型最近一次请求定价的价格表：list 为标价，managed 为 modelPricing 表，两者都不匹配该模型 ID 时为 unknown（需要 Claude Code v2.1.246 及以上）。

ConfigScope、NonNullableUsage 与 Usage

type ConfigScope = "local" | "user" | "project";

type NonNullableUsage = {
  [K in keyof Usage]: NonNullable<Usage[K]>;
};

type Usage = {
  input_tokens: number;
  output_tokens: number;
  cache_creation_input_tokens: number | null;
  cache_read_input_tokens: number | null;
  cache_creation: {
    ephemeral_5m_input_tokens: number;
    ephemeral_1h_input_tokens: number;
  } | null;
  server_tool_use: BetaServerToolUsage | null;
  service_tier: "standard" | "priority" | "batch" | null;
  speed: "standard" | "fast" | null;
  inference_geo: string | null;
  iterations: BetaIterationsUsage | null;
  output_tokens_details: BetaOutputTokensDetails | null;
};

NonNullableUsage 是把所有可空字段都变成非空的 Usage 版本。Usage 是 token 用量统计，即 @anthropic-ai/sdk 的 BetaUsage 类型；BetaServerToolUsage、BetaIterationsUsage 和 BetaOutputTokensDetails 定义在 @anthropic-ai/sdk 里。output_tokens_details 按类别拆分计费的输出，目前只有一个字段 thinking_tokens: number，统计模型作为内部推理生成的输出 token（含思考块分隔符）；该字段需要 TypeScript SDK v0.3.228 及以上（它捆绑 Claude Code v2.1.228）。

• 计费：读这个拆分用于可观测性，不要用于计费：output_tokens 仍是权威总数，output_tokens - thinking_tokens 近似非推理输出。
• 计数涵盖什么：模型产生的原始推理，它可能比响应正文里返回的思考文本更长；API 通过重新分词该原始文本来计算它，所以它可能与模型确切的生成计数相差几个 token。
• 流式：在流式助手消息上，这个拆分与 output_tokens 一样是 message_start 占位符，不带真实计数，所以要从结果消息的 usage 读取；在结果消息上，模型或提供商没有报告拆分时 thinking_tokens 读作 0。
• null 的情形：在 Claude Code 合成的助手消息（如 API 错误消息）上，output_tokens_details 本身为 null。

CallToolResult

MCP 工具结果类型（来自 @modelcontextprotocol/sdk/types.js）。structuredContent 是可以与 content（包括图片块）一起返回的 JSON 对象。

type CallToolResult = {
  content: Array<{
    type: "text" | "image" | "audio" | "resource" | "resource_link";
    // 其他字段随类型而异
  }>;
  structuredContent?: Record<string, unknown>;
  isError?: boolean;
};

SDKMcpResourceLink

MCP 工具按引用返回的一个文件。Claude Code 从工具结果里的 resource_link 块构建每个条目，并把列表作为 SDKUserMessage.tool_use_result 上的 resourceLinks 交付，或在调用在后台结束时作为 SDKTaskNotificationMessage 上的 resource_links 交付（需要 Agent SDK v0.3.257 及以上）。

type SDKMcpResourceLink = {
  uri: string;
  name: string;
  title?: string;
  description?: string;
  mimeType?: string;
  size?: number;
  annotations?: Record<string, unknown>;
};

Claude Code 丢弃 uri 或 name 不是字符串的块，并省略值不是所列类型的可选字段。字段：uri 是资源的 URI，原样来自服务器；name 是服务器给资源起的名字；title、description、mimeType、size（字节）、annotations（该块的 MCP 注解对象）在服务器设置了时才有。

ThinkingConfig

控制 Claude 的思考/推理行为，优先于已弃用的 maxThinkingTokens。

type ThinkingDisplay = "summarized" | "omitted";

type ThinkingConfig =
  | { type: "adaptive"; display?: ThinkingDisplay } // 模型决定何时以及推理多少（Opus 4.6+）
  | { type: "enabled"; budgetTokens?: number; display?: ThinkingDisplay } // 固定的思考 token 预算
  | { type: "disabled" }; // 不使用扩展思考

可选的 display 字段控制思考文本是以 "summarized" 还是 "omitted" 返回。在 Claude Opus 4.7 及以后，API 默认是 "omitted"，所以要设 "summarized" 才能在 thinking 块里收到思考内容。Claude Code 不向 Amazon Bedrock 或 Google Cloud Agent Platform 发送 display，所以在这些提供商上，Opus 4.7 及以后即使你设了 display 也返回空的 thinking 块。

SpawnedProcess 与 SpawnOptions

用于自定义进程派生的接口（配合 spawnClaudeCodeProcess 选项使用）。ChildProcess 已满足 SpawnedProcess。

interface SpawnedProcess {
  stdin: Writable;
  stdout: Readable;
  readonly killed: boolean;
  readonly exitCode: number | null;
  kill(signal: NodeJS.Signals): boolean;
  on(
    event: "exit",
    listener: (code: number | null, signal: NodeJS.Signals | null) => void
  ): void;
  on(event: "error", listener: (error: Error) => void): void;
  once(
    event: "exit",
    listener: (code: number | null, signal: NodeJS.Signals | null) => void
  ): void;
  once(event: "error", listener: (error: Error) => void): void;
  off(
    event: "exit",
    listener: (code: number | null, signal: NodeJS.Signals | null) => void
  ): void;
  off(event: "error", listener: (error: Error) => void): void;
}

interface SpawnOptions {
  command: string;
  args: string[];
  cwd?: string;
  env: Record<string, string | undefined>;
  signal: AbortSignal;
}

SpawnOptions 的 signal 字段告诉你的派生函数何时拆除进程：把它作为 signal 选项传给 Node 的 spawn()，或传给你的 VM 或容器拆除处理程序。这个信号不会在 Options.abortController 中止的瞬间触发：SDK 先关闭进程的 stdin 并等约两秒让 CLI 干净关闭，然后才中止这个信号。要在调用方中止的那一刻就作出反应，监听你自己的 Options.abortController.signal，你的派生函数可以从外围作用域引用它。

McpSetServersResult

setMcpServers() 操作的结果。

type McpSetServersResult = {
  added: string[];
  removed: string[];
  errors: Record<string, string>;
};

调用 setMcpServers() 时，Claude Code 应用这些规则：调用没有点名的服务器——Claude Code 让插件提供的服务器保持运行（需要 Agent SDK v0.3.210 及以上）；调用点名的服务器——除 CLI 在启动时启动的内置服务器外，只有当运行中服务器的配置与你传入的不同时，Claude Code 才替换它；CLI 在启动时启动的内置服务器——调用点名其中之一时，Claude Code 丢弃该条目并在 errors 里报告它。promise 在新添加的 stdio、HTTP 和 SSE 服务器连接或失败之后才解析，所以已连接服务器的工具在下一个轮次可用。added 列出 Claude Code 添加或替换的服务器，不论是否连接上；连接失败的服务器同时出现在 added 和 errors 里，失败文本在 errors 下，且 mcpServerStatus() 里有一行 failed（Claude Code v2.1.257 之前，连接尝试抛出异常的服务器只在 errors 下报告）。

RewindFilesResult

rewindFiles() 操作的结果。

type RewindFilesResult = {
  canRewind: boolean;
  error?: string;
  filesChanged?: string[];
  insertions?: number;
  deletions?: number;
  skippedLinks?: number;
};

skippedLinks 统计回退出于链接安全而拒绝恢复或删除的被跟踪路径：被跟踪路径上的符号链接、硬链接或其他非常规文件，不再解析到检查点创建时它所指位置的父目录，或无法安全读取的备份（需要 Claude Code v2.1.216 及以上）。

其他系统消息类型

SDKStatusMessage

状态更新消息（例如压缩中）。

type SDKStatusMessage = {
  type: "system";
  subtype: "status";
  status: "compacting" | null;
  permissionMode?: PermissionMode;
  uuid: UUID;
  session_id: string;
};

SDKTaskNotificationMessage

后台任务完成、失败或被停止时的通知。后台任务包括 run_in_background 的 Bash 命令、Monitor 监视和后台子智能体。ambient 字段见 SDKTaskStartedMessage，它在那里定义并说明版本要求。

type SDKTaskNotificationMessage = {
  type: "system";
  subtype: "task_notification";
  task_id: string;
  tool_use_id?: string;
  status: "completed" | "failed" | "stopped";
  output_file: string;
  summary: string;
  ambient?: boolean;
  usage?: {
    total_tokens: number;
    tool_uses: number;
    duration_ms: number;
  };
  resource_links?: SDKMcpResourceLink[];
  uuid: UUID;
  session_id: string;
};

当 Claude Code 把长时间的 MCP 工具调用转入后台时，该调用的 tool_result 块只含占位符，调用的真实结果在这条通知里到达；用 tool_use_id 把通知与调用匹配。在 completed 通知上，resource_links 以 SDKMcpResourceLink 条目列出工具按引用返回的文件，限制与 tool_use_result 相同。Claude Code 在发给模型的每条任务通知前加一段说明，带有 scheduled-trigger subkind 的投递除外（它们带分配任务的表述）；该说明声明没有发生人类输入，使模型不会把通知当作用户指令或批准。要检测任务通知轮次，检查 SDKUserMessage 或 SDKResultMessage 上的 origin.kind === "task-notification"，而不是匹配说明文本；需要知道是什么引发的，从同一字段读 subkind（v2.1.205 之前，Claude Code 在会话空闲时到达的通知上省略该说明）。

SDKToolUseSummaryMessage

对话中工具使用的摘要。

type SDKToolUseSummaryMessage = {
  type: "tool_use_summary";
  summary: string;
  preceding_tool_use_ids: string[];
  uuid: UUID;
  session_id: string;
};

hook 生命周期消息

Claude Code 把 SDKHookStartedMessage、SDKHookProgressMessage 和 SDKHookResponseMessage 立即交付到消息流，包括 SessionStart 或 Setup hook 在会话启动期间仍在运行时（Claude Code v2.1.169 到 v2.1.203 是在 SessionStart 或 Setup hook 完成后成批交付这些消息；v2.1.204 恢复了实时交付）。

type SDKHookStartedMessage = {
  type: "system";
  subtype: "hook_started";
  hook_id: string;
  hook_name: string;
  hook_event: string;
  uuid: UUID;
  session_id: string;
};

type SDKHookProgressMessage = {
  type: "system";
  subtype: "hook_progress";
  hook_id: string;
  hook_name: string;
  hook_event: string;
  stdout: string;
  stderr: string;
  output: string;
  uuid: UUID;
  session_id: string;
};

type SDKHookResponseMessage = {
  type: "system";
  subtype: "hook_response";
  hook_id: string;
  hook_name: string;
  hook_event: string;
  output: string;
  stdout: string;
  stderr: string;
  exit_code?: number;
  outcome: "success" | "error" | "cancelled";
  uuid: UUID;
  session_id: string;
};

hook_started 在 hook 开始执行时发出；hook_progress 在 hook 运行期间带 stdout/stderr 输出发出；hook_response 在 hook 执行结束时发出。

SDKToolProgressMessage

工具执行期间定期发出，指示进度。

type SDKToolProgressMessage = {
  type: "tool_progress";
  tool_use_id: string;
  tool_name: string;
  parent_tool_use_id: string | null;
  elapsed_time_seconds: number;
  task_id?: string;
  heartbeat?: boolean;
  subagent_type?: string;
  subagent_retry?: {
    agent_id: string;
    attempt: number;
    max_retries: number;
    retry_delay_ms: number;
    error_status: number | null;
    error_category: string;
  };
  uuid: UUID;
  session_id: string;
};

工具调用在主对话里运行时，Claude Code 每 30 秒发出一条带 heartbeat: true 的 tool_progress 消息。每个心跳携带工具名和已用秒数，使你能区分长时间运行的调用与停滞的会话；Claude Code 不为子智能体内的工具调用发心跳（heartbeat 字段需要 Agent SDK v0.3.214 及以上）。在 Agent 工具的非心跳 tool_progress 消息上，subagent_type 点名运行中的子智能体类型，如 general-purpose；subagent_retry 在该子智能体等待 API 错误退避（如速率限制或过载）期间存在，每次重试尝试一条消息；两个字段都需要 Agent SDK v0.3.214 及以上。要从 subagent_retry 渲染重试指示：按 parent_tool_use_id（每个子智能体唯一）跟踪指示器，因为一个助手轮次里的并行子智能体共享 tool_use_id，按它跟踪会让一个子智能体的更新清掉另一个的指示；当同一个 parent_tool_use_id 的后续 tool_progress 到达且既没有 subagent_retry 也没有 heartbeat: true，或工具的结果消息到达时清除指示器（带 heartbeat: true 的帧只报告存活，所以收到时保持指示器；在持续重试下 attempt 可以超过 max_retries，所以不要用计数器推导清除）；把 error_category 当作用来选择你自己消息文本的标记，而不是显示文本，取值有 rate_limit、overloaded、authentication_failed、server_error、cloud_credential_error 和 unknown，遇到你不认识的值要像处理 unknown 那样处理，因为之后的版本可能增加取值。

SDKAuthStatusMessage

在认证流程期间发出。

type SDKAuthStatusMessage = {
  type: "auth_status";
  isAuthenticating: boolean;
  output: string[];
  error?: string;
  uuid: UUID;
  session_id: string;
};

任务消息：SDKTaskStartedMessage、SDKTaskProgressMessage、SDKTaskUpdatedMessage、SDKBackgroundTasksChangedMessage

SDKTaskStartedMessage 在任务开始时发出；task_type 字段对 Bash 命令和 Monitor 监视是 "local_bash"，对子智能体是 "local_agent"，或 "remote_agent"。

type SDKTaskStartedMessage = {
  type: "system";
  subtype: "task_started";
  task_id: string;
  tool_use_id?: string;
  description: string;
  task_type?: string;
  is_backgrounded?: boolean;
  spawn_depth?: number;
  ambient?: boolean;
  uuid: UUID;
  session_id: string;
};

ambient 对不属于会话工作的任务为 true，如 Claude Code 为自身运行而执行的任务；实时更新监视器也是 ambient，包括用户要求的监视器；要把 ambient 任务排除在活动指示器之外（该字段需要 Agent SDK v0.3.247 及以上；ambient 也出现在 SDKTaskNotificationMessage 和 SDKBackgroundTasksChangedMessage 的条目上）。is_backgrounded 和 spawn_depth 描述 Claude Code 如何启动该任务，两者需要 Agent SDK v0.3.238 及以上：is_backgrounded 由 Claude Code 设在 "local_agent" 和 "local_bash" 任务上，true 表示任务在后台运行，false 表示任务在前台运行，启动它的工具调用保持阻塞直到任务结束或转入后台；spawn_depth 只设在 "local_agent" 任务上，主线程派生的子智能体深度为 1，深度为 1 的子智能体派生的子智能体深度为 2，依此类推。恢复的子智能体总是报告 is_backgrounded: true，因为 Claude Code 在后台运行每个恢复的子智能体；前台任务之后转入后台时，Claude Code 在 task_updated 消息里报告新的 is_backgrounded 值，而不是再发一次 task_started。

SDKTaskProgressMessage 在子智能体或后台任务运行期间定期发出。对子智能体任务，summary 字段携带模型生成的进度摘要，只在启用 agentProgressSummaries 时才填充；对转入后台的 MCP 工具调用，summary 携带 MCP 服务器最近报告的进度，不依赖该选项。

type SDKTaskProgressMessage = {
  type: "system";
  subtype: "task_progress";
  task_id: string;
  tool_use_id?: string;
  description: string;
  subagent_type?: string;
  usage: {
    total_tokens: number;
    tool_uses: number;
    duration_ms: number;
  };
  last_tool_name?: string;
  summary?: string;
  uuid: UUID;
  session_id: string;
};

SDKTaskUpdatedMessage 在后台任务状态改变时发出，例如从 running 变为 completed。把 patch 合并进你以 task_id 为键的本地任务映射；end_time 字段是以毫秒计的 Unix epoch 时间戳，可与 Date.now() 比较。

type SDKTaskUpdatedMessage = {
  type: "system";
  subtype: "task_updated";
  task_id: string;
  patch: {
    status?: "pending" | "running" | "completed" | "failed" | "killed";
    description?: string;
    end_time?: number;
    total_paused_ms?: number;
    error?: string;
    is_backgrounded?: boolean;
  };
  uuid: UUID;
  session_id: string;
};

SDKBackgroundTasksChangedMessage 在活动后台任务的集合每次变化时发出：任务开始、完成、被杀、前台智能体转入后台，或任务的 description 或 ambient 字段改变。tasks 数组是完整的活动集合，要用每个载荷替换你缓存的集合，而不是配对 task_started 和 task_notification 事件，这样下一次成员变化会修正你错过的任何事件；它与这些按任务事件的相对顺序未指定，所以不要关联这两个流；启动时不发出任何东西，每当会话的 CLI 进程启动或重启时要重置为空集合，让下一次成员变化重新填充；你向运行中的会话发送重复的 initialize 控制请求时（如传输中断后用 reinitialize()），Claude Code 在响应之后跟一份当前活动集合的快照，即使它为空，所以重新连接的宿主无需等下一次成员变化就能知道什么在运行（Agent SDK v0.3.239 之前，重复 initialize 之后不发快照）。需要 Claude Code v2.1.203 及以上。

type SDKBackgroundTasksChangedMessage = {
  type: "system";
  subtype: "background_tasks_changed";
  tasks: {
    task_id: string;
    task_type: string;
    description: string;
    ambient?: boolean;
  }[];
  uuid: UUID;
  session_id: string;
};

SDKThinkingTokensMessage

Claude 生成思考块（包括被编辑的）期间发出。estimated_tokens 是当前块到目前为止生成的思考 token 的运行估计，estimated_tokens_delta 是这一帧携带的增量；用这些估计来显示进度。当模型或提供商报告了拆分时，顶层智能体循环的最终计数是结果消息的 usage.output_tokens_details.thinking_tokens，不含子智能体的 token。需要 Claude Code v2.1.153 及以上。

type SDKThinkingTokensMessage = {
  type: "system";
  subtype: "thinking_tokens";
  estimated_tokens: number;
  estimated_tokens_delta: number;
  user_message_uuid?: string;
  uuid: UUID;
  session_id: string;
};

SDKFilesPersistedEvent 与 SDKRateLimitEvent

type SDKFilesPersistedEvent = {
  type: "system";
  subtype: "files_persisted";
  files: { filename: string; file_id: string }[];
  failed: { filename: string; error: string }[];
  processed_at: string;
  uuid: UUID;
  session_id: string;
};

type SDKRateLimitEvent = {
  type: "rate_limit_event";
  rate_limit_info: {
    status: "allowed" | "allowed_warning" | "rejected";
    resetsAt?: number;
    utilization?: number;
    errorCode?: "credits_required";
    canUserPurchaseCredits?: boolean;
    hasChargeableSavedPaymentMethod?: boolean;
  };
  uuid: UUID;
  session_id: string;
};

SDKFilesPersistedEvent 在文件检查点持久化到磁盘时发出。SDKRateLimitEvent 在会话遇到速率限制时发出：当 errorCode 为 "credits_required" 时，拒绝来自包含用量已耗尽的 claude.ai 订阅，会话无法继续，直到用户购买用量额度；canUserPurchaseCredits 表示已认证用户能否为账号购买额度，hasChargeableSavedPaymentMethod 表示是否有已保存的支付方式；这三个字段在速率限制的其他情形里都不存在。

SDKLocalCommandOutputMessage、SDKCommandsChangedMessage、SDKPromptSuggestionMessage

type SDKLocalCommandOutputMessage = {
  type: "system";
  subtype: "local_command_output";
  content: string;
  uuid: UUID;
  session_id: string;
};

type SDKCommandsChangedMessage = {
  type: "system";
  subtype: "commands_changed";
  commands: SlashCommand[];
  uuid: UUID;
  session_id: string;
};

type SDKPromptSuggestionMessage = {
  type: "prompt_suggestion";
  suggestion: string;
  uuid: UUID;
  session_id: string;
};

Claude Code 不发出 SDKLocalCommandOutputMessage 这种消息类型：把 /context 或 /usage 这样的命令作为提示发送时，其输出以 SDKAssistantMessage 到达。SDKCommandsChangedMessage 在会话中途可用命令集合变化时发出，例如智能体进入子目录时 Claude Code 发现了 skills；commands 数组是完整的更新后列表，要用该载荷替换你缓存的命令列表；这条消息之后调用 supportedCommands() 返回同一个更新后的列表，因为该方法跟踪最近的推送（需要 Agent SDK v0.3.216 及以上）。MCP 服务器的提示加入或离开列表时（例如服务器在会话开始后才完成连接），Claude Code 也发出这条消息（需要 Claude Code v2.1.281 及以上）。SDKPromptSuggestionMessage 在启用 promptSuggestions 且 Claude Code 为该轮次生成了建议时，在轮次之后发出，包含预测的下一个用户提示。

SDKConversationResetMessage

在会话的对话被替换而不结束会话时发出。在 query() 调用里，只有 /clear 及其别名会产生这条消息。要在 new_conversation_id 下挂载一个空记录，并丢弃任何缓存的会话标题。

type SDKConversationResetMessage = {
  type: "conversation_reset";
  new_conversation_id: UUID;
  uuid: UUID;
  session_id: string;
  trigger?: "clear" | "plan_mode_exit" | "fresh_session" | "onboarding";
  user_message_uuid?: string;
  timestamp?: string;
};

可选字段描述这次重置：trigger 是什么丢弃了对话，每条 conversation_reset 消息上都要重置你的记录，包括该字段缺失或携带你不认识的值的那条；user_message_uuid 是携带 /clear 的用户消息的 uuid，用来把重置匹配到该消息；timestamp 是重置发生的时间，UTC 的 ISO 8601 字符串，用于显示，不要用于给消息排序。trigger、user_message_uuid 和 timestamp 字段需要 Claude Code v2.1.281 及以上。SDK 已发布的类型声明在 Claude Code v2.1.203 及以上声明 SDKConversationResetMessage；v2.1.203 之前，SDKMessage 引用该类型却没有声明它，所以禁用 skipLibCheck 时对 type === "conversation_reset" 的收窄无法通过类型检查。

AbortError

中止操作的自定义错误类。

class AbortError extends Error {}

AbortError 是 SDK 类型化 API 里唯一的错误类。其他失败（如 Claude Code 进程退出或启动失败）以不带可匹配 SDK 类的错误拒绝消息迭代；排障页按消息给这些错误建立索引，给出每个的原因和修复办法。

沙盒配置

SandboxSettings

沙盒行为的配置。用它以编程方式启用命令沙盒并配置网络限制。

type SandboxSettings = {
  enabled?: boolean;
  failIfUnavailable?: boolean;
  autoAllowBashIfSandboxed?: boolean;
  excludedCommands?: string[];
  allowUnsandboxedCommands?: boolean;
  network?: SandboxNetworkConfig;
  filesystem?: SandboxFilesystemConfig;
  ignoreViolations?: Record<string, string[]>;
  enableWeakerNestedSandbox?: boolean;
  ripgrep?: { command: string; args?: string[] };
};

注意：沙盒依赖平台支持，在 Linux 上还依赖 bubblewrap 和 socat 这类工具。当 enabled 为 true 而沙盒无法启动时，query() 报告 subtype: "error_during_execution" 的 result 消息，原因在 errors 里；对单条消息的 query() 调用，SDK 在产出该错误结果之后抛出异常，所以要把循环包进 try 块才能继续。要改为不带沙盒运行，设 failIfUnavailable: false。

import { query } from "@anthropic-ai/claude-agent-sdk";

try {
  for await (const message of query({
    prompt: "Build and test my project",
    options: {
      sandbox: {
        enabled: true,
        autoAllowBashIfSandboxed: true,
        network: {
          allowLocalBinding: true
        }
      }
    }
  })) {
    if ("result" in message) console.log(message.result);
  }
} catch (error) {
  // 单次 query() 在产出错误结果之后抛出，
  // 例如沙盒无法启动时（failIfUnavailable 默认为 true）。
  console.log(`Session ended with an error: ${error}`);
}

Unix socket 安全：allowUnixSockets 选项可以授予对延伸到沙盒之外的系统服务的访问。例如允许 /var/run/docker.sock 实际上通过 Docker API 授予完全的宿主系统访问，绕过沙盒隔离。只允许严格必需的 Unix socket，并理解每个的安全含义。

SandboxNetworkConfig

沙盒模式的网络配置。当父级 SandboxSettings 里 enabled 为 true 时，这些设置适用于沙盒里的 Bash 命令；它们不限制 WebFetch 工具，后者改用权限规则。

type SandboxNetworkConfig = {
  allowedDomains?: string[];
  deniedDomains?: string[];
  strictAllowlist?: boolean;
  allowManagedDomainsOnly?: boolean;
  allowLocalBinding?: boolean;
  allowUnixSockets?: string[];
  allowAllUnixSockets?: boolean;
  httpProxyPort?: number;
  socksProxyPort?: number;
};

注意：内置的沙盒代理按请求的主机名强制 allowedDomains，不终止也不检查 TLS 流量，所以域前置之类的技术可能绕过它（细节见沙盒安全限制；配置终止 TLS 的代理见「安全部署」）。

SandboxFilesystemConfig

沙盒模式的文件系统配置。

type SandboxFilesystemConfig = {
  allowWrite?: string[];
  denyWrite?: string[];
  denyRead?: string[];
};

对不带沙盒命令的权限回退

启用 allowUnsandboxedCommands 时，模型可以通过在工具输入里设 dangerouslyDisableSandbox: true 请求在沙盒之外运行命令。这些请求回落到现有的权限系统，也就是会调用你的 canUseTool 处理程序，让你能实现自定义的授权逻辑。你的 excludedCommands 条目则无需模型参与就把调用移出沙盒。下面的例子里，isCommandAuthorized 代表你自己定义的授权检查：

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Deploy my application",
  options: {
    sandbox: {
      enabled: true,
      allowUnsandboxedCommands: true // 模型可以请求不带沙盒执行
    },
    permissionMode: "default",
    canUseTool: async (tool, input) => {
      // 检查模型是否在请求绕过沙盒
      if (tool === "Bash" && input.dangerouslyDisableSandbox) {
        // 模型请求在沙盒之外运行这条命令
        console.log(`Unsandboxed command requested: ${input.command}`);

        if (isCommandAuthorized(input.command)) {
          return { behavior: "allow" as const, updatedInput: input };
        }
        return {
          behavior: "deny" as const,
          message: "Command not authorized for unsandboxed execution"
        };
      }
      return { behavior: "allow" as const, updatedInput: input };
    }
  }
})) {
  if ("result" in message) console.log(message.result);
}

注意：带 dangerouslyDisableSandbox: true 运行的命令拥有完整的系统访问，要确保你的 canUseTool 处理程序仔细验证这些请求。如果 permissionMode 设为 bypassPermissions 且启用了 allowUnsandboxedCommands，模型可以不经批准提示自主执行沙盒之外的命令（没有任何模式自动批准的动作除外），这种组合实际上让模型静默逃出沙盒隔离。

另见

• Agent SDK 概览：通用的 SDK 概念
• Python SDK 参考：Python SDK 文档
• CLI 参考：命令行界面
• 常见工作流：逐步指南