TypeScript Agent SDK 参考文档：包含所有函数（query、startup、tool、createSdkMcpServer 等）、配置选项、钩子类型、工具输入输出模式，以及沙箱和权限控制。安装 @anthropic-ai/claude-agent-sdk 后即可通过 API 调用 Claude Code，无需单独安装 CLI。打包为单文件可执行文件时需处理原生二进制路径，否则会抛 Native CLI binary not found 错误。

Claude Code Agent SDK TypeScript 参考：函数、类型与配置 #

安装 #

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

SDK 会为当前平台绑定额外的 Claude Code 原生二进制（如 @anthropic-ai/claude-agent-sdk-darwin-arm64），你无需单独安装 Claude Code。如果你的包管理器跳过了可选依赖，SDK 会抛出 Native CLI binary for <platform> not found；此时需要通过 pathToClaudeCodeExecutable 指定一个单独安装的 claude 二进制路径。

编译为单文件可执行文件 #

当你用 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 或更高版本。以下示例针对 macOS Apple Silicon 构建：

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 子进程：生成进程并完成初始化握手。返回的 WarmQuery 句柄可以在稍后传入提示，直接写入一个已就绪的进程，从而让首次 query() 调用无需等待子进程生成和初始化。

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

参数 #

返回值 #

返回 Promise<WarmQuery>，在子进程生成并完成初始化握手后 resolve。

示例 #

在应用启动时尽早调用 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() #

创建一个类型安全的 MCP 工具定义，用于 SDK 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() 之前检查它会看到什么配置。

此函数为 Alpha 状态，其 API 可能不稳定。它读取 MDM 源（包括 macOS plist 和 Windows HKLM/HKCU）以实现与 CLI 启动的等价性，但不执行管理员配置的 policyHelper 子进程。permissions.defaultMode 字段原样返回自所有层级（包括项目设置）。CLI 在应用权限模式升级前应用的信任过滤不会被应用。

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。每次重试有自己的 API_TIMEOUT_MS 窗口，因此最坏情况墙钟时间大约为 API_TIMEOUT_MS × (CLAUDE_CODE_MAX_RETRIES + 1) 加上退避。
• CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS：针对 run_in_background 启动的子代理的停滞看门狗。默认 600000。在每次流事件上重置；在停滞时终止子代理，标记任务失败，并将错误（含任何部分结果）抛给父代理。不应用于同步子代理。
• CLAUDE_ENABLE_STREAM_WATCHDOG=1 配合 CLAUDE_STREAM_IDLE_TIMEOUT_MS：当头部已到达但响应体停止流式传输时终止请求。默认关闭。CLAUDE_STREAM_IDLE_TIMEOUT_MS 默认为 300000 并被限制为该最小值。被终止的请求会进入正常重试路径。

Query 对象 #

query() 函数返回的接口。

interface Query extends AsyncGenerator<SDKMessage, void> {
  interrupt(): Promise<void>;
  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>;
  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() 相同。

这些值被写入标志设置层，与 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 });

applyFlagSettings() 仅适用于 TypeScript。Python SDK 不公开等效方法。

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

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" // 计划模式 - 仅只读工具
  | "dontAsk" // 不弹出权限提示，若未预先批准则拒绝
  | "auto"; // 使用模型分类器批准或拒绝每个工具调用

CanUseTool #

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

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

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 中加载插件的配置。

type SdkPluginConfig = {
  type: "local";
  path: string;
};

示例：

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

关于创建和使用插件的完整信息，见插件。

消息类型 #

SDKMessage #

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

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

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'、'invalid_request'、'model_not_found'、'server_error'、'max_output_tokens' 或 'unknown'。'model_not_found' 表示所选模型不存在或对你的账户/部署不可用。

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 可将消息追加到记录中而不触发助手轮次。该消息会被保留并合并到下一次触发轮次的用户消息中。用于注入上下文，例如你离线运行的命令的输出，而不消耗模型调用。

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

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;
      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：到第一个令牌的时间（毫秒）。仅出现在成功分支上。
• terminal_reason：循环结束的原因。值为 "completed"、"max_turns"、"tool_deferred"、"aborted_streaming"、"aborted_tools"、"hook_stopped"、"stop_hook_prevented"、"blocking_limit"、"rapid_refill_breaker"、"prompt_too_long"、"image_error" 或 "model_error"。
• fast_mode_state：值为 "on"、"off" 或 "cooldown"。

