200| :- | :- | :- | :- |200| :- | :- | :- | :- |
201| `title` | `string` | `undefined` | 工具的人類可讀標題 |201| `title` | `string` | `undefined` | 工具的人類可讀標題 |
202| `readOnlyHint` | `boolean` | `false` | 若為 `true`，工具不會修改其環境 |202| `readOnlyHint` | `boolean` | `false` | 若為 `true`，工具不會修改其環境 |
203| `destructiveHint` | `boolean` | `true` | 若為 `true`，工具可能執行破壞性更新（僅在 `readOnlyHint` 為 `false` 時有意義） |203| `destructiveHint` | `boolean` | `true` | 若為 `true`，工具可能執行破壞性更新。對於您標記為 [`always_ask`](#mcpservertoolpolicy) 的任何工具，請明確設定 `destructiveHint: true`，否則自動模式分類器可能會代替您的 `canUseTool` 回呼核准該工具的呼叫。僅讓 `destructiveHint` 保持未設定是不夠的，因為 Claude Code 在處理 `always_ask` 呼叫時，會將未設定的 `destructiveHint` 視為 `false`，儘管 MCP 規格的預設值為 `true` |
204| `idempotentHint` | `boolean` | `false` | 若為 `true`，以相同引數重複呼叫不會產生額外效果（僅在 `readOnlyHint` 為 `false` 時有意義） |204| `idempotentHint` | `boolean` | `false` | 若為 `true`，以相同引數重複呼叫不會產生額外效果（僅在 `readOnlyHint` 為 `false` 時有意義） |
205| `openWorldHint` | `boolean` | `true` | 若為 `true`，工具會與外部實體互動（例如網路搜尋）。若為 `false`，工具的範圍是封閉的（例如記憶工具） |205| `openWorldHint` | `boolean` | `true` | 若為 `true`，工具會與外部實體互動（例如網路搜尋）。若為 `false`，工具的範圍是封閉的（例如記憶工具） |
206 206
630 ): Promise<SDKControlReadFileResponse | null>;630 ): Promise<SDKControlReadFileResponse | null>;
631 reloadPlugins(options?: {631 reloadPlugins(options?: {
632 holdOnCacheImpact?: boolean;632 holdOnCacheImpact?: boolean;
633 addPlugins?: SdkPluginConfig[];
633 }): Promise<SDKControlReloadPluginsResponse>;634 }): Promise<SDKControlReloadPluginsResponse>;
634 reloadSkills(): Promise<SDKControlReloadSkillsResponse>;635 reloadSkills(): Promise<SDKControlReloadSkillsResponse>;
635 reloadOutputStyles(): Promise<SDKControlReloadOutputStylesResponse>;636 reloadOutputStyles(): Promise<SDKControlReloadOutputStylesResponse>;
669| `mcpServerStatus()` | 以 [`McpServerStatus`](#mcpserverstatus)`[]` 回傳已連線 MCP 伺服器的狀態 |670| `mcpServerStatus()` | 以 [`McpServerStatus`](#mcpserverstatus)`[]` 回傳已連線 MCP 伺服器的狀態 |
670| `getContextUsage(opts?)` | 回傳 [`SDKControlGetContextUsageResponse`](#sdkcontrolgetcontextusageresponse)，依類別、skill 與工具細分工作階段的上下文視窗用量。使用預設的 `detail` 時，它包含 `/context` 在互動式工作階段中顯示的資料，並透過不會出現在訊息串流中的 token 計數 API 請求計算；請參閱[這些請求的處理方式](#sdkcontrolgetcontextusageresponse)。[`detail` 選項](#sdkcontrolgetcontextusageresponse)需要 Agent SDK v0.3.257 或更新版本 |671| `getContextUsage(opts?)` | 回傳 [`SDKControlGetContextUsageResponse`](#sdkcontrolgetcontextusageresponse)，依類別、skill 與工具細分工作階段的上下文視窗用量。使用預設的 `detail` 時，它包含 `/context` 在互動式工作階段中顯示的資料，並透過不會出現在訊息串流中的 token 計數 API 請求計算；請參閱[這些請求的處理方式](#sdkcontrolgetcontextusageresponse)。[`detail` 選項](#sdkcontrolgetcontextusageresponse)需要 Agent SDK v0.3.257 或更新版本 |
671| `readFile(path, options?)` | 從工作階段的檔案系統讀取檔案。Claude Code 會相對於 `cwd` 解析路徑；[`readFile()` 可以讀取的內容](#what-readfile-can-read)列出了它會提供的檔案。傳遞 `{ maxBytes }` 以變更讀取上限（預設 1 MB，最高 10 MB），二進位檔案（例如圖片）則傳遞 `{ encoding: 'base64' }`。會以 [`SDKControlReadFileResponse`](#sdkcontrolreadfileresponse) 解析，或在權限遭拒、檔案不存在或傳輸錯誤時解析為 `null`。需要 TypeScript SDK v0.2.121 或更新版本 |672| `readFile(path, options?)` | 從工作階段的檔案系統讀取檔案。Claude Code 會相對於 `cwd` 解析路徑；[`readFile()` 可以讀取的內容](#what-readfile-can-read)列出了它會提供的檔案。傳遞 `{ maxBytes }` 以變更讀取上限（預設 1 MB，最高 10 MB），二進位檔案（例如圖片）則傳遞 `{ encoding: 'base64' }`。會以 [`SDKControlReadFileResponse`](#sdkcontrolreadfileresponse) 解析，或在權限遭拒、檔案不存在或傳輸錯誤時解析為 `null`。需要 TypeScript SDK v0.2.121 或更新版本 |
672| `reloadPlugins(options?)` | 從磁碟重新載入外掛，讓您在工作階段中途安裝或編輯的外掛能送達正在執行的工作階段。會以 [`SDKControlReloadPluginsResponse`](#sdkcontrolreloadpluginsresponse) 解析，其中列出工作階段的命令、subagent、外掛和 MCP 伺服器狀態。需要 Agent SDK v0.2.85 或更新版本。[`holdOnCacheImpact` 選項](#sdkcontrolreloadpluginsresponse)需要 Agent SDK v0.3.268 或更新版本 |673| `reloadPlugins(options?)` | 從磁碟重新載入外掛，讓您在工作階段中途安裝或編輯的外掛能套用至執行中的工作階段。會解析為 [`SDKControlReloadPluginsResponse`](#sdkcontrolreloadpluginsresponse)，列出工作階段的命令、subagent、外掛與 MCP 伺服器狀態。需要 Agent SDK v0.2.85 或更新版本。[`holdOnCacheImpact` 選項](#sdkcontrolreloadpluginsresponse)需要 Agent SDK v0.3.268 或更新版本。[`addPlugins` 選項](#load-more-plugin-folders-with-addplugins)需要 Agent SDK v0.3.301 或更新版本 |
673| `reloadSkills()` | 從磁碟重新載入 skill，讓您在工作階段中途新增或編輯的 skill 可供正在執行的工作階段使用。會以 [`SDKControlReloadSkillsResponse`](#sdkcontrolreloadskillsresponse) 解析，其中列出重新載入後可用的 skill。需要 Agent SDK v0.3.163 或更新版本 |674| `reloadSkills()` | 從磁碟重新載入 skill，讓您在工作階段中途新增或編輯的 skill 可供正在執行的工作階段使用。會以 [`SDKControlReloadSkillsResponse`](#sdkcontrolreloadskillsresponse) 解析，其中列出重新載入後可用的 skill。需要 Agent SDK v0.3.163 或更新版本 |
674| `reloadOutputStyles()` | 從磁碟重新讀取[輸出風格](https://code.claude.com/docs/zh-TW/output-styles.md)，讓您在工作階段中途新增或編輯的風格檔案可供正在執行的工作階段使用。會以 [`SDKControlReloadOutputStylesResponse`](#sdkcontrolreloadoutputstylesresponse) 解析，其中列出重新載入後可用的風格名稱。需要 Agent SDK v0.3.261 或更新版本 |675| `reloadOutputStyles()` | 從磁碟重新讀取[輸出風格](https://code.claude.com/docs/zh-TW/output-styles.md)，讓您在工作階段中途新增或編輯的風格檔案可供正在執行的工作階段使用。會以 [`SDKControlReloadOutputStylesResponse`](#sdkcontrolreloadoutputstylesresponse) 解析，其中列出重新載入後可用的風格名稱。需要 Agent SDK v0.3.261 或更新版本 |
675| `seedReadState(path, mtime)` | 將檔案標記為已讀取，讓之後的 Edit 不會因 `File has not been read yet` 而失敗。請參閱 [`seedReadState()`](#seedreadstate)。需要 TypeScript SDK v0.2.83 或更新版本 |676| `seedReadState(path, mtime)` | 將檔案標記為已讀取，讓之後的 Edit 不會因 `File has not been read yet` 而失敗。請參閱 [`seedReadState()`](#seedreadstate)。需要 TypeScript SDK v0.2.83 或更新版本 |
1135 1136
1136`cache_impact` 只會與 `held: true` 一起出現。`mcp_servers_added` 和 `mcp_servers_removed` 以具範圍的 `plugin:<plugin>:<server>` 名稱，指出重新載入會註冊或移除的外掛 MCP 伺服器。這些名稱由外掛作者撰寫，因此在顯示之前請先驗證。`lsp_tool_change` 說明套用後是否會新增或移除 LSP 工具，若兩者皆不會則為 `null`。`may-` 形式表示檢查無法完整看到待處理的外掛集合。1137`cache_impact` 只會與 `held: true` 一起出現。`mcp_servers_added` 和 `mcp_servers_removed` 以具範圍的 `plugin:<plugin>:<server>` 名稱，指出重新載入會註冊或移除的外掛 MCP 伺服器。這些名稱由外掛作者撰寫，因此在顯示之前請先驗證。`lsp_tool_change` 說明套用後是否會新增或移除 LSP 工具，若兩者皆不會則為 `null`。`may-` 形式表示檢查無法完整看到待處理的外掛集合。
1137 1138
1139#### 使用 `addPlugins` 載入更多外掛資料夾
1140
1141若要載入啟動時不在 [`plugins`](#options) 選項中的外掛資料夾，請將它們以 `addPlugins` 傳給 `reloadPlugins()`，這是一個 [`SdkPluginConfig`](#sdkpluginconfig) 項目清單，其 `path` 必須是絕對路徑。Claude Code 會在一次處理中載入新資料夾並重新載入工作階段現有的外掛。每個新增外掛的 MCP 伺服器也會連線，除非您在該資料夾的項目上設定了 [`skipMcpDiscovery`](#sdkpluginconfig)。需要 Agent SDK v0.3.301 或更新版本，以及 Claude Code v2.1.301 或更新版本。
1142
1143此範例將一個資料夾新增至正在執行的查詢 `q`，並在呼叫回傳時列印工作階段已載入的每個外掛的安裝路徑：
1144
1145```typescript theme={null}
1146const result = await q.reloadPlugins({
1147 addPlugins: [{ type: "local", path: "/opt/my-app/plugins/reports" }]
1148});
1149
1150console.log(result.plugins.map((plugin) => plugin.path));
1151```
1152
1153如果資料夾已載入，列印出的清單會包含 `/opt/my-app/plugins/reports`，且該外掛的命令和 subagent 會出現在 `result.commands` 和 `result.agents` 中。
1154
1155新增的資料夾會一直是工作階段的一部分。當您再次呼叫 `reloadPlugins()` 時，Claude Code 會將它與其他外掛一起重新載入，您不需要再次在 `addPlugins` 中傳入它。
1156
1157##### 當 `reloadPlugins()` 未載入 `addPlugins` 資料夾時
1158
1159如果 `reloadPlugins()` 被拒絕，則不會新增任何 `addPlugins` 資料夾，因此重試時請再次在 `addPlugins` 中傳入它們。當拒絕是由下列原因之一造成時，工作階段會保留原本已有的外掛：
1160
1161* **相對 `path` 或格式錯誤的項目**：錯誤訊息為 `add_plugins must be a list of { type: "local", path } entries with absolute paths`。只要有一個錯誤項目，Claude Code 就會拒絕整個清單，因此請將每個項目都以 `{ type: "local", path }` 搭配絕對 `path` 傳入
1162* **管理員已在您的受管設定中開啟 [`disableSideloadFlags`](https://code.claude.com/docs/zh-TW/settings-reference#disablesideloadflags)**：訊息為 `reload_plugins add_plugins is disabled by managed settings (disableSideloadFlags)`。若要載入該資料夾，請要求該管理員移除此設定
1163* **無法重建[沙箱](https://code.claude.com/docs/zh-TW/sandboxing.md)**：在開啟[沙箱機制](#sandboxsettings)時，Claude Code 會重建沙箱設定，使在沙箱中執行的 shell 命令無法寫入您新增的資料夾。訊息為 `the sandbox could not be rebuilt to keep shell commands out of this folder`。請檢查您的[沙箱設定](#sandboxsettings)是否仍構成有效的設定
1164
1165如果您傳入 `holdOnCacheImpact` 且呼叫以 [`held: true`](#sdkcontrolreloadpluginsresponse) 解析，則不會新增 `addPlugins` 資料夾。若仍要新增，請以相同的 `addPlugins` 清單且不帶 `holdOnCacheImpact` 再次呼叫 `reloadPlugins()`。
1166
1167當呼叫解析結果沒有 `held: true`，而某個資料夾仍未出現在 `result.plugins` 中時，請先檢查下列原因：
1168
1169* **資料夾不存在或其外掛載入失敗**：`result.error_count` 為 `1` 或更高。即便如此，該資料夾仍是工作階段的一部分。修正資料夾後，再次呼叫 `reloadPlugins()` 以載入它，這次不需在 `addPlugins` 中列出它
1170* **Claude Code 執行檔早於 v2.1.301**：早於 v2.1.301 的執行檔會忽略 `addPlugins`，只重新載入工作階段原本已有的外掛。請檢查 [init 訊息](#sdksystemmessage)上的 `claude_code_version`，並執行 v2.1.301 或更新版本的執行檔
1171
1138### `SDKControlReloadSkillsResponse`1172### `SDKControlReloadSkillsResponse`
1139 1173
1140[`reloadSkills()`](#query-object) 的回傳型別。1174[`reloadSkills()`](#query-object) 的回傳型別。
1430 1464
1431#### `McpSdkServerConfigWithInstance`1465#### `McpSdkServerConfigWithInstance`
1432 1466
1467程序內 MCP 伺服器的設定，即由 [`createSdkMcpServer()`](#createsdkmcpserver) 建立並在您應用程式的程序內執行的伺服器。它是 `createSdkMcpServer()` 回傳的物件，再加上您自行新增的選用 `tools` 清單，內含 [`McpServerToolPolicy`](#mcpservertoolpolicy) 項目。若要要求對伺服器某個工具的呼叫進行核准，或拒絕這些呼叫，請新增一個指名該工具的項目。
1468
1433```typescript theme={null}1469```typescript theme={null}
1434type McpSdkServerConfigWithInstance = {1470type McpSdkServerConfigWithInstance = {
1435 type: "sdk";1471 type: "sdk";
1436 name: string;1472 name: string;
1437 timeout?: number;1473 timeout?: number;
1474 tools?: McpServerToolPolicy[];
1438 instance: McpServer;1475 instance: McpServer;
1439};1476};
1440```1477```
1441 1478
1479若要設定原則，請將 `createSdkMcpServer()` 回傳的物件展開到 `mcpServers` 中的新物件，並在該新物件中加入 `tools` 清單。`createSdkMcpServer()` 本身的 `tools` 選項是另一個清單，它存放工具定義，不接受原則項目。原則清單需要 Agent SDK v0.3.301 或更新版本，而 [`McpServerToolPolicy`](#mcpservertoolpolicy) 說明了每個 `permission_policy` 值的作用。
1480
1481此範例以 `allowedTools` 萬用字元預先核准 `records` 伺服器上的每個工具，接著將 `delete_record` 標記為 `always_ask`，使對它的呼叫仍會送到 `canUseTool`。搭配 `destructiveHint: true` 註解，即使工作階段以 `auto` 模式執行，呼叫仍會抵達回呼；否則自動模式的[分類器](https://code.claude.com/docs/zh-TW/permission-modes.md#eliminate-prompts-with-auto-mode)可能會核准它。
1482
1483```typescript theme={null}
1484import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";
1485import { z } from "zod";
1486
1487const deleteRecord = tool(
1488 "delete_record",
1489 "Delete a customer record by ID",
1490 { id: z.string() },
1491 async ({ id }) => ({ content: [{ type: "text", text: `Deleted record ${id}` }] }),
1492 { annotations: { destructiveHint: true } }
1493);
1494
1495const records = createSdkMcpServer({ name: "records", tools: [deleteRecord] });
1496
1497for await (const message of query({
1498 prompt: "Delete customer record 42",
1499 options: {
1500 mcpServers: {
1501 // Spread the returned config and add the policy list beside it
1502 records: {
1503 ...records,
1504 tools: [{ name: "delete_record", permission_policy: "always_ask" as const }]
1505 }
1506 },
1507 allowedTools: ["mcp__records__*"],
1508 canUseTool: async (toolName, input) => {
1509 console.log(`Approval requested for ${toolName}`);
1510 return { behavior: "allow", updatedInput: input };
1511 }
1512 }
1513})) {
1514 if (message.type === "result" && message.subtype === "success") {
1515 console.log(message.result);
1516 }
1517}
1518```
1519
1520當 Claude 呼叫此工具時，腳本會在 `delete_record` 工具執行之前列印 `Approval requested for mcp__records__delete_record`，儘管 `allowedTools` 項目原本會核准此呼叫。
1521
1522若要在工作階段執行期間變更或解除工具的原則，請將帶有新 `tools` 值的伺服器設定傳給 [`setMcpServers()`](#mcpsetserversresult)。您傳入的 `tools` 值會從 Claude 下一次呼叫該伺服器的工具時生效：
1523
1524* **含有項目的清單**：這些項目會取代目前的原則
1525* **空清單**：清除伺服器上的所有原則
1526* **沒有 `tools` 鍵**：保留目前的原則
1527
1528請在該呼叫中納入您的其他程序內伺服器，以及先前 `setMcpServers()` 呼叫所新增的任何伺服器，否則該呼叫會中斷它們的連線。
1529
1530#### `McpServerToolPolicy`
1531
1532[`McpSdkServerConfigWithInstance`](#mcpsdkserverconfigwithinstance) 的 `tools` 清單中的一個項目，指名伺服器的某個工具，並為對該工具的呼叫設定權限原則。此清單需要 Agent SDK v0.3.301 或更新版本，以及 Claude Code v2.1.301 或更新版本。較舊的 Claude Code 執行檔（例如您以 `pathToClaudeCodeExecutable` 指向的執行檔）會忽略此清單。此時 `always_ask` 和 `always_deny` 不會被強制執行，每個呼叫都會經過[權限流程](https://code.claude.com/docs/zh-TW/agent-sdk/permissions.md#how-permissions-are-evaluated)。
1533
1534```typescript theme={null}
1535type McpServerToolPolicy = {
1536 name: string;
1537 permission_policy?: "always_allow" | "always_ask" | "always_deny";
1538 org_max_permission?: "allow" | "ask" | "blocked";
1539};
1540```
1541
1542| 欄位 | 型別 | 說明 |
1543| :- | :- | :- |
1544| `name` | `string` | 傳給 [`tool()`](#tool) 的工具原始名稱，不含 `mcp__<server>__` 前綴 |
1545| `permission_policy` | `'always_allow' \| 'always_ask' \| 'always_deny'` | 此工具呼叫的核准原則，[`always_ask` 或 `always_deny`](#permission-policy-values)。`always_allow` 在程序內伺服器上會被忽略：若要預先核准工具，請改為在 [`allowedTools`](#options) 中列出它 |
1546| `org_max_permission` | `'allow' \| 'ask' \| 'blocked'` | 由組織管理員設定的每個工具上限。在程序內伺服器上會被忽略，因此請保持未設定 |
1547
1548##### `permission_policy` 值
1549
1550選擇 `always_ask` 以自行核准每個呼叫，或選擇 `always_deny` 以直接封鎖該工具：
1551
1552* **`always_ask`**：對該工具的每個呼叫都[需要核准](https://code.claude.com/docs/zh-TW/agent-sdk/permissions.md#how-permissions-are-evaluated)，即使有 `allowedTools` 項目或允許規則涵蓋它。除非先行處理，否則呼叫會送到您的 `canUseTool` 回呼或 [`permissionPromptToolName`](#options) 工具。您載入的外掛中的 [mod](https://code.claude.com/docs/zh-TW/plugins/mods/overview.md) [可以先核准它](https://code.claude.com/docs/zh-TW/permissions.md#precedence-among-rules-hooks-and-mods)。否則，在 `dontAsk` 模式下會被拒絕，而在 [`auto`、`plan` 和 `bypassPermissions` 模式](#permission-modes-that-can-approve-an-always_ask-call)下，它可能在抵達您的回呼之前就被核准
1553* **`always_deny`**：對該工具的呼叫在每種權限模式下都[會被拒絕](https://code.claude.com/docs/zh-TW/agent-sdk/permissions.md#how-permissions-are-evaluated)，包括 `bypassPermissions`，但您載入的外掛中的 mod [仍可以核准它](https://code.claude.com/docs/zh-TW/permissions.md#precedence-among-rules-hooks-and-mods)
1554
1555如果您既未傳入 `canUseTool` 也未傳入 `permissionPromptToolName`，或將 [`permissionPrompts`](#options) 設為 `'none'`，則未先行處理的 `always_ask` 呼叫會被拒絕，除非有 [`PermissionRequest` hook](https://code.claude.com/docs/zh-TW/hooks#permissionrequest) 允許它。
1556
1557##### 可以核准 `always_ask` 呼叫的權限模式
1558
1559在 `auto`、`plan` 和 `bypassPermissions` 模式下，對標記為 [`always_ask`](#permission-policy-values) 的工具的呼叫，可能在抵達您的 `canUseTool` 回呼之前就被核准。請在此清單中找到您工作階段的模式，了解該核准何時發生，以及要設定什麼才能讓呼叫仍抵達您的回呼：
1560
1561* **`auto`**：自動模式[分類器](https://code.claude.com/docs/zh-TW/permission-modes.md#eliminate-prompts-with-auto-mode)會審查呼叫並可能允許它。若要讓每個呼叫在 `auto` 模式下都抵達您的回呼，請在工具的[註解](#toolannotations)中設定 `destructiveHint: true`
1562* **`plan`**：當工作階段[可使用自動模式](https://code.claude.com/docs/zh-TW/permission-modes.md#eliminate-prompts-with-auto-mode)時，對註解為 `readOnlyHint: true` 的 `always_ask` 工具的呼叫會送到自動模式分類器，分類器可能允許它們。對其他 `always_ask` 工具的呼叫會抵達您的回呼。若要讓唯讀工具的呼叫也抵達您的回呼，請在該工具的註解中，於 `readOnlyHint: true` 旁加入 `destructiveHint: true`。或者，將 [`useAutoModeDuringPlan`](https://code.claude.com/docs/zh-TW/settings-reference#useautomodeduringplan) 設為 `false`，這會在規劃期間關閉分類器
1563* **`bypassPermissions`**：當 [`CLAUDE_CODE_REMOTE`](https://code.claude.com/docs/zh-TW/env-vars#variables) 環境變數為 `true` 時（在[雲端工作階段](https://code.claude.com/docs/zh-TW/claude-code-on-the-web.md)中即是如此），無論工具的註解為何，呼叫都會在不經過您回呼的情況下被核准。在其他任何地方，呼叫都會抵達您的回呼。若要讓它在雲端工作階段中也抵達您的回呼，請改以 `default` 或 `acceptEdits` 模式執行工作階段
1564
1565在 `auto` 和 `plan` 模式下，請明確將 `destructiveHint` 設為 `true`。對於 `always_ask` 呼叫，Claude Code 會將未設定的 `destructiveHint` 視為 `false`，儘管 [`ToolAnnotations`](#toolannotations) 下列出的預設值為 `true`。
1566
1442#### `McpClaudeAIProxyServerConfig`1567#### `McpClaudeAIProxyServerConfig`
1443 1568
1444```typescript theme={null}1569```typescript theme={null}
1464| 欄位 | 型別 | 說明 |1589| 欄位 | 型別 | 說明 |
1465| :- | :- | :- |1590| :- | :- | :- |
1466| `type` | `'local'` | 必須為 `'local'`（目前僅支援本機外掛） |1591| `type` | `'local'` | 必須為 `'local'`（目前僅支援本機外掛） |
1467| `path` | `string` | 外掛目錄的絕對或相對路徑 |1592| `path` | `string` | 外掛目錄的路徑。相對路徑會在工作階段啟動時相對於 [`cwd`](#options) 選項解析。當您在工作階段中途以 [`addPlugins`](#load-more-plugin-folders-with-addplugins) 載入外掛時，路徑必須是絕對路徑 |
1468| `skipMcpDiscovery` | `boolean` | 當為 `true` 時，SDK 會從此外掛載入 skill、hook、agent 與命令，但不會讀取其 `.mcp.json` 或 manifest 中的 `mcpServers`。當您的應用程式自行管理外掛的 MCP 連線時，請設定此項。 |1593| `skipMcpDiscovery` | `boolean` | 當為 `true` 時，SDK 會從此外掛載入 skill、hook、agent 與命令，但不會讀取其 `.mcp.json` 或 manifest 中的 `mcpServers`。當您的應用程式自行管理外掛的 MCP 連線時，請設定此項。 |
1469 1594
1470**範例：**1595**範例：**
5075};5200};
5076```5201```
5077 5202
5078`source` 說明伺服器定義的來源，具有與 [`McpServerProvenance`](#mcpserverprovenance) 的 `source` 相同的值和信任規則。該欄位需要 Agent SDK v0.3.274 或更新版本，在較早版本上不存在。5203使用 `source` 決定對伺服器的信任程度，並使用每個 `tools` 項目上的 `_meta` 找出伺服器附加到該工具的 UI 資源：
5204
5205* **`source`**：伺服器定義的來源，其值與 [`McpServerProvenance`](#mcpserverprovenance) 上的 `source` 相同。請根據 `source` 而非 `name` 做出信任決定，因為只有您自己的進程內伺服器會報告 `sdk`，無論任何其他伺服器以何種名稱註冊。如果您不認識某個 `source` 值，請以對待任何 `source` 不是 `sdk` 之伺服器的方式對待該伺服器。需要 Agent SDK v0.3.274 或更新版本
5206* **`_meta`**：來自伺服器為該工具宣告之 `_meta` 的 `ui` 物件和 `ui/resourceUri` 字串。Claude Code 會扣留所有其他 `_meta` 鍵。`ui/resourceUri` 是 `ui.resourceUri` 較舊的頂層寫法。當伺服器將 [MCP Apps UI 資源](https://code.claude.com/docs/zh-TW/mcp.md#reference-mcp-resources) 附加到工具時，`ui.resourceUri` 或 `ui/resourceUri` 會保存該資源的 `ui://` URI。使用 [`readMcpResource()`](#query-object) 擷取該 URI，並在您的應用程式中呈現該資源。需要 Agent SDK v0.3.280 或更新版本
5207
5208Claude Code 僅在 subtype 為 `init` 的 `system` 訊息之 [`capabilities`](#sdksystemmessage) 陣列列出 `mcp_tool_ui_meta_v1` 時才傳送 `_meta`。您無需自行開啟 `mcp_tool_ui_meta_v1`。
5209
5210#### 當工具的 `_meta.ui` 僅包含 `visibility` 時
5211
5212如果您的伺服器為工具宣告了 `ui.resourceUri`，但您的應用程式收到的 `_meta.ui` 僅包含 `visibility`，表示伺服器傳送的 `ui` 物件未通過 Claude Code 的某項檢查。Claude Code 會分別檢查 `ui` 和 `ui/resourceUri`，因此當其中一個鍵未通過時，另一個鍵仍可能送達您的應用程式。請將您伺服器 `tools/list` 回應中的 `_meta` 與每個鍵的檢查進行比較：
5213
5214* **`ui`**：若三項檢查全部通過，會原封不動地送達您的應用程式，包括 `resourceUri` 和 `visibility` 以外的任何成員：
5215
5216 * `resourceUri` 不存在，或是以 `ui://` 開頭的字串
5217 * `visibility` 不存在，或僅列出 `"model"` 和 `"app"`
5218 * 整個物件序列化為 JSON 時最多 4,096 個字元
5219
5220 如果任何一項檢查失敗，您的應用程式最多只會收到一個 `ui`，其唯一成員是包含伺服器所列 `"model"` 和 `"app"` 項目的 `visibility` 陣列。
5221* **`ui/resourceUri`**：若它是以 `ui://` 開頭且最多 4,096 個字元的字串，就會送達您的應用程式。否則 Claude Code 會將其捨棄
5079 5222
5080`_meta` 在 `tools` 項目上攜帶該工具的 `_meta` 的 MCP Apps 成員，因此您的應用程式可以找到 `ui://` 資源以使用 [`readMcpResource()`](#query-object) 呈現。Claude Code 傳遞 `ui` 物件和已棄用的平面 `ui/resourceUri` 字串，並扣留所有其他鍵，不予傳遞。在 `ui` 內，`resourceUri` 是 `ui://` 字串，`visibility` 是當伺服器設定時 `"model"` 和 `"app"` 的陣列，任何其他成員原封不動地傳遞。Claude Code 在值格式不正確時捨棄任一鍵，並從未宣告任一鍵的工具中省略 `_meta`。該欄位僅在初始化訊息的 [`capabilities`](#sdksystemmessage) 包含 `mcp_tool_ui_meta_v1` 時存在，並需要 TypeScript Agent SDK v0.3.280 或更新版本。5223當 Claude Code 沒有剩下任何可傳送的 `ui` 成員或 `ui/resourceUri` 字串時，該 `tools` 項目完全沒有 `_meta`。
5081 5224
5082### `McpServerStatusConfig`5225### `McpServerStatusConfig`
5083 5226
5312當您呼叫 `setMcpServers()` 時，Claude Code 應用這些規則：5455當您呼叫 `setMcpServers()` 時，Claude Code 應用這些規則：
5313 5456
5314* **呼叫未命名的伺服器**：在[雲端工作階段](https://code.claude.com/docs/zh-TW/claude-code-on-the-web.md)之外，Claude Code 會中斷先前 `setMcpServers()` 呼叫所新增的伺服器以及進程內 SDK 伺服器的連線，並在 `removed` 中列出它們。其他伺服器會持續執行，且不會列在 `removed` 中，其中包括來自 [`mcpServers`](#options) 選項的 stdio、HTTP 和 SSE 伺服器、來自設定檔的伺服器，以及外掛提供的伺服器。5457* **呼叫未命名的伺服器**：在[雲端工作階段](https://code.claude.com/docs/zh-TW/claude-code-on-the-web.md)之外，Claude Code 會中斷先前 `setMcpServers()` 呼叫所新增的伺服器以及進程內 SDK 伺服器的連線，並在 `removed` 中列出它們。其他伺服器會持續執行，且不會列在 `removed` 中，其中包括來自 [`mcpServers`](#options) 選項的 stdio、HTTP 和 SSE 伺服器、來自設定檔的伺服器，以及外掛提供的伺服器。
5315* **呼叫命名的伺服器**：對於先前 `setMcpServers()` 呼叫所新增的 stdio、HTTP 或 SSE 伺服器，Claude Code 只在其設定與您傳遞的設定不同時才替換它。已以該名稱註冊的進程內 SDK 伺服器會保持不變，因此若要替換它，請在一次呼叫中將其省略，並在下一次呼叫中新增它。5458* **先前 `setMcpServers()` 呼叫所新增的 stdio、HTTP 和 SSE 伺服器**：在雲端工作階段之外，您以相同設定再次命名的伺服器會保留其連線和工具。它既不會出現在 `added` 中，也不會出現在 `removed` 中。如果您傳遞變更後的設定，Claude Code 會使用該設定重新連線該伺服器，並將其列在 `added` 中，而非 `removed` 中。
5459* **呼叫所命名、但先前沒有任何呼叫新增的 stdio、HTTP 和 SSE 伺服器**：在雲端工作階段之外，Claude Code 會新增該伺服器並將其列在 `added` 中；若拒絕該伺服器，則列在 `errors` 中。
5460* **呼叫所命名的進程內 SDK 伺服器**：已透過 `mcpServers` 或先前呼叫註冊的伺服器會保留其執行中的實例和逾時。如果您為其傳遞 [`tools` 政策清單](#mcpsdkserverconfigwithinstance)，即使是空清單，也會取代其政策；否則政策保持不變。若要在雲端工作階段之外執行新實例，請在一次呼叫中省略該伺服器，並在下一次呼叫中命名它。
5316* **CLI 在啟動時啟動的內建伺服器**：如果呼叫命名一個，Claude Code 會捨棄該項目並在 `errors` 中報告它。5461* **CLI 在啟動時啟動的內建伺服器**：如果呼叫命名一個，Claude Code 會捨棄該項目並在 `errors` 中報告它。
5317* **與 MCP 安裝範圍（例如 `.mcp.json`）中的伺服器同名的 stdio、HTTP 或 SSE 伺服器**：在該名稱下，工作階段會使用您的伺服器的工具，而非[安裝範圍伺服器](https://code.claude.com/docs/zh-TW/mcp.md#mcp-installation-scopes)的工具。在 Claude Code v2.1.305 之前，當您的應用程式[重新載入外掛](#query-object)時，Claude Code 可能會中斷您的伺服器連線，改為連線至安裝範圍伺服器。5462* **與 MCP 安裝範圍（例如 `.mcp.json`）中的伺服器同名的 stdio、HTTP 或 SSE 伺服器**：在該名稱下，工作階段會使用您的伺服器的工具，而非[安裝範圍伺服器](https://code.claude.com/docs/zh-TW/mcp.md#mcp-installation-scopes)的工具。在 Claude Code v2.1.305 之前，當您的應用程式[重新載入外掛](#query-object)時，Claude Code 可能會中斷您的伺服器連線，改為連線至安裝範圍伺服器。
5318 5463
5799 5944
5800SDK 的已發佈類型在 Claude Code v2.1.203 及更新版本中宣告 `SDKConversationResetMessage`。在 v2.1.203 之前，`SDKMessage` 參考該類型而不宣告它，因此當 `skipLibCheck` 被停用時，在 `type === "conversation_reset"` 上縮小範圍無法通過類型檢查。5945SDK 的已發佈類型在 Claude Code v2.1.203 及更新版本中宣告 `SDKConversationResetMessage`。在 v2.1.203 之前，`SDKMessage` 參考該類型而不宣告它，因此當 `skipLibCheck` 被停用時，在 `type === "conversation_reset"` 上縮小範圍無法通過類型檢查。
5801 5946
5947### `BUILTIN_TOOL_NAMES` 和 `LEGACY_TOOL_NAME_ALIASES`
5948
5949使用這兩個常數檢查您的應用程式使用者輸入的工具名稱。兩者拼寫每個名稱的方式，都與您在權限規則、hook matcher 以及 `tools` 和 `disallowedTools` 選項中撰寫的方式相同。從 `@anthropic-ai/claude-agent-sdk` 或 `@anthropic-ai/claude-agent-sdk/core` 匯入它們。它們需要 Agent SDK v0.3.301 或更新版本，且為 alpha 版。
5950
5951SDK 的類型宣告為 `BUILTIN_TOOL_NAMES` 提供唯讀 tuple 類型，為 `LEGACY_TOOL_NAME_ALIASES` 提供字串對字串的 record 類型：
5952
5953```typescript theme={null}
5954const BUILTIN_TOOL_NAMES: readonly ["Agent", /* ...more names... */ "Write"];
5955const LEGACY_TOOL_NAME_ALIASES: Readonly<Record<string, string>>;
5956```
5957
5958* **`BUILTIN_TOOL_NAMES`**：Claude Code 內建工具的名稱，依字母順序排列，例如 `Agent`、`Bash` 和 `Read`。不包括 MCP 工具名稱。由於該類型是字串常值的 tuple，`(typeof BUILTIN_TOOL_NAMES)[number]` 會提供這些名稱的聯合類型
5959* **`LEGACY_TOOL_NAME_ALIASES`**：權限規則、hook matcher 以及 `tools` 和 `disallowedTools` 選項仍接受的較早工具名稱。每個鍵是較早的名稱，其值是目前的名稱：例如，`Task` 對應至 `Agent`，`KillShell` 和 `KillBash` 對應至 `TaskStop`
5960
5961您可以用兩種測試中的任一種確認名稱：`BUILTIN_TOOL_NAMES` 包含它，或 `Object.hasOwn(LEGACY_TOOL_NAME_ALIASES, name)` 傳回 `true`。兩項測試都未通過的名稱仍可能有效，因為 `BUILTIN_TOOL_NAMES` 未列入 MCP 工具和某些內建工具。如果您從 `BUILTIN_TOOL_NAMES` 建立拒絕清單，Claude 仍可使用該常數未列入的工具。若要拒絕所有工具，請改為設定 [`disallowedTools: ["*"]`](https://code.claude.com/docs/zh-TW/agent-sdk/permissions#allow-and-deny-rules)。
5962
5963在 `BUILTIN_TOOL_NAMES` 中找到某個名稱，並不代表工作階段具有該工具：`TodoWrite` 雖然[預設為停用](https://code.claude.com/docs/zh-TW/tools-reference.md)，仍列於其中。若要查看工作階段具有哪些工具，請讀取其 [`SDKSystemMessage`](#sdksystemmessage) 的 `tools` 陣列。該陣列包含 MCP 工具，並將 Agent 工具列為 `Task`，因此在與 `BUILTIN_TOOL_NAMES` 比較之前，請先透過 `LEGACY_TOOL_NAME_ALIASES` 對應每個名稱。
5964
5802### `AbortError`5965### `AbortError`
5803 5966
5804中止操作的自訂錯誤類別。5967中止操作的自訂錯誤類別。
