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() 函數的配置對象。

Handle slow or stalled API responses

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 object

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

Methods

applyFlagSettings()

在運行會話上更改任何 settings，無需重新啟動查詢。當沒有專用設置器的設置需要在會話中期更改時使用它，例如在代理讀取不受信任的輸入後收緊 permissions。setModel() 和 setPermissionMode() 是這兩個鍵的專用設置器；applyFlagSettings() 是接受任何設置鍵子集的通用形式，在此處傳遞 model 的行為與 setModel() 相同。

只有某些鍵在會話中期生效：

• 在下一個轉數上應用：model、effortLevel、ultracode、permissions、hooks、skillOverrides、fastMode、agent。切換 agent 也會在下一個轉數上應用該代理的模型覆蓋、hooks 和系統提示。
• 在會話中期無效：系統提示選項。這些在啟動時解決一次，因此運行會話保持原始值，即使調用成功。要更改它們，請啟動新會話。

effortLevel 接受 effort level 名稱。它也接受 "ultracode"，它以 xhigh 努力運行會話並打開 ultracode。Settings 類型聲明 effortLevel 沒有該值，因此在 TypeScript 中傳遞等效的 { ultracode: true }。ultracode 值需要 Claude Code v2.1.203 或更高版本，並且僅由 applyFlagSettings() 接受，不由設置文件中的 effortLevel 鍵接受。

這些值被寫入標誌設置層，這是內聯 query() 的 settings 選項在啟動時填充的同一層。標誌設置位於 settings precedence order 的頂部附近：它們覆蓋用戶、項目和本地設置，只有託管策略設置可以覆蓋它們。這是 on-page precedence section 稱為編程選項的同一層。

連續調用淺合併頂級鍵。第二次調用 { 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;
}

Methods

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，例如 scheduled task 觸發器。忽略您不認識的 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";

Default behavior

當 settingSources 被省略或 undefined 時，query() 加載與 Claude Code CLI 相同的文件系統設置：用戶、項目和本地。託管策略設置在所有情況下都會加載；當會話使用組織憑證在 eligible configuration 上進行身份驗證時，會獲取服務器管理的設置。見 What settingSources does not control 了解無論此選項如何都會讀取的輸入，以及如何禁用它們。

Why use 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"]
  }
});

Settings precedence

加載多個源時，設置按此優先級（最高到最低）合併：

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 替代交互式權限提示：它僅在 permission evaluation flow 解決為提示時調用。已由 allowedTools 條目、設置 allow 規則或權限模式（如 acceptEdits 或 bypassPermissions）批准的工具調用永遠不會調用它。要限制每個工具調用，改用 PreToolUse hook。

AskUserQuestion、標記為 requiresUserInteraction 的 MCP tools 和 connector tools 您的組織設置為 ask 即使 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; // milliseconds, max 600000; higher values are clamped to the max
  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 被設置，當 Claude Code 創建它時，worktreeBranch 命名該 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;
};

返回退出 Plan Mode 後的計劃狀態。

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

MCP 服務器的配置，如 mcpServerStatus() 報告的那樣。這是所有 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 字段是 "local_bash" 用於後台 Bash 命令和 Monitor 監視，"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

子代理或後台任務運行時定期發出。summary 字段僅在啟用 agentProgressSummaries 時填充。

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 參考 - 命令行介面
• 常見工作流 - 分步指南