Agent SDK 参考 - TypeScript

TypeScript Agent SDK 的完整 API 参考，包括所有函数、类型和接口。

安装

npm install @anthropic-ai/claude-agent-sdk

编译为单个可执行文件

当您使用 bun build --compile 将应用程序编译为单文件可执行文件时，SDK 无法在运行时解析捆绑的 CLI 二进制文件。require.resolve 在编译后的可执行文件的 $bunfs 虚拟文件系统内不起作用，因此 SDK 会抛出 Native CLI binary for <platform> not found。

要解决此问题，请将平台二进制文件作为文件资产嵌入，在启动时使用 extractFromBunfs() 将其提取到真实路径，然后将该路径传递给 pathToClaudeCodeExecutable。

extractFromBunfs() 辅助函数需要 @anthropic-ai/claude-agent-sdk v0.3.144 或更高版本。下面的示例为 Apple Silicon 上的 macOS 构建：

import binPath from "@anthropic-ai/claude-agent-sdk-darwin-arm64/claude" with { type: "file" };
import { extractFromBunfs } from "@anthropic-ai/claude-agent-sdk/extract";
import { query } from "@anthropic-ai/claude-agent-sdk";

const cliPath = extractFromBunfs(binPath);

for await (const message of query({
  prompt: "Hello",
  options: { pathToClaudeCodeExecutable: cliPath },
})) {
  console.log(message);
}

extractFromBunfs() 将嵌入的二进制文件从编译后的可执行文件的虚拟文件系统复制到每个用户的临时目录，并返回真实路径。在编译后的可执行文件之外，它返回输入路径不变，因此相同的代码在开发中无需修改即可运行。

每个编译后的可执行文件都嵌入了单个平台的二进制文件。将导入中的平台包与您的 --target 匹配：

• 要进行交叉编译，请安装不匹配的平台包，例如 npm install @anthropic-ai/claude-agent-sdk-linux-x64 --force。
• 在 Windows 上，二进制文件子路径是 claude.exe，例如 @anthropic-ai/claude-agent-sdk-win32-x64/claude.exe。

函数

query()

与 Claude Code 交互的主要函数。创建一个异步生成器，在消息到达时流式传输消息。

function query({
  prompt,
  options
}: {
  prompt: string | AsyncIterable<SDKUserMessage>;
  options?: Options;
}): Query;

参数

返回值

返回一个 Query 对象，该对象扩展 AsyncGenerator<SDKMessage, void>，并具有其他方法。

startup()

通过生成 CLI 子进程并在提示可用之前完成初始化握手来预热 CLI 子进程。返回的 WarmQuery 句柄稍后接受提示并将其写入已准备好的进程，因此第一个 query() 调用解析时无需支付子进程生成和初始化成本。

function startup(params?: {
  options?: Options;
  initializeTimeoutMs?: number;
}): Promise<WarmQuery>;

参数

返回值

返回一个 Promise<WarmQuery>，在子进程生成并完成其初始化握手后解析。

示例

早期调用 startup()，例如在应用程序启动时，然后在提示准备好后在返回的句柄上调用 .query()。这会将子进程生成和初始化移出关键路径。

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

// 提前支付启动成本
const warm = await startup({ options: { maxTurns: 3 } });

// 稍后，当提示准备好时，这是立即的
for await (const message of warm.query("What files are here?")) {
  console.log(message);
}

tool()

为与 SDK MCP 服务器一起使用创建类型安全的 MCP 工具定义。

function tool<Schema extends AnyZodRawShape>(
  name: string,
  description: string,
  inputSchema: Schema,
  handler: (args: InferShape<Schema>, extra: unknown) => Promise<CallToolResult>,
  extras?: { annotations?: ToolAnnotations }
): SdkMcpToolDefinition<Schema>;

参数

ToolAnnotations

从 @modelcontextprotocol/sdk/types.js 重新导出。所有字段都是可选提示；客户端不应依赖它们做出安全决策。

import { tool } from "@anthropic-ai/claude-agent-sdk";
import { z } from "zod";

const searchTool = tool(
  "search",
  "Search the web",
  { query: z.string() },
  async ({ query }) => {
    return { content: [{ type: "text", text: `Results for: ${query}` }] };
  },
  { annotations: { readOnlyHint: true, openWorldHint: true } }
);

createSdkMcpServer()

创建在与应用程序相同的进程中运行的 MCP 服务器实例。

function createSdkMcpServer(options: {
  name: string;
  version?: string;
  tools?: Array<SdkMcpToolDefinition<any>>;
}): McpSdkServerConfigWithInstance;

参数

listSessions()

发现并列出具有轻量级元数据的过去会话。按项目目录筛选或列出所有项目中的会话。

function listSessions(options?: ListSessionsOptions): Promise<SDKSessionInfo[]>;

参数

返回类型：SDKSessionInfo

示例

打印项目的 10 个最近会话。结果按 lastModified 降序排序，因此第一项是最新的。省略 dir 以搜索所有项目。

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

const sessions = await listSessions({ dir: "/path/to/project", limit: 10 });

for (const session of sessions) {
  console.log(`${session.summary} (${session.sessionId})`);
}

getSessionMessages()

从过去的会话记录中读取用户和助手消息。

function getSessionMessages(
  sessionId: string,
  options?: GetSessionMessagesOptions
): Promise<SessionMessage[]>;

参数

返回类型：SessionMessage

示例

import { listSessions, getSessionMessages } from "@anthropic-ai/claude-agent-sdk";

const [latest] = await listSessions({ dir: "/path/to/project", limit: 1 });

if (latest) {
  const messages = await getSessionMessages(latest.sessionId, {
    dir: "/path/to/project",
    limit: 20
  });

  for (const msg of messages) {
    console.log(`[${msg.type}] ${msg.uuid}`);
  }
}

getSessionInfo()

按 ID 读取单个会话的元数据，无需扫描完整项目目录。

function getSessionInfo(
  sessionId: string,
  options?: GetSessionInfoOptions
): Promise<SDKSessionInfo | undefined>;

参数

返回 SDKSessionInfo，如果找不到会话，则返回 undefined。

renameSession()

通过附加自定义标题条目来重命名会话。重复调用是安全的；最新的标题获胜。

function renameSession(
  sessionId: string,
  title: string,
  options?: SessionMutationOptions
): Promise<void>;

参数

tagSession()

标记会话。传递 null 以清除标签。重复调用是安全的；最新的标签获胜。

function tagSession(
  sessionId: string,
  tag: string | null,
  options?: SessionMutationOptions
): Promise<void>;

参数

resolveSettings()

使用与 CLI 相同的合并引擎为给定目录解析有效的 Claude Code 设置，无需生成 Claude CLI。在调用 query() 之前使用它来检查 query() 调用将看到的配置。

function resolveSettings(
  options?: ResolveSettingsOptions
): Promise<ResolvedSettings>;

参数

resolveSettings() 接受单个选项对象。所有字段都是可选的。

返回类型：ResolvedSettings

resolveSettings() 返回一个对象，描述合并的设置和为每个密钥提供的源。

示例

下面的示例为项目目录解析设置，并打印控制清理周期的源。

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

const { effective, provenance } = await resolveSettings({
  cwd: "/path/to/project",
  settingSources: ["user", "project", "local"],
});

console.log(`Cleanup period: ${effective.cleanupPeriodDays} days`);
console.log(`Set by: ${provenance.cleanupPeriodDays?.source}`);

类型

Options

query() 函数的配置对象。

处理缓慢或停滞的 API 响应

CLI 子进程读取多个环境变量，这些变量控制 API 超时和停滞检测。通过 env 选项传递它们：

const result = query({
  prompt: "Analyze this code",
  options: {
    env: {
      ...process.env,
      API_TIMEOUT_MS: "120000",
      CLAUDE_CODE_MAX_RETRIES: "2",
      CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS: "120000",
    },
  },
});

• API_TIMEOUT_MS：Anthropic 客户端上的每个请求超时，以毫秒为单位。默认 600000。适用于主循环和所有子代理。
• 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 并移除此变量的上限。
• CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS：使用 run_in_background 启动的子代理的停滞监视程序。默认 600000。在每个流事件上重置；在停滞时中止子代理，将任务标记为失败，并将错误与任何部分结果一起呈现给父级。不适用于同步子代理。
• CLAUDE_ENABLE_STREAM_WATCHDOG 与 CLAUDE_STREAM_IDLE_TIMEOUT_MS：当标头已到达但响应正文停止流式传输时中止请求。监视程序对所有提供商默认启用；设置 CLAUDE_ENABLE_STREAM_WATCHDOG=0 以禁用它。CLAUDE_STREAM_IDLE_TIMEOUT_MS 默认为 300000 并被限制为该最小值。中止的请求通过正常重试路径进行。

Query 对象

由 query() 函数返回的接口。

interface Query extends AsyncGenerator<SDKMessage, void> {
  interrupt(): Promise<SDKControlInterruptResponse | undefined>;
  rewindFiles(
    userMessageId: string,
    options?: { dryRun?: boolean }
  ): Promise<RewindFilesResult>;
  setPermissionMode(mode: PermissionMode): Promise<void>;
  setModel(model?: string): Promise<void>;
  setMaxThinkingTokens(maxThinkingTokens: number | null): Promise<void>;
  applyFlagSettings(settings: { [K in keyof Settings]?: Settings[K] | null }): Promise<void>;
  initializationResult(): Promise<SDKControlInitializeResponse>;
  reinitialize(): Promise<SDKControlInitializeResponse>;
  supportedCommands(): Promise<SlashCommand[]>;
  supportedModels(): Promise<ModelInfo[]>;
  supportedAgents(): Promise<AgentInfo[]>;
  mcpServerStatus(): Promise<McpServerStatus[]>;
  accountInfo(): Promise<AccountInfo>;
  reconnectMcpServer(serverName: string): Promise<void>;
  toggleMcpServer(serverName: string, enabled: boolean): Promise<void>;
  setMcpServers(servers: Record<string, McpServerConfig>): Promise<McpSetServersResult>;
  streamInput(stream: AsyncIterable<SDKUserMessage>): Promise<void>;
  stopTask(taskId: string): Promise<void>;
  close(): void;
}

方法

applyFlagSettings()

在运行的会话上更改任何设置而无需重新启动查询。当没有专用设置器的设置需要在会话中期更改时使用它，例如在代理读取不受信任的输入后收紧 permissions。setModel() 和 setPermissionMode() 是这两个键的专用设置器；applyFlagSettings() 是接受任何设置键子集的通用形式，在此处传递 model 的行为与 setModel() 相同。

仅某些键在会话中期生效：

• 在下一个轮次应用：model、effortLevel、ultracode、permissions、hooks、skillOverrides、fastMode、agent。切换 agent 也会在下一个轮次应用该代理的模型覆盖、hooks 和系统提示。
• 会话中期无效：系统提示选项。这些在启动时解决一次，因此运行的会话保持原始值，即使调用成功。要更改它们，请启动新会话。

effortLevel 接受一个努力级别名称。它也接受 "ultracode"，它以 xhigh 努力运行会话并打开ultracode。Settings 类型声明 effortLevel 不包含该值，因此在 TypeScript 中传递等效的 { ultracode: true }。ultracode 值需要 Claude Code v2.1.203 或更高版本，仅由 applyFlagSettings() 接受，不由设置文件中的 effortLevel 键接受。

这些值被写入标志设置层，这是内联 query() 的 settings 选项在启动时填充的同一层。标志设置位于设置优先级顺序的顶部附近：它们覆盖用户、项目和本地设置，只有托管策略设置可以覆盖它们。这与优先级部分称为编程选项的层相同。

连续调用浅合并顶级键。第二次调用 { permissions: {...} } 会替换先前调用中的整个 permissions 对象，而不是深度合并到其中。要从标志层清除键并回退到较低优先级源，请为该键传递 null。传递 undefined 无效，因为 JSON 序列化会将其删除。

仅在流式输入模式下可用，与 setModel() 和 setPermissionMode() 的约束相同。

下面的示例在会话中期切换活动模型，然后清除覆盖，以便模型回退到用户或项目设置指定的任何内容。

const q = query({ prompt: messageStream });

// 覆盖会话其余部分的模型
await q.applyFlagSettings({ model: "claude-opus-4-6" });

// 稍后：清除覆盖并回退到较低优先级设置
await q.applyFlagSettings({ model: null });

WarmQuery

由 startup() 返回的句柄。子进程已生成并初始化，因此在此句柄上调用 query() 会直接将提示写入准备好的进程，无需启动延迟。

interface WarmQuery extends AsyncDisposable {
  query(prompt: string | AsyncIterable<SDKUserMessage>): Query;
  close(): void;
}

方法

WarmQuery 实现 AsyncDisposable，因此可以与 await using 一起使用以进行自动清理。

SDKControlInitializeResponse

initializationResult() 的返回类型。包含会话初始化数据。

type SDKControlInitializeResponse = {
  commands: SlashCommand[];
  agents: AgentInfo[];
  output_style: string;
  available_output_styles: string[];
  models: ModelInfo[];
  account: AccountInfo;
  fast_mode_state?: "off" | "cooldown" | "on";
};

当客户端向已运行的会话发送 initialize 时，控制响应包装器也会携带一个可选的 pending_permission_requests 数组。该字段位于响应包装器本身，而不是上面的 SDKControlInitializeResponse 有效负载中。每个条目都是一个完整的 control_request 消息，具有与会话在运行时为权限请求流式传输的相同 { type: "control_request", request_id, request } 形状。

这些是在客户端连接之前发出的请求，仍在等待回复。SDK 为您读取数组并将每个条目分派到您的 canUseTool 回调，这与 reinitialize() 在传输间隙后触发的相同重新发送。使用重复的请求 ID 幂等地处理，因为条目可以重复回调已在连接断开前收到的请求。

SDKControlInterruptResponse

中断收据：interrupt() 在通告 SDKSystemMessage.capabilities 中的 interrupt_receipt_v1 功能的 CLI 上解决的值。需要 Claude Code v2.1.205 或更高版本。较早的 CLI 使用空成功有效负载回答中断，因此 interrupt() 解决为 undefined。

type SDKControlInterruptResponse = {
  still_queued: string[];
};

still_queued 列出存活中断的用户消息的 UUID：仍在队列中的消息，加上已为下一个轮次出队但尚未被中止到达的任何批次。除非您首先取消它，否则每个都作为其自己的轮次在中断后运行。使用收据来决定是否重新发送任何内容；重新发送已列出的消息会产生重复的轮次。

使用这些注意事项解释列表：

• 仅出现已使用 UUID 入队的消息。空数组并不意味着没有其他内容会运行。
• 仅列出主线程消息。寻址到子代理的消息超出范围。
• 列表可以包括您的客户端从未发送的 UUID，例如计划任务触发器。忽略您不识别的 UUID，而不是将其视为错误。

收据是在处理中断时拍摄的快照，在干净中断时，它在中断轮次的 SDKResultMessage 之前到达。在该结果之后读取收据而不是检查队列：循环立即启动下一个排队的轮次，因此您在结果后检查的队列已经改变。

AgentDefinition

以编程方式定义的子代理的配置。

type AgentDefinition = {
  description: string;
  tools?: string[];
  disallowedTools?: string[];
  prompt: string;
  model?: string;
  mcpServers?: AgentMcpServerSpec[];
  skills?: string[];
  initialPrompt?: string;
  maxTurns?: number;
  background?: boolean;
  memory?: "user" | "project" | "local";
  effort?: "low" | "medium" | "high" | "xhigh" | "max" | number;
  permissionMode?: PermissionMode;
  criticalSystemReminder_EXPERIMENTAL?: string;
};

AgentMcpServerSpec

指定子代理可用的 MCP 服务器。可以是服务器名称（字符串，引用父级 mcpServers 配置中的服务器）或内联服务器配置记录，将服务器名称映射到配置。

type AgentMcpServerSpec = string | Record<string, McpServerConfigForProcessTransport>;

其中 McpServerConfigForProcessTransport 是 McpStdioServerConfig | McpSSEServerConfig | McpHttpServerConfig | McpSdkServerConfig。

SettingSource

控制 SDK 从哪些基于文件系统的配置源加载设置。

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

默认行为

当 settingSources 被省略或 undefined 时，query() 加载与 Claude Code CLI 相同的文件系统设置：用户、项目和本地。在所有情况下都会加载端点管理的策略；当会话使用组织凭证在符合条件的配置上进行身份验证时，会获取服务器管理的设置。请参阅settingSources 不控制的内容了解无论此选项如何都会读取的输入，以及如何禁用它们。

为什么使用 settingSources

禁用文件系统设置：

// 不从磁盘加载用户、项目或本地设置
const result = query({
  prompt: "Analyze this code",
  options: { settingSources: [] }
});

显式加载所有文件系统设置：

const result = query({
  prompt: "Analyze this code",
  options: {
    settingSources: ["user", "project", "local"] // 加载所有设置
  }
});

仅加载特定设置源：

// 仅加载项目设置，忽略用户和本地
const result = query({
  prompt: "Run CI checks",
  options: {
    settingSources: ["project"] // 仅 .claude/settings.json
  }
});

测试和 CI 环境：

// 通过排除本地设置确保 CI 中的一致行为
const result = query({
  prompt: "Run tests",
  options: {
    settingSources: ["project"], // 仅团队共享设置
    permissionMode: "bypassPermissions"
  }
});

仅 SDK 应用程序：

// 以编程方式定义所有内容。
// 传递 [] 以选择退出文件系统设置源。
const result = query({
  prompt: "Review this PR",
  options: {
    settingSources: [],
    agents: {
      /* ... */
    },
    mcpServers: {
      /* ... */
    },
    allowedTools: ["Read", "Grep", "Glob"]
  }
});

加载 CLAUDE.md 项目说明：

// 加载项目设置以包括 CLAUDE.md 文件
const result = query({
  prompt: "Add a new feature following project conventions",
  options: {
    systemPrompt: {
      type: "preset",
      preset: "claude_code" // 使用 Claude Code 的系统提示
    },
    settingSources: ["project"], // 从项目目录加载 CLAUDE.md
    allowedTools: ["Read", "Write", "Edit"]
  }
});

设置优先级

加载多个源时，设置按此优先级合并（从高到低）：

1. 本地设置（.claude/settings.local.json）
2. 项目设置（.claude/settings.json）
3. 用户设置（~/.claude/settings.json）

编程选项（如 agents、allowedTools 和 settings）覆盖用户、项目和本地文件系统设置。托管策略设置优先于编程选项。

PermissionMode

type PermissionMode =
  | "default" // 标准权限行为
  | "acceptEdits" // 自动接受文件编辑
  | "bypassPermissions" // 绕过权限检查；显式询问规则仍然提示
  | "plan" // Plan Mode - 仅读取工具
  | "dontAsk" // 不提示权限，如果未预先批准则拒绝
  | "auto"; // 使用模型分类器批准或拒绝每个工具调用

CanUseTool

用于控制工具使用的自定义权限函数类型。

该函数是 SDK 替代交互式权限提示：仅当权限评估流解决为提示时才调用它。已由 allowedTools 条目、设置 allow 规则或权限模式（如 acceptEdits 或 bypassPermissions）批准的工具调用永远不会调用它。要限制每个工具调用，请改用 PreToolUse hook。

AskUserQuestion、标记为 requiresUserInteraction 的 MCP 工具和您的组织设置为 ask 的 connector 工具即使 allow 规则匹配也会到达该函数。在 dontAsk 模式下这些调用会被拒绝，不调用它。

type CanUseTool = (
  toolName: string,
  input: Record<string, unknown>,
  options: {
    signal: AbortSignal;
    suggestions?: PermissionUpdate[];
    blockedPath?: string;
    decisionReason?: string;
    toolUseID: string;
    agentID?: string;
    requestId: string;
  }
) => Promise<PermissionResult | null>;

回调通常通过返回 PermissionResult 来解决请求，SDK 将其写回其传输作为 control_response。仅当您的应用程序已通过其自己的通道为此请求发送 control_response（回显 requestId）时才返回 null；SDK 然后跳过将响应写入其传输。在任何其他情况下返回 null 会使工具调用无限期被阻止，因为永远不会发送 control_response 且权限提示不会超时。

requestId 选项和 null 返回值需要 Claude Code v2.1.199 或更高版本。

PermissionResult

权限检查的结果。

type PermissionResult =
  | {
      behavior: "allow";
      updatedInput?: Record<string, unknown>;
      updatedPermissions?: PermissionUpdate[];
      toolUseID?: string;
    }
  | {
      behavior: "deny";
      message: string;
      interrupt?: boolean;
      toolUseID?: string;
    };

ToolConfig

内置工具行为的配置。

type ToolConfig = {
  askUserQuestion?: {
    previewFormat?: "markdown" | "html";
  };
};

McpServerConfig

MCP 服务器的配置。

type McpServerConfig =
  | McpStdioServerConfig
  | McpSSEServerConfig
  | McpHttpServerConfig
  | McpSdkServerConfigWithInstance;

McpStdioServerConfig

type McpStdioServerConfig = {
  type?: "stdio";
  command: string;
  args?: string[];
  env?: Record<string, string>;
};

McpSSEServerConfig

type McpSSEServerConfig = {
  type: "sse";
  url: string;
  headers?: Record<string, string>;
};

McpHttpServerConfig

type McpHttpServerConfig = {
  type: "http";
  url: string;
  headers?: Record<string, string>;
};

McpSdkServerConfigWithInstance

type McpSdkServerConfigWithInstance = {
  type: "sdk";
  name: string;
  instance: McpServer;
};

McpClaudeAIProxyServerConfig

type McpClaudeAIProxyServerConfig = {
  type: "claudeai-proxy";
  url: string;
  id: string;
};

SdkPluginConfig

SDK 中加载 plugins 的配置。

type SdkPluginConfig = {
  type: "local";
  path: string;
  skipMcpDiscovery?: boolean;
};

示例：

plugins: [
  { type: "local", path: "./my-plugin" },
  { type: "local", path: "/absolute/path/to/plugin" }
];

有关创建和使用 plugins 的完整信息，请参阅Plugins。

消息类型

SDKMessage

查询返回的所有可能消息的联合类型。

type SDKMessage =
  | SDKAssistantMessage
  | SDKUserMessage
  | SDKUserMessageReplay
  | SDKResultMessage
  | SDKSystemMessage
  | SDKPartialAssistantMessage
  | SDKCompactBoundaryMessage
  | SDKStatusMessage
  | SDKLocalCommandOutputMessage
  | SDKHookStartedMessage
  | SDKHookProgressMessage
  | SDKHookResponseMessage
  | SDKPluginInstallMessage
  | SDKToolProgressMessage
  | SDKAuthStatusMessage
  | SDKTaskNotificationMessage
  | SDKTaskStartedMessage
  | SDKTaskProgressMessage
  | SDKTaskUpdatedMessage
  | SDKBackgroundTasksChangedMessage
  | SDKThinkingTokensMessage
  | SDKSessionStateChangedMessage
  | SDKWorkerShuttingDownMessage
  | SDKCommandsChangedMessage
  | SDKNotificationMessage
  | SDKFilesPersistedEvent
  | SDKToolUseSummaryMessage
  | SDKMemoryRecallMessage
  | SDKRateLimitEvent
  | SDKElicitationCompleteMessage
  | SDKPermissionDeniedMessage
  | SDKPromptSuggestionMessage
  | SDKAPIRetryMessage
  | SDKMirrorErrorMessage
  | SDKInformationalMessage
  | SDKConversationResetMessage;

SDKAssistantMessage

助手响应消息。

type SDKAssistantMessage = {
  type: "assistant";
  uuid: UUID;
  session_id: string;
  message: BetaMessage; // 来自 Anthropic SDK
  parent_tool_use_id: string | null;
  error?: SDKAssistantMessageError;
};

message 字段是来自 Anthropic SDK 的 BetaMessage。它包括 id、content、model、stop_reason 和 usage 等字段。

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 错误。

SDKUserMessage

用户输入消息。

type SDKUserMessage = {
  type: "user";
  uuid?: UUID;
  session_id?: string;
  message: MessageParam; // 来自 Anthropic SDK
  parent_tool_use_id: string | null;
  isSynthetic?: boolean;
  shouldQuery?: boolean;
  tool_use_result?: unknown;
  origin?: SDKMessageOrigin;
};

将 shouldQuery 设置为 false 以将消息附加到记录中而不触发助手轮次。消息被保留并合并到下一个触发轮次的用户消息中。使用此方法注入上下文，例如您在带外运行的命令的输出，而无需在其上花费模型调用。

在携带 tool_result 块的消息上，tool_use_result 是工具的结构化输出对象，而不是发送给模型的文本。其形状取决于匹配的 tool_use 块命名的工具，因此该字段被类型化为 unknown；内置形状列在工具输出类型下。

对于 Agent 工具，tool_use_result 是 AgentOutput。在 completed 结果上，content 保存子代理的报告，不包含 Claude Code 附加到 tool_result 文本的代理 ID 和使用情况预告片，因此从 tool_use_result 呈现而不是解析该文本。

SDKUserMessageReplay

具有必需 UUID 的重放用户消息。

type SDKUserMessageReplay = {
  type: "user";
  uuid: UUID;
  session_id: string;
  message: MessageParam;
  parent_tool_use_id: string | null;
  isSynthetic?: boolean;
  tool_use_result?: unknown;
  origin?: SDKMessageOrigin;
  isReplay: true;
};

从会话外部注入的用户轮次，其 origin 类型为 peer 或 channel，无论是在活跃轮次期间交付还是在会话空闲时启动新轮次，都会作为重放到达流。在 v2.1.207 之前，在会话空闲时交付的注入轮次在流上不产生任何消息，仅在您重新读取记录时出现。

SDKResultMessage

最终结果消息。

type SDKResultMessage =
  | {
      type: "result";
      subtype: "success";
      uuid: UUID;
      session_id: string;
      duration_ms: number;
      duration_api_ms: number;
      is_error: boolean;
      api_error_status?: number | null;
      num_turns: number;
      result: string;
      stop_reason: string | null;
      ttft_ms?: number;
      ttft_stream_ms?: number;
      total_cost_usd: number;
      usage: NonNullableUsage;
      modelUsage: { [modelName: string]: ModelUsage };
      permission_denials: SDKPermissionDenial[];
      structured_output?: unknown;
      deferred_tool_use?: { id: string; name: string; input: Record<string, unknown> };
      terminal_reason?: TerminalReason;
      fast_mode_state?: FastModeState;
      origin?: SDKMessageOrigin;
    }
  | {
      type: "result";
      subtype:
        | "error_max_turns"
        | "error_during_execution"
        | "error_max_budget_usd"
        | "error_max_structured_output_retries";
      uuid: UUID;
      session_id: string;
      duration_ms: number;
      duration_api_ms: number;
      is_error: boolean;
      num_turns: number;
      stop_reason: string | null;
      total_cost_usd: number;
      usage: NonNullableUsage;
      modelUsage: { [modelName: string]: ModelUsage };
      permission_denials: SDKPermissionDenial[];
      errors: string[];
      terminal_reason?: TerminalReason;
      fast_mode_state?: FastModeState;
      origin?: SDKMessageOrigin;
    };

结果上的多个字段除了 subtype 之外还提供诊断详情：

• api_error_status：终止对话的 API 错误的 HTTP 状态码。当轮次在没有 API 错误的情况下结束时，该字段不存在或为 null。
• ttft_ms：首个令牌的时间（毫秒），在第一个完整的助手消息到达时测量。仅在成功分支上显示。
• ttft_stream_ms：直到第一个 message_start 流事件的时间（毫秒），当响应流打开时。低于 ttft_ms；两者之间的差距是流式传输第一条消息所花费的时间。仅在成功分支上显示。
• 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" 之一。
• fast_mode_state：为 "on"、"off" 或 "cooldown" 之一。

origin 字段转发触发此结果的用户消息的 SDKMessageOrigin。当后台任务完成且 SDK 注入合成后续轮次时，生成的 SDKResultMessage 携带 origin: { kind: "task-notification" }。检查此字段以区分回答您的提示的结果与为后台任务后续操作发出的结果，以便您可以路由或抑制后者。对于在任何用户轮次之前发出的结果（例如启动错误），该字段不存在。

当 PreToolUse hook 返回 permissionDecision: "defer" 时，结果具有 stop_reason: "tool_deferred" 和 deferred_tool_use 携带待处理工具的 id、name 和 input。读取此字段以在您自己的 UI 中显示请求，然后使用相同的 session_id 恢复以继续。有关完整的往返过程，请参阅稍后延迟工具调用。

SDKSystemMessage

系统初始化消息。

type SDKSystemMessage = {
  type: "system";
  subtype: "init";
  uuid: UUID;
  session_id: string;
  agents?: string[];
  apiKeySource: ApiKeySource;
  betas?: string[];
  claude_code_version: string;
  cwd: string;
  tools: string[];
  mcp_servers: {
    name: string;
    status: string;
  }[];
  model: string;
  permissionMode: PermissionMode;
  slash_commands: string[];
  output_style: string;
  skills: string[];
  plugins: { name: string; path: string }[];
  capabilities?: string[];
};

capabilities 数组命名此 CLI 实现的协议行为，因此您可以进行功能检测而不是比较 claude_code_version 字符串。这是一个开放集合：忽略您不认识的值，并检查您依赖其行为的特定功能。该字段需要 Claude Code v2.1.205 或更高版本，在较早的 CLI 上不存在。

SDKPartialAssistantMessage

流式部分消息（仅当 includePartialMessages 为 true 时）。parent_tool_use_id 字段始终为 null：流事件仅针对主会话发出。对于子代理归属，使用携带 parent_tool_use_id 的完整消息，或启用 forwardSubagentText 以接收子代理文本和思考作为完整消息。

type SDKPartialAssistantMessage = {
  type: "stream_event";
  event: BetaRawMessageStreamEvent; // 来自 Anthropic SDK
  parent_tool_use_id: string | null;
  uuid: UUID;
  session_id: string;
  ttft_ms?: number; // 首个令牌的时间（毫秒），仅在 message_start 事件上显示
};

SDKCompactBoundaryMessage

指示对话压缩边界的消息。

type SDKCompactBoundaryMessage = {
  type: "system";
  subtype: "compact_boundary";
  uuid: UUID;
  session_id: string;
  compact_metadata: {
    trigger: "manual" | "auto";
    pre_tokens: number;
  };
};

SDKInformationalMessage

由循环发出的通用文本横幅。携带非错误状态行、hook 反馈（例如 UserPromptSubmit hook 的阻止原因）和命令输出。将 content 呈现为给定 level 的纯文本。

type SDKInformationalMessage = {
  type: "system";
  subtype: "informational";
  content: string;
  level: "info" | "notice" | "suggestion" | "warning";
  tool_use_id?: string;
  prevent_continuation?: boolean;
  uuid: UUID;
  session_id: string;
};

SDKWorkerShuttingDownMessage

在优雅的 worker 拆卸时发出，以便远程客户端可以显示 worker 消失的原因，而不是等待心跳超时。reason 是由主机 CLI 设置的短 snake_case 字符串，例如 "host_exit" 或 "remote_control_disabled"。仅在实时流式传输时对此采取行动。恢复的会话会重放此消息的过去实例，因此在这种情况下忽略它们。

type SDKWorkerShuttingDownMessage = {
  type: "system";
  subtype: "worker_shutting_down";
  reason: string;
  uuid: UUID;
  session_id: string;
};

SDKPluginInstallMessage

插件安装进度事件。当设置 CLAUDE_CODE_SYNC_PLUGIN_INSTALL 时发出，以便您的 Agent SDK 应用程序可以在第一个轮次之前跟踪市场插件安装。started 和 completed 状态括起整体安装。installed 和 failed 状态报告单个市场并包括 name。

type SDKPluginInstallMessage = {
  type: "system";
  subtype: "plugin_install";
  status: "started" | "installed" | "failed" | "completed";
  name?: string;
  error?: string;
  uuid: UUID;
  session_id: string;
};

SDKPermissionDeniedMessage

当权限系统自动拒绝工具调用而不显示交互式提示时发出的流事件。使用它在发生时在您的 UI 中呈现拒绝，而不仅仅观察随后的 is_error 工具结果。交互式询问路径通过 canUseTool 回调单独到达您的应用程序。由 PreToolUse hook 发出的拒绝不会通过此事件报告。

此事件需要 Claude Code v2.1.136 或更高版本。

type SDKPermissionDeniedMessage = {
  type: "system";
  subtype: "permission_denied";
  tool_name: string;
  tool_use_id: string;
  agent_id?: string;
  decision_reason_type?: string;
  decision_reason?: string;
  message: string;
  uuid: UUID;
  session_id: string;
};

SDKPermissionDenial

有关被拒绝的工具使用的信息。

type SDKPermissionDenial = {
  tool_name: string;
  tool_use_id: string;
  tool_input: Record<string, unknown>;
};

SDKMessageOrigin

用户角色消息的来源。这在 SDKUserMessage 上显示为 origin，并转发到相应的 SDKResultMessage，以便您可以判断给定轮次的触发因素。

type SDKMessageOrigin =
  | { kind: "human" }
  | { kind: "channel"; server: string }
  | {
      kind: "peer";
      from: string;
      name?: string;
      senderTaskId?: string;
      body?: string;
    }
  | { kind: "task-notification" }
  | { kind: "coordinator" }
  | { kind: "auto-continuation" };

Hook 类型

有关使用 hooks 的综合指南，包括示例和常见模式，请参阅 Hooks 指南。

HookEvent

可用的 hook 事件。

type HookEvent =
  | "PreToolUse"
  | "PostToolUse"
  | "PostToolUseFailure"
  | "PostToolBatch"
  | "Notification"
  | "UserPromptSubmit"
  | "SessionStart"
  | "SessionEnd"
  | "Stop"
  | "SubagentStart"
  | "SubagentStop"
  | "PreCompact"
  | "PermissionRequest"
  | "Setup"
  | "TeammateIdle"
  | "TaskCompleted"
  | "ConfigChange"
  | "WorktreeCreate"
  | "WorktreeRemove"
  | "MessageDisplay";

HookCallback

Hook 回调函数类型。

type HookCallback = (
  input: HookInput, // 所有 hook 输入类型的联合
  toolUseID: string | undefined,
  options: { signal: AbortSignal }
) => Promise<HookJSONOutput>;

HookCallbackMatcher

带有可选匹配器的 Hook 配置。

interface HookCallbackMatcher {
  matcher?: string;
  hooks: HookCallback[];
  timeout?: number; // 此匹配器中所有 hooks 的超时时间（秒）
}

HookInput

所有 hook 输入类型的联合类型。

type HookInput =
  | PreToolUseHookInput
  | PostToolUseHookInput
  | PostToolUseFailureHookInput
  | PostToolBatchHookInput
  | NotificationHookInput
  | UserPromptSubmitHookInput
  | SessionStartHookInput
  | SessionEndHookInput
  | StopHookInput
  | SubagentStartHookInput
  | SubagentStopHookInput
  | PreCompactHookInput
  | PermissionRequestHookInput
  | SetupHookInput
  | TeammateIdleHookInput
  | TaskCompletedHookInput
  | ConfigChangeHookInput
  | WorktreeCreateHookInput
  | WorktreeRemoveHookInput
  | MessageDisplayHookInput;

BaseHookInput

所有 hook 输入类型扩展的基本接口。

type BaseHookInput = {
  session_id: string;
  transcript_path: string;
  cwd: string;
  prompt_id?: string;
  permission_mode?: string;
  effort?: { level: string };
  agent_id?: string;
  agent_type?: string;
};

prompt_id 字段是一个 UUID，用于标识当前正在处理的用户提示。它与 OpenTelemetry 事件上的 prompt.id 属性匹配，在第一个用户输入之前不存在。需要 Claude Code v2.1.196 或更高版本。

PreToolUseHookInput

type PreToolUseHookInput = BaseHookInput & {
  hook_event_name: "PreToolUse";
  tool_name: string;
  tool_input: unknown;
  tool_use_id: string;
};

PostToolUseHookInput

type PostToolUseHookInput = BaseHookInput & {
  hook_event_name: "PostToolUse";
  tool_name: string;
  tool_input: unknown;
  tool_response: unknown;
  tool_use_id: string;
  duration_ms?: number;
};

PostToolUseFailureHookInput

type PostToolUseFailureHookInput = BaseHookInput & {
  hook_event_name: "PostToolUseFailure";
  tool_name: string;
  tool_input: unknown;
  tool_use_id: string;
  error: string;
  is_interrupt?: boolean;
  duration_ms?: number;
};

PostToolBatchHookInput

在批处理中的每个工具调用都已解决后触发一次，在下一个模型请求之前。tool_response 携带序列化的 tool_result 内容，模型会看到该内容；其形状与 PostToolUseHookInput 的结构化 Output 对象不同。

type PostToolBatchHookInput = BaseHookInput & {
  hook_event_name: "PostToolBatch";
  tool_calls: PostToolBatchToolCall[];
};

type PostToolBatchToolCall = {
  tool_name: string;
  tool_input: unknown;
  tool_use_id: string;
  tool_response?: unknown;
};

NotificationHookInput

type NotificationHookInput = BaseHookInput & {
  hook_event_name: "Notification";
  message: string;
  title?: string;
  notification_type: string;
};

UserPromptSubmitHookInput

type UserPromptSubmitHookInput = BaseHookInput & {
  hook_event_name: "UserPromptSubmit";
  prompt: string;
};

SessionStartHookInput

type SessionStartHookInput = BaseHookInput & {
  hook_event_name: "SessionStart";
  source: "startup" | "resume" | "clear" | "compact";
  agent_type?: string;
  model?: string;
};

SessionEndHookInput

type SessionEndHookInput = BaseHookInput & {
  hook_event_name: "SessionEnd";
  reason: ExitReason; // EXIT_REASONS 数组中的字符串
};

StopHookInput

type StopHookInput = BaseHookInput & {
  hook_event_name: "Stop";
  stop_hook_active: boolean;
  last_assistant_message?: string;
  background_tasks?: BackgroundTaskSummary[];
  session_crons?: SessionCronSummary[];
};

SubagentStartHookInput

type SubagentStartHookInput = BaseHookInput & {
  hook_event_name: "SubagentStart";
  agent_id: string;
  agent_type: string;
};

SubagentStopHookInput

type SubagentStopHookInput = BaseHookInput & {
  hook_event_name: "SubagentStop";
  stop_hook_active: boolean;
  agent_id: string;
  agent_transcript_path: string;
  agent_type: string;
  last_assistant_message?: string;
  background_tasks?: BackgroundTaskSummary[];
  session_crons?: SessionCronSummary[];
};

type BackgroundTaskSummary = {
  id: string;
  type: string;
  status: string;
  description: string;
  command?: string;
  agent_type?: string;
  server?: string;
  tool?: string;
  name?: string;
};

type SessionCronSummary = {
  id: string;
  schedule: string;
  recurring: boolean;
  prompt: string;
};

PreCompactHookInput

type PreCompactHookInput = BaseHookInput & {
  hook_event_name: "PreCompact";
  trigger: "manual" | "auto";
  custom_instructions: string | null;
};

PermissionRequestHookInput

type PermissionRequestHookInput = BaseHookInput & {
  hook_event_name: "PermissionRequest";
  tool_name: string;
  tool_input: unknown;
  permission_suggestions?: PermissionUpdate[];
};

SetupHookInput

type SetupHookInput = BaseHookInput & {
  hook_event_name: "Setup";
  trigger: "init" | "maintenance";
};

TeammateIdleHookInput

type TeammateIdleHookInput = BaseHookInput & {
  hook_event_name: "TeammateIdle";
  teammate_name: string;
  /** @deprecated 自 v2.1.178 起已弃用。携带会话派生的团队名称；将被移除。 */
  team_name: string;
};

TaskCompletedHookInput

type TaskCompletedHookInput = BaseHookInput & {
  hook_event_name: "TaskCompleted";
  task_id: string;
  task_subject: string;
  task_description?: string;
  teammate_name?: string;
  /** @deprecated 自 v2.1.178 起已弃用。携带会话派生的团队名称；将被移除。 */
  team_name?: string;
};

ConfigChangeHookInput

type ConfigChangeHookInput = BaseHookInput & {
  hook_event_name: "ConfigChange";
  source:
    | "user_settings"
    | "project_settings"
    | "local_settings"
    | "policy_settings"
    | "skills";
  file_path?: string;
};

WorktreeCreateHookInput

type WorktreeCreateHookInput = BaseHookInput & {
  hook_event_name: "WorktreeCreate";
  name: string;
};

WorktreeRemoveHookInput

type WorktreeRemoveHookInput = BaseHookInput & {
  hook_event_name: "WorktreeRemove";
  worktree_path: string;
};

MessageDisplayHookInput

type MessageDisplayHookInput = BaseHookInput & {
  hook_event_name: "MessageDisplay";
  turn_id: string;
  message_id: string;
  index: number;
  final: boolean;
  delta: string;
};

HookJSONOutput

Hook 返回值。

type HookJSONOutput = AsyncHookJSONOutput | SyncHookJSONOutput;

AsyncHookJSONOutput

type AsyncHookJSONOutput = {
  async: true;
  asyncTimeout?: number;
};

SyncHookJSONOutput

type SyncHookJSONOutput = {
  continue?: boolean;
  suppressOutput?: boolean;
  stopReason?: string;
  decision?: "approve" | "block";
  systemMessage?: string;
  reason?: string;
  hookSpecificOutput?:
    | {
        hookEventName: "PreToolUse";
        permissionDecision?: "allow" | "deny" | "ask" | "defer";
        permissionDecisionReason?: string;
        updatedInput?: Record<string, unknown>;
        additionalContext?: string;
      }
    | {
        hookEventName: "UserPromptSubmit";
        additionalContext?: string;
      }
    | {
        hookEventName: "SessionStart";
        additionalContext?: string;
      }
    | {
        hookEventName: "Setup";
        additionalContext?: string;
      }
    | {
        hookEventName: "SubagentStart";
        additionalContext?: string;
      }
    | {
        hookEventName: "PostToolUse";
        additionalContext?: string;
        updatedToolOutput?: unknown;
        /** @deprecated 使用 `updatedToolOutput`，它适用于所有工具。 */
        updatedMCPToolOutput?: unknown;
      }
    | {
        hookEventName: "PostToolUseFailure";
        additionalContext?: string;
      }
    | {
        hookEventName: "PostToolBatch";
        additionalContext?: string;
      }
    | {
        hookEventName: "Notification";
        additionalContext?: string;
      }
    | {
        hookEventName: "PermissionRequest";
        decision:
          | {
              behavior: "allow";
              updatedInput?: Record<string, unknown>;
              updatedPermissions?: PermissionUpdate[];
            }
          | {
              behavior: "deny";
              message?: string;
              interrupt?: boolean;
            };
      };
};

工具输入类型

所有内置 Claude Code 工具的输入架构文档。这些类型从 @anthropic-ai/claude-agent-sdk 导出，可用于类型安全的工具交互。

ToolInputSchemas

所有工具输入类型的联合，从 @anthropic-ai/claude-agent-sdk 导出。

type ToolInputSchemas =
  | AgentInput
  | AskUserQuestionInput
  | BashInput
  | TaskOutputInput
  | EnterWorktreeInput
  | ExitPlanModeInput
  | FileEditInput
  | FileReadInput
  | FileWriteInput
  | GlobInput
  | GrepInput
  | ListMcpResourcesInput
  | McpInput
  | MonitorInput
  | NotebookEditInput
  | ReadMcpResourceInput
  | SubscribeMcpResourceInput
  | SubscribePollingInput
  | TaskCreateInput
  | TaskGetInput
  | TaskListInput
  | TaskStopInput
  | TaskUpdateInput
  | TodoWriteInput
  | UnsubscribeMcpResourceInput
  | UnsubscribePollingInput
  | WebFetchInput
  | WebSearchInput
  | WorkflowInput;

Agent

工具名称： Agent（之前为 Task，仍然接受作为别名）