origin 字段转发触发此结果的用户消息的 SDKMessageOrigin。当后台任务完成且 SDK 注入一个合成的后续轮次时，生成的 SDKResultMessage 携带 origin: { kind: "task-notification" }。检查此字段以区分直接回答你的提示的结果与后台任务后续产生的结果，以便你路由或抑制后者。在第一条用户轮次之前发出的结果（如启动错误）中，此字段缺失。

当 PreToolUse 钩子返回 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 }[];
};

SDKPartialAssistantMessage #

流式部分消息（仅在 includePartialMessages 为 true 时发送）。

type SDKPartialAssistantMessage = {
  type: "stream_event";
  event: BetaRawMessageStreamEvent; // 来自 Anthropic SDK
  parent_tool_use_id: string | null;
  uuid: UUID;
  session_id: string;
};

SDKCompactBoundaryMessage #

表示对话压缩边界。

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

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 钩子发出的拒绝不会通过此事件报告。

此事件需要 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 #

用户角色消息的溯源信息。作为 origin 出现在 SDKUserMessage 上，并转发到对应的 SDKResultMessage，以便你知道什么触发了该轮次。

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

钩子类型 #

关于使用钩子的完整指南和常见模式，见钩子指南。

HookEvent #

可用的钩子事件。

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

HookCallback #

钩子回调函数类型。

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

HookCallbackMatcher #

带有可选匹配器的钩子配置。

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

HookInput #

所有钩子输入类型的联合。

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

BaseHookInput #

所有钩子输入类型扩展的基础接口。

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

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;
  team_name: string;
};

TaskCompletedHookInput #

type TaskCompletedHookInput = BaseHookInput & {
  hook_event_name: "TaskCompleted";
  task_id: string;
  task_subject: string;
  task_description?: string;
  teammate_name?: string;
  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;
};

HookJSONOutput #

钩子返回值。

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;

Agent #

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

type AgentInput = {
  description: string;
  prompt: string;
  subagent_type: string;
  model?: "sonnet" | "opus" | "haiku";
  resume?: string;
  run_in_background?: boolean;
  max_turns?: number;
  name?: string;
  team_name?: string;
  mode?: "acceptEdits" | "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;
  description?: string;
  run_in_background?: boolean;
  dangerouslyDisableSandbox?: boolean;
};

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

Monitor #

工具名称： Monitor

type MonitorInput = {
  command: string;
  description: string;
  timeout_ms?: number;
  persistent?: boolean;
};

运行后台脚本，并将每条 stdout 行作为事件传递给 Claude，以便无需轮询即可做出反应。设置 persistent: true 用于跨会话的监视，如日志跟踪。Monitor 遵循与 Bash 相同的权限规则。见 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 笔记本。使用 pages 指定 PDF 页面范围（例如 "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。

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

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

TodoWrite #

工具名称： TodoWrite

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

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

自 TypeScript Agent SDK 0.3.142 起，TodoWrite 默认禁用。请改用 TaskCreate、TaskGet、TaskUpdate 和 TaskList。见迁移到 Task 工具更新你的监控代码，或设置 CLAUDE_CODE_ENABLE_TASKS=0 以回退到 TodoWrite。

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

退出计划模式。可选地指定计划执行所需的基于提示的权限。

ListMcpResources #

工具名称： ListMcpResources

type ListMcpResourcesInput = {
  server?: string;
};

列出已连接服务器上可用的 MCP 资源。

ReadMcpResource #

工具名称： ReadMcpResource

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

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

EnterWorktree #

工具名称： EnterWorktree

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

创建并进入一个临时的 git worktree 用于隔离工作。传递 path 切换到当前仓库的现有 worktree，而不是创建新的。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;

Agent #

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

type AgentOutput =
  | {
      status: "completed";
      agentId: string;
      content: Array<{ type: "text"; text: 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: ("standard" | "priority" | "batch") | null;
        cache_creation: {
          ephemeral_1h_input_tokens: number;
          ephemeral_5m_input_tokens: number;
        } | null;
      };
      prompt: string;
    }
  | {
      status: "async_launched";
      agentId: string;
      description: string;
      prompt: string;
      outputFile: string;
      canReadOutputFile?: boolean;
    }
  | {
      status: "sub_agent_entered";
      description: string;
      message: string;
    };

返回子代理的结果。按 status 字段区分："completed" 用于完成的任务，"async_launched" 用于后台任务，"sub_agent_entered" 用于交互式子代理。

AskUserQuestion #

工具名称： AskUserQuestion

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

返回提的问题和用户的答案。

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