200| :- | :- | :- | :- |200| :- | :- | :- | :- |
201| `title` | `string` | `undefined` | Título legível para a ferramenta |201| `title` | `string` | `undefined` | Título legível para a ferramenta |
202| `readOnlyHint` | `boolean` | `false` | Se `true`, a ferramenta não modifica seu ambiente |202| `readOnlyHint` | `boolean` | `false` | Se `true`, a ferramenta não modifica seu ambiente |
203| `destructiveHint` | `boolean` | `true` | Se `true`, a ferramenta pode realizar atualizações destrutivas (apenas significativo quando `readOnlyHint` é `false`) |203| `destructiveHint` | `boolean` | `true` | Se `true`, a ferramenta pode realizar atualizações destrutivas. Defina `destructiveHint: true` explicitamente em qualquer ferramenta que você marcar como [`always_ask`](#mcpservertoolpolicy), caso contrário o classificador do modo auto pode aprovar as chamadas dessa ferramenta no lugar do seu callback `canUseTool`. Deixar `destructiveHint` sem definir não é suficiente, porque o Claude Code trata um `destructiveHint` não definido como `false` ao lidar com chamadas `always_ask`, embora o padrão da especificação MCP seja `true` |
204| `idempotentHint` | `boolean` | `false` | Se `true`, chamadas repetidas com os mesmos argumentos não têm efeito adicional (apenas significativo quando `readOnlyHint` é `false`) |204| `idempotentHint` | `boolean` | `false` | Se `true`, chamadas repetidas com os mesmos argumentos não têm efeito adicional (apenas significativo quando `readOnlyHint` é `false`) |
205| `openWorldHint` | `boolean` | `true` | Se `true`, a ferramenta interage com entidades externas (por exemplo, busca na web). Se `false`, o domínio da ferramenta é fechado (por exemplo, uma ferramenta de memória) |205| `openWorldHint` | `boolean` | `true` | Se `true`, a ferramenta interage com entidades externas (por exemplo, busca na web). Se `false`, o domínio da ferramenta é fechado (por exemplo, uma ferramenta de memória) |
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()` | Retorna o status dos servidores MCP conectados como [`McpServerStatus`](#mcpserverstatus)`[]` |670| `mcpServerStatus()` | Retorna o status dos servidores MCP conectados como [`McpServerStatus`](#mcpserverstatus)`[]` |
670| `getContextUsage(opts?)` | Retorna um [`SDKControlGetContextUsageResponse`](#sdkcontrolgetcontextusageresponse) que detalha o uso da janela de contexto da sessão por categoria, skill e ferramenta. Com o `detail` padrão, inclui os dados que `/context` mostra em uma sessão interativa, calculados com requisições de contagem de tokens à API que não aparecem no fluxo de mensagens; consulte [como essas requisições são tratadas](#sdkcontrolgetcontextusageresponse). A [opção `detail`](#sdkcontrolgetcontextusageresponse) requer o Agent SDK v0.3.257 ou posterior |671| `getContextUsage(opts?)` | Retorna um [`SDKControlGetContextUsageResponse`](#sdkcontrolgetcontextusageresponse) que detalha o uso da janela de contexto da sessão por categoria, skill e ferramenta. Com o `detail` padrão, inclui os dados que `/context` mostra em uma sessão interativa, calculados com requisições de contagem de tokens à API que não aparecem no fluxo de mensagens; consulte [como essas requisições são tratadas](#sdkcontrolgetcontextusageresponse). A [opção `detail`](#sdkcontrolgetcontextusageresponse) requer o Agent SDK v0.3.257 ou posterior |
671| `readFile(path, options?)` | Lê um arquivo do sistema de arquivos da sessão. O Claude Code resolve o caminho em relação a `cwd`; [O que `readFile()` pode ler](#what-readfile-can-read) lista os arquivos que ele fornece. Passe `{ maxBytes }` para alterar o limite de leitura (padrão de 1 MB, teto de 10 MB) e `{ encoding: 'base64' }` para arquivos binários, como imagens. É resolvido com um [`SDKControlReadFileResponse`](#sdkcontrolreadfileresponse), ou `null` em caso de negação de permissão, arquivo ausente ou erro de transporte. Requer o TypeScript SDK v0.2.121 ou posterior |672| `readFile(path, options?)` | Lê um arquivo do sistema de arquivos da sessão. O Claude Code resolve o caminho em relação a `cwd`; [O que `readFile()` pode ler](#what-readfile-can-read) lista os arquivos que ele fornece. Passe `{ maxBytes }` para alterar o limite de leitura (padrão de 1 MB, teto de 10 MB) e `{ encoding: 'base64' }` para arquivos binários, como imagens. É resolvido com um [`SDKControlReadFileResponse`](#sdkcontrolreadfileresponse), ou `null` em caso de negação de permissão, arquivo ausente ou erro de transporte. Requer o TypeScript SDK v0.2.121 ou posterior |
672| `reloadPlugins(options?)` | Recarrega os plugins do disco, para que plugins que você instala ou edita no meio da sessão cheguem à sessão em execução. É resolvido com um [`SDKControlReloadPluginsResponse`](#sdkcontrolreloadpluginsresponse) listando os comandos, subagentes, plugins e o status dos servidores MCP da sessão. Requer o Agent SDK v0.2.85 ou posterior. A [opção `holdOnCacheImpact`](#sdkcontrolreloadpluginsresponse) requer o Agent SDK v0.3.268 ou posterior |673| `reloadPlugins(options?)` | Recarrega os plugins do disco, para que plugins que você instala ou edita no meio da sessão cheguem à sessão em execução. Resolve com um [`SDKControlReloadPluginsResponse`](#sdkcontrolreloadpluginsresponse) listando os comandos, subagentes, plugins e o status dos servidores MCP da sessão. Requer Agent SDK v0.2.85 ou posterior. A [opção `holdOnCacheImpact`](#sdkcontrolreloadpluginsresponse) requer Agent SDK v0.3.268 ou posterior. A [opção `addPlugins`](#load-more-plugin-folders-with-addplugins) requer Agent SDK v0.3.301 ou posterior |
673| `reloadSkills()` | Recarrega as skills do disco, para que skills que você adiciona ou edita no meio da sessão fiquem disponíveis para a sessão em execução. É resolvido com um [`SDKControlReloadSkillsResponse`](#sdkcontrolreloadskillsresponse) listando as skills disponíveis após o recarregamento. Requer o Agent SDK v0.3.163 ou posterior |674| `reloadSkills()` | Recarrega as skills do disco, para que skills que você adiciona ou edita no meio da sessão fiquem disponíveis para a sessão em execução. É resolvido com um [`SDKControlReloadSkillsResponse`](#sdkcontrolreloadskillsresponse) listando as skills disponíveis após o recarregamento. Requer o Agent SDK v0.3.163 ou posterior |
674| `reloadOutputStyles()` | Relê os [estilos de saída](https://code.claude.com/docs/pt/output-styles.md) do disco, para que um arquivo de estilo que você adiciona ou edita no meio da sessão fique disponível para a sessão em execução. É resolvido com um [`SDKControlReloadOutputStylesResponse`](#sdkcontrolreloadoutputstylesresponse) listando os nomes de estilos disponíveis após o recarregamento. Requer o Agent SDK v0.3.261 ou posterior |675| `reloadOutputStyles()` | Relê os [estilos de saída](https://code.claude.com/docs/pt/output-styles.md) do disco, para que um arquivo de estilo que você adiciona ou edita no meio da sessão fique disponível para a sessão em execução. É resolvido com um [`SDKControlReloadOutputStylesResponse`](#sdkcontrolreloadoutputstylesresponse) listando os nomes de estilos disponíveis após o recarregamento. Requer o Agent SDK v0.3.261 ou posterior |
675| `seedReadState(path, mtime)` | Marca um arquivo como já lido para que um Edit posterior não falhe com `File has not been read yet`. Consulte [`seedReadState()`](#seedreadstate). Requer o TypeScript SDK v0.2.83 ou posterior |676| `seedReadState(path, mtime)` | Marca um arquivo como já lido para que um Edit posterior não falhe com `File has not been read yet`. Consulte [`seedReadState()`](#seedreadstate). Requer o TypeScript SDK v0.2.83 ou posterior |
1135 1136
1136`cache_impact` está presente apenas junto com `held: true`. `mcp_servers_added` e `mcp_servers_removed` nomeiam os servidores MCP de plugins que o recarregamento registraria ou removeria, como nomes com escopo `plugin:<plugin>:<server>`. Os nomes são definidos pelos autores dos plugins, então valide-os antes de exibi-los. `lsp_tool_change` informa se a aplicação adicionaria ou removeria a ferramenta LSP, ou `null` quando não faria nenhuma das duas coisas. As formas `may-` significam que a verificação não conseguiu ver completamente o conjunto de plugins pendente.1137`cache_impact` está presente apenas junto com `held: true`. `mcp_servers_added` e `mcp_servers_removed` nomeiam os servidores MCP de plugins que o recarregamento registraria ou removeria, como nomes com escopo `plugin:<plugin>:<server>`. Os nomes são definidos pelos autores dos plugins, então valide-os antes de exibi-los. `lsp_tool_change` informa se a aplicação adicionaria ou removeria a ferramenta LSP, ou `null` quando não faria nenhuma das duas coisas. As formas `may-` significam que a verificação não conseguiu ver completamente o conjunto de plugins pendente.
1137 1138
1139#### Carregar mais pastas de plugins com `addPlugins`
1140
1141Para carregar pastas de plugins que não estavam na opção [`plugins`](#options) na inicialização, passe-as para `reloadPlugins()` como `addPlugins`, uma lista de entradas [`SdkPluginConfig`](#sdkpluginconfig) cujo `path` é absoluto. O Claude Code carrega as novas pastas e recarrega os plugins existentes da sessão em uma única passagem. Os servidores MCP de cada plugin adicionado também se conectam, a menos que você defina [`skipMcpDiscovery`](#sdkpluginconfig) na entrada dessa pasta. Requer o Agent SDK v0.3.301 ou posterior e o Claude Code v2.1.301 ou posterior.
1142
1143Este exemplo adiciona uma pasta a uma query `q` em execução e imprime o caminho de instalação de cada plugin que a sessão carregou quando a chamada retorna:
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
1153Se a pasta foi carregada, a lista impressa inclui `/opt/my-app/plugins/reports`, e os comandos e subagentes do plugin aparecem em `result.commands` e `result.agents`.
1154
1155Uma pasta adicionada permanece parte da sessão. Quando você chama `reloadPlugins()` novamente, o Claude Code a recarrega com os outros plugins, e você não a passa em `addPlugins` de novo.
1156
1157##### Quando `reloadPlugins()` não carrega as pastas de `addPlugins`
1158
1159Se `reloadPlugins()` for rejeitada, nenhuma das pastas de `addPlugins` é adicionada, então passe-as em `addPlugins` novamente ao tentar novamente. Quando a rejeição tem uma das causas a seguir, a sessão mantém os plugins que já tinha:
1160
1161* **Um `path` relativo ou uma entrada malformada**: a mensagem de erro diz `add_plugins must be a list of { type: "local", path } entries with absolute paths`. O Claude Code recusa a lista inteira por causa de uma única entrada inválida, então passe cada entrada como `{ type: "local", path }` com um `path` absoluto
1162* **Um administrador ativou [`disableSideloadFlags`](https://code.claude.com/docs/pt/settings-reference#disablesideloadflags) nas suas configurações gerenciadas**: a mensagem diz `reload_plugins add_plugins is disabled by managed settings (disableSideloadFlags)`. Para carregar a pasta, peça a esse administrador que remova a configuração
1163* **O [sandbox](https://code.claude.com/docs/pt/sandboxing.md) não pôde ser reconstruído**: com o [sandboxing](#sandboxsettings) ativado, o Claude Code reconstrói a configuração do sandbox para que comandos de shell em sandbox não possam gravar nas pastas que você adiciona. A mensagem diz `the sandbox could not be rebuilt to keep shell commands out of this folder`. Verifique se as suas [configurações de sandbox](#sandboxsettings) ainda formam uma configuração válida
1164
1165Se você passar `holdOnCacheImpact` e a chamada for resolvida com [`held: true`](#sdkcontrolreloadpluginsresponse), as pastas de `addPlugins` não são adicionadas. Para adicioná-las mesmo assim, chame `reloadPlugins()` novamente com a mesma lista `addPlugins` e sem `holdOnCacheImpact`.
1166
1167Quando a chamada é resolvida sem `held: true` e uma pasta ainda está ausente de `result.plugins`, comece verificando estas causas:
1168
1169* **A pasta não existe ou o plugin dela falhou ao carregar**: `result.error_count` é `1` ou maior. Mesmo assim, a pasta permanece parte da sessão. Depois de corrigir a pasta, chame `reloadPlugins()` novamente para carregá-la, desta vez sem listá-la em `addPlugins`
1170* **O executável do Claude Code é anterior à v2.1.301**: um executável anterior à v2.1.301 ignora `addPlugins` e recarrega somente os plugins que a sessão já tinha. Verifique `claude_code_version` na [mensagem de inicialização](#sdksystemmessage) e execute um executável na v2.1.301 ou posterior
1171
1138### `SDKControlReloadSkillsResponse`1172### `SDKControlReloadSkillsResponse`
1139 1173
1140Tipo de retorno de [`reloadSkills()`](#query-object).1174Tipo de retorno de [`reloadSkills()`](#query-object).
1430 1464
1431#### `McpSdkServerConfigWithInstance`1465#### `McpSdkServerConfigWithInstance`
1432 1466
1467A configuração para um servidor MCP em processo, um que [`createSdkMcpServer()`](#createsdkmcpserver) cria e que é executado dentro do processo da sua aplicação. É o objeto que `createSdkMcpServer()` retorna, mais uma lista opcional `tools` de entradas [`McpServerToolPolicy`](#mcpservertoolpolicy) que você mesmo adiciona. Para exigir aprovação para chamadas a uma das ferramentas do servidor, ou para negá-las, adicione uma entrada que nomeie a ferramenta.
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
1479Para definir uma política, espalhe o objeto que `createSdkMcpServer()` retorna em um novo objeto em `mcpServers` e adicione a lista `tools` a esse novo objeto. A opção `tools` do próprio `createSdkMcpServer()` é uma lista diferente, que contém as definições das ferramentas e não aceita entradas de política. A lista de políticas requer o Agent SDK v0.3.301 ou posterior, e [`McpServerToolPolicy`](#mcpservertoolpolicy) descreve o que cada valor de `permission_policy` faz.
1480
1481Este exemplo pré-aprova todas as ferramentas do servidor `records` com um curinga em `allowedTools` e, em seguida, marca `delete_record` como `always_ask` para que as chamadas a ela cheguem a `canUseTool` mesmo assim. Com a anotação `destructiveHint: true`, a chamada ainda chega ao callback se a sessão for executada no modo `auto`, em que o [classificador](https://code.claude.com/docs/pt/permission-modes.md#eliminate-prompts-with-auto-mode) do modo auto poderia aprová-la de outra forma.
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
1520Quando o Claude chama a ferramenta, o script imprime `Approval requested for mcp__records__delete_record` antes de a ferramenta `delete_record` ser executada, embora a entrada de `allowedTools` fosse, de outra forma, aprovar a chamada.
1521
1522Para alterar ou remover a política de uma ferramenta enquanto a sessão está em execução, passe a configuração do servidor com um novo valor de `tools` para [`setMcpServers()`](#mcpsetserversresult). O valor de `tools` que você passa entra em vigor a partir da próxima chamada do Claude às ferramentas desse servidor:
1523
1524* **Uma lista com entradas**: as entradas substituem as políticas atuais
1525* **Uma lista vazia**: todas as políticas do servidor são removidas
1526* **Nenhuma chave `tools`**: as políticas atuais permanecem
1527
1528Inclua nessa chamada os seus outros servidores em processo e qualquer servidor que uma chamada anterior de `setMcpServers()` tenha adicionado, caso contrário a chamada os desconecta.
1529
1530#### `McpServerToolPolicy`
1531
1532Uma entrada na lista `tools` de um [`McpSdkServerConfigWithInstance`](#mcpsdkserverconfigwithinstance), que nomeia uma das ferramentas do servidor e define a política de permissão para chamadas a essa ferramenta. A lista requer o Agent SDK v0.3.301 ou posterior e o Claude Code v2.1.301 ou posterior. Um executável mais antigo do Claude Code, como um executável para o qual você aponta `pathToClaudeCodeExecutable`, ignora a lista. Nesse caso, `always_ask` e `always_deny` não são aplicados, e cada chamada passa pelo [fluxo de permissões](https://code.claude.com/docs/pt/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| Campo | Tipo | Descrição |
1543| :- | :- | :- |
1544| `name` | `string` | O nome simples da ferramenta, como passado para [`tool()`](#tool), sem o prefixo `mcp__<server>__` |
1545| `permission_policy` | `'always_allow' \| 'always_ask' \| 'always_deny'` | A política de aprovação para as chamadas da ferramenta, [`always_ask` ou `always_deny`](#permission-policy-values). `always_allow` é ignorado em um servidor em processo: para pré-aprovar uma ferramenta, liste-a em [`allowedTools`](#options) em vez disso |
1546| `org_max_permission` | `'allow' \| 'ask' \| 'blocked'` | Um limite máximo por ferramenta que um administrador da organização define. Ignorado em um servidor em processo, então deixe-o sem definir |
1547
1548##### Valores de `permission_policy`
1549
1550Escolha `always_ask` para aprovar cada chamada você mesmo, ou `always_deny` para bloquear a ferramenta completamente:
1551
1552* **`always_ask`**: cada chamada à ferramenta [precisa de aprovação](https://code.claude.com/docs/pt/agent-sdk/permissions.md#how-permissions-are-evaluated), mesmo que uma entrada de `allowedTools` ou uma regra de permissão a cubra. A chamada vai para o seu callback `canUseTool` ou para a ferramenta [`permissionPromptToolName`](#options), a menos que seja resolvida antes. Um [mod](https://code.claude.com/docs/pt/plugins/mods/overview.md) em um plugin que você carrega [pode aprová-la antes](https://code.claude.com/docs/pt/permissions.md#precedence-among-rules-hooks-and-mods). Caso contrário, no modo `dontAsk` ela é negada, e nos [modos `auto`, `plan` e `bypassPermissions`](#permission-modes-that-can-approve-an-always_ask-call) ela pode ser aprovada antes de chegar ao seu callback
1553* **`always_deny`**: uma chamada à ferramenta [é negada](https://code.claude.com/docs/pt/agent-sdk/permissions.md#how-permissions-are-evaluated) em todos os modos de permissão, incluindo `bypassPermissions`, mas um mod em um plugin que você carrega [ainda pode aprová-la](https://code.claude.com/docs/pt/permissions.md#precedence-among-rules-hooks-and-mods)
1554
1555Se você não passar nem `canUseTool` nem `permissionPromptToolName`, ou definir [`permissionPrompts`](#options) como `'none'`, uma chamada `always_ask` que não seja resolvida antes é negada, a menos que um [hook `PermissionRequest`](https://code.claude.com/docs/pt/hooks#permissionrequest) a permita.
1556
1557##### Modos de permissão que podem aprovar uma chamada `always_ask`
1558
1559Nos modos `auto`, `plan` e `bypassPermissions`, uma chamada a uma ferramenta marcada como [`always_ask`](#permission-policy-values) pode ser aprovada antes de chegar ao seu callback `canUseTool`. Encontre o modo da sua sessão nesta lista para ver quando essa aprovação acontece e o que definir para que a chamada chegue ao seu callback mesmo assim:
1560
1561* **`auto`**: o [classificador](https://code.claude.com/docs/pt/permission-modes.md#eliminate-prompts-with-auto-mode) do modo auto revisa a chamada e pode permiti-la. Para fazer com que todas as chamadas cheguem ao seu callback no modo `auto`, defina `destructiveHint: true` nas [anotações](#toolannotations) da ferramenta
1562* **`plan`**: enquanto o [modo auto estiver disponível](https://code.claude.com/docs/pt/permission-modes.md#eliminate-prompts-with-auto-mode) para a sessão, as chamadas a uma ferramenta `always_ask` anotada com `readOnlyHint: true` vão para o classificador do modo auto, que pode permiti-las. As chamadas a outras ferramentas `always_ask` chegam ao seu callback. Para fazer com que as chamadas de uma ferramenta somente leitura também cheguem ao seu callback, adicione `destructiveHint: true` às anotações dessa ferramenta junto com `readOnlyHint: true`. Como alternativa, defina [`useAutoModeDuringPlan`](https://code.claude.com/docs/pt/settings-reference#useautomodeduringplan) como `false`, o que desativa o classificador durante o planejamento
1563* **`bypassPermissions`**: quando a variável de ambiente [`CLAUDE_CODE_REMOTE`](https://code.claude.com/docs/pt/env-vars#variables) é `true`, como acontece em uma [sessão na nuvem](https://code.claude.com/docs/pt/claude-code-on-the-web.md), a chamada é aprovada sem o seu callback, independentemente das anotações da ferramenta. Em qualquer outro lugar, a chamada chega ao seu callback. Para fazer com que ela chegue ao seu callback também em uma sessão na nuvem, execute a sessão no modo `default` ou `acceptEdits` em vez disso
1564
1565Defina `destructiveHint` como `true` explicitamente nos modos `auto` e `plan`. Para chamadas `always_ask`, o Claude Code interpreta um `destructiveHint` não definido como `false`, embora o padrão listado em [`ToolAnnotations`](#toolannotations) seja `true`.
1566
1442#### `McpClaudeAIProxyServerConfig`1567#### `McpClaudeAIProxyServerConfig`
1443 1568
1444```typescript theme={null}1569```typescript theme={null}
1464| Campo | Tipo | Descrição |1589| Campo | Tipo | Descrição |
1465| :- | :- | :- |1590| :- | :- | :- |
1466| `type` | `'local'` | Deve ser `'local'` (atualmente apenas plugins locais são suportados) |1591| `type` | `'local'` | Deve ser `'local'` (atualmente apenas plugins locais são suportados) |
1467| `path` | `string` | Caminho absoluto ou relativo para o diretório do plugin |1592| `path` | `string` | Caminho para o diretório do plugin. Um caminho relativo é resolvido em relação à opção [`cwd`](#options) quando a sessão inicia. O caminho deve ser absoluto quando você carrega o plugin no meio da sessão com [`addPlugins`](#load-more-plugin-folders-with-addplugins) |
1468| `skipMcpDiscovery` | `boolean` | Quando `true`, o SDK carrega skills, hooks, agentes e comandos deste plugin, mas não lê seu `.mcp.json` nem os `mcpServers` do manifesto. Defina isso quando sua aplicação for responsável pelas conexões MCP do plugin. |1593| `skipMcpDiscovery` | `boolean` | Quando `true`, o SDK carrega skills, hooks, agentes e comandos deste plugin, mas não lê seu `.mcp.json` nem os `mcpServers` do manifesto. Defina isso quando sua aplicação for responsável pelas conexões MCP do plugin. |
1469 1594
1470**Exemplo:**1595**Exemplo:**
5076};5201};
5077```5202```
5078 5203
5079`source` diz de onde a definição do servidor veio, com os mesmos valores e regra de confiança que o `source` de [`McpServerProvenance`](#mcpserverprovenance). O campo requer Agent SDK v0.3.274 ou posterior e está ausente em versões anteriores.5204Use `source` para decidir o quanto confiar em um servidor, e o `_meta` em cada entrada `tools` para encontrar um recurso de UI que o servidor anexou a essa ferramenta:
5205
5206* **`source`**: de onde a definição do servidor veio, com os mesmos valores que `source` em [`McpServerProvenance`](#mcpserverprovenance). Baseie decisões de confiança em `source` em vez de em `name`, porque apenas seu próprio servidor em processo relata `sdk`, qualquer que seja o nome sob o qual qualquer outro servidor esteja registrado. Se você não reconhecer um valor de `source`, trate esse servidor como trata qualquer servidor cujo `source` não seja `sdk`. Requer Agent SDK v0.3.274 ou posterior
5207* **`_meta`**: o objeto `ui` e a string `ui/resourceUri` do `_meta` que o servidor declarou para a ferramenta. Claude Code retém todas as outras chaves de `_meta`. `ui/resourceUri` é uma grafia de nível superior mais antiga de `ui.resourceUri`. Quando o servidor anexa um [recurso de UI do MCP Apps](https://code.claude.com/docs/pt/mcp.md#reference-mcp-resources) à ferramenta, `ui.resourceUri` ou `ui/resourceUri` contém o URI `ui://` do recurso. Busque esse URI com [`readMcpResource()`](#query-object) e renderize o recurso em sua aplicação. Requer Agent SDK v0.3.280 ou posterior
5208
5209Claude Code envia `_meta` apenas quando o array [`capabilities`](#sdksystemmessage) da mensagem `system` com subtipo `init` lista `mcp_tool_ui_meta_v1`. Você não ativa `mcp_tool_ui_meta_v1` por conta própria.
5210
5211#### Quando o `_meta.ui` de uma ferramenta contém apenas `visibility`
5212
5213Se seu servidor declara `ui.resourceUri` para uma ferramenta, mas o `_meta.ui` que sua aplicação recebe contém apenas `visibility`, o objeto `ui` que o servidor enviou falhou em uma das verificações do Claude Code. Claude Code verifica `ui` e `ui/resourceUri` separadamente, então uma chave pode chegar à sua aplicação quando a outra falha. Compare o `_meta` na resposta `tools/list` do seu servidor com as verificações de cada chave:
5214
5215* **`ui`**: chega à sua aplicação inalterado, incluindo quaisquer membros além de `resourceUri` e `visibility`, se todas as três verificações forem aprovadas:
5216
5217 * `resourceUri` está ausente, ou é uma string que começa com `ui://`
5218 * `visibility` está ausente, ou lista apenas `"model"` e `"app"`
5219 * O objeto inteiro tem no máximo 4.096 caracteres quando serializado como JSON
5220
5221 Se qualquer uma das verificações falhar, sua aplicação recebe no máximo um `ui` cujo único membro é um array `visibility` com as entradas `"model"` e `"app"` que o servidor listou.
5222* **`ui/resourceUri`**: chega à sua aplicação se for uma string que começa com `ui://` e tem no máximo 4.096 caracteres. Caso contrário, Claude Code a descarta
5080 5223
5081`_meta` em uma entrada `tools` carrega os membros MCP Apps de `_meta` dessa ferramenta, para que sua aplicação possa encontrar o recurso `ui://` para renderizar com [`readMcpResource()`](#query-object). Claude Code passa através do objeto `ui` e da string `ui/resourceUri` plana descontinuada, e retém todas as outras chaves. Dentro de `ui`, `resourceUri` é uma string `ui://` e `visibility` um array de `"model"` e `"app"` quando o servidor os define, e qualquer outro membro passa através inalterado. Claude Code descarta qualquer chave quando o valor é malformado, e omite `_meta` de uma ferramenta que não declara nenhum. O campo está presente apenas quando o [`capabilities`](#sdksystemmessage) da mensagem init incluem `mcp_tool_ui_meta_v1`, e requer TypeScript Agent SDK v0.3.280 ou posterior.5224Quando Claude Code fica sem nenhum membro `ui` e sem nenhuma string `ui/resourceUri` para enviar, a entrada `tools` não tem nenhum `_meta`.
5082 5225
5083### `McpServerStatusConfig`5226### `McpServerStatusConfig`
5084 5227
5313Quando você chama `setMcpServers()`, Claude Code aplica estas regras:5456Quando você chama `setMcpServers()`, Claude Code aplica estas regras:
5314 5457
5315* **Servidores que a chamada não nomeia**: fora de uma [sessão na nuvem](https://code.claude.com/docs/pt/claude-code-on-the-web.md), Claude Code desconecta os servidores que uma chamada anterior de `setMcpServers()` adicionou e os servidores SDK em processo, e os lista em `removed`. Outros servidores continuam em execução e não são listados em `removed`, entre eles os servidores stdio, HTTP e SSE da opção [`mcpServers`](#options), servidores de arquivos de configuração e servidores fornecidos por plugin.5458* **Servidores que a chamada não nomeia**: fora de uma [sessão na nuvem](https://code.claude.com/docs/pt/claude-code-on-the-web.md), Claude Code desconecta os servidores que uma chamada anterior de `setMcpServers()` adicionou e os servidores SDK em processo, e os lista em `removed`. Outros servidores continuam em execução e não são listados em `removed`, entre eles os servidores stdio, HTTP e SSE da opção [`mcpServers`](#options), servidores de arquivos de configuração e servidores fornecidos por plugin.
5316* **Servidores que a chamada nomeia**: Claude Code substitui um servidor stdio, HTTP ou SSE que uma chamada anterior de `setMcpServers()` adicionou apenas quando sua configuração difere da que você passou. Um servidor SDK em processo já registrado sob esse nome permanece como está, então, para trocar um, deixe-o de fora de uma chamada e adicione-o na seguinte.5459* **Servidores stdio, HTTP e SSE que uma chamada anterior de `setMcpServers()` adicionou**: fora de uma sessão na nuvem, um servidor que você nomeia novamente com uma configuração idêntica mantém sua conexão e suas ferramentas. Ele não aparece nem em `added` nem em `removed`. Se você passar uma configuração alterada, Claude Code reconecta o servidor usando essa configuração e o lista em `added`, não em `removed`.
5460* **Servidores stdio, HTTP e SSE que a chamada nomeia e que nenhuma chamada anterior adicionou**: fora de uma sessão na nuvem, Claude Code adiciona o servidor e o lista em `added`, ou em `errors` se recusar o servidor.
5461* **Servidores SDK em processo que a chamada nomeia**: um servidor já registrado por meio de `mcpServers` ou de uma chamada anterior mantém sua instância em execução e seu timeout. Se você passar uma [lista de políticas `tools`](#mcpsdkserverconfigwithinstance) para ele, mesmo vazia, você substitui suas políticas; caso contrário, elas permanecem. Para executar uma nova instância fora de uma sessão na nuvem, omita o servidor de uma chamada e nomeie-o na seguinte.
5317* **Servidores integrados que a CLI iniciou na inicialização**: se a chamada nomear um, Claude Code descarta essa entrada e a relata em `errors`.5462* **Servidores integrados que a CLI iniciou na inicialização**: se a chamada nomear um, Claude Code descarta essa entrada e a relata em `errors`.
5318* **Servidores stdio, HTTP ou SSE que compartilham um nome com um servidor de um escopo de instalação MCP, como `.mcp.json`**: sob esse nome, a sessão usa as ferramentas do seu servidor em vez das do [servidor do escopo de instalação](https://code.claude.com/docs/pt/mcp.md#mcp-installation-scopes). Antes do Claude Code v2.1.305, Claude Code podia desconectar seu servidor e conectar o servidor do escopo de instalação quando sua aplicação [recarregava plugins](#query-object).5463* **Servidores stdio, HTTP ou SSE que compartilham um nome com um servidor de um escopo de instalação MCP, como `.mcp.json`**: sob esse nome, a sessão usa as ferramentas do seu servidor em vez das do [servidor do escopo de instalação](https://code.claude.com/docs/pt/mcp.md#mcp-installation-scopes). Antes do Claude Code v2.1.305, Claude Code podia desconectar seu servidor e conectar o servidor do escopo de instalação quando sua aplicação [recarregava plugins](#query-object).
5319 5464
5800 5945
5801As tipagens publicadas do SDK declaram `SDKConversationResetMessage` no Claude Code v2.1.203 e posterior. Antes de v2.1.203, `SDKMessage` referenciava o tipo sem declará-lo, então o estreitamento em `type === "conversation_reset"` falhou ao verificar o tipo quando `skipLibCheck` estava desativado.5946As tipagens publicadas do SDK declaram `SDKConversationResetMessage` no Claude Code v2.1.203 e posterior. Antes de v2.1.203, `SDKMessage` referenciava o tipo sem declará-lo, então o estreitamento em `type === "conversation_reset"` falhou ao verificar o tipo quando `skipLibCheck` estava desativado.
5802 5947
5948### `BUILTIN_TOOL_NAMES` e `LEGACY_TOOL_NAME_ALIASES`
5949
5950Use estas duas constantes para verificar nomes de ferramentas que os usuários da sua aplicação digitam. Ambas escrevem cada nome da forma como você o escreve em regras de permissão, matchers de hook e nas opções `tools` e `disallowedTools`. Importe-as de `@anthropic-ai/claude-agent-sdk` ou de `@anthropic-ai/claude-agent-sdk/core`. Elas requerem Agent SDK v0.3.301 ou posterior e estão em alfa.
5951
5952As declarações de tipo do SDK dão a `BUILTIN_TOOL_NAMES` um tipo de tupla readonly e a `LEGACY_TOOL_NAME_ALIASES` um tipo de registro de string para string:
5953
5954```typescript theme={null}
5955const BUILTIN_TOOL_NAMES: readonly ["Agent", /* ...more names... */ "Write"];
5956const LEGACY_TOOL_NAME_ALIASES: Readonly<Record<string, string>>;
5957```
5958
5959* **`BUILTIN_TOOL_NAMES`**: nomes das ferramentas integradas do Claude Code em ordem alfabética, como `Agent`, `Bash` e `Read`. Nomes de ferramentas MCP não estão incluídos. Como o tipo é uma tupla de literais de string, `(typeof BUILTIN_TOOL_NAMES)[number]` fornece um tipo união dos nomes
5960* **`LEGACY_TOOL_NAME_ALIASES`**: nomes de ferramentas anteriores que regras de permissão, matchers de hook e as opções `tools` e `disallowedTools` ainda aceitam. Cada chave é um nome anterior e seu valor é o atual: por exemplo, `Task` mapeia para `Agent`, e `KillShell` e `KillBash` mapeiam para `TaskStop`
5961
5962Você pode confirmar um nome com qualquer um de dois testes: `BUILTIN_TOOL_NAMES` o inclui, ou `Object.hasOwn(LEGACY_TOOL_NAME_ALIASES, name)` retorna `true`. Um nome que falha em ambos ainda pode ser válido, porque `BUILTIN_TOOL_NAMES` deixa de fora ferramentas MCP e algumas ferramentas integradas. Se você construir uma lista de negação a partir de `BUILTIN_TOOL_NAMES`, Claude ainda pode usar as ferramentas que a constante deixa de fora. Para negar todas as ferramentas, defina [`disallowedTools: ["*"]`](https://code.claude.com/docs/pt/agent-sdk/permissions#allow-and-deny-rules) em vez disso.
5963
5964Encontrar um nome em `BUILTIN_TOOL_NAMES` não indica que a sessão tem essa ferramenta: `TodoWrite` está listada mesmo estando [desativada por padrão](https://code.claude.com/docs/pt/tools-reference.md). Para ver quais ferramentas uma sessão tem, leia o array `tools` de seu [`SDKSystemMessage`](#sdksystemmessage). Esse array inclui ferramentas MCP e lista a ferramenta Agent como `Task`, então mapeie cada nome por meio de `LEGACY_TOOL_NAME_ALIASES` antes de compará-lo com `BUILTIN_TOOL_NAMES`.
5965
5803### `AbortError`5966### `AbortError`
5804 5967
5805Classe de erro personalizada para operações de abort.5968Classe de erro personalizada para operações de abort.