type AgentInput = {
  description: string;
  prompt: string;
  subagent_type?: string;
  model?: "sonnet" | "opus" | "haiku" | "fable";
  run_in_background?: boolean;
  name?: string;
  mode?: "acceptEdits" | "auto" | "bypassPermissions" | "default" | "dontAsk" | "plan";
  isolation?: "worktree";
};

启动新代理以自主处理复杂的多步骤任务。

AskUserQuestion

工具名称： AskUserQuestion

type AskUserQuestionInput = {
  questions: Array<{
    question: string;
    header: string;
    options: Array<{ label: string; description: string; preview?: string }>;
    multiSelect: boolean;
  }>;
};

在执行期间向用户提出澄清问题。请参阅处理批准和用户输入了解使用详情。

Bash

工具名称： Bash

type BashInput = {
  command: string;
  timeout?: number; // 毫秒，最大 600000；更高的值会被限制为最大值
  description?: string;
  run_in_background?: boolean;
  dangerouslyDisableSandbox?: boolean;
};

在持久 shell 会话中执行 bash 命令，支持可选超时和后台执行。

Monitor

工具名称： Monitor

type MonitorInput = {
  command?: string;
  ws?: {
    url: string;
    protocols?: string[];
  };
  description: string;
  timeout_ms?: number;
  persistent?: boolean;
};

运行后台源并将每个事件传递给 Claude，以便它可以做出反应而无需轮询：command 运行脚本并为每个 stdout 行发出一个事件，ws 打开 WebSocket 并为每个文本帧发出一个事件。恰好提供 command 或 ws 之一。ws 源需要 Claude Code v2.1.195 或更高版本。

为会话长度的监视（如日志尾部）设置 persistent: true。当 Monitor 运行命令时，它遵循与 Bash 相同的权限规则；WebSocket 监视会单独提示批准。请参阅 Monitor 工具参考了解行为和提供商可用性。

TaskOutput

工具名称： TaskOutput

type TaskOutputInput = {
  task_id: string;
  block: boolean;
  timeout: number;
};

从运行中或已完成的后台任务检索输出。

Edit

工具名称： Edit

type FileEditInput = {
  file_path: string;
  old_string: string;
  new_string: string;
  replace_all?: boolean;
};

在文件中执行精确字符串替换。

Read

工具名称： Read

type FileReadInput = {
  file_path: string;
  offset?: number;
  limit?: number;
  pages?: string;
};

从本地文件系统读取文件，包括文本、图像、PDF 和 Jupyter 笔记本。对 PDF 页面范围使用 pages（例如，"1-5"）。

Write

工具名称： Write

type FileWriteInput = {
  file_path: string;
  content: string;
};

将文件写入本地文件系统，如果存在则覆盖。

Glob

工具名称： Glob

type GlobInput = {
  pattern: string;
  path?: string;
};

快速文件模式匹配，适用于任何代码库大小。

Grep

工具名称： Grep

type GrepInput = {
  pattern: string;
  path?: string;
  glob?: string;
  type?: string;
  output_mode?: "content" | "files_with_matches" | "count";
  "-i"?: boolean;
  "-n"?: boolean;
  "-B"?: number;
  "-A"?: number;
  "-C"?: number;
  context?: number;
  head_limit?: number;
  offset?: number;
  multiline?: boolean;
};

基于 ripgrep 的强大搜索工具，支持正则表达式。

TaskStop

工具名称： TaskStop

type TaskStopInput = {
  task_id?: string;
  shell_id?: string; // 已弃用：使用 task_id
};

按 ID 停止运行的后台任务或 shell。自 v2.1.198 起，task_id 也接受代理团队队友或按代理 ID 或名称的命名后台代理。

NotebookEdit

工具名称： NotebookEdit

type NotebookEditInput = {
  notebook_path: string;
  cell_id?: string;
  new_source: string;
  cell_type?: "code" | "markdown";
  edit_mode?: "replace" | "insert" | "delete";
};

编辑 Jupyter 笔记本文件中的单元格。

WebFetch

工具名称： WebFetch

type WebFetchInput = {
  url: string;
  prompt: string;
};

从 URL 获取内容并使用 AI 模型处理它。

WebSearch

工具名称： WebSearch

type WebSearchInput = {
  query: string;
  allowed_domains?: string[];
  blocked_domains?: string[];
};

搜索网络并返回格式化的结果。

Workflow

工具名称： Workflow

type WorkflowInput = {
  script?: string;
  name?: string;
  scriptPath?: string;
  args?: unknown;
  resumeFromRunId?: string;
};

运行动态工作流：一个脚本，在后台协调许多子代理并返回一个统一的结果。Workflow 工具在 Agent SDK v0.3.149 及更高版本中可用。至少需要 script、name 或 scriptPath 之一。

TodoWrite

工具名称： TodoWrite

type TodoWriteInput = {
  todos: Array<{
    content: string;
    status: "pending" | "in_progress" | "completed";
    activeForm: string;
  }>;
};

创建和管理结构化任务列表以跟踪进度。

TaskCreate

工具名称： TaskCreate

type TaskCreateInput = {
  subject: string;
  description: string;
  activeForm?: string;
  metadata?: Record<string, unknown>;
};

创建单个任务并返回其分配的 ID。

TaskUpdate

工具名称： TaskUpdate

type TaskUpdateInput = {
  taskId: string;
  status?: "pending" | "in_progress" | "completed" | "deleted";
  subject?: string;
  description?: string;
  activeForm?: string;
  addBlocks?: string[];
  addBlockedBy?: string[];
  owner?: string;
  metadata?: Record<string, unknown>;
};

按 ID 修补一个任务。将 status 设置为 "deleted" 以删除它。

TaskGet

工具名称： TaskGet

type TaskGetInput = {
  taskId: string;
};

返回一个任务的完整详情，或在找不到 ID 时返回 null。

TaskList

工具名称： TaskList

type TaskListInput = {};

返回当前列表中所有任务的快照。

ExitPlanMode

工具名称： ExitPlanMode

type ExitPlanModeInput = {
  /** 已弃用：不再使用。 */
  allowedPrompts?: Array<{
    tool: "Bash";
    prompt: string;
  }>;
};

退出规划模式。allowedPrompts 字段已弃用且被忽略；Claude Code 仍然接受它，以便现有调用者和记录验证。在 v2.1.205 之前，它请求基于提示的 Bash 权限以实现计划。

ListMcpResources

工具名称： ListMcpResourcesTool

type ListMcpResourcesInput = {
  server?: string;
};

列出来自连接服务器的可用 MCP 资源。

ReadMcpResource

工具名称： ReadMcpResourceTool

type ReadMcpResourceInput = {
  server: string;
  uri: string;
};

从服务器读取特定的 MCP 资源。

EnterWorktree

工具名称： EnterWorktree

type EnterWorktreeInput = {
  name?: string;
  path?: string;
};

创建并进入临时 git worktree 以进行隔离工作。传递 path 以切换到现有 worktree 而不是创建新的。在首次进入时，目标必须是当前存储库的已注册 worktree，或在多存储库工作区中，必须是嵌套在其中的存储库的已注册 worktree；从 worktree 会话内进入时，必须在会话存储库的 .claude/worktrees/ 下。name 和 path 互斥。

工具输出类型

所有内置 Claude Code 工具的输出架构文档。这些类型从 @anthropic-ai/claude-agent-sdk 导出，代表每个工具返回的实际响应数据。

ToolOutputSchemas

所有工具输出类型的联合。

type ToolOutputSchemas =
  | AgentOutput
  | AskUserQuestionOutput
  | BashOutput
  | EnterWorktreeOutput
  | ExitPlanModeOutput
  | FileEditOutput
  | FileReadOutput
  | FileWriteOutput
  | GlobOutput
  | GrepOutput
  | ListMcpResourcesOutput
  | MonitorOutput
  | NotebookEditOutput
  | ReadMcpResourceOutput
  | TaskCreateOutput
  | TaskGetOutput
  | TaskListOutput
  | TaskStopOutput
  | TaskUpdateOutput
  | TodoWriteOutput
  | WebFetchOutput
  | WebSearchOutput
  | WorkflowOutput;

Agent

工具名称： Agent（之前为 Task，仍然接受作为别名）

type AgentOutput =
  | {
      status: "completed";
      agentId: string;
      agentType?: string;
      content: Array<{ type: "text"; text: string; citations?: unknown[] | null }>;
      resolvedModel?: string;
      totalToolUseCount: number;
      totalDurationMs: number;
      totalTokens: number;
      usage: {
        input_tokens: number;
        output_tokens: number;
        cache_creation_input_tokens: number | null;
        cache_read_input_tokens: number | null;
        server_tool_use: {
          web_search_requests: number;
          web_fetch_requests: number;
        } | null;
        service_tier: string | null;
        cache_creation: {
          ephemeral_1h_input_tokens: number;
          ephemeral_5m_input_tokens: number;
        } | null;
        inference_geo?: string | null;
        speed?: string | null;
        iterations?: unknown;
      };
      toolStats?: {
        readCount: number;
        searchCount: number;
        bashCount: number;
        editFileCount: number;
        linesAdded: number;
        linesRemoved: number;
        otherToolCount: number;
        frameCount?: number;
      };
      prompt: string;
      worktreePath?: string;
      worktreeBranch?: string;
    }
  | {
      status: "async_launched";
      isAsync?: true;
      agentId: string;
      description: string;
      resolvedModel?: string;
      prompt: string;
      outputFile: string;
      canReadOutputFile?: boolean;
    }
  | {
      status: "remote_launched";
      taskId: string;
      sessionUrl: string;
      description: string;
      prompt: string;
      outputFile: string;
    };

