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`를 설정하지 않은 채로 두는 것만으로는 충분하지 않습니다. MCP 사양의 기본값은 `true`이지만, Claude Code는 `always_ask` 호출을 처리할 때 설정되지 않은 `destructiveHint`를 `false`로 취급하기 때문입니다 |
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()` | 연결된 MCP 서버의 상태를 [`McpServerStatus`](#mcpserverstatus)`[]`로 반환합니다 |670| `mcpServerStatus()` | 연결된 MCP 서버의 상태를 [`McpServerStatus`](#mcpserverstatus)`[]`로 반환합니다 |
670| `getContextUsage(opts?)` | 세션의 컨텍스트 윈도우 사용량을 카테고리, 스킬, 도구별로 분류한 [`SDKControlGetContextUsageResponse`](#sdkcontrolgetcontextusageresponse)를 반환합니다. 기본 `detail`에서는 대화형 세션에서 `/context`가 보여 주는 데이터를 포함하며, 메시지 스트림에 나타나지 않는 토큰 계산 API 요청으로 계산됩니다. [이러한 요청이 처리되는 방식](#sdkcontrolgetcontextusageresponse)을 참조하세요. [`detail` 옵션](#sdkcontrolgetcontextusageresponse)에는 Agent SDK v0.3.257 이상이 필요합니다 |671| `getContextUsage(opts?)` | 세션의 컨텍스트 윈도우 사용량을 카테고리, 스킬, 도구별로 분류한 [`SDKControlGetContextUsageResponse`](#sdkcontrolgetcontextusageresponse)를 반환합니다. 기본 `detail`에서는 대화형 세션에서 `/context`가 보여 주는 데이터를 포함하며, 메시지 스트림에 나타나지 않는 토큰 계산 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)로 resolve되며, 권한 거부, 파일 없음 또는 전송 오류 시에는 `null`로 resolve됩니다. 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)로 resolve되며, 권한 거부, 파일 없음 또는 전송 오류 시에는 `null`로 resolve됩니다. TypeScript SDK v0.2.121 이상이 필요합니다 |
672| `reloadPlugins(options?)` | 디스크에서 플러그인을 다시 로드하여, 세션 중에 설치하거나 편집한 플러그인이 실행 중인 세션에 반영되도록 합니다. 세션의 명령, 서브에이전트, 플러그인, MCP 서버 상태를 나열하는 [`SDKControlReloadPluginsResponse`](#sdkcontrolreloadpluginsresponse)로 resolve됩니다. Agent SDK v0.2.85 이상이 필요합니다. [`holdOnCacheImpact` 옵션](#sdkcontrolreloadpluginsresponse)에는 Agent SDK v0.3.268 이상이 필요합니다 |673| `reloadPlugins(options?)` | 디스크에서 플러그인을 다시 로드하여 세션 중에 설치하거나 편집한 플러그인이 실행 중인 세션에 반영되도록 합니다. 세션의 명령, 서브에이전트, 플러그인, MCP 서버 상태를 나열하는 [`SDKControlReloadPluginsResponse`](#sdkcontrolreloadpluginsresponse)로 확인됩니다. 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()` | 디스크에서 스킬을 다시 로드하여, 세션 중에 추가하거나 편집한 스킬을 실행 중인 세션에서 사용할 수 있게 합니다. 다시 로드한 후 사용 가능한 스킬을 나열하는 [`SDKControlReloadSkillsResponse`](#sdkcontrolreloadskillsresponse)로 resolve됩니다. Agent SDK v0.3.163 이상이 필요합니다 |674| `reloadSkills()` | 디스크에서 스킬을 다시 로드하여, 세션 중에 추가하거나 편집한 스킬을 실행 중인 세션에서 사용할 수 있게 합니다. 다시 로드한 후 사용 가능한 스킬을 나열하는 [`SDKControlReloadSkillsResponse`](#sdkcontrolreloadskillsresponse)로 resolve됩니다. Agent SDK v0.3.163 이상이 필요합니다 |
674| `reloadOutputStyles()` | 디스크에서 [출력 스타일](https://code.claude.com/docs/ko/output-styles.md)을 다시 읽어, 세션 중에 추가하거나 편집한 스타일 파일을 실행 중인 세션에서 사용할 수 있게 합니다. 다시 로드한 후 사용 가능한 스타일 이름을 나열하는 [`SDKControlReloadOutputStylesResponse`](#sdkcontrolreloadoutputstylesresponse)로 resolve됩니다. Agent SDK v0.3.261 이상이 필요합니다 |675| `reloadOutputStyles()` | 디스크에서 [출력 스타일](https://code.claude.com/docs/ko/output-styles.md)을 다시 읽어, 세션 중에 추가하거나 편집한 스타일 파일을 실행 중인 세션에서 사용할 수 있게 합니다. 다시 로드한 후 사용 가능한 스타일 이름을 나열하는 [`SDKControlReloadOutputStylesResponse`](#sdkcontrolreloadoutputstylesresponse)로 resolve됩니다. 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`는 다시 로드가 등록하거나 제거할 플러그인 MCP 서버를 범위가 지정된 `plugin:<plugin>:<server>` 이름으로 나타냅니다. 이 이름은 플러그인 작성자가 정하므로 표시하기 전에 검증하세요. `lsp_tool_change`는 적용 시 LSP 도구가 추가되는지 제거되는지를 나타내며, 둘 다 아니면 `null`입니다. `may-` 형식은 검사가 대기 중인 플러그인 집합을 완전히 파악할 수 없었음을 의미합니다.1137`cache_impact`는 `held: true`와 함께 있을 때만 존재합니다. `mcp_servers_added`와 `mcp_servers_removed`는 다시 로드가 등록하거나 제거할 플러그인 MCP 서버를 범위가 지정된 `plugin:<plugin>:<server>` 이름으로 나타냅니다. 이 이름은 플러그인 작성자가 정하므로 표시하기 전에 검증하세요. `lsp_tool_change`는 적용 시 LSP 도구가 추가되는지 제거되는지를 나타내며, 둘 다 아니면 `null`입니다. `may-` 형식은 검사가 대기 중인 플러그인 집합을 완전히 파악할 수 없었음을 의미합니다.
1137 1138
1139#### `addPlugins`로 플러그인 폴더 추가 로드
1140
1141시작 시 [`plugins`](#options) 옵션에 없던 플러그인 폴더를 로드하려면, `path`가 절대 경로인 [`SdkPluginConfig`](#sdkpluginconfig) 항목 목록을 `addPlugins`로 `reloadPlugins()`에 전달합니다. Claude Code는 새 폴더를 로드하고 세션의 기존 플러그인을 한 번에 다시 로드합니다. 해당 폴더 항목에 [`skipMcpDiscovery`](#sdkpluginconfig)를 설정하지 않는 한, 추가된 각 플러그인의 MCP 서버도 연결됩니다. 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`가 포함되며, 플러그인의 명령과 서브에이전트가 `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는 잘못된 항목 하나 때문에 목록 전체를 거부하므로, 모든 항목을 절대 `path`를 가진 `{ type: "local", path }` 형식으로 전달해야 합니다
1162* **관리자가 관리형 설정에서 [`disableSideloadFlags`](https://code.claude.com/docs/ko/settings-reference#disablesideloadflags)를 켠 경우**: 메시지에 `reload_plugins add_plugins is disabled by managed settings (disableSideloadFlags)`가 표시됩니다. 폴더를 로드하려면 해당 관리자에게 설정 제거를 요청합니다
1163* **[샌드박스](https://code.claude.com/docs/ko/sandboxing.md)를 다시 빌드할 수 없는 경우**: [샌드박싱](#sandboxsettings)이 켜져 있으면 Claude Code는 샌드박스 처리된 셸 명령이 추가한 폴더에 쓸 수 없도록 샌드박스 구성을 다시 빌드합니다. 메시지에 `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[`createSdkMcpServer()`](#createsdkmcpserver)가 생성하여 애플리케이션 프로세스 내부에서 실행되는 인프로세스 MCP 서버의 구성입니다. `createSdkMcpServer()`가 반환하는 객체에, 직접 추가하는 선택적 [`McpServerToolPolicy`](#mcpservertoolpolicy) 항목의 `tools` 목록을 더한 것입니다. 서버 도구 중 하나에 대한 호출에 승인을 요구하거나 호출을 거부하려면 해당 도구 이름을 지정한 항목을 추가합니다.
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 이상이 필요하며, 각 `permission_policy` 값의 동작은 [`McpServerToolPolicy`](#mcpservertoolpolicy)에서 설명합니다.
1480
1481다음 예시는 `allowedTools` 와일드카드로 `records` 서버의 모든 도구를 미리 승인한 다음, `delete_record`를 `always_ask`로 표시하여 해당 호출이 어쨌든 `canUseTool`로 전달되도록 합니다. `destructiveHint: true` 어노테이션이 있으므로, 세션이 `auto` 모드에서 실행되어 자동 모드 [분류기](https://code.claude.com/docs/ko/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
1520Claude가 도구를 호출하면, `allowedTools` 항목이 원래라면 호출을 승인했을 것임에도 스크립트는 `delete_record` 도구가 실행되기 전에 `Approval requested for mcp__records__delete_record`를 출력합니다.
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 이상이 필요합니다. `pathToClaudeCodeExecutable`로 지정한 실행 파일과 같은 이전 Claude Code 실행 파일은 이 목록을 무시합니다. 그러면 `always_ask`와 `always_deny`가 적용되지 않으며, 각 호출은 [권한 흐름](https://code.claude.com/docs/ko/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`**: `allowedTools` 항목이나 허용 규칙이 해당하더라도 도구에 대한 각 호출은 [승인이 필요합니다](https://code.claude.com/docs/ko/agent-sdk/permissions.md#how-permissions-are-evaluated). 호출은 먼저 처리되지 않는 한 `canUseTool` 콜백 또는 [`permissionPromptToolName`](#options) 도구로 전달됩니다. 로드한 플러그인의 [mod](https://code.claude.com/docs/ko/plugins/mods/overview.md)가 [먼저 승인할 수 있습니다](https://code.claude.com/docs/ko/permissions.md#precedence-among-rules-hooks-and-mods). 그렇지 않으면 `dontAsk` 모드에서는 거부되고, [`auto`, `plan`, `bypassPermissions` 모드](#permission-modes-that-can-approve-an-always_ask-call)에서는 콜백에 도달하기 전에 승인될 수 있습니다
1553* **`always_deny`**: `bypassPermissions`를 포함한 모든 권한 모드에서 도구 호출이 [거부됩니다](https://code.claude.com/docs/ko/agent-sdk/permissions.md#how-permissions-are-evaluated). 단, 로드한 플러그인의 mod는 [여전히 승인할 수 있습니다](https://code.claude.com/docs/ko/permissions.md#precedence-among-rules-hooks-and-mods)
1554
1555`canUseTool`과 `permissionPromptToolName`을 모두 전달하지 않거나 [`permissionPrompts`](#options)를 `'none'`으로 설정하면, 먼저 처리되지 않은 `always_ask` 호출은 [`PermissionRequest` 훅](https://code.claude.com/docs/ko/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/ko/permission-modes.md#eliminate-prompts-with-auto-mode)가 호출을 검토하여 허용할 수 있습니다. `auto` 모드에서 모든 호출이 콜백에 도달하도록 하려면 도구의 [어노테이션](#toolannotations)에 `destructiveHint: true`를 설정합니다
1562* **`plan`**: 세션에서 [자동 모드를 사용할 수 있는](https://code.claude.com/docs/ko/permission-modes.md#eliminate-prompts-with-auto-mode) 동안, `readOnlyHint: true`로 어노테이션된 `always_ask` 도구에 대한 호출은 자동 모드 분류기로 전달되며, 분류기가 이를 허용할 수 있습니다. 다른 `always_ask` 도구에 대한 호출은 콜백에 도달합니다. 읽기 전용 도구의 호출도 콜백에 도달하도록 하려면 해당 도구의 어노테이션에 `readOnlyHint: true`와 함께 `destructiveHint: true`를 추가합니다. 또는 [`useAutoModeDuringPlan`](https://code.claude.com/docs/ko/settings-reference#useautomodeduringplan)을 `false`로 설정하여 계획 중에 분류기를 끌 수 있습니다
1563* **`bypassPermissions`**: [클라우드 세션](https://code.claude.com/docs/ko/claude-code-on-the-web.md)에서처럼 [`CLAUDE_CODE_REMOTE`](https://code.claude.com/docs/ko/env-vars#variables) 환경 변수가 `true`이면, 도구의 어노테이션과 관계없이 호출이 콜백 없이 승인됩니다. 그 외의 환경에서는 호출이 콜백에 도달합니다. 클라우드 세션에서도 콜백에 도달하도록 하려면 대신 `default` 또는 `acceptEdits` 모드로 세션을 실행합니다
1564
1565`auto` 및 `plan` 모드에서는 `destructiveHint`를 명시적으로 `true`로 설정합니다. `always_ask` 호출의 경우, [`ToolAnnotations`](#toolannotations)에 나열된 기본값은 `true`이지만 Claude Code는 설정되지 않은 `destructiveHint`를 `false`로 읽습니다.
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는 이 플러그인에서 스킬, 훅, 에이전트, 명령을 로드하지만 `.mcp.json`이나 매니페스트의 `mcpServers`는 읽지 않습니다. 애플리케이션이 플러그인의 MCP 연결을 직접 관리하는 경우 이 값을 설정하세요. |1593| `skipMcpDiscovery` | `boolean` | `true`인 경우, SDK는 이 플러그인에서 스킬, 훅, 에이전트, 명령을 로드하지만 `.mcp.json`이나 매니페스트의 `mcpServers`는 읽지 않습니다. 애플리케이션이 플러그인의 MCP 연결을 직접 관리하는 경우 이 값을 설정하세요. |
1469 1594
1470**예시:**1595**예시:**
5072};5197};
5073```5198```
5074 5199
5075`source`는 서버의 정의가 어디에서 왔는지를 나타내며, [`McpServerProvenance`](#mcpserverprovenance)의 `source`와 동일한 값 및 신뢰 규칙을 가집니다. 필드는 Agent SDK v0.3.274 이상이 필요하며 이전 버전에서는 없습니다.5200서버를 얼마나 신뢰할지 결정하려면 `source`를 사용하고, 서버가 해당 도구에 첨부한 UI 리소스를 찾으려면 각 `tools` 항목의 `_meta`를 사용하세요:
5201
5202* **`source`**: 서버의 정의가 어디에서 왔는지를 나타내며, [`McpServerProvenance`](#mcpserverprovenance)의 `source`와 동일한 값을 가집니다. 다른 서버가 어떤 이름으로 등록되든 자체 인프로세스 서버만 `sdk`를 보고하므로, `name`이 아닌 `source`를 기반으로 신뢰 결정을 내리세요. `source` 값을 인식하지 못하는 경우, 해당 서버를 `source`가 `sdk`가 아닌 다른 서버와 동일하게 취급하세요. Agent SDK v0.3.274 이상이 필요합니다
5203* **`_meta`**: 서버가 도구에 대해 선언한 `_meta`의 `ui` 객체와 `ui/resourceUri` 문자열입니다. Claude Code는 다른 모든 `_meta` 키를 보류합니다. `ui/resourceUri`는 `ui.resourceUri`의 이전 최상위 표기입니다. 서버가 도구에 [MCP Apps UI 리소스](https://code.claude.com/docs/ko/mcp.md#reference-mcp-resources)를 첨부하면 `ui.resourceUri` 또는 `ui/resourceUri`에 리소스의 `ui://` URI가 담깁니다. [`readMcpResource()`](#query-object)로 해당 URI를 가져와 애플리케이션에서 리소스를 렌더링하세요. Agent SDK v0.3.280 이상이 필요합니다
5204
5205Claude Code는 subtype이 `init`인 `system` 메시지의 [`capabilities`](#sdksystemmessage) 배열에 `mcp_tool_ui_meta_v1`이 나열될 때만 `_meta`를 전송합니다. `mcp_tool_ui_meta_v1`은 직접 켜는 것이 아닙니다.
5206
5207#### 도구의 `_meta.ui`에 `visibility`만 있는 경우
5208
5209서버가 도구에 대해 `ui.resourceUri`를 선언했지만 애플리케이션이 받은 `_meta.ui`에 `visibility`만 있다면, 서버가 보낸 `ui` 객체가 Claude Code의 검사 중 하나를 통과하지 못한 것입니다. Claude Code는 `ui`와 `ui/resourceUri`를 별도로 검사하므로, 한 키가 실패해도 다른 키는 애플리케이션에 도달할 수 있습니다. 서버의 `tools/list` 응답에 있는 `_meta`를 각 키에 대한 검사와 비교하세요:
5210
5211* **`ui`**: 다음 세 가지 검사를 모두 통과하면 `resourceUri` 및 `visibility` 이외의 멤버를 포함하여 변경 없이 애플리케이션에 도달합니다:
5212
5213 * `resourceUri`가 없거나, `ui://`로 시작하는 문자열입니다
5214 * `visibility`가 없거나, `"model"`과 `"app"`만 나열합니다
5215 * 전체 객체를 JSON으로 직렬화했을 때 최대 4,096자입니다
5216
5217 검사 중 하나라도 실패하면, 애플리케이션은 기껏해야 서버가 나열한 `"model"` 및 `"app"` 항목으로 된 `visibility` 배열만을 유일한 멤버로 가진 `ui`를 받습니다.
5218* **`ui/resourceUri`**: `ui://`로 시작하고 최대 4,096자인 문자열이면 애플리케이션에 도달합니다. 그렇지 않으면 Claude Code가 이를 삭제합니다
5076 5219
5077`tools` 항목의 `_meta`는 해당 도구의 `_meta`의 MCP Apps 멤버를 전달하므로, 애플리케이션이 [`readMcpResource()`](#query-object)로 렌더링할 `ui://` 리소스를 찾을 수 있습니다. Claude Code는 `ui` 객체와 deprecated된 평면 `ui/resourceUri` 문자열을 통과시키고, 다른 모든 키를 보류합니다. `ui` 내에서 `resourceUri`는 `ui://` 문자열이고 `visibility`는 서버가 설정할 때 `"model"` 및 `"app"`의 배열이며, 다른 멤버는 변경되지 않고 통과합니다. Claude Code는 값이 잘못된 형식일 때 어느 키든 삭제하고, 도구가 둘 다 선언하지 않을 때 `_meta`를 생략합니다. 필드는 초기화 메시지의 [`capabilities`](#sdksystemmessage)에 `mcp_tool_ui_meta_v1`이 포함될 때만 나타나며, TypeScript Agent SDK v0.3.280 이상이 필요합니다.5220Claude Code에 전송할 `ui` 멤버와 `ui/resourceUri` 문자열이 하나도 남지 않으면, 해당 `tools` 항목에는 `_meta`가 전혀 없습니다.
5078 5221
5079### `McpServerStatusConfig`5222### `McpServerStatusConfig`
5080 5223
5309`setMcpServers()`를 호출할 때, Claude Code는 다음 규칙을 적용합니다:5452`setMcpServers()`를 호출할 때, Claude Code는 다음 규칙을 적용합니다:
5310 5453
5311* **호출이 이름을 지정하지 않는 서버**: [클라우드 세션](https://code.claude.com/docs/ko/claude-code-on-the-web.md) 외부에서 Claude Code는 이전 `setMcpServers()` 호출이 추가한 서버와 인프로세스 SDK 서버의 연결을 끊고 이를 `removed`에 나열합니다. 다른 서버는 계속 실행되며 `removed`에 나열되지 않습니다. 여기에는 [`mcpServers`](#options) 옵션의 stdio, HTTP 및 SSE 서버, 설정 파일의 서버, 플러그인 제공 서버가 포함됩니다.5454* **호출이 이름을 지정하지 않는 서버**: [클라우드 세션](https://code.claude.com/docs/ko/claude-code-on-the-web.md) 외부에서 Claude Code는 이전 `setMcpServers()` 호출이 추가한 서버와 인프로세스 SDK 서버의 연결을 끊고 이를 `removed`에 나열합니다. 다른 서버는 계속 실행되며 `removed`에 나열되지 않습니다. 여기에는 [`mcpServers`](#options) 옵션의 stdio, HTTP 및 SSE 서버, 설정 파일의 서버, 플러그인 제공 서버가 포함됩니다.
5312* **호출이 이름을 지정하는 서버**: Claude Code는 이전 `setMcpServers()` 호출이 추가한 stdio, HTTP 또는 SSE 서버를 해당 구성이 전달한 것과 다를 때만 교체합니다. 해당 이름으로 이미 등록된 인프로세스 SDK 서버는 그대로 유지되므로, 이를 교체하려면 한 호출에서 제외한 다음 호출에서 추가하세요.5455* **이전 `setMcpServers()` 호출이 추가한 stdio, HTTP 및 SSE 서버**: 클라우드 세션 외부에서, 동일한 구성으로 다시 이름을 지정한 서버는 연결과 도구를 유지합니다. 이 서버는 `added`와 `removed` 어디에도 나타나지 않습니다. 변경된 구성을 전달하면 Claude Code는 해당 구성을 사용하여 서버를 다시 연결하고 `removed`가 아닌 `added`에 나열합니다.
5456* **이전 호출이 추가하지 않았는데 호출이 이름을 지정하는 stdio, HTTP 및 SSE 서버**: 클라우드 세션 외부에서 Claude Code는 서버를 추가하고 `added`에 나열하며, 서버를 거부하는 경우에는 `errors`에 나열합니다.
5457* **호출이 이름을 지정하는 인프로세스 SDK 서버**: `mcpServers` 또는 이전 호출을 통해 이미 등록된 서버는 실행 중인 인스턴스와 타임아웃을 유지합니다. 해당 서버에 대해 [`tools` 정책 목록](#mcpsdkserverconfigwithinstance)을 전달하면, 빈 목록이라도 정책이 교체됩니다. 그렇지 않으면 정책이 그대로 유지됩니다. 클라우드 세션 외부에서 새 인스턴스를 실행하려면 한 호출에서 서버를 제외한 다음 호출에서 이름을 지정하세요.
5313* **CLI가 시작 시 시작한 기본 제공 서버**: 호출이 하나를 이름으로 지정하면, Claude Code는 해당 항목을 삭제하고 `errors`에서 보고합니다.5458* **CLI가 시작 시 시작한 기본 제공 서버**: 호출이 하나를 이름으로 지정하면, Claude Code는 해당 항목을 삭제하고 `errors`에서 보고합니다.
5314* **`.mcp.json`과 같은 MCP 설치 범위의 서버와 이름이 같은 stdio, HTTP 또는 SSE 서버**: 해당 이름에 대해 세션은 [설치 범위 서버](https://code.claude.com/docs/ko/mcp.md#mcp-installation-scopes)의 도구 대신 사용자의 서버 도구를 사용합니다. Claude Code v2.1.305 이전에는 앱이 [플러그인을 다시 로드](#query-object)할 때 Claude Code가 사용자의 서버 연결을 끊고 설치 범위 서버를 연결할 수 있었습니다.5459* **`.mcp.json`과 같은 MCP 설치 범위의 서버와 이름이 같은 stdio, HTTP 또는 SSE 서버**: 해당 이름에 대해 세션은 [설치 범위 서버](https://code.claude.com/docs/ko/mcp.md#mcp-installation-scopes)의 도구 대신 사용자의 서버 도구를 사용합니다. Claude Code v2.1.305 이전에는 앱이 [플러그인을 다시 로드](#query-object)할 때 Claude Code가 사용자의 서버 연결을 끊고 설치 범위 서버를 연결할 수 있었습니다.
5315 5460
5796 5941
5797SDK의 게시된 타이핑은 Claude Code v2.1.203 이상에서 `SDKConversationResetMessage`를 선언합니다. v2.1.203 이전에는 `SDKMessage`가 타입을 선언하지 않고 참조했으므로, `skipLibCheck`가 비활성화되었을 때 `type === "conversation_reset"`에 대한 타입 좁히기가 타입 검사에 실패했습니다.5942SDK의 게시된 타이핑은 Claude Code v2.1.203 이상에서 `SDKConversationResetMessage`를 선언합니다. v2.1.203 이전에는 `SDKMessage`가 타입을 선언하지 않고 참조했으므로, `skipLibCheck`가 비활성화되었을 때 `type === "conversation_reset"`에 대한 타입 좁히기가 타입 검사에 실패했습니다.
5798 5943
5944### `BUILTIN_TOOL_NAMES` 및 `LEGACY_TOOL_NAME_ALIASES`
5945
5946애플리케이션 사용자가 입력하는 도구 이름을 확인하려면 이 두 상수를 사용하세요. 두 상수 모두 각 이름을 권한 규칙, 훅 matcher, `tools` 및 `disallowedTools` 옵션에서 작성하는 방식 그대로 표기합니다. `@anthropic-ai/claude-agent-sdk` 또는 `@anthropic-ai/claude-agent-sdk/core`에서 가져오세요. Agent SDK v0.3.301 이상이 필요하며 알파 상태입니다.
5947
5948SDK의 타입 선언은 `BUILTIN_TOOL_NAMES`에 readonly 튜플 타입을, `LEGACY_TOOL_NAME_ALIASES`에 문자열-문자열 레코드 타입을 부여합니다:
5949
5950```typescript theme={null}
5951const BUILTIN_TOOL_NAMES: readonly ["Agent", /* ...more names... */ "Write"];
5952const LEGACY_TOOL_NAME_ALIASES: Readonly<Record<string, string>>;
5953```
5954
5955* **`BUILTIN_TOOL_NAMES`**: `Agent`, `Bash`, `Read` 같은 Claude Code 기본 제공 도구의 이름을 알파벳순으로 나열합니다. MCP 도구 이름은 포함되지 않습니다. 타입이 문자열 리터럴의 튜플이므로, `(typeof BUILTIN_TOOL_NAMES)[number]`로 이름들의 유니온 타입을 얻을 수 있습니다
5956* **`LEGACY_TOOL_NAME_ALIASES`**: 권한 규칙, 훅 matcher, `tools` 및 `disallowedTools` 옵션이 여전히 허용하는 이전 도구 이름입니다. 각 키는 이전 이름이고 값은 현재 이름입니다. 예를 들어 `Task`는 `Agent`에 매핑되고, `KillShell`과 `KillBash`는 `TaskStop`에 매핑됩니다
5957
5958이름은 두 가지 검사 중 하나로 확인할 수 있습니다. `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/ko/agent-sdk/permissions#allow-and-deny-rules)를 설정하세요.
5959
5960`BUILTIN_TOOL_NAMES`에서 이름을 찾았다고 해서 세션에 해당 도구가 있다는 의미는 아닙니다. `TodoWrite`는 [기본적으로 비활성화](https://code.claude.com/docs/ko/tools-reference.md)되어 있지만 목록에 포함되어 있습니다. 세션에 어떤 도구가 있는지 확인하려면 해당 세션의 [`SDKSystemMessage`](#sdksystemmessage)에 있는 `tools` 배열을 읽으세요. 이 배열은 MCP 도구를 포함하고 Agent 도구를 `Task`로 나열하므로, `BUILTIN_TOOL_NAMES`와 비교하기 전에 각 이름을 `LEGACY_TOOL_NAME_ALIASES`로 매핑하세요.
5961
5799### `AbortError`5962### `AbortError`
5800 5963
5801중단 작업을 위한 사용자 정의 오류 클래스입니다.5964중단 작업을 위한 사용자 정의 오류 클래스입니다.