返回来自子代理的结果。在 status 字段上进行区分："completed" 表示已完成的任务，"async_launched" 表示后台任务，"remote_launched" 表示 Claude Code 分派到远程云会话的任务，其中 sessionUrl 链接到该会话，taskId 标识它。

completed 和 async_launched 变体上的 resolvedModel 字段命名子代理实际运行的模型，当应用 availableModels 或其他覆盖时，该模型可能与请求的 model 输入不同。此字段需要 Claude Code v2.1.174 或更高版本。

在 completed 变体上，当子代理在隔离的 git worktree 中运行时，worktreePath 被设置，worktreeBranch 在 Claude Code 创建该 worktree 时命名其分支。usage.service_tier 携带 API 为子代理的请求报告的服务层字符串。

在 v2.1.207 之前，发布的类型更窄。它省略了 worktreePath、worktreeBranch、citations、toolStats.frameCount 和 inference_geo、speed 和 iterations 使用字段，并将 service_tier 类型化为 "standard" | "priority" | "batch"。类型标记为可选的字段可能在早期版本记录的结果中不存在。

AskUserQuestion

工具名称： AskUserQuestion

type AskUserQuestionOutput = {
  questions: Array<{
    question: string;
    header: string;
    options: Array<{ label: string; description: string; preview?: string }>;
    multiSelect: boolean;
  }>;
  answers: Record<string, string>;
  response?: string;
};

返回提出的问题和用户的答案。当用户输入自由形式的回复而不是回答结构化问题时，response 被设置；当存在时，Claude 会收到"用户回复：…"而不是每个问题的答案列表。

Bash

工具名称： Bash

type BashOutput = {
  stdout: string;
  stderr: string;
  rawOutputPath?: string;
  interrupted: boolean;
  isImage?: boolean;
  backgroundTaskId?: string;
  backgroundedByUser?: boolean;
  dangerouslyDisableSandbox?: boolean;
  returnCodeInterpretation?: string;
  structuredContent?: unknown[];
  persistedOutputPath?: string;
  persistedOutputSize?: number;
};

返回命令输出，stdout/stderr 分开。后台命令包括 backgroundTaskId。

Monitor

工具名称： Monitor

type MonitorOutput = {
  taskId: string;
  timeoutMs: number;
  persistent?: boolean;
};

返回运行监视器的后台任务 ID。使用此 ID 与 TaskStop 一起提前取消监视。

Edit

工具名称： Edit

type FileEditOutput = {
  filePath: string;
  oldString: string;
  newString: string;
  originalFile: string;
  structuredPatch: Array<{
    oldStart: number;
    oldLines: number;
    newStart: number;
    newLines: number;
    lines: string[];
  }>;
  userModified: boolean;
  replaceAll: boolean;
  gitDiff?: {
    filename: string;
    status: "modified" | "added";
    additions: number;
    deletions: number;
    changes: number;
    patch: string;
  };
};

返回编辑操作的结构化差异。

Read

工具名称： Read

type FileReadOutput =
  | {
      type: "text";
      file: {
        filePath: string;
        content: string;
        numLines: number;
        startLine: number;
        totalLines: number;
      };
    }
  | {
      type: "image";
      file: {
        base64: string;
        type: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
        originalSize: number;
        dimensions?: {
          originalWidth?: number;
          originalHeight?: number;
          displayWidth?: number;
          displayHeight?: number;
        };
      };
    }
  | {
      type: "notebook";
      file: {
        filePath: string;
        cells: unknown[];
      };
    }
  | {
      type: "pdf";
      file: {
        filePath: string;
        base64: string;
        originalSize: number;
      };
    }
  | {
      type: "parts";
      file: {
        filePath: string;
        originalSize: number;
        count: number;
        outputDir: string;
      };
    };

返回适合文件类型的格式的文件内容。在 type 字段上进行区分。

Write

工具名称： Write

type FileWriteOutput = {
  type: "create" | "update";
  filePath: string;
  content: string;
  structuredPatch: Array<{
    oldStart: number;
    oldLines: number;
    newStart: number;
    newLines: number;
    lines: string[];
  }>;
  originalFile: string | null;
  gitDiff?: {
    filename: string;
    status: "modified" | "added";
    additions: number;
    deletions: number;
    changes: number;
    patch: string;
  };
};

返回写入结果，包含结构化差异信息。

Glob

工具名称： Glob

type GlobOutput = {
  durationMs: number;
  numFiles: number;
  filenames: string[];
  truncated: boolean;
};

返回与 glob 模式匹配的文件路径，按修改时间排序。

Grep

工具名称： Grep

type GrepOutput = {
  mode?: "content" | "files_with_matches" | "count";
  numFiles: number;
  filenames: string[];
  content?: string;
  numLines?: number;
  numMatches?: number;
  appliedLimit?: number;
  appliedOffset?: number;
};

返回搜索结果。形状因 mode 而异：文件列表、带匹配的内容或匹配计数。

TaskStop

工具名称： TaskStop

type TaskStopOutput = {
  message: string;
  task_id: string;
  task_type: string;
  command?: string;
};

停止后台任务后返回确认。

NotebookEdit

工具名称： NotebookEdit

type NotebookEditOutput = {
  new_source: string;
  cell_id?: string;
  cell_type: "code" | "markdown";
  language: string;
  edit_mode: string;
  error?: string;
  notebook_path: string;
  original_file: string;
  updated_file: string;
};

返回笔记本编辑的结果，包含原始和更新的文件内容。

WebFetch

工具名称： WebFetch

type WebFetchOutput = {
  bytes: number;
  code: number;
  codeText: string;
  result: string;
  durationMs: number;
  url: string;
};

返回获取的内容，包含 HTTP 状态和元数据。

WebSearch

工具名称： WebSearch

type WebSearchOutput = {
  query: string;
  results: Array<
    | {
        tool_use_id: string;
        content: Array<{ title: string; url: string }>;
      }
    | string
  >;
  durationSeconds: number;
};

返回来自网络的搜索结果。

Workflow

工具名称： Workflow

type WorkflowOutput = {
  status: "async_launched";
  taskId: string;
  runId?: string;
  summary?: string;
  transcriptDir?: string;
  scriptPath?: string;
  error?: string;
};

在工具接受调用后立即返回。最终结果稍后作为任务完成到达。在将运行视为已启动之前检查 error：脚本如果语法检查失败，会返回 status: "async_launched" 并设置 error，且永远不会运行。

TodoWrite

工具名称： TodoWrite

type TodoWriteOutput = {
  oldTodos: Array<{
    content: string;
    status: "pending" | "in_progress" | "completed";
    activeForm: string;
  }>;
  newTodos: Array<{
    content: string;
    status: "pending" | "in_progress" | "completed";
    activeForm: string;
  }>;
};

返回之前和更新的任务列表。

TaskCreate

工具名称： TaskCreate

type TaskCreateOutput = {
  task: {
    id: string;
    subject: string;
  };
};

返回创建的任务及其分配的 ID。

TaskUpdate

工具名称： TaskUpdate

type TaskUpdateOutput = {
  success: boolean;
  taskId: string;
  updatedFields: string[];
  error?: string;
  statusChange?: {
    from: string;
    to: string;
  };
};

返回更新结果，包括哪些字段已更改。

TaskGet

工具名称： TaskGet

type TaskGetOutput = {
  task: {
    id: string;
    subject: string;
    description: string;
    status: "pending" | "in_progress" | "completed";
    blocks: string[];
    blockedBy: string[];
  } | null;
};

返回完整的任务记录，或在找不到 ID 时返回 null。

TaskList

工具名称： TaskList

type TaskListOutput = {
  tasks: Array<{
    id: string;
    subject: string;
    status: "pending" | "in_progress" | "completed";
    owner?: string;
    blockedBy: string[];
  }>;
};

返回当前列表中所有任务的快照。

ExitPlanMode

工具名称： ExitPlanMode

type ExitPlanModeOutput = {
  plan: string | null;
  isAgent: boolean;
  filePath?: string;
  hasTaskTool?: boolean;
  awaitingLeaderApproval?: boolean;
  requestId?: string;
};

返回退出规划模式后的计划状态。

ListMcpResources

工具名称： ListMcpResourcesTool

type ListMcpResourcesOutput = Array<{
  uri: string;
  name: string;
  mimeType?: string;
  description?: string;
  server: string;
}>;

返回可用 MCP 资源的数组。

ReadMcpResource

工具名称： ReadMcpResourceTool

type ReadMcpResourceOutput = {
  contents: Array<{
    uri: string;
    mimeType?: string;
    text?: string;
  }>;
};

返回请求的 MCP 资源的内容。

EnterWorktree

工具名称： EnterWorktree

type EnterWorktreeOutput = {
  worktreePath: string;
  worktreeBranch?: string;
  message: string;
};

返回有关 git worktree 的信息。

权限类型

PermissionUpdate

用于更新权限的操作。

type PermissionUpdate =
  | {
      type: "addRules";
      rules: PermissionRuleValue[];
      behavior: PermissionBehavior;
      destination: PermissionUpdateDestination;
    }
  | {
      type: "replaceRules";
      rules: PermissionRuleValue[];
      behavior: PermissionBehavior;
      destination: PermissionUpdateDestination;
    }
  | {
      type: "removeRules";
      rules: PermissionRuleValue[];
      behavior: PermissionBehavior;
      destination: PermissionUpdateDestination;
    }
  | {
      type: "setMode";
      mode: PermissionMode;
      destination: PermissionUpdateDestination;
    }
  | {
      type: "addDirectories";
      directories: string[];
      destination: PermissionUpdateDestination;
    }
  | {
      type: "removeDirectories";
      directories: string[];
      destination: PermissionUpdateDestination;
    };

PermissionBehavior

type PermissionBehavior = "allow" | "deny" | "ask";

PermissionUpdateDestination

type PermissionUpdateDestination =
  | "userSettings" // 全局用户设置
  | "projectSettings" // 每个目录的项目设置
  | "localSettings" // 本地项目设置
  | "session" // 仅当前会话
  | "cliArg"; // CLI 参数

PermissionRuleValue

type PermissionRuleValue = {
  toolName: string;
  ruleContent?: string;
};

其他类型

ApiKeySource

type ApiKeySource = "user" | "project" | "org" | "temporary" | "oauth";

SdkBeta

可通过 betas 选项启用的可用测试功能。请参阅 Beta 标头了解更多信息。

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

SlashCommand

有关可用 slash command 的信息。

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

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;
};

McpServerStatus

连接的 MCP 服务器的状态。

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

McpServerStatusConfig

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

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

请参阅 McpServerConfig了解每种传输类型的详情。

AccountInfo

经过身份验证的用户的帐户信息。

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

ModelUsage

结果消息中返回的每个模型使用统计。costUSD 值是客户端估计。请参阅跟踪成本和使用情况了解计费注意事项。

type ModelUsage = {
  inputTokens: number;
  outputTokens: number;
  cacheReadInputTokens: number;
  cacheCreationInputTokens: number;
  webSearchRequests: number;
  costUSD: number;
  contextWindow: number;
  maxOutputTokens: number;
};

ConfigScope

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

NonNullableUsage

Usage 的版本，所有可空字段都变为非可空。

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

Usage

令牌使用统计。这是来自 @anthropic-ai/sdk 的 BetaUsage 类型。

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;
};

BetaServerToolUsage 和 BetaIterationsUsage 在 @anthropic-ai/sdk 中定义。

CallToolResult

MCP 工具结果类型（来自 @modelcontextprotocol/sdk/types.js）。structuredContent 是一个 JSON 对象，可以与 content 一起返回，包括图像块。请参阅返回结构化数据。

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

ThinkingConfig

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

type ThinkingDisplay = "summarized" | "omitted";

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

可选的 display 字段控制思考文本是否以 "summarized" 或 "omitted" 形式返回。在 Claude Opus 4.7 及更高版本上，API 默认值为 "omitted"，因此设置 "summarized" 以在 thinking 块中接收思考内容。

SpawnedProcess

自定义进程生成的接口（与 spawnClaudeCodeProcess 选项一起使用）。ChildProcess 已满足此接口。

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;
}

SpawnOptions

传递给自定义生成函数的选项。

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

McpSetServersResult

setMcpServers() 操作的结果。

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

RewindFilesResult

rewindFiles() 操作的结果。

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

SDKStatusMessage

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

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

SDKTaskNotificationMessage

后台任务完成、失败或停止时的通知。后台任务包括 run_in_background Bash 命令、Monitor 监视和后台子代理。

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

SDKToolUseSummaryMessage

对话中工具使用的摘要。

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

SDKHookStartedMessage

当 hook 开始执行时发出。

Claude Code 将此消息、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;
};

SDKHookProgressMessage

在 hook 运行时发出，包含 stdout/stderr 输出。

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;
};

SDKHookResponseMessage

当 hook 完成执行时发出。

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;
};

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;
  uuid: UUID;
  session_id: string;
};

SDKAuthStatusMessage

在身份验证流程中发出。

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

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;
  uuid: UUID;
  session_id: string;
};

SDKTaskProgressMessage

在子代理或后台任务运行时定期发出。仅当启用 agentProgressSummaries 时，summary 字段才会被填充。

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 纪元时间戳（以毫秒为单位），可与 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

每当实时后台任务集发生变化时发出：任务启动、完成、被杀死，或前台代理被后台化。tasks 数组是完整的实时集。用每个有效负载替换任何缓存的集，而不是配对 task_started 和 task_notification 事件，以便下一个成员资格变化纠正您错过的任何事件。

相对于这些每个任务事件的顺序是未指定的，因此不要关联这两个流。

启动时不发出任何内容。每当会话的 CLI 进程启动或重新启动时重置为空集，并让下一个成员资格变化重新填充它。

需要 Claude Code v2.1.203 或更高版本。

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

SDKThinkingTokensMessage

在 Claude 生成思考块（包括编辑过的块）时发出，携带迄今为止生成的思考令牌的运行估计。estimated_tokens 是当前思考块的运行总计，estimated_tokens_delta 是此帧携带的增量。将其用于进度显示。顶级代理循环的最终计数是结果消息的 usage.output_tokens，它不包括子代理令牌；使用 modelUsage 进行整树会计。

需要 Claude Code v2.1.153 或更高版本。

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

SDKFilesPersistedEvent

当文件检查点持久化到磁盘时发出。

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;
};

SDKRateLimitEvent

当会话遇到速率限制时发出。

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;
};

当 errorCode 为 "credits_required" 时，拒绝来自 claude.ai 订阅，其包含的使用量已耗尽，会话在用户购买使用额度之前无法继续。canUserPurchaseCredits 指示经过身份验证的用户是否可以为帐户购买额度，hasChargeableSavedPaymentMethod 指示是否有保存的付款方式。所有三个字段在非信用额度必需拒绝的速率限制事件中不存在。需要 Claude Code v2.1.181 或更高版本。

SDKLocalCommandOutputMessage

来自本地 slash command 的输出（例如，/voice 或 /usage）。在记录中显示为助手样式的文本。

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

SDKCommandsChangedMessage

当可用命令集在会话中期发生变化时发出，例如当代理进入子目录时发现技能。commands 数组是完整的更新列表，因此用此有效负载替换任何缓存的命令列表。再次调用 supportedCommands() 不等同：该方法返回在初始化时捕获的快照，不反映会话中期的变化。

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

SDKPromptSuggestionMessage

当启用 promptSuggestions 时在每个轮次后发出。包含预测的下一个用户提示。

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

SDKConversationResetMessage

当会话的对话被替换而不结束会话时发出，例如在 /clear 之后、在计划模式退出时或当新对话启动时。在 new_conversation_id 下挂载空记录，并丢弃任何缓存的会话标题。

type SDKConversationResetMessage = {
  type: "conversation_reset";
  new_conversation_id: UUID;
  uuid: UUID;
  session_id: string;
};

SDK 的已发布类型在 Claude Code v2.1.203 及更高版本中声明 SDKConversationResetMessage。在 v2.1.203 之前，SDKMessage 引用该类型而不声明它，因此当 skipLibCheck 被禁用时，在 type === "conversation_reset" 上缩小范围失败类型检查。

AbortError

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

class AbortError extends Error {}

沙箱配置

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[] };
};

示例用法

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}`);
}

SandboxNetworkConfig

沙箱模式的网络特定配置。这些设置适用于当父级 SandboxSettings 中的 enabled 为 true 时的沙箱化 Bash 命令。它们不限制 WebFetch 工具，该工具改用权限规则。

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

SandboxFilesystemConfig

沙箱模式的文件系统特定配置。

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

沙箱外命令的权限回退

启用 allowUnsandboxedCommands 时，模型可以通过在工具输入中设置 dangerouslyDisableSandbox: true 来请求在沙箱外运行命令。这些请求回退到现有权限系统，意味着您的 canUseTool 处理程序被调用，允许您实现自定义授权逻辑。在下面的示例中，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);
}

此模式使您能够：

• 审计模型请求： 记录模型何时请求沙箱外执行
• 实现允许列表： 仅允许特定命令在沙箱外运行
• 添加批准工作流： 需要对特权操作进行明确授权

另请参阅

• SDK 概述 - 常规 SDK 概念
• Python SDK 参考 - Python SDK 文档
• CLI 参考 - 命令行界面
• 常见工作流 - 分步指南