186 console.error("Claim failed:", error.message);186 console.error("Claim failed:", error.message);
187});187});
188 188
189for await (const message of claimedQuery) {189try {
190 for await (const message of claimedQuery) {
190 console.log(message);191 console.log(message);
192 }
193} catch (error) {
194 // Após uma reivindicação recusada, a query reivindicada lança uma exceção assim que tiver produzido o resultado de erro
195 console.error(`Session ended with an error: ${error}`);
191}196}
192```197```
193 198
539| Propriedade | Tipo | Padrão | Descrição |544| Propriedade | Tipo | Padrão | Descrição |
540| :- | :- | :- | :- |545| :- | :- | :- | :- |
541| `abortController` | `AbortController` | `new AbortController()` | Controlador para cancelar operações |546| `abortController` | `AbortController` | `new AbortController()` | Controlador para cancelar operações |
542| `additionalDirectories` | `string[]` | `[]` | Diretórios adicionais que Claude pode acessar. O SDK passa cada entrada para Claude Code como `--add-dir`, então com a configuração `project` o Claude Code também [carrega as skills, comandos e subagentes do diretório](/docs/pt/permissions#additional-directories-grant-file-access-not-configuration) |547| `additionalDirectories` | `string[]` | `[]` | Diretórios adicionais que Claude pode acessar. O SDK passa cada entrada para o Claude Code como `--add-dir`, portanto, com a fonte de configuração `project`, o Claude Code também [carrega as skills, os comandos e os subagentes do diretório](/docs/pt/permissions#additional-directories-grant-file-access-not-configuration) |
543| `agent` | `string` | `undefined` | Nome do agente para a thread principal. O agente deve ser definido na opção `agents` ou em configurações |548| `agent` | `string` | `undefined` | Nome do agente para a thread principal. O agente deve estar definido na opção `agents` ou nas configurações |
544| `agents` | `Record<string, [`AgentDefinition`](#agentdefinition)>` | `undefined` | Defina subagentes programaticamente |549| `agents` | `Record<string, [`AgentDefinition`](#agentdefinition)>` | `undefined` | Definir subagentes programaticamente |
545| `agentProgressSummaries` | `boolean` | `false` | Quando `true`, gera resumos de progresso de uma linha para subagentes e os encaminha em eventos [`task_progress`](#sdktaskprogressmessage) através do campo `summary`. Aplica-se a subagentes em primeiro plano e em segundo plano |550| `agentProgressSummaries` | `boolean` | `false` | Quando `true`, gera resumos de progresso de uma linha para os subagentes e os encaminha nos eventos [`task_progress`](#sdktaskprogressmessage) por meio do campo `summary`. Aplica-se a subagentes em primeiro plano e em segundo plano |
546| `allowDangerouslySkipPermissions` | `boolean` | `false` | Ativar bypass de permissões. Obrigatório ao usar `permissionMode: 'bypassPermissions'`, na inicialização ou depois através de `setPermissionMode()`. Veja [plan mode](/docs/pt/agent-sdk/permissions#plan-mode-plan) para como interage com `permissionMode: 'plan'` |551| `allowDangerouslySkipPermissions` | `boolean` | `false` | Habilita a dispensa de permissões. Obrigatório ao usar `permissionMode: 'bypassPermissions'`, na inicialização ou posteriormente por meio de `setPermissionMode()`. Consulte [modo de planejamento](/docs/pt/agent-sdk/permissions#plan-mode-plan) para ver como isso interage com `permissionMode: 'plan'` |
547| `allowedTools` | `string[]` | `[]` | Ferramentas para auto-aprovar sem solicitar. Isso não restringe Claude apenas a essas ferramentas. Se você nomear uma das [ferramentas de rastreamento de tarefas](/docs/pt/agent-sdk/todo-tracking#model-availability) aqui, Claude Code também opta a sessão. Outras ferramentas não listadas caem em `permissionMode` e `canUseTool`. Use `disallowedTools` para bloquear ferramentas. Veja [Permissões](/docs/pt/agent-sdk/permissions#allow-and-deny-rules) |552| `allowedTools` | `string[]` | `[]` | Ferramentas a aprovar automaticamente sem solicitar confirmação. Isso não restringe Claude apenas a essas ferramentas. Se você nomear aqui uma das [ferramentas de acompanhamento de tarefas](/docs/pt/agent-sdk/todo-tracking#model-availability), o Claude Code também habilita esse recurso na sessão. Outras ferramentas não listadas seguem para `permissionMode` e `canUseTool`. Use `disallowedTools` para bloquear ferramentas. Consulte [Permissões](/docs/pt/agent-sdk/permissions#allow-and-deny-rules) |
548| `betas` | [`SdkBeta`](#sdkbeta)`[]` | `[]` | Ativar recursos beta |553| `betas` | [`SdkBeta`](#sdkbeta)`[]` | `[]` | Habilitar recursos beta |
549| `canUseTool` | [`CanUseTool`](#canusetool) | `undefined` | Função de permissão personalizada, invocada apenas quando o [fluxo de permissão](/docs/pt/agent-sdk/permissions#how-permissions-are-evaluated) cai em um prompt. Não invocada para chamadas auto-aprovadas por `allowedTools`, regras de permissão, ou `permissionMode`. Uma regra de permissão não pré-aprova as [ações que nenhum modo auto-aprova](/docs/pt/permission-modes#actions-no-mode-auto-approves). Veja [`CanUseTool`](#canusetool) para detalhes |554| `canUseTool` | [`CanUseTool`](#canusetool) | `undefined` | Função de permissão personalizada, invocada somente quando o [fluxo de permissão](/docs/pt/agent-sdk/permissions#how-permissions-are-evaluated) chega a um prompt. Não é invocada para chamadas aprovadas automaticamente por `allowedTools`, regras de permissão ou `permissionMode`. Uma regra de permissão não pré-aprova as [ações que nenhum modo aprova automaticamente](/docs/pt/permission-modes#actions-no-mode-auto-approves). Consulte [`CanUseTool`](#canusetool) para obter detalhes |
550| `continue` | `boolean` | `false` | Continuar a conversa mais recente |555| `continue` | `boolean` | `false` | Continuar a conversa mais recente |
551| `cwd` | `string` | `process.cwd()` | Diretório de trabalho atual |556| `cwd` | `string` | `process.cwd()` | Diretório de trabalho atual |
552| `debug` | `boolean` | `false` | Ativar modo de depuração para o processo Claude Code |557| `debug` | `boolean` | `false` | Habilitar o modo de depuração para o processo do Claude Code |
553| `debugFile` | `string` | `undefined` | Escrever logs de depuração em um caminho de arquivo específico. Ativa implicitamente o modo de depuração |558| `debugFile` | `string` | `undefined` | Gravar logs de depuração em um caminho de arquivo específico. Habilita implicitamente o modo de depuração |
554| `disallowedTools` | `string[]` | `[]` | Ferramentas para negar. Um nome simples como `"Bash"` remove a ferramenta do contexto do Claude. Uma regra com escopo como `"Bash(rm *)"` deixa a ferramenta disponível e nega chamadas correspondentes em todos os modos de permissão, incluindo `bypassPermissions`, para o comando [conforme escrito](/docs/pt/permissions#bash-rule-limits). Veja [Permissões](/docs/pt/agent-sdk/permissions#allow-and-deny-rules) |559| `disallowedTools` | `string[]` | `[]` | Ferramentas a negar. Um nome simples como `"Bash"` remove a ferramenta do contexto de Claude. Uma regra com escopo como `"Bash(rm *)"` mantém a ferramenta disponível e nega as chamadas correspondentes em todos os modos de permissão, incluindo `bypassPermissions`, para o comando [conforme escrito](/docs/pt/permissions#bash-rule-limits). Consulte [Permissões](/docs/pt/agent-sdk/permissions#allow-and-deny-rules) |
555| `effort` | `'low' \| 'medium' \| 'high' \| 'xhigh' \| 'max'` | `undefined` | Controla quanto esforço Claude coloca em sua resposta. Funciona com pensamento adaptativo para guiar a profundidade do pensamento. Veja [ajustar o nível de esforço](/docs/pt/model-config#adjust-effort-level) |560| `effort` | `'low' \| 'medium' \| 'high' \| 'xhigh' \| 'max'` | `undefined` | Controla quanto esforço Claude dedica à resposta. Funciona com o pensamento adaptativo para orientar a profundidade do pensamento. Consulte [ajustar o nível de esforço](/docs/pt/model-config#adjust-effort-level) |
556| `enableFileCheckpointing` | `boolean` | `false` | Ativar rastreamento de mudanças de arquivo para retrocesso. Veja [File checkpointing](/docs/pt/agent-sdk/file-checkpointing) |561| `enableFileCheckpointing` | `boolean` | `false` | Habilitar o rastreamento de alterações em arquivos para retrocesso. Consulte [Checkpointing de arquivos](/docs/pt/agent-sdk/file-checkpointing) |
557| `env` | `Record<string, string \| undefined>` | `process.env` | Variáveis de ambiente. Quando definido, isso substitui o ambiente do subprocesso em vez de mesclar com `process.env`, então passe `{ ...process.env, YOUR_VAR: 'value' }` para manter variáveis herdadas como `PATH`. Veja [Lidar com respostas de API lentas ou travadas](#handle-slow-or-stalled-api-responses) para um exemplo deste padrão, e [Variáveis de ambiente](/docs/pt/env-vars) para variáveis que a CLI subjacente lê. Defina `CLAUDE_AGENT_SDK_CLIENT_APP` para identificar sua aplicação no cabeçalho User-Agent |562| `env` | `Record<string, string \| undefined>` | `process.env` | Variáveis de ambiente. Quando definida, substitui o ambiente do subprocesso em vez de mesclar com `process.env`, portanto passe `{ ...process.env, YOUR_VAR: 'value' }` para manter variáveis herdadas como `PATH`. Consulte [Lidar com respostas de API lentas ou travadas](#handle-slow-or-stalled-api-responses) para ver um exemplo desse padrão e [Variáveis de ambiente](/docs/pt/env-vars) para ver as variáveis que a CLI subjacente lê. Defina `CLAUDE_AGENT_SDK_CLIENT_APP` para identificar seu aplicativo no cabeçalho User-Agent |
558| `executable` | `'bun' \| 'deno' \| 'node'` | Auto-detectado | Runtime JavaScript a usar |563| `executable` | `'bun' \| 'deno' \| 'node'` | Detectado automaticamente | Runtime JavaScript a usar |
559| `executableArgs` | `string[]` | `[]` | Argumentos a passar para o executável |564| `executableArgs` | `string[]` | `[]` | Argumentos a passar para o executável |
560| `extraArgs` | `Record<string, string \| null>` | `{}` | Argumentos adicionais |565| `extraArgs` | `Record<string, string \| null>` | `{}` | Argumentos adicionais |
561| `fallbackModel` | `string` | `undefined` | Modelo a usar se o primário falhar. Aceita uma lista separada por vírgula. Para a ordem e o limite, veja [Cadeias de modelo de fallback](/docs/pt/model-config#fallback-model-chains). Para orientação, veja [Escolher um modelo](/docs/pt/agent-sdk/configuration#choose-a-model) |566| `fallbackModel` | `string` | `undefined` | Modelo a usar se o modelo principal falhar. Aceita uma lista separada por vírgulas. Para a ordem e o limite, consulte [Cadeias de modelos de fallback](/docs/pt/model-config#fallback-model-chains). Para orientações, consulte [Escolher um modelo](/docs/pt/agent-sdk/configuration#choose-a-model) |
562| `forkSession` | `boolean` | `false` | Ao retomar com `resume`, bifurcar para um novo ID de sessão em vez de continuar a sessão original |567| `forkSession` | `boolean` | `false` | Ao retomar com `resume`, bifurca para um novo ID de sessão em vez de continuar a sessão original |
563| `forwardSubagentText` | `boolean` | `false` | Encaminhar blocos de texto e pensamento de subagentes como mensagens de assistente e usuário com `parent_tool_use_id` definido, para que os consumidores possam renderizar uma transcrição aninhada. Sem esta opção, Claude Code emite blocos `tool_use` e `tool_result` de subagentes mas não texto ou pensamento. Mensagens de subagentes em cada profundidade de aninhamento são encaminhadas no Claude Code v2.1.219 e posterior; antes de v2.1.219, apenas mensagens de subagentes de profundidade-1 apareciam. Mensagens de subagentes que uma skill bifurcada gera, e de skills bifurcadas aninhadas, requerem v2.1.275 ou posterior |568| `forwardSubagentText` | `boolean` | `false` | Encaminha blocos de texto e de pensamento dos subagentes como mensagens de assistente e de usuário com `parent_tool_use_id` definido, para que os consumidores possam renderizar uma transcrição aninhada. Sem essa opção, o Claude Code emite os blocos `tool_use` e `tool_result` dos subagentes, mas não texto nem pensamento. Mensagens de subagentes em qualquer profundidade de aninhamento são encaminhadas no Claude Code v2.1.219 e posterior; antes da v2.1.219, apenas mensagens de subagentes de profundidade 1 apareciam. Mensagens de subagentes gerados por uma skill bifurcada, e de skills bifurcadas aninhadas, exigem a v2.1.275 ou posterior |
564| `hooks` | `Partial<Record<`[`HookEvent`](#hookevent)`, `[`HookCallbackMatcher`](#hookcallbackmatcher)`[]>>` | `{}` | Callbacks de hook para eventos |569| `hooks` | `Partial<Record<`[`HookEvent`](#hookevent)`, `[`HookCallbackMatcher`](#hookcallbackmatcher)`[]>>` | `{}` | Callbacks de hook para eventos |
565| `includeHookEvents` | `boolean` | `false` | Incluir eventos de ciclo de vida de hook no fluxo de mensagens como [`SDKHookStartedMessage`](#sdkhookstartedmessage), [`SDKHookProgressMessage`](#sdkhookprogressmessage), e [`SDKHookResponseMessage`](#sdkhookresponsemessage). Eventos de ciclo de vida para hooks `SessionStart` e `Setup` são sempre incluídos e não precisam desta opção. Alguns eventos de hook, como `Notification`, `SessionEnd`, `PreCompact`, e `PostCompact`, nunca produzem um `SDKHookStartedMessage`, mesmo com esta opção. Para esses eventos, Claude Code ainda emite um `SDKHookProgressMessage` enquanto um hook de comando que é executado por mais de um segundo produz saída, e emite um `SDKHookResponseMessage` apenas quando um hook [que é executado em segundo plano](/docs/pt/hooks#run-hooks-in-the-background) termina |570| `includeHookEvents` | `boolean` | `false` | Inclui eventos do ciclo de vida dos hooks no fluxo de mensagens como [`SDKHookStartedMessage`](#sdkhookstartedmessage), [`SDKHookProgressMessage`](#sdkhookprogressmessage) e [`SDKHookResponseMessage`](#sdkhookresponsemessage). Eventos do ciclo de vida dos hooks `SessionStart` e `Setup` são sempre incluídos e não precisam dessa opção. Alguns eventos de hook, como `Notification`, `SessionEnd`, `PreCompact` e `PostCompact`, nunca produzem uma `SDKHookStartedMessage`, mesmo com essa opção. Para esses eventos, o Claude Code ainda emite uma `SDKHookProgressMessage` enquanto um hook de comando executado por mais de um segundo produz saída, e emite uma `SDKHookResponseMessage` somente quando um hook [executado em segundo plano](/docs/pt/hooks#run-hooks-in-the-background) termina |
566| `includePartialMessages` | `boolean` | `false` | Incluir eventos de mensagem parcial |571| `includePartialMessages` | `boolean` | `false` | Incluir eventos de mensagens parciais |
567| `loadTimeoutMs` | `number` | `60000` | *Alfa.* Timeout em milissegundos para cada chamada `sessionStore.load()` e `sessionStore.listSubkeys()` durante materialização de retomada. Se o adaptador não se resolver dentro desta janela, a consulta falha em vez de travar. Ignorado quando `sessionStore` não está definido |572| `loadTimeoutMs` | `number` | `60000` | *Alpha.* Timeout em milissegundos para cada chamada de `sessionStore.load()` e `sessionStore.listSubkeys()` durante a materialização da retomada. Se o adaptador não concluir dentro dessa janela, a consulta falha em vez de travar. Ignorado quando `sessionStore` não está definido |
568| `managedSettings` | `Settings` | `undefined` | Configurações de nível de política que seu processo host fornece para a sessão gerada. Em máquinas com configurações gerenciadas implantadas por administrador, Claude Code ignora estas a menos que a fonte gerenciada de maior prioridade do administrador defina `parentSettingsBehavior: 'merge'`, e nunca as mescla enquanto um [`policyHelper`](/docs/pt/settings-reference#policyhelper) fornece configurações gerenciadas. Valores mesclados passam por um filtro apenas restritivo; [Restringir configurações pai](/docs/pt/claude-apps-gateway#restrict-parent-settings) cobre o que o filtro admite e os bloqueios `allowManaged*Only`. Um host que define [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](/docs/pt/env-vars) tem três chaves lidas diretamente desta carga: sua [configuração de modelo](/docs/pt/model-config#restrict-model-selection) no Claude Code v2.1.222 ou posterior, [`modelPricing`](/docs/pt/settings-reference#modelpricing) quando nenhuma fonte gerenciada a define no v2.1.246 ou posterior, e sua entrada `ENABLE_TOOL_SEARCH` env no v2.1.247 ou posterior |573| `managedSettings` | `Settings` | `undefined` | Configurações do nível de política que seu processo host fornece à sessão gerada. Em máquinas com configurações gerenciadas implantadas pelo administrador, o Claude Code as ignora, a menos que a fonte gerenciada de maior prioridade do administrador defina `parentSettingsBehavior: 'merge'`, e nunca as mescla enquanto um [`policyHelper`](/docs/pt/settings-reference#policyhelper) fornece configurações gerenciadas. Os valores mesclados passam por um filtro somente restritivo; [Restringir configurações do pai](/docs/pt/claude-apps-gateway#restrict-parent-settings) aborda o que o filtro admite e os bloqueios `allowManaged*Only`. Um host que define [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](/docs/pt/env-vars) tem três chaves lidas diretamente deste payload: sua [configuração de modelo](/docs/pt/model-config#restrict-model-selection) no Claude Code v2.1.222 ou posterior, [`modelPricing`](/docs/pt/settings-reference#modelpricing) quando nenhuma fonte gerenciada a define na v2.1.246 ou posterior, e sua entrada de env `ENABLE_TOOL_SEARCH` na v2.1.247 ou posterior |
569| `maxBudgetUsd` | `number` | `undefined` | Parar a consulta quando a estimativa de custo do lado do cliente atingir este valor em USD. Comparado com a mesma estimativa que `total_cost_usd`. Para ressalvas de precisão e comportamento de reset, veja [Rastrear custo e uso](/docs/pt/agent-sdk/cost-tracking) |574| `maxBudgetUsd` | `number` | `undefined` | Interrompe a consulta quando a estimativa de custo do lado do cliente atinge este valor em USD. Conta apenas o gasto da própria chamada; totais restaurados de uma sessão retomada não contam. Para ressalvas de precisão e comportamento de redefinição, consulte [Acompanhar custo e uso](/docs/pt/agent-sdk/cost-tracking) |
570| `maxThinkingTokens` | `number` | `undefined` | *Descontinuado:* Use `thinking` em vez disso. Tokens máximos para processo de pensamento |575| `maxThinkingTokens` | `number` | `undefined` | *Obsoleto:* Use `thinking` em vez disso. Máximo de tokens para o processo de pensamento |
571| `maxTurns` | `number` | `undefined` | Turnos agênticos máximos (round trips de uso de ferramenta) |576| `maxTurns` | `number` | `undefined` | Máximo de turnos agênticos (idas e voltas de uso de ferramentas) |
572| `mcpServers` | `Record<string, [`McpServerConfig`](#mcpserverconfig)>` | `{}` | Configurações de servidor MCP |577| `mcpServers` | `Record<string, [`McpServerConfig`](#mcpserverconfig)>` | `{}` | Configurações de servidores MCP |
573| `model` | `string` | Padrão da CLI | Alias de modelo Claude ou nome de modelo completo. Veja [valores aceitos e IDs específicos do provedor](/docs/pt/model-config#available-models) |578| `model` | `string` | Padrão da CLI | Alias do modelo Claude ou nome completo do modelo. Consulte [valores aceitos e IDs específicos de provedores](/docs/pt/model-config#available-models) |
574| `onElicitation` | `(request: ElicitationRequest, options: { signal: AbortSignal }) => Promise<ElicitationResult>` | `undefined` | Callback para lidar com solicitações de elicitação MCP. Chamado quando um servidor MCP solicita entrada do usuário e nenhum hook a trata primeiro. Quando não fornecido, solicitações de elicitação não tratadas são recusadas automaticamente |579| `onElicitation` | `(request: ElicitationRequest, options: { signal: AbortSignal }) => Promise<ElicitationResult>` | `undefined` | Callback para lidar com requisições de elicitação MCP. Chamado quando um servidor MCP solicita entrada do usuário e nenhum hook a trata primeiro. Quando não fornecido, requisições de elicitação não tratadas são recusadas automaticamente |
575| `outputFormat` | `{ type: 'json_schema', schema: JSONSchema }` | `undefined` | Defina o formato de saída para resultados de agente. Veja [Structured outputs](/docs/pt/agent-sdk/structured-outputs) para detalhes |580| `outputFormat` | `{ type: 'json_schema', schema: JSONSchema }` | `undefined` | Define o formato de saída para os resultados do agente. Consulte [Saídas estruturadas](/docs/pt/agent-sdk/structured-outputs) para obter detalhes |
576| `outputStyle` | `string` | `undefined` | Não é um campo `Options`. Defina `outputStyle` no objeto [`settings`](/docs/pt/settings) inline ou em um arquivo de configurações. Veja [Ativar um estilo de saída](/docs/pt/agent-sdk/modifying-system-prompts#activate-an-output-style) |581| `outputStyle` | `string` | `undefined` | Não é um campo de `Options`. Defina `outputStyle` no objeto inline [`settings`](/docs/pt/settings) ou em um arquivo de configurações. Consulte [Ativar um estilo de saída](/docs/pt/agent-sdk/modifying-system-prompts#activate-an-output-style) |
577| `pathToClaudeCodeExecutable` | `string` | Auto-resolvido do binário nativo agrupado | Caminho para executável Claude Code. Apenas necessário se dependências opcionais foram puladas durante a instalação ou sua plataforma não está no conjunto suportado |582| `pathToClaudeCodeExecutable` | `string` | Resolvido automaticamente a partir do binário nativo incluído | Caminho para o executável do Claude Code. Necessário apenas se as dependências opcionais foram ignoradas durante a instalação ou se sua plataforma não está no conjunto suportado |
578| `permissionMode` | [`PermissionMode`](#permissionmode) | `undefined` | Modo de permissão para a sessão. Se você omitir, a sessão pode começar em modo automático. Veja [Modos de permissão](/docs/pt/agent-sdk/permissions#permission-modes) para como Claude Code escolhe o modo de permissão inicial |583| `permissionMode` | [`PermissionMode`](#permissionmode) | `undefined` | Modo de permissão da sessão. Se você o omitir, a sessão pode iniciar no modo auto. Consulte [Modos de permissão](/docs/pt/agent-sdk/permissions#permission-modes) para ver como o Claude Code escolhe o modo de permissão inicial |
579| `permissionPromptToolName` | `string` | `undefined` | Nome da ferramenta MCP para prompts de permissão |584| `permissionPromptToolName` | `string` | `undefined` | Nome da ferramenta MCP para prompts de permissão |
580| `permissionPrompts` | `'host' \| 'none'` | `'host'` | Quem responde aos prompts de permissão: `'host'` os encaminha para seu callback [`canUseTool`](#canusetool) ou a ferramenta `permissionPromptToolName`, e `'none'` [nega as chamadas que teriam solicitado](/docs/pt/agent-sdk/permissions#how-permissions-are-evaluated). Requer Claude Code v2.1.259 ou posterior |585| `permissionPrompts` | `'host' \| 'none'` | `'host'` | Quem responde aos prompts de permissão: `'host'` os encaminha para seu callback [`canUseTool`](#canusetool) ou para a ferramenta `permissionPromptToolName`, e `'none'` [nega as chamadas que teriam gerado um prompt](/docs/pt/agent-sdk/permissions#how-permissions-are-evaluated). Requer o Claude Code v2.1.259 ou posterior |
581| `persistSession` | `boolean` | `true` | Quando `false`, desativa persistência de sessão em disco. Sessões não podem ser retomadas depois |586| `persistSession` | `boolean` | `true` | Quando `false`, desabilita a persistência da sessão em disco. As sessões não podem ser retomadas posteriormente |
582| `planModeInstructions` | `string` | `undefined` | Instruções de fluxo de trabalho personalizado para Plan Mode. Quando `permissionMode` é `'plan'`, esta string substitui o corpo de fluxo de trabalho de Plan Mode padrão. A CLI ainda o envolve com o preâmbulo de imposição somente leitura e o rodapé do protocolo ExitPlanMode |587| `planModeInstructions` | `string` | `undefined` | Instruções de fluxo de trabalho personalizadas para o modo de planejamento. Quando `permissionMode` é `'plan'`, essa string substitui o corpo padrão do fluxo de trabalho do modo de planejamento. A CLI ainda o envolve com o preâmbulo de imposição somente leitura e o rodapé do protocolo ExitPlanMode |
583| `plugins` | [`SdkPluginConfig`](#sdkpluginconfig)`[]` | `[]` | Carregar plugins personalizados de caminhos locais. Veja [Plugins](/docs/pt/agent-sdk/plugins) para detalhes |588| `plugins` | [`SdkPluginConfig`](#sdkpluginconfig)`[]` | `[]` | Carregar plugins personalizados a partir de caminhos locais. Consulte [Plugins](/docs/pt/agent-sdk/plugins) para obter detalhes |
584| `projectConfigRoot` | `string` | `undefined` | Caminho absoluto do checkout confiável que `cwd` é uma worktree de. Claude Code lê configurações de projeto, `.mcp.json`, e os comandos, agentes, skills, workflows, rotinas e estilos de saída do projeto `.claude/` deste diretório em vez de `cwd`, e define `CLAUDE_PROJECT_DIR` para ele. Hooks, scripts auxiliares como `apiKeyHelper`, e servidores MCP stdio começam com este diretório como seu diretório de trabalho. Arquivos `CLAUDE.md` e `.claude/rules/` ainda carregam de `cwd`. Requer Claude Code v2.1.275 ou posterior |589| `projectConfigRoot` | `string` | `undefined` | Caminho absoluto do checkout confiável do qual `cwd` é um worktree. O Claude Code lê as configurações do projeto, `.mcp.json` e os comandos, agentes, skills, fluxos de trabalho, rotinas e estilos de saída em `.claude/` do projeto a partir deste diretório em vez de `cwd`, e define `CLAUDE_PROJECT_DIR` com ele. Hooks, scripts auxiliares como `apiKeyHelper` e servidores MCP stdio iniciam com este diretório como diretório de trabalho. Arquivos `CLAUDE.md` e `.claude/rules/` ainda são carregados a partir de `cwd`. Requer o Claude Code v2.1.275 ou posterior |
585| `promptSuggestions` | `boolean` | `false` | Ativar sugestões de prompt. Após um turno, Claude Code emite uma mensagem `prompt_suggestion` carregando um prompt de usuário previsto. Claude Code não gera sugestão para alguns turnos, como quando sua conta está próxima ou no limite de uso. Veja [Quando Claude Code pula sugestões](/docs/pt/interactive-mode#when-claude-code-skips-suggestions) |590| `promptSuggestions` | `boolean` | `false` | Habilitar sugestões de prompt. Após um turno, o Claude Code emite uma mensagem `prompt_suggestion` contendo uma previsão do próximo prompt do usuário. O Claude Code não gera sugestão em alguns turnos, por exemplo, quando sua conta está perto de atingir ou já atingiu o limite de uso. Consulte [Quando o Claude Code pula sugestões](/docs/pt/interactive-mode#when-claude-code-skips-suggestions) |
586| `resume` | `string` | `undefined` | ID de sessão a retomar |591| `resume` | `string` | `undefined` | ID da sessão a retomar |
587| `resumeDropsTurn` | `string` | `undefined` | Com `resumeSessionAt`: o UUID do prompt do turno que a retomada truncada pretende descartar. Claude Code recusa a retomada quando o intervalo descartado contém algo não atribuível a esse turno, como mensagens enfileiradas absorvidas ou notificações de tarefas, e nomeia o sinalizador `--resume-drops-turn` na mensagem de rejeição. Apenas o Agent SDK e retomadas em modo de impressão leem o par. Requer Claude Code v2.1.223 ou posterior |592| `resumeDropsTurn` | `string` | `undefined` | Com `resumeSessionAt`: o UUID do prompt do turno que a retomada com truncamento pretende descartar. O Claude Code recusa a retomada quando o intervalo descartado contém algo não atribuível a esse turno, como mensagens enfileiradas absorvidas ou notificações de tarefas, e nomeia a flag `--resume-drops-turn` na mensagem de rejeição. Apenas o Agent SDK e as retomadas no modo print leem o par. Requer o Claude Code v2.1.223 ou posterior |
588| `resumeSessionAt` | `string` | `undefined` | Retomar sessão em um UUID de mensagem específico |593| `resumeSessionAt` | `string` | `undefined` | Retomar a sessão em um UUID de mensagem específico |
589| `sandbox` | [`SandboxSettings`](#sandboxsettings) | `undefined` | Configurar comportamento de sandbox programaticamente. Veja [Sandbox settings](#sandboxsettings) para detalhes |594| `sandbox` | [`SandboxSettings`](#sandboxsettings) | `undefined` | Configurar o comportamento do sandbox programaticamente. Consulte [Configurações do sandbox](#sandboxsettings) para obter detalhes |
590| `sessionId` | `string` | Auto-gerado | Use um UUID específico para a sessão em vez de auto-gerar um |595| `sessionId` | `string` | Gerado automaticamente | Usar um UUID específico para a sessão em vez de gerar um automaticamente |
591| `sessionStore` | [`SessionStore`](/docs/pt/agent-sdk/session-storage#the-sessionstore-interface) | `undefined` | Espelhar transcrições de sessão para um backend externo para que outro host possa retomá-las. Veja [Persist sessions to external storage](/docs/pt/agent-sdk/session-storage) |596| `sessionStore` | [`SessionStore`](/docs/pt/agent-sdk/session-storage#the-sessionstore-interface) | `undefined` | Espelhar as transcrições da sessão em um backend externo para que outro host possa retomá-las. Consulte [Persistir sessões em armazenamento externo](/docs/pt/agent-sdk/session-storage) |
592| `sessionStoreFlush` | `'batched' \| 'eager'` | `'batched'` | *Alfa.* Modo de flush para `sessionStore`. Ignorado quando `sessionStore` não está definido |597| `sessionStoreFlush` | `'batched' \| 'eager'` | `'batched'` | *Alpha.* Modo de descarga para `sessionStore`. Ignorado quando `sessionStore` não está definido |
593| `settings` | `string \| Settings` | `undefined` | Objeto de [configurações](/docs/pt/settings) inline, caminho para um arquivo de configurações, ou uma string JSON inline. Popula a camada de configurações de flag na [ordem de precedência](/docs/pt/settings#settings-precedence). Altere em tempo de execução com [`applyFlagSettings()`](#applyflagsettings) |598| `settings` | `string \| Settings` | `undefined` | Objeto inline de [configurações](/docs/pt/settings), um caminho de arquivo de configurações ou uma string JSON inline. Preenche a camada de configurações de flag na [ordem de precedência](/docs/pt/settings#settings-precedence). Altere em tempo de execução com [`applyFlagSettings()`](#applyflagsettings) |
594| `settingSources` | [`SettingSource`](#settingsource)`[]` | Padrões da CLI (todas as fontes) | Controle quais configurações do sistema de arquivos carregar. Passe `[]` para desativar configurações de usuário, projeto e local. [Política gerenciada por endpoint](/docs/pt/managed-settings#delivery-mechanisms) carrega independentemente; configurações gerenciadas pelo servidor são buscadas quando a sessão se autentica com uma credencial organizacional em uma [configuração elegível](/docs/pt/server-managed-settings#platform-availability). Veja [Use Claude Code features](/docs/pt/agent-sdk/claude-code-features#what-settingsources-does-not-control) |599| `settingSources` | [`SettingSource`](#settingsource)`[]` | Padrões da CLI (todas as fontes) | Controla quais configurações do sistema de arquivos carregar. Passe `[]` para desabilitar as configurações de usuário, de projeto e locais. A [política gerenciada por endpoint](/docs/pt/managed-settings#delivery-mechanisms) é carregada de qualquer forma; as configurações gerenciadas pelo servidor são obtidas quando a sessão se autentica com uma credencial de organização em uma [configuração elegível](/docs/pt/server-managed-settings#platform-availability). Consulte [Usar recursos do Claude Code](/docs/pt/agent-sdk/claude-code-features#what-settingsources-does-not-control) |
595| `skills` | `string[] \| 'all'` | `undefined` | Skills disponíveis para a sessão. Passe `'all'` para ativar cada skill descoberta, ou uma lista de nomes de skills. Passe apenas nomes exatos. No Agent SDK v0.3.221 ou posterior, o SDK rejeita nomes malformados e em forma de wildcard com um erro antes de iniciar o processo Claude Code. Quando definido, o SDK adiciona a ferramenta Skill a `allowedTools` automaticamente. Se você também passar `tools`, inclua `'Skill'` nessa lista. Veja [Skills](/docs/pt/agent-sdk/skills) |600| `skills` | `string[] \| 'all'` | `undefined` | Skills disponíveis para a sessão. Passe `'all'` para habilitar todas as skills descobertas, ou uma lista de nomes de skills. Passe apenas nomes exatos. No Agent SDK v0.3.221 ou posterior, o SDK rejeita nomes malformados e em forma de curinga com um erro antes de iniciar o processo do Claude Code. Quando definido, o SDK adiciona a ferramenta Skill a `allowedTools` automaticamente. Se você também passar `tools`, inclua `'Skill'` nessa lista. Consulte [Skills](/docs/pt/agent-sdk/skills) |
596| `spawnClaudeCodeProcess` | `(options: SpawnOptions) => SpawnedProcess` | `undefined` | Função personalizada para gerar o processo Claude Code. Use para executar Claude Code em VMs, contêineres ou ambientes remotos |601| `spawnClaudeCodeProcess` | `(options: SpawnOptions) => SpawnedProcess` | `undefined` | Função personalizada para gerar o processo do Claude Code. Use para executar o Claude Code em VMs, contêineres ou ambientes remotos |
597| `stderr` | `(data: string) => void` | `undefined` | Callback para saída stderr |602| `stderr` | `(data: string) => void` | `undefined` | Callback para a saída stderr |
598| `strictMcpConfig` | `boolean` | `false` | Use apenas os servidores passados em `mcpServers` e ignore o projeto `.mcp.json`, configurações do usuário, servidores MCP fornecidos por plugin, e [conectores claude.ai](/docs/pt/mcp#use-mcp-servers-from-claude-ai) |603| `strictMcpConfig` | `boolean` | `false` | Usa apenas os servidores passados em `mcpServers` e ignora o `.mcp.json` do projeto, as configurações de usuário, os servidores MCP fornecidos por plugins e os [conectores do claude.ai](/docs/pt/mcp#use-mcp-servers-from-claude-ai) |
599| `systemPrompt` | `string \| string[] \| { type: 'custom'; prompt: string \| string[]; snapshot?: boolean } \| { type: 'preset'; preset: 'claude_code'; append?: string; excludeDynamicSections?: boolean; snapshot?: boolean }` | `undefined` (prompt mínimo) | Configuração de prompt do sistema. Passe uma string para prompt personalizado, ou `{ type: 'preset', preset: 'claude_code' }` para usar o prompt do sistema do Claude Code. Passe um array de strings com a constante exportada `SYSTEM_PROMPT_DYNAMIC_BOUNDARY` entre as partes estática e por solicitação para [cachear a parte estática de um prompt personalizado](/docs/pt/agent-sdk/modifying-system-prompts#cache-the-static-part-of-a-custom-prompt). Ao usar a forma de objeto preset, adicione `append` para estendê-lo com instruções adicionais, e defina `excludeDynamicSections: true` para mover contexto por sessão para a primeira mensagem do usuário para [melhor reutilização de cache de prompt entre máquinas](/docs/pt/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines). Defina `snapshot: false` para reconstruir o prompt em cada solicitação em vez de [reutilizar o prompt que a sessão registrou em sua primeira solicitação](/docs/pt/agent-sdk/modifying-system-prompts#change-the-prompt-of-an-existing-session). Para definir `snapshot` em um prompt personalizado, passe a forma `{ type: 'custom', prompt }`. A forma `{ type: 'custom' }` e o campo `snapshot` requerem TypeScript Agent SDK v0.3.257 ou posterior |604| `systemPrompt` | `string \| string[] \| { type: 'custom'; prompt: string \| string[]; snapshot?: boolean } \| { type: 'preset'; preset: 'claude_code'; append?: string; excludeDynamicSections?: boolean; snapshot?: boolean }` | `undefined` (prompt mínimo) | Configuração do system prompt. Passe uma string para um prompt personalizado, ou `{ type: 'preset', preset: 'claude_code' }` para usar o system prompt do Claude Code. Passe um array de strings com a constante exportada `SYSTEM_PROMPT_DYNAMIC_BOUNDARY` entre as partes estática e por requisição para [armazenar em cache a parte estática de um prompt personalizado](/docs/pt/agent-sdk/modifying-system-prompts#cache-the-static-part-of-a-custom-prompt). Ao usar a forma de objeto preset, adicione `append` para estendê-lo com instruções adicionais e defina `excludeDynamicSections: true` para mover o contexto por sessão para a primeira mensagem do usuário, obtendo [melhor reutilização do cache de prompt entre máquinas](/docs/pt/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines). Defina `snapshot: false` para reconstruir o prompt a cada requisição em vez de [reutilizar o prompt que a sessão registrou em sua primeira requisição](/docs/pt/agent-sdk/modifying-system-prompts#change-the-prompt-of-an-existing-session). Para definir `snapshot` em um prompt personalizado, passe a forma `{ type: 'custom', prompt }`. A forma `{ type: 'custom' }` e o campo `snapshot` exigem o TypeScript Agent SDK v0.3.257 ou posterior |
600| `taskBudget` | `{ total: number }` | `undefined` | *Alfa.* Orçamento de tarefa do lado da API em tokens. Quando definido, o modelo é informado sobre seu orçamento de token restante para que possa controlar o uso de ferramentas e encerrar antes do limite |605| `taskBudget` | `{ total: number }` | `undefined` | *Alpha.* Orçamento de tarefa do lado da API em tokens. Quando definido, o modelo é informado sobre seu orçamento de tokens restante para poder dosar o uso de ferramentas e concluir antes do limite |
601| `thinking` | [`ThinkingConfig`](#thinkingconfig) | `{ type: 'adaptive' }` para modelos suportados | Controla o comportamento de pensamento/raciocínio do Claude. Veja [`ThinkingConfig`](#thinkingconfig) para opções |606| `thinking` | [`ThinkingConfig`](#thinkingconfig) | `{ type: 'adaptive' }` para modelos suportados | Controla o comportamento de pensamento/raciocínio de Claude. Consulte [`ThinkingConfig`](#thinkingconfig) para ver as opções |
602| `title` | `string` | `undefined` | Título de exibição para a sessão. Ao retomar via `resume` ou `continue`, o título persistido da sessão retomada tem precedência; use [`renameSession()`](#renamesession) para renomear uma sessão existente |607| `title` | `string` | `undefined` | Título de exibição da sessão. Ao retomar via `resume` ou `continue`, o título persistido da sessão retomada tem precedência; use [`renameSession()`](#renamesession) para renomear uma sessão existente |
603| `toolAliases` | `Record<string, string>` | `undefined` | Mapear nomes de ferramentas integradas para nomes de ferramentas MCP para que Claude chame sua implementação MCP em vez da integrada. Por exemplo, `{ Bash: 'mcp__workspace__bash' }` |608| `toolAliases` | `Record<string, string>` | `undefined` | Mapeia nomes de ferramentas integradas para nomes de ferramentas MCP para que Claude chame sua implementação MCP no lugar da integrada. Por exemplo, `{ Bash: 'mcp__workspace__bash' }` |
604| `toolConfig` | [`ToolConfig`](#toolconfig) | `undefined` | Configuração para comportamento de ferramenta integrada. Veja [`ToolConfig`](#toolconfig) para detalhes |609| `toolConfig` | [`ToolConfig`](#toolconfig) | `undefined` | Configuração do comportamento das ferramentas integradas. Consulte [`ToolConfig`](#toolconfig) para obter detalhes |
605| `tools` | `string[] \| { type: 'preset'; preset: 'claude_code' }` | `undefined` | Configuração de ferramenta. Passe um array de nomes de ferramentas ou use o preset para obter as ferramentas padrão do Claude Code |610| `tools` | `string[] \| { type: 'preset'; preset: 'claude_code' }` | `undefined` | Configuração de ferramentas. Passe um array de nomes de ferramentas ou use o preset para obter as ferramentas padrão do Claude Code |
606| `verbatimPrompts` | `boolean` | `false` | Entregar cada prompt conforme escrito. O SDK envia cada mensagem de usuário com `client_composed: true`. Veja [`client_composed`](#sdkusermessage) para o que Claude Code pula nessas mensagens. Use esta opção quando seu texto de prompt inclui conteúdo que o usuário final não digitou. Para controle por turno, deixe desativado e defina `client_composed` em mensagens individuais transmitidas em vez disso. Requer TypeScript Agent SDK v0.3.280 ou posterior e Claude Code v2.1.248 ou posterior; a versão Claude Code agrupada com essas versões SDK satisfaz o requisito de versão Claude Code |611| `verbatimPrompts` | `boolean` | `false` | Entrega cada prompt exatamente como escrito. O SDK envia cada mensagem do usuário com `client_composed: true`. Consulte [`client_composed`](#sdkusermessage) para ver o que o Claude Code ignora nessas mensagens. Use esta opção quando o texto do seu prompt incluir conteúdo que o usuário final não digitou. Para controle por turno, deixe-a desativada e defina `client_composed` em mensagens transmitidas individualmente. Requer o TypeScript Agent SDK v0.3.280 ou posterior e o Claude Code v2.1.248 ou posterior; a versão do Claude Code incluída nessas versões do SDK atende ao requisito do Claude Code |
607 612
608<h4 id="handle-slow-or-stalled-api-responses">613<h4 id="handle-slow-or-stalled-api-responses">
609 Lidar com respostas de API lentas ou travadas614 Lidar com respostas de API lentas ou travadas
610</h4>615</h4>
611 616
612O subprocesso da CLI lê várias variáveis de ambiente que controlam timeouts de API e detecção de travamento. Passe-as através da opção `env`:617O subprocesso da CLI lê várias variáveis de ambiente que controlam timeouts de API e a detecção de travamentos. Passe-as por meio da opção `env`:
613 618
614```typescript theme={null}619```typescript theme={null}
615import { query } from "@anthropic-ai/claude-agent-sdk";620import { query } from "@anthropic-ai/claude-agent-sdk";
627});632});
628```633```
629 634
630* `API_TIMEOUT_MS`: timeout por solicitação no cliente Anthropic, em milissegundos. Padrão `600000`. Aplica-se ao loop principal e a todos os subagentes.635* `API_TIMEOUT_MS`: timeout por requisição no cliente da Anthropic, em milissegundos. Padrão `600000`. Aplica-se ao loop principal e a todos os subagentes.
631* `CLAUDE_CODE_MAX_RETRIES`: máximo de tentativas de API. Padrão `10`, limitado a `15`. Cada tentativa obtém sua própria janela `API_TIMEOUT_MS`, então o tempo de parede no pior caso é aproximadamente `API_TIMEOUT_MS × (CLAUDE_CODE_MAX_RETRIES + 1)` mais backoff. Para execuções sem supervisão que precisam aguardar através de interrupções mais longas, defina [`CLAUDE_CODE_RETRY_WATCHDOG=1`](/docs/pt/errors#tune-retry-behavior): ele tenta erros de capacidade transitória indefinidamente e, no Claude Code v2.1.199 ou posterior, aumenta o padrão para outros erros transitórios para `300` e remove o limite nesta variável.636* `CLAUDE_CODE_MAX_RETRIES`: máximo de novas tentativas da API. Padrão `10`, limitado a `15`. Cada nova tentativa tem sua própria janela de `API_TIMEOUT_MS`, portanto o tempo total no pior caso é aproximadamente `API_TIMEOUT_MS × (CLAUDE_CODE_MAX_RETRIES + 1)` mais o backoff. Para execuções não supervisionadas que precisam aguardar interrupções mais longas, defina [`CLAUDE_CODE_RETRY_WATCHDOG=1`](/docs/pt/errors#tune-retry-behavior): ela tenta novamente erros transitórios de capacidade indefinidamente e, no Claude Code v2.1.199 ou posterior, eleva o padrão para outros erros transitórios a `300` e remove o limite desta variável.
632* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`: watchdog de travamento para subagentes. Enquanto o watchdog de stream está ativado, o padrão é `CLAUDE_STREAM_IDLE_TIMEOUT_MS` mais 5 minutos, que chega a `600000` a menos que você aumente essa variável. Com o watchdog de stream desativado, o padrão é `600000`. Antes de v2.1.257, o padrão era sempre `600000`.637* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`: watchdog de travamento para subagentes. Enquanto o watchdog de stream está ativado, o padrão é `CLAUDE_STREAM_IDLE_TIMEOUT_MS` mais 5 minutos, o que resulta em `600000`, a menos que você aumente essa variável. Com o watchdog de stream desativado, o padrão é `600000`. Antes da v2.1.257, o padrão era sempre `600000`.
633 638
634 O temporizador redefine em cada evento de stream. Em caso de travamento, Claude Code aborta o subagente e relata o travamento ao pai. Para um subagente em segundo plano, também marca a tarefa como falhada e anexa qualquer resultado parcial.639 O temporizador é redefinido a cada evento de stream. Em caso de travamento, o Claude Code aborta o subagente e relata o travamento ao pai. Para um subagente em segundo plano, ele também marca a tarefa como falha e anexa qualquer resultado parcial.
635* `CLAUDE_ENABLE_STREAM_WATCHDOG` com `CLAUDE_STREAM_IDLE_TIMEOUT_MS`: watchdog de stream que aborta a solicitação quando os cabeçalhos chegaram mas o corpo da resposta para de fazer stream. O watchdog está ativado por padrão para todos os provedores; defina `CLAUDE_ENABLE_STREAM_WATCHDOG=0` para desativá-lo. `CLAUDE_STREAM_IDLE_TIMEOUT_MS` padrão é `300000` e é fixado nesse mínimo. Após a anulação, [Tentativas automáticas](/docs/pt/errors#automatic-retries) cobre o que Claude Code faz, com base em quanto a resposta havia progredido.640* `CLAUDE_ENABLE_STREAM_WATCHDOG` com `CLAUDE_STREAM_IDLE_TIMEOUT_MS`: watchdog de stream que aborta a requisição quando os cabeçalhos chegaram, mas o corpo da resposta para de ser transmitido. O watchdog está ativado por padrão para todos os provedores; defina `CLAUDE_ENABLE_STREAM_WATCHDOG=0` para desativá-lo. `CLAUDE_STREAM_IDLE_TIMEOUT_MS` tem padrão `300000` e é limitado a esse mínimo. Após o aborto, [Novas tentativas automáticas](/docs/pt/errors#automatic-retries) aborda o que o Claude Code faz, com base em quanto a resposta havia avançado.
636 641
637 Enquanto o watchdog aguarda uma resposta que um gateway atrás de `ANTHROPIC_BASE_URL` mantém aberta com pings keep-alive, um host que define `includePartialMessages` continua recebendo eventos de `ping` [stream](#sdkpartialassistantmessage), então leia esses frames como vivacidade em vez de expirar a sessão no silêncio. Antes de v2.1.257, os frames paravam 5 minutos após o último evento de stream real.642 Enquanto o watchdog aguarda uma resposta que um gateway por trás de `ANTHROPIC_BASE_URL` mantém aberta com pings de keep-alive, um host que define `includePartialMessages` continua recebendo [eventos de stream](#sdkpartialassistantmessage) `ping`, portanto interprete esses frames como sinal de atividade em vez de encerrar a sessão por timeout devido ao silêncio. Antes da v2.1.257, os frames paravam 5 minutos após o último evento de stream real.
638 643
639<h3 id="query-object">644<h3 id="query-object">
640 Objeto `Query`645 Objeto `Query`
696 701
697| Método | Descrição |702| Método | Descrição |
698| :- | :- |703| :- | :- |
699| `interrupt()` | Interrompe a consulta. Apenas disponível em modo de entrada de transmissão. Quando a CLI anuncia a capacidade `interrupt_receipt_v1` em [`SDKSystemMessage.capabilities`](#sdksystemmessage), resolve com um [`SDKControlInterruptResponse`](#sdkcontrolinterruptresponse) listando as mensagens que estavam pendentes quando a interrupção chegou. Resolve `undefined` em CLIs anteriores a v2.1.205 |704| `interrupt()` | Interrompe a consulta. Disponível apenas no modo de entrada por streaming. Quando a CLI anuncia a capacidade `interrupt_receipt_v1` em [`SDKSystemMessage.capabilities`](#sdksystemmessage), resolve com uma [`SDKControlInterruptResponse`](#sdkcontrolinterruptresponse) listando as mensagens que estavam pendentes quando a interrupção chegou. Resolve `undefined` em CLIs anteriores à v2.1.205 |
700| `rewindFiles(userMessageId, options?)` | Restaura arquivos para seu estado na mensagem de usuário especificada. Passe `{ dryRun: true }` para visualizar mudanças. Requer `enableFileCheckpointing: true`. Veja [File checkpointing](/docs/pt/agent-sdk/file-checkpointing) |705| `rewindFiles(userMessageId, options?)` | Restaura os arquivos ao estado em que estavam na mensagem do usuário especificada. Passe `{ dryRun: true }` para visualizar as alterações. Requer `enableFileCheckpointing: true`. Consulte [Checkpointing de arquivos](/docs/pt/agent-sdk/file-checkpointing) |
701| `setPermissionMode()` | Altera o modo de permissão (apenas disponível em modo de entrada de transmissão) |706| `setPermissionMode()` | Altera o modo de permissão (disponível apenas no modo de entrada por streaming) |
702| `setModel()` | Altera o modelo (apenas disponível em modo de entrada de transmissão). Passar `undefined` ou a string `"default"` redefine para [o modelo padrão do Claude Code](/docs/pt/model-config) |707| `setModel()` | Altera o modelo (disponível apenas no modo de entrada por streaming). Passar `undefined` ou a string `"default"` redefine para o [modelo padrão do Claude Code](/docs/pt/model-config) |
703| `setMaxThinkingTokens()` | *Descontinuado:* Use a opção `thinking` em vez disso. Altera os tokens de pensamento máximos. Passar `null` redefine o pensamento para o padrão da sessão: uma substituição no meio da sessão é limpa, e o pensamento permanece desativado para sessões que o têm desativado |708| `setMaxThinkingTokens()` | *Obsoleto:* Use a opção `thinking` em vez disso. Altera o máximo de tokens de pensamento. Passar `null` redefine o pensamento para o padrão da sessão: uma substituição feita no meio da sessão é removida, e o pensamento permanece desativado para sessões que o têm desabilitado |
704| `applyFlagSettings(settings)` | Mescla configurações na camada de configurações de flag da sessão em tempo de execução (apenas disponível em modo de entrada de transmissão). Veja [`applyFlagSettings()`](#applyflagsettings) |709| `applyFlagSettings(settings)` | Mescla configurações na camada de configurações de flag da sessão em tempo de execução (disponível apenas no modo de entrada por streaming). Consulte [`applyFlagSettings()`](#applyflagsettings) |
705| `updateSettings(source, settings)` | Escreve uma chave permitida no arquivo de configurações local do projeto ou no arquivo de configurações do usuário, para que o valor persista para sessões posteriores. Veja [`updateSettings()`](#updatesettings). Requer TypeScript SDK v0.3.257 ou posterior, que agrupa Claude Code v2.1.257 |710| `updateSettings(source, settings)` | Grava uma chave da lista de permitidas no arquivo de configurações locais do projeto ou no seu arquivo de configurações de usuário, para que o valor persista em sessões posteriores. Consulte [`updateSettings()`](#updatesettings). Requer o TypeScript SDK v0.3.257 ou posterior, que inclui o Claude Code v2.1.257 |
706| `initializationResult()` | Retorna o resultado de inicialização completo incluindo comandos suportados, modelos, informações de conta e configuração de estilo de saída |711| `initializationResult()` | Retorna o resultado completo da inicialização, incluindo comandos suportados, modelos, informações da conta e configuração de estilo de saída |
707| `reinitialize()` | Re-envia a solicitação de controle `initialize` para a CLI em execução e retorna um resultado novo em vez do resultado de primeira conexão em cache. Use-o após uma lacuna de transporte, como reconectar a uma sessão após uma desconexão, para que solicitações de permissão pendentes alcancem seu callback `canUseTool` novamente. Torne o callback idempotente por ID de solicitação, porque uma solicitação cuja resposta foi perdida é despachada novamente. Requer Claude Code v2.1.195 ou posterior |712| `reinitialize()` | Reenvia a requisição de controle `initialize` para a CLI em execução e retorna um resultado novo em vez do resultado em cache da primeira conexão. Use-o após uma lacuna de transporte, como ao reconectar-se a uma sessão após uma desconexão, para que as requisições de permissão pendentes cheguem novamente ao seu callback `canUseTool`. Torne o callback idempotente por ID de requisição, porque uma requisição cuja resposta foi perdida é despachada novamente. Requer o Claude Code v2.1.195 ou posterior |
708| `supportedCommands()` | Retorna comandos disponíveis. A partir do Agent SDK v0.3.216 a lista reflete mudanças de comando no meio da sessão; veja [`SDKCommandsChangedMessage`](#sdkcommandschangedmessage) |713| `supportedCommands()` | Retorna os comandos disponíveis. A partir do Agent SDK v0.3.216, a lista reflete alterações de comandos no meio da sessão; consulte [`SDKCommandsChangedMessage`](#sdkcommandschangedmessage) |
709| `supportedModels()` | Retorna modelos disponíveis com informações de exibição |714| `supportedModels()` | Retorna os modelos disponíveis com informações de exibição |
710| `supportedAgents()` | Retorna subagentes disponíveis como [`AgentInfo`](#agentinfo)`[]` |715| `supportedAgents()` | Retorna os subagentes disponíveis como [`AgentInfo`](#agentinfo)`[]` |
711| `mcpServerStatus()` | Retorna status de servidores MCP conectados como [`McpServerStatus`](#mcpserverstatus)`[]` |716| `mcpServerStatus()` | Retorna o status dos servidores MCP conectados como [`McpServerStatus`](#mcpserverstatus)`[]` |
712| `getContextUsage(opts?)` | Retorna um [`SDKControlGetContextUsageResponse`](#sdkcontrolgetcontextusageresponse) dividindo o uso da janela de contexto da sessão por categoria, skill e ferramenta. Com o `detail` padrão, é o mesmo dado que `/context` mostra em uma sessão interativa, computado com solicitações de API de contagem de token que não aparecem no fluxo de mensagens; veja [como essas solicitações são tratadas](#sdkcontrolgetcontextusageresponse). A [opção `detail`](#sdkcontrolgetcontextusageresponse) requer Agent SDK v0.3.257 ou posterior |717| `getContextUsage(opts?)` | Retorna uma [`SDKControlGetContextUsageResponse`](#sdkcontrolgetcontextusageresponse) que detalha o uso da janela de contexto da sessão por categoria, skill e ferramenta. Com o `detail` padrão, são os mesmos dados que `/context` mostra em uma sessão interativa, calculados com requisições de API de contagem de tokens 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 |
713| `readFile(path, options?)` | Lê um arquivo do sistema de arquivos da sessão. Claude Code resolve o caminho contra `cwd`; [O que `readFile()` pode ler](#what-readfile-can-read) lista os arquivos que ele serve. Passe `{ maxBytes }` para alterar o limite de leitura (padrão 1 MB, teto 10 MB) e `{ encoding: 'base64' }` para arquivos binários como imagens. Resolve com um [`SDKControlReadFileResponse`](#sdkcontrolreadfileresponse), ou `null` em negação de permissão, arquivo ausente, ou erro de transporte. Requer TypeScript SDK v0.2.121 ou posterior |718| `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 1 MB, máximo 10 MB) e `{ encoding: 'base64' }` para arquivos binários, como imagens. Resolve com uma [`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 |
714| `reloadPlugins(options?)` | Recarrega plugins do disco, para que plugins que você instala ou edita no meio da sessão alcancem a sessão em execução. Resolve com um [`SDKControlReloadPluginsResponse`](#sdkcontrolreloadpluginsresponse) listando os comandos, subagentes, plugins e status do servidor 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 |719| `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 uma [`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 |
715| `reloadSkills()` | Recarrega 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. Resolve com um [`SDKControlReloadSkillsResponse`](#sdkcontrolreloadskillsresponse) listando as skills disponíveis após o recarregamento. Requer Agent SDK v0.3.163 ou posterior |720| `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. Resolve com uma [`SDKControlReloadSkillsResponse`](#sdkcontrolreloadskillsresponse) listando as skills disponíveis após o recarregamento. Requer o Agent SDK v0.3.163 ou posterior |
716| `reloadOutputStyles()` | Re-lê [estilos de saída](/docs/pt/output-styles) 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. Resolve com um [`SDKControlReloadOutputStylesResponse`](#sdkcontrolreloadoutputstylesresponse) listando os nomes de estilo disponíveis após o recarregamento. Requer Agent SDK v0.3.261 ou posterior |721| `reloadOutputStyles()` | Relê os [estilos de saída](/docs/pt/output-styles) 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. Resolve com uma [`SDKControlReloadOutputStylesResponse`](#sdkcontrolreloadoutputstylesresponse) listando os nomes dos estilos disponíveis após o recarregamento. Requer o Agent SDK v0.3.261 ou posterior |
717| `accountInfo()` | Retorna informações de conta |722| `accountInfo()` | Retorna informações da conta |
718| `reconnectMcpServer(serverName)` | Reconectar um servidor MCP por nome. Se o nome também corresponder a uma entrada em um arquivo de configurações como `.mcp.json` ou `~/.claude.json`, Claude Code reconecta o servidor que você configurou através de [`mcpServers`](#options) ou `setMcpServers()`, não a entrada do arquivo de configurações. Essa ordem de resolução requer Claude Code v2.1.257 ou posterior |723| `reconnectMcpServer(serverName)` | Reconecta um servidor MCP pelo nome. Se o nome também corresponder a uma entrada em um arquivo de configurações como `.mcp.json` ou `~/.claude.json`, o Claude Code reconecta o servidor que você configurou por meio de [`mcpServers`](#options) ou `setMcpServers()`, não a entrada do arquivo de configurações. Essa ordem de resolução requer o Claude Code v2.1.257 ou posterior |
719| `toggleMcpServer(serverName, enabled)` | Habilita ou desabilita um servidor MCP pelo nome, com a mesma resolução de nomes que `reconnectMcpServer()`. Desabilitar um servidor o desconecta e remove suas ferramentas. Consulte [`toggleMcpServer()`](#togglemcpserver) para saber a versão do Claude Code necessária para cada tipo de servidor |724| `toggleMcpServer(serverName, enabled)` | Habilita ou desabilita um servidor MCP pelo nome, com a mesma resolução de nomes de `reconnectMcpServer()`. Desabilitar um servidor o desconecta e remove suas ferramentas. Consulte [`toggleMcpServer()`](#togglemcpserver) para ver a versão do Claude Code necessária para cada tipo de servidor |
720| `setMcpServers(servers)` | Substituir dinamicamente o conjunto de servidores MCP para esta sessão. Resolve com um [`McpSetServersResult`](#mcpsetserversresult) nomeando quais servidores foram adicionados e removidos, e quaisquer erros |725| `setMcpServers(servers)` | Substitui os servidores MCP que este método gerencia: servidores adicionados por meio dele e [servidores SDK em processo](#createsdkmcpserver). Resolve com um [`McpSetServersResult`](#mcpsetserversresult) informando quais servidores foram adicionados e removidos, além de eventuais erros; essa seção informa quais outros servidores permanecem conectados |
721| `readMcpResource(serverName, uri)` | *Alfa.* Lê um recurso MCP Apps `ui://` de um servidor MCP conectado para que sua aplicação possa renderizar um widget de ferramenta. Resolve com um [`SDKControlMcpReadResourceResponse`](#sdkcontrolmcpreadresourceresponse). Requer TypeScript Agent SDK v0.3.280 ou posterior |726| `readMcpResource(serverName, uri)` | *Alpha.* Lê um recurso `ui://` do MCP Apps de um servidor MCP conectado para que seu aplicativo possa renderizar o widget de uma ferramenta. Resolve com uma [`SDKControlMcpReadResourceResponse`](#sdkcontrolmcpreadresourceresponse). Requer o TypeScript Agent SDK v0.3.280 ou posterior |
722| `streamInput(stream)` | Transmitir mensagens de entrada para a consulta para conversas multi-turno |727| `streamInput(stream)` | Transmite mensagens de entrada para a consulta em conversas de múltiplos turnos |
723| `stopTask(taskId)` | Parar uma tarefa de fundo em execução por ID |728| `stopTask(taskId)` | Interrompe uma tarefa em segundo plano em execução pelo ID |
724| `close()` | Fechar a consulta e encerrar o processo subjacente. Força o término da consulta e limpa todos os recursos |729| `close()` | Fecha a consulta e encerra o processo subjacente. Encerra a consulta à força e limpa todos os recursos |
725 730
726<h4 id="applyflagsettings">731<h4 id="applyflagsettings">
727 `applyFlagSettings()`732 `applyFlagSettings()`
728</h4>733</h4>
729 734
730Altera [configurações](/docs/pt/settings) em uma sessão em execução sem reiniciar a consulta. Use-a quando uma configuração que não tem um setter dedicado precisa mudar no meio da sessão, como apertar `permissions` depois que o agente lê entrada não confiável. `setModel()` e `setPermissionMode()` são setters dedicados para essas duas chaves; `applyFlagSettings()` é a forma geral que aceita qualquer subconjunto das chaves de configurações, e passar `model` aqui se comporta igual a `setModel()`.735Altera [configurações](/docs/pt/settings) em uma sessão em execução sem reiniciar a consulta. Use-o quando uma configuração que não tem um setter dedicado precisa mudar no meio da sessão, como restringir `permissions` depois que o agente lê entrada não confiável. `setModel()` e `setPermissionMode()` são setters dedicados para essas duas chaves; `applyFlagSettings()` é a forma geral que aceita qualquer subconjunto das chaves de configuração, e passar `model` aqui se comporta da mesma forma que `setModel()`.
731 736
732Apenas algumas chaves têm efeito no meio da sessão:737Apenas algumas chaves têm efeito no meio da sessão:
733 738
734* **Aplicadas no próximo turno**: `effortLevel`, `ultracode`, `permissions`, `hooks`, `skillOverrides`, `fastMode`, `agent`. Mudar `agent` também aplica a substituição de modelo e hooks desse agente no próximo turno. Seu prompt do sistema se aplica no próximo turno, ou, em uma sessão que [reutiliza um prompt do sistema registrado](/docs/pt/agent-sdk/modifying-system-prompts#change-the-prompt-of-an-existing-session), uma vez que a sessão é compactada.739* **Aplicadas no próximo turno**: `effortLevel`, `ultracode`, `permissions`, `hooks`, `skillOverrides`, `fastMode`, `agent`. Trocar `agent` também aplica a substituição de modelo e os hooks desse agente no próximo turno. O system prompt dele se aplica no próximo turno ou, em uma sessão que [reutiliza um system prompt registrado](/docs/pt/agent-sdk/modifying-system-prompts#change-the-prompt-of-an-existing-session), assim que a sessão for compactada.
735* **Aplicadas durante o turno atual**: `model`. Se você mudar `model` enquanto Claude está trabalhando em um turno, a resposta que Claude já está gerando termina no modelo antigo, e o resto do turno, começando com a próxima chamada que Claude Code faz para o modelo, usa o novo. Subagentes mantêm seu próprio modelo. Antes de v2.1.212, uma mudança no meio do turno aguardava o próximo turno.740* **Aplicadas durante o turno atual**: `model`. Se você trocar `model` enquanto Claude está trabalhando em um turno, a resposta que Claude já está gerando termina no modelo antigo, e o restante do turno, a partir da próxima chamada que o Claude Code fizer ao modelo, usa o novo. Os subagentes mantêm seu próprio modelo. Antes da v2.1.212, uma troca no meio do turno aguardava o próximo turno.
736* **Sem efeito no meio da sessão**: as opções de prompt do sistema. Estas são resolvidas uma vez na inicialização, então a sessão em execução mantém o valor original mesmo que a chamada tenha sucesso. Para alterá-los, inicie uma nova sessão.741* **Sem efeito no meio da sessão**: as opções de system prompt. Elas são resolvidas uma única vez na inicialização, portanto a sessão em execução mantém o valor original mesmo que a chamada tenha sucesso. Para alterá-las, inicie uma nova sessão.
737 742
738`effortLevel` aceita um nome de [nível de esforço](/docs/pt/model-config#adjust-effort-level). Também aceita `"ultracode"`, que executa a sessão em esforço `xhigh` e ativa [ultracode](/docs/pt/workflows#let-claude-decide-with-ultracode). `applyFlagSettings()` declara `effortLevel` sem esse valor, então em TypeScript passe `{ ultracode: true, effortLevel: "xhigh" }` para o mesmo resultado, ou a chave [`ultracode`](/docs/pt/settings-reference#ultracode) sozinha para ativar ultracode no nível de esforço atual da sessão. O valor `ultracode` requer Claude Code v2.1.203 ou posterior e é aceito apenas por `applyFlagSettings()`, não pela chave `effortLevel` em um arquivo de configurações. Antes de v2.1.284, a chave `ultracode` sozinha também definia o nível para `xhigh`.743`effortLevel` aceita o nome de um [nível de esforço](/docs/pt/model-config#adjust-effort-level). Também aceita `"ultracode"`, que solicita esforço `xhigh` com o [ultracode](/docs/pt/workflows#let-claude-decide-with-ultracode) ativado. `applyFlagSettings()` declara `effortLevel` sem esse valor, portanto em TypeScript passe `{ ultracode: true, effortLevel: "xhigh" }` para obter o mesmo resultado, ou apenas a chave [`ultracode`](/docs/pt/settings-reference#ultracode) para ativar o ultracode no nível de esforço atual da sessão. O valor `ultracode` requer o Claude Code v2.1.203 ou posterior e é aceito apenas por `applyFlagSettings()`, não pela chave `effortLevel` em um arquivo de configurações. Antes da v2.1.284, a chave `ultracode` sozinha também definia o nível como `xhigh`.
739 744
740Os valores são escritos na camada de configurações de flag, mesclados sobre o que a opção `settings` inline de `query()` definiu na inicialização. Esta é a mesma camada que a [seção de precedência na página](#settings-precedence) chama de opções programáticas.745Os valores são gravados na camada de configurações de flag, mesclados sobre o que a opção inline `settings` de `query()` definiu na inicialização. Esse é o mesmo nível que a [seção de precedência nesta página](#settings-precedence) chama de opções programáticas.
741 746
742Chamadas sucessivas fazem shallow-merge de chaves de nível superior. Uma segunda chamada com `{ permissions: {...} }` substitui o objeto `permissions` inteiro da chamada anterior em vez de fazer deep-merge nele.747Chamadas sucessivas fazem uma mesclagem superficial das chaves de nível superior. Uma segunda chamada com `{ permissions: {...} }` substitui todo o objeto `permissions` da chamada anterior, em vez de mesclá-lo profundamente.
743 748
744Para limpar uma chave que você definiu com `applyFlagSettings()`, passe `null` para essa chave. A maioria das chaves então volta a um valor que a opção `settings` de `query()` definiu na inicialização, depois a fontes de precedência mais baixa. Um `model` limpo redefine para [o modelo padrão do Claude Code](/docs/pt/model-config), mesmo quando um arquivo de configurações define `model`. Passar `undefined` não tem efeito porque a serialização JSON a descarta.749Para limpar uma chave que você definiu com `applyFlagSettings()`, passe `null` para essa chave. A maioria das chaves então recorre primeiro a um valor que a opção `settings` de `query()` definiu na inicialização e, em seguida, a fontes de menor precedência. Um `model` limpo é redefinido para o [modelo padrão do Claude Code](/docs/pt/model-config), mesmo quando um arquivo de configurações define `model`. Passar `undefined` não tem efeito porque a serialização JSON o descarta.
745 750
746Três chaves além de `model` redefinem o estado da sessão em vez de voltar:751Três chaves além de `model` redefinem o estado da sessão em vez de recorrer a um fallback:
747 752
748* `effortLevel: null` retorna a sessão ao nível de esforço padrão do modelo, não à opção `effort` de `query()` ou um `effortLevel` de um arquivo de configurações.753* `effortLevel: null` retorna a sessão ao nível de esforço padrão do modelo, não à opção `effort` de `query()` nem a um `effortLevel` de um arquivo de configurações.
749* `agent: null` executa a thread principal sem agente, começando com o próximo turno, em vez de restaurar a opção `agent` de `query()` ou um `agent` de um arquivo de configurações. Se o agente limpo tivesse aplicado seu próprio modelo, a sessão volta ao modelo que resolveu na inicialização.754* `agent: null` executa a thread principal sem agente, a partir do próximo turno, em vez de restaurar a opção `agent` de `query()` ou um `agent` de um arquivo de configurações. Se o agente removido tiver aplicado seu próprio modelo, a sessão retorna ao modelo que resolveu na inicialização.
750* `ultracode: null` desativa ultracode, como `false` faz, em vez de restaurar um valor `ultracode` de um arquivo de configurações. A sessão mantém seu nível de esforço atual, então passe `effortLevel` na mesma chamada para alterá-lo.755* `ultracode: null` desativa o ultracode, como `false` faz, em vez de restaurar um valor `ultracode` de um arquivo de configurações. A sessão mantém seu nível de esforço atual, portanto passe `effortLevel` na mesma chamada para alterá-lo.
751 756
752Apenas disponível em modo de entrada de transmissão, a mesma restrição que `setModel()` e `setPermissionMode()`.757Disponível apenas no modo de entrada por streaming, a mesma restrição de `setModel()` e `setPermissionMode()`.
753 758
754O exemplo abaixo muda o modelo ativo no meio da sessão, depois limpa a substituição para que o modelo volte ao [modelo padrão do Claude Code](/docs/pt/model-config).759O exemplo abaixo troca o modelo ativo no meio da sessão e, em seguida, limpa a substituição para que o modelo seja redefinido para o [modelo padrão do Claude Code](/docs/pt/model-config).
755 760
756```typescript theme={null}761```typescript theme={null}
757import { query } from "@anthropic-ai/claude-agent-sdk";762import { query } from "@anthropic-ai/claude-agent-sdk";
758 763
759const q = query({ prompt: messageStream });764const q = query({ prompt: messageStream });
760 765
761// Substituir o modelo para o resto da sessão766// Override the model for the rest of the session
762await q.applyFlagSettings({ model: "claude-opus-4-6" });767await q.applyFlagSettings({ model: "claude-opus-4-6" });
763 768
764// Depois: limpar a substituição; o modelo redefine para o modelo padrão do Claude Code769// Later: clear the override; the model resets to Claude Code's default
765await q.applyFlagSettings({ model: null });770await q.applyFlagSettings({ model: null });
766```771```
767 772
768<Note>773<Note>
769 `applyFlagSettings()` é apenas TypeScript. O SDK Python não expõe um método equivalente.774 `applyFlagSettings()` é exclusivo do TypeScript. O Python SDK não expõe um método equivalente.
770</Note>775</Note>
771 776
772<h4 id="updatesettings">777<h4 id="updatesettings">
773 `updateSettings()`778 `updateSettings()`
774</h4>779</h4>
775 780
776Escreve uma chave permitida em um arquivo de configurações em disco, para que o valor persista para sessões posteriores que carregam essa fonte. Cada fonte aceita uma chave, com um valor de string:781Grava uma chave da lista de permitidas em um arquivo de configurações no disco, para que o valor persista em sessões posteriores que carregam essa fonte. Cada fonte aceita uma chave, com um valor string:
777 782
778* **`"localSettings"`**: aceita `outputStyle` e mescla em um arquivo de configurações local do projeto, `.claude/settings.local.json`. O novo estilo entra em vigor na próxima solicitação da sessão.783* **`"localSettings"`**: aceita `outputStyle` e o mescla no arquivo de configurações locais do projeto, `.claude/settings.local.json`. O novo estilo entra em vigor na próxima requisição da sessão.
779* **`"userSettings"`**: aceita `effortLevel` e o salva como o [nível de esforço](/docs/pt/model-config#adjust-effort-level) padrão para o modelo atual da sessão, sob [`modelSettings`](/docs/pt/settings-reference#modelsettings) no arquivo de configurações do usuário. Passar `max` não escreve nada, porque `max` é apenas de sessão. A sessão em execução mantém seu nível de esforço atual de qualquer forma, então chame [`applyFlagSettings()`](#applyflagsettings) quando você também quiser alterar isso. Esta fonte requer TypeScript SDK v0.3.277 ou posterior, que agrupa Claude Code v2.1.277.784* **`"userSettings"`**: aceita `effortLevel` e o salva como o [nível de esforço](/docs/pt/model-config#adjust-effort-level) padrão para o modelo atual da sessão, em [`modelSettings`](/docs/pt/settings-reference#modelsettings) no seu arquivo de configurações de usuário. Passar `max` não grava nada, porque `max` vale apenas para a sessão. A sessão em execução mantém seu nível de esforço atual de qualquer forma, portanto chame [`applyFlagSettings()`](#applyflagsettings) quando também quiser alterá-lo. Esta fonte requer o TypeScript SDK v0.3.277 ou posterior, que inclui o Claude Code v2.1.277.
780 785
781A chamada rejeita quando a solicitação carrega qualquer outra chave, quando a sessão é executada sobre um transporte remoto, e quando os [`settingSources`](#options) da sessão excluem a fonte que você nomeia. Deletar uma chave não é suportado.786A chamada é rejeitada quando a requisição contém qualquer outra chave, quando a sessão é executada por um transporte remoto e quando as [`settingSources`](#options) da sessão excluem a fonte que você nomeia. Excluir uma chave não é suportado.
782 787
783<h4 id="togglemcpserver">788<h4 id="togglemcpserver">
784 `toggleMcpServer()`789 `toggleMcpServer()`
785</h4>790</h4>
786 791
787Desabilitar um servidor o desconecta e remove suas ferramentas da sessão. Para servidores adicionados no meio da sessão e para servidores em processo, isso depende da sua versão do Claude Code:792Desabilitar um servidor o desconecta e remove suas ferramentas da sessão. Para servidores que você adicionou no meio da sessão e para servidores em processo, isso depende da sua versão do Claude Code:
788 793
789* Um servidor stdio, SSE ou HTTP que você adicionou no meio da sessão com `setMcpServers()`: remover suas ferramentas requer Claude Code v2.1.285 ou posterior.794* Um servidor stdio, SSE ou HTTP que você adicionou no meio da sessão com `setMcpServers()`: remover suas ferramentas requer o Claude Code v2.1.285 ou posterior.
790* Um servidor em processo que você criou com [`createSdkMcpServer()`](#createsdkmcpserver), seja passado em `mcpServers` ou com `setMcpServers()`: desconectá-lo e remover suas ferramentas requer Claude Code v2.1.286 ou posterior. Desabilitar um deles também faz falhar as chamadas de ferramenta dele que ainda estão em execução, de modo que o Claude recebe imediatamente um resultado de erro para cada uma delas, sem esperar que seu handler retorne.795* Um servidor em processo que você criou com [`createSdkMcpServer()`](#createsdkmcpserver), seja passado em `mcpServers` ou com `setMcpServers()`: desconectá-lo e remover suas ferramentas requer o Claude Code v2.1.286 ou posterior. Desabilitar um deles também faz falhar as chamadas de ferramenta dele que ainda estão em execução, portanto Claude recebe imediatamente um resultado de erro para cada uma delas, sem esperar que seu handler retorne.
791 796
792<h3 id="warmquery">797<h3 id="warmquery">
793 `WarmQuery`798 `WarmQuery`
794</h3>799</h3>
795 800
796Handle retornado por [`startup()`](#startup). O subprocesso já está gerado e inicializado, então chamar `query()` neste handle escreve o prompt diretamente em um processo pronto sem latência de inicialização.801Handle retornado por [`startup()`](#startup). O subprocesso já foi gerado e inicializado, portanto chamar `query()` neste handle grava o prompt diretamente em um processo pronto, sem latência de inicialização.
797 802
798```typescript theme={null}803```typescript theme={null}
799interface WarmQuery extends AsyncDisposable {804interface WarmQuery extends AsyncDisposable {
808 813
809| Método | Descrição |814| Método | Descrição |
810| :- | :- |815| :- | :- |
811| `query(prompt)` | Enviar um prompt para o subprocesso pré-aquecido e retornar uma [`Query`](#query-object). Pode ser chamado apenas uma vez por `WarmQuery` |816| `query(prompt)` | Envia um prompt para o subprocesso pré-aquecido e retorna uma [`Query`](#query-object). Só pode ser chamado uma vez por `WarmQuery` |
812| `close()` | Fechar o subprocesso sem enviar um prompt. Use isso para descartar uma consulta quente que não é mais necessária |817| `close()` | Fecha o subprocesso sem enviar um prompt. Use para descartar uma consulta pré-aquecida que não é mais necessária |
813 818
814`WarmQuery` implementa `AsyncDisposable`, então pode ser usado com `await using` para limpeza automática.819`WarmQuery` implementa `AsyncDisposable`, portanto pode ser usado com `await using` para limpeza automática.
815 820
816<h3 id="spareprocess">821<h3 id="spareprocess">
817 `SpareProcess`822 `SpareProcess`
818</h3>823</h3>
819 824
820*Alfa.* Handle retornado por [`prewarm()`](#prewarm): um processo Claude Code iniciado que ainda não está vinculado a uma sessão e pode ser reivindicado uma vez. Requer TypeScript Agent SDK v0.3.282 ou posterior.825*Alpha.* Handle retornado por [`prewarm()`](#prewarm): um processo do Claude Code iniciado que ainda não está vinculado a uma sessão e pode ser reivindicado uma vez. Requer o TypeScript Agent SDK v0.3.282 ou posterior.
821 826
822```typescript theme={null}827```typescript theme={null}
823interface SpareProcess extends AsyncDisposable {828interface SpareProcess extends AsyncDisposable {
837 842
838| Membro | Descrição |843| Membro | Descrição |
839| :- | :- |844| :- | :- |
840| `claim({ prompt, options })` | Vincular o spare a uma sessão em `options.cwd` e enviar sua primeira mensagem. Retorna uma [`Query`](#query-object) sincronamente, como `query()` faz. Pode ser chamado apenas uma vez |845| `claim({ prompt, options })` | Vincula o processo reserva a uma sessão em `options.cwd` e envia sua primeira mensagem. Retorna uma [`Query`](#query-object) de forma síncrona, como `query()` faz. Só pode ser chamado uma vez |
841| `claimed` | Resolve com o diretório de trabalho e ID da sessão uma vez que Claude Code aceita a reivindicação. Rejeita quando Claude Code recusa a reivindicação, quando o processo saiu ou foi fechado primeiro, e, com uma mensagem que começa com `option_not_applied`, quando a sessão está em execução sem o `model` ou `maxThinkingTokens` que você pediu |846| `claimed` | Resolve com o diretório de trabalho e o ID da sessão assim que o Claude Code aceita a reivindicação. É rejeitado quando o Claude Code recusa a reivindicação, quando o processo terminou ou foi fechado antes e, com uma mensagem que começa com `option_not_applied`, quando a sessão está em execução sem o `model` ou o `maxThinkingTokens` que você solicitou |
842| `exited` | Resolve quando o processo sai, reivindicado ou não. Substitua um spare que sai antes de você reivindicá-lo |847| `exited` | É concluído quando o processo termina, reivindicado ou não. Substitua um processo reserva que termine antes de você reivindicá-lo |
843| `close()` | Encerrar o processo. Antes de uma reivindicação isso descarta o spare e rejeita `claimed` |848| `close()` | Encerra o processo. Antes de uma reivindicação, isso descarta o processo reserva e rejeita `claimed` |
844 849
845`options.cwd` é obrigatório. Uma reivindicação também pode definir `additionalDirectories`, `model`, `permissionMode`, `maxThinkingTokens`, uma sobreposição de configurações de flag em `settings`, `appendSystemPrompt`, `title`, `agents`, e tokens por sessão em `env`.850`options.cwd` é obrigatório. Uma reivindicação também pode definir `additionalDirectories`, `model`, `permissionMode`, `maxThinkingTokens`, uma sobreposição de configurações de flag em `settings`, `appendSystemPrompt`, `title`, `agents` e tokens por sessão em `env`.
846 851
847Claude Code pode recusar uma reivindicação, por exemplo para uma pasta que não existe ou uma cujas configurações de projeto definem `env`, `agent`, ou `model`. Quando `claimed` rejeita com uma mensagem que começa com `option_not_applied`, a sessão está em execução sem o `model` ou `maxThinkingTokens` que você pediu. Após qualquer outra rejeição seu prompt não foi executado, então inicie a sessão com `query()` em vez disso.852O Claude Code pode recusar uma reivindicação, por exemplo, para uma pasta que não existe ou uma cujas configurações de projeto definem `env`, `agent` ou `model`. Após uma recusa, um prompt que `claim()` já enviou recebe um resultado de erro cujo texto começa com `not_claimed`, e a consulta retornada então lança uma exceção. Envolva o loop da consulta em um bloco try para continuar após a exceção. Quando `claimed` rejeita com uma mensagem que começa com `option_not_applied`, a sessão está em execução sem o `model` ou `maxThinkingTokens` que você solicitou. Após qualquer outra rejeição, seu prompt não foi executado, então inicie a sessão com `query()`.
848 853
849<h3 id="sdkcontrolinitializeresponse">854<h3 id="sdkcontrolinitializeresponse">
850 `SDKControlInitializeResponse`855 `SDKControlInitializeResponse`
851</h3>856</h3>
852 857
853Tipo de retorno de `initializationResult()`. Contém dados de inicialização de sessão.858Tipo de retorno de `initializationResult()`. Contém os dados de inicialização da sessão.
854 859
855```typescript theme={null}860```typescript theme={null}
856type SDKControlInitializeResponse = {861type SDKControlInitializeResponse = {
874};879};
875```880```
876 881
877`hooks_applied` relata se Claude Code registrou os `hooks` que a solicitação `initialize` carregava. O SDK envia essa solicitação uma vez quando a sessão inicia e novamente em cada chamada [`reinitialize()`](#query-object). O campo requer Agent SDK v0.3.238 ou posterior.882`hooks_applied` informa se o Claude Code registrou os `hooks` que a requisição `initialize` continha. O SDK envia essa requisição uma vez quando a sessão inicia e novamente a cada chamada de [`reinitialize()`](#query-object). O campo requer o Agent SDK v0.3.238 ou posterior.
878 883
879Claude Code omite o campo quando a solicitação não carregava hooks. Quando a solicitação carregava hooks, o valor depende se a solicitação é a primeira inicialização da sessão e, para uma repetida, de como ela alcançou a sessão:884O Claude Code omite o campo quando a requisição não continha hooks. Quando a requisição continha hooks, o valor depende de a requisição ser o primeiro initialize da sessão e, para um initialize repetido, de como ele chegou à sessão:
880 885
881* `true`: Claude Code registrou os hooks. A primeira inicialização de uma sessão retorna esse valor. Uma inicialização repetida enviada sobre stdin da CLI também retorna `true`. Nesse caso os hooks na nova solicitação substituem os hooks registrados anteriormente.886* `true`: o Claude Code registrou os hooks. O primeiro initialize de uma sessão retorna esse valor. Um initialize repetido enviado pelo stdin da CLI também retorna `true`. Nesse caso, os hooks da nova requisição substituem os hooks registrados anteriormente.
882* `false`: Claude Code ignorou os hooks. Uma inicialização repetida enviada para uma sessão remota retorna esse valor, então um segundo cliente que se junta a uma sessão não pode substituir os hooks que o primeiro cliente registrou.887* `false`: o Claude Code ignorou os hooks. Um initialize repetido enviado a uma sessão remota retorna esse valor, de modo que um segundo cliente que entra em uma sessão não pode substituir os hooks que o primeiro cliente registrou.
883 888
884Antes do Agent SDK v0.3.238, a resposta nunca carregava o campo, e Claude Code ignorava `hooks` em cada inicialização repetida.889Antes do Agent SDK v0.3.238, a resposta nunca continha o campo, e o Claude Code ignorava `hooks` em todo initialize repetido.
885 890
886O campo `sdkMcpServerManifests` da requisição e o campo `sdk_mcp_manifests_parked` da resposta são destinados aos [servidores MCP do SDK](/docs/pt/agent-sdk/custom-tools) em processo que você criou com [`createSdkMcpServer()`](#createsdkmcpserver). Sua aplicação não define nem lê nenhum desses campos.891O campo `sdkMcpServerManifests` da requisição e o campo `sdk_mcp_manifests_parked` da resposta são para os [servidores MCP do SDK](/docs/pt/agent-sdk/custom-tools) em processo que você criou com [`createSdkMcpServer()`](#createsdkmcpserver). Seu aplicativo não define nem lê nenhum desses campos.
887 892
888A resposta sempre relata `fast_mode_state`, e quando algo bloqueia [fast mode](/docs/pt/fast-mode), `fast_mode_disabled_reason` carrega o código de razão junto com ele, para que você possa explicar o estado bloqueado em vez de re-derivar a disponibilidade. Ambos os comportamentos requerem Claude Code v2.1.219 ou posterior. Antes de v2.1.219, a resposta omitia `fast_mode_state` quando fast mode não estava disponível e nunca carregava uma razão. Para os códigos de razão e seus significados, veja [`fast_mode_disabled_reason`](#sdkresultmessage) na mensagem de resultado.893A resposta sempre informa `fast_mode_state` e, quando algo bloqueia o [modo rápido](/docs/pt/fast-mode), `fast_mode_disabled_reason` traz o código do motivo junto com ele, para que você possa explicar o estado bloqueado em vez de deduzir novamente a disponibilidade. Ambos os comportamentos requerem o Claude Code v2.1.219 ou posterior. Antes da v2.1.219, a resposta omitia `fast_mode_state` quando o modo rápido não estava disponível e nunca continha um motivo. Para os códigos de motivo e seus significados, consulte [`fast_mode_disabled_reason`](#sdkresultmessage) na mensagem de resultado.
889 894
890O wrapper de resposta de controle para um `initialize` bem-sucedido também carrega um array `pending_permission_requests`. O campo está no wrapper de resposta em si, não na carga `SDKControlInitializeResponse` acima. Cada entrada é uma mensagem `control_request` completa com a mesma forma `{ type: "control_request", request_id, request }` que a sessão transmite para solicitações de permissão durante a execução.895O wrapper da resposta de controle para um `initialize` bem-sucedido também contém um array `pending_permission_requests`. O campo está no próprio wrapper da resposta, não no payload `SDKControlInitializeResponse` acima. Cada entrada é uma mensagem `control_request` completa com o mesmo formato `{ type: "control_request", request_id, request }` que a sessão transmite para requisições de permissão durante a execução.
891 896
892O array lista as solicitações de permissão que este processo Claude Code emitiu e ainda não resolveu. O SDK lê o array para você e despacha cada entrada para seu callback [`canUseTool`](#canusetool), o mesmo reenvio que [`reinitialize()`](#query-object) dispara após uma lacuna de transporte. Trate IDs de solicitação repetidos idempotentemente, porque uma entrada pode repetir uma solicitação que o callback já recebeu antes da conexão cair.897O array lista as requisições de permissão que este processo do Claude Code emitiu e ainda não resolveu. O SDK lê o array para você e despacha cada entrada para seu callback [`canUseTool`](#canusetool), a mesma reentrega que [`reinitialize()`](#query-object) aciona após uma lacuna de transporte. Trate IDs de requisição repetidos de forma idempotente, porque uma entrada pode repetir uma requisição que o callback já recebeu antes de a conexão cair.
893 898
894O array está sempre presente em uma resposta `initialize` bem-sucedida e está vazio quando este processo não tem nenhuma solicitação de permissão não resolvida. Requer Claude Code v2.1.268 ou posterior. Versões anteriores poderiam omitir o campo, então se você analisar o protocolo de fio você mesmo, trate um campo ausente como uma CLI mais antiga em vez de como prova de que nada está pendente.899O array está sempre presente em uma resposta `initialize` bem-sucedida e fica vazio quando este processo não tem requisição de permissão não resolvida. Requer o Claude Code v2.1.268 ou posterior. Versões anteriores podiam omitir o campo, portanto, se você analisa o protocolo de comunicação por conta própria, trate um campo ausente como uma CLI mais antiga, e não como prova de que nada está pendente.
895 900
896<h3 id="sdkcontrolinterruptresponse">901<h3 id="sdkcontrolinterruptresponse">
897 `SDKControlInterruptResponse`902 `SDKControlInterruptResponse`
898</h3>903</h3>
899 904
900O recebimento de interrupção: o valor que [`interrupt()`](#query-object) resolve em uma CLI que anuncia a capacidade `interrupt_receipt_v1` em [`SDKSystemMessage.capabilities`](#sdksystemmessage). Requer Claude Code v2.1.205 ou posterior. CLIs anteriores respondem à interrupção com uma carga de sucesso vazia, então `interrupt()` resolve para `undefined`.905O recibo de interrupção: o valor com que [`interrupt()`](#query-object) resolve em uma CLI que anuncia a capacidade `interrupt_receipt_v1` em [`SDKSystemMessage.capabilities`](#sdksystemmessage). Requer o Claude Code v2.1.205 ou posterior. CLIs anteriores respondem à interrupção com um payload de sucesso vazio, portanto `interrupt()` resolve para `undefined`.
901 906
902```typescript theme={null}907```typescript theme={null}
903type SDKControlInterruptResponse = {908type SDKControlInterruptResponse = {
906};911};
907```912```
908 913
909`still_queued` lista os UUIDs das mensagens de usuário que estavam pendentes quando a interrupção chegou: mensagens ainda na fila, mais qualquer mensagem que Claude Code já havia tirado da fila para o próximo turno. Uma vez que o primeiro turno da sessão começou, Claude Code processa as mensagens listadas após a interrupção a menos que você as cancele primeiro, e pode mesclar várias em um turno. Se você interromper antes do primeiro turno começar, Claude Code aborta esse turno assim que ele inicia, e as mensagens listadas nesse turno não recebem resposta.914`still_queued` lista os UUIDs das mensagens do usuário que estavam pendentes quando a interrupção chegou: mensagens ainda na fila, além de quaisquer mensagens que o Claude Code já havia retirado da fila para o próximo turno. Depois que o primeiro turno da sessão tiver começado, o Claude Code processa as mensagens listadas após a interrupção, a menos que você as cancele antes, e pode mesclar várias em um único turno. Se você interromper antes de o primeiro turno começar, o Claude Code aborta esse turno assim que ele começa, e as mensagens listadas nesse turno não recebem resposta.
910 915
911Use o recebimento para decidir se deve reenviar algo. Uma mensagem listada que você não cancela entra na conversa independentemente de receber uma resposta, então reenviá-la a entrega para Claude duas vezes.916Use o recibo para decidir se deve reenviar algo. Uma mensagem listada que você não cancela entra na conversa, recebendo resposta ou não, portanto reenviá-la a entrega a Claude duas vezes.
912 917
913Interprete a lista com estas ressalvas:918Interprete a lista com estas ressalvas:
914 919
915* Apenas mensagens que foram enfileiradas com um UUID aparecem. Um array vazio não significa que nada mais será executado.920* Apenas mensagens que foram enfileiradas com um UUID aparecem. Um array vazio não significa que nada mais será executado.
916* Apenas mensagens da thread principal estão listadas. Mensagens endereçadas a um subagente estão fora do escopo.921* Apenas mensagens da thread principal são listadas. Mensagens endereçadas a um subagente estão fora do escopo.
917* A lista pode incluir UUIDs que seu cliente nunca enviou, como [acionadores de tarefa agendada](/docs/pt/scheduled-tasks). Ignore UUIDs que você não reconhece em vez de tratá-los como um erro.922* A lista pode incluir UUIDs que seu cliente nunca enviou, como gatilhos de [tarefas agendadas](/docs/pt/scheduled-tasks). Ignore UUIDs que você não reconhece em vez de tratá-los como erro.
918 923
919Um cliente que dirige o protocolo de controle da CLI diretamente, em vez de através de `interrupt()`, pode definir `cancel_queued: true` na solicitação de controle `interrupt`. Claude Code v2.1.219 e posterior anuncia suporte com a capacidade `interrupt_cancel_queued_v1` em [`SDKSystemMessage.capabilities`](#sdksystemmessage); CLIs mais antigas ignoram o campo e deixam mensagens enfileiradas para executar como de costume. Tal interrupção também cancela cada mensagem que seria listada sob `still_queued`: o recebimento as lista sob `cancelled` em vez disso, `still_queued` está vazio, e nenhuma delas é executada.924Um cliente que controla o protocolo de controle da CLI diretamente, em vez de usar `interrupt()`, pode definir `cancel_queued: true` na requisição de controle `interrupt`. O Claude Code v2.1.219 e posterior anuncia suporte com a capacidade `interrupt_cancel_queued_v1` em [`SDKSystemMessage.capabilities`](#sdksystemmessage); CLIs mais antigas ignoram o campo e deixam as mensagens enfileiradas serem executadas normalmente. Essa interrupção também cancela todas as mensagens que, de outra forma, seriam listadas em `still_queued`: o recibo as lista em `cancelled`, `still_queued` fica vazio e nenhuma delas é executada.
920 925
921A lista `cancelled` carrega as mesmas ressalvas que `still_queued`. O método `interrupt()` nunca envia `cancel_queued`, então recebimentos que ele resolve não carregam `cancelled`.926A lista `cancelled` tem as mesmas ressalvas que `still_queued`. O método `interrupt()` nunca envia `cancel_queued`, portanto os recibos com que ele resolve não contêm `cancelled`.
922 927
923O recebimento é um snapshot tirado no momento em que a interrupção é processada, e em uma interrupção limpa chega antes do [`SDKResultMessage`](#sdkresultmessage) do turno interrompido. Leia o recebimento em vez de inspecionar a fila após esse resultado: o loop inicia o próximo turno enfileirado imediatamente, então a fila que você inspeciona após o resultado já mudou.928O recibo é um instantâneo tirado no momento em que a interrupção é processada e, em uma interrupção limpa, chega antes da [`SDKResultMessage`](#sdkresultmessage) do turno interrompido. Leia o recibo em vez de inspecionar a fila após esse resultado: o loop inicia o próximo turno enfileirado imediatamente, portanto a fila que você inspeciona após o resultado já mudou.
924 929
925<h3 id="sdkcontrolgetcontextusageresponse">930<h3 id="sdkcontrolgetcontextusageresponse">
926 `SDKControlGetContextUsageResponse`931 `SDKControlGetContextUsageResponse`
927</h3>932</h3>
928 933
929Tipo de retorno de [`getContextUsage()`](#query-object). Com o `detail` padrão, este é o mesmo payload que Claude Code renderiza para o comando `/context` em uma sessão interativa, então junto com as contagens de token carrega campos de exibição como `color` e `gridRows` que Claude Code usa para desenhar a grade de uso `/context`.934Tipo de retorno de [`getContextUsage()`](#query-object). Com o `detail` padrão, este é o mesmo payload que o Claude Code renderiza para o comando `/context` em uma sessão interativa, portanto, além das contagens de tokens, contém campos de exibição como `color` e `gridRows` que o Claude Code usa para desenhar a grade de uso do `/context`.
930 935
931O argumento `detail` opcional do método escolhe como Claude Code conta cada categoria. O argumento `detail` requer Agent SDK v0.3.257 ou posterior.936O argumento opcional `detail` do método escolhe como o Claude Code conta cada categoria. O argumento `detail` requer o Agent SDK v0.3.257 ou posterior.
932 937
933* **`'full'`**: o padrão. Claude Code conta cada categoria com [solicitações de API de contagem de token](https://platform.claude.com/docs/pt/build-with-claude/token-counting). Estas solicitações não aparecem no fluxo de mensagens, então rastreamento de custo que lê o fluxo não as verá. Na API Anthropic, contagem de token não é cobrada.938* **`'full'`**: o padrão. O Claude Code conta cada categoria com requisições de API de [contagem de tokens](https://platform.claude.com/docs/en/build-with-claude/token-counting). Essas requisições não aparecem no fluxo de mensagens, portanto o acompanhamento de custos que lê o fluxo não as verá. Na API da Anthropic, a contagem de tokens não é cobrada.
934* **`'summary'`**: passe `{ detail: 'summary' }` para obter uma resposta do uso da última resposta e estimativas locais em vez disso. Nenhuma solicitação de contagem de token sai, e os números por categoria são aproximados.939* **`'summary'`**: passe `{ detail: 'summary' }` para obter uma resposta a partir do uso da última resposta e de estimativas locais. Nenhuma requisição de contagem de tokens é enviada, e os números por categoria são aproximados.
935 940
936Quando você envia `/context` como um prompt em vez de chamar o método, Claude Code anexa uma carga [`SDKContextUsage`](#sdkcontextusage) ao campo `context_usage` da mensagem do assistente que entrega o resultado. Esse campo requer Agent SDK v0.3.232 ou posterior.941Quando você envia `/context` como prompt em vez de chamar o método, o Claude Code anexa um payload [`SDKContextUsage`](#sdkcontextusage) ao campo `context_usage` da mensagem de assistente que entrega o resultado. Esse campo requer o Agent SDK v0.3.232 ou posterior.
937 942
938```typescript theme={null}943```typescript theme={null}
939type SDKControlGetContextUsageResponse = {944type SDKControlGetContextUsageResponse = {
1030};1035};
1031```1036```
1032 1037
1033Leia atribuição de token da coleção de campos:1038Leia a atribuição de tokens a partir dos campos de coleção:
1034 1039
1035* `categories` contém os totais por categoria. Cada entrada `kind` classifica a linha com os mesmos valores que [`SDKContextUsageCategory`](#sdkcontextusagecategory). Classifique linhas nele em vez de no `name` de exibição. O campo requer Agent SDK v0.3.268 ou posterior.1040* `categories` contém os totais por categoria. O `kind` de cada entrada classifica a linha com os mesmos valores de [`SDKContextUsageCategory`](#sdkcontextusagecategory). Classifique as linhas com base nele, e não no `name` de exibição. O campo requer o Agent SDK v0.3.268 ou posterior.
1036* `mcpTools` e `agents` atribuem tokens a ferramentas MCP individuais e subagentes.1041* `mcpTools` e `agents` atribuem tokens a ferramentas MCP e subagentes individuais.
1037* `memoryFiles` lista cada arquivo de memória carregado com seu custo.1042* `memoryFiles` lista cada arquivo de memória carregado com seu custo.
1038* `skills.skillFrontmatter` atribui os tokens da listagem de skills a cada skill incluída. As contagens por skill medem cada entrada de listagem de skill conforme Claude Code realmente a envia, que pode ser mais curta que o frontmatter completo da skill. Compare `skills.totalSkills` com `skills.includedSkills` para ver se cada skill descoberta fez parte da listagem.1043* `skills.skillFrontmatter` atribui os tokens da listagem de skills a cada skill incluída. As contagens por skill medem a entrada de cada skill na listagem conforme o Claude Code realmente a envia, o que pode ser mais curto que o frontmatter completo da skill. Compare `skills.totalSkills` com `skills.includedSkills` para ver se todas as skills descobertas entraram na listagem.
1039 1044
1040`totalTokens` é o uso de contexto atual da sessão, e `maxTokens` é a janela contra a qual o uso é medido. Essa janela é a janela de contexto do modelo, ou a janela de auto-compactação mais baixa quando uma se aplica. `rawMaxTokens` carrega o mesmo valor que `maxTokens`, e `percentage` é `totalTokens` como uma porcentagem arredondada dessa janela. `apiUsage` contém o uso da resposta de API mais recente, não um total em execução para a sessão.1045`totalTokens` é o uso atual de contexto da sessão, e `maxTokens` é a janela em relação à qual esse uso é medido. Essa janela é a janela de contexto do modelo, ou a janela menor de compactação automática quando houver uma. `rawMaxTokens` contém o mesmo valor que `maxTokens`, e `percentage` é `totalTokens` como uma porcentagem arredondada dessa janela. `apiUsage` contém o uso da resposta de API mais recente, não um total acumulado da sessão.
1041 1046
1042Claude Code deixa os diagnósticos opcionais `deferredBuiltinTools`, `systemTools`, e `systemPromptSections` não definidos, então espere que estejam ausentes mesmo que o tipo os declare.1047O Claude Code deixa sem definir os diagnósticos opcionais `deferredBuiltinTools`, `systemTools` e `systemPromptSections`, portanto espere que estejam ausentes, embora o tipo os declare.
1043 1048
1044<h3 id="sdkcontrolreadfileresponse">1049<h3 id="sdkcontrolreadfileresponse">
1045 `SDKControlReadFileResponse`1050 `SDKControlReadFileResponse`
1056};1061};
1057```1062```
1058 1063
1059`contents` contém o texto do arquivo, ou dados base64 quando você solicitou `encoding: 'base64'`; o campo `encoding` da resposta é definido como `'base64'` nesse caso. `absPath` é o caminho absoluto resolvido. `truncated` é definido quando o arquivo era mais longo que o limite `maxBytes` e o conteúdo foi cortado nesse limite.1064`contents` contém o texto do arquivo, ou dados em base64 quando você solicitou `encoding: 'base64'`; nesse caso, o campo `encoding` da resposta é definido como `'base64'`. `absPath` é o caminho absoluto resolvido. `truncated` é definido quando o arquivo era maior que o limite `maxBytes` e o conteúdo foi cortado nesse limite.
1060 1065
1061<h4 id="what-readfile-can-read">1066<h4 id="what-readfile-can-read">
1062 O que `readFile()` pode ler1067 O que `readFile()` pode ler
1063</h4>1068</h4>
1064 1069
1065`readFile()` serve um conjunto mais estreito de arquivos do que a ferramenta Read:1070`readFile()` fornece um conjunto de arquivos mais restrito que a ferramenta Read:
1066 1071
1067* Um arquivo regular dentro de um dos diretórios de trabalho da sessão, como `cwd` e `additionalDirectories`1072* Um arquivo regular dentro de um dos diretórios de trabalho da sessão, como `cwd` e `additionalDirectories`
1068* Alguns dos próprios arquivos do Claude Code para a sessão, como resultados de ferramentas1073* Alguns dos próprios arquivos do Claude Code para a sessão, como resultados de ferramentas
1069 1074
1070As regras de negação e solicitação de Read ainda bloqueiam um caminho correspondente, e uma regra de permissão ampla de Read não abre o resto do sistema de arquivos para `readFile()`. Para qualquer outra coisa a chamada resolve com `null`.1075Regras de negação e de confirmação de `Read` ainda bloqueiam um caminho correspondente, e uma regra ampla de permissão de `Read` não abre o restante do sistema de arquivos para `readFile()`. Para qualquer outra coisa, a chamada resolve com `null`.
1071 1076
1072<h3 id="sdkcontrolreloadpluginsresponse">1077<h3 id="sdkcontrolreloadpluginsresponse">
1073 `SDKControlReloadPluginsResponse`1078 `SDKControlReloadPluginsResponse`
1098 1103
1099Os campos de coleção descrevem a sessão após a chamada:1104Os campos de coleção descrevem a sessão após a chamada:
1100 1105
1101* `commands`, `agents`, e `mcpServers`: os comandos, subagentes e status do servidor MCP da sessão, nas mesmas formas que `supportedCommands()`, `supportedAgents()`, e `mcpServerStatus()` retornam. `supportedAgents()` continua retornando a lista capturada na inicialização, então leia `agents` aqui para o conjunto após um recarregamento1106* `commands`, `agents` e `mcpServers`: os comandos, subagentes e o status dos servidores MCP da sessão, nos mesmos formatos que `supportedCommands()`, `supportedAgents()` e `mcpServerStatus()` retornam. `supportedAgents()` continua retornando a lista capturada na inicialização, portanto leia `agents` aqui para obter o conjunto após um recarregamento
1102* `plugins`: cada plugin carregado com seu `name` e `path` de instalação. `version` repete o que o manifesto do plugin declara e é controlado pelo autor do plugin, então valide-o antes de confiar nele. É omitido quando o manifesto não declara nenhum1107* `plugins`: cada plugin carregado com seu `name` e o `path` de instalação. `version` repete o que o manifesto do plugin declara e é controlado pelo autor do plugin, portanto valide-o antes de confiar nele. É omitido quando o manifesto não declara nenhuma versão
1103* `error_count`: o número de erros ao carregar plugins1108* `error_count`: o número de erros ao carregar plugins
1104 1109
1105Passe `{ holdOnCacheImpact: true }` para `reloadPlugins()` para manter um recarregamento que invalidaria o cache de prompt da conversa em vez de aplicá-lo. Claude Code executa a verificação que o comando interativo `/reload-plugins` faz antes de [avisar sobre o custo do cache](/docs/pt/prompt-caching#enabling-or-disabling-a-plugin). A opção requer Agent SDK v0.3.268 ou posterior. Um executável Claude Code mais antigo que v2.1.268, como um que você aponta `pathToClaudeCodeExecutable` para, ignora a opção e aplica o recarregamento.1110Passe `{ holdOnCacheImpact: true }` para `reloadPlugins()` para reter um recarregamento que invalidaria o cache de prompt da conversa em vez de aplicá-lo. O Claude Code executa a verificação que o comando interativo `/reload-plugins` faz antes de [avisar sobre o custo do cache](/docs/pt/prompt-caching#enabling-or-disabling-a-plugin). A opção requer o Agent SDK v0.3.268 ou posterior. Um executável do Claude Code anterior à v2.1.268, como um para o qual você aponta `pathToClaudeCodeExecutable`, ignora a opção e aplica o recarregamento.
1106 1111
1107Quando você passa a opção, leia `held` para aprender o que aconteceu:1112Quando você passa a opção, leia `held` para saber o que aconteceu:
1108 1113
1109* `true`: o recarregamento não foi aplicado, e os campos de coleção descrevem a sessão como ainda está. `cache_impact` diz o que aplicar mudaria. Para aplicar mesmo assim, chame `reloadPlugins()` novamente sem a opção.1114* `true`: o recarregamento não foi aplicado, e os campos de coleção descrevem a sessão como ela ainda está. `cache_impact` informa o que a aplicação mudaria. Para aplicar mesmo assim, chame `reloadPlugins()` novamente sem a opção.
1110* `false`: a verificação não encontrou impacto no cache, e o recarregamento foi aplicado.1115* `false`: a verificação não encontrou impacto no cache, e o recarregamento foi aplicado.
1111* Ausente: você não passou a opção, ou o executável Claude Code é mais antigo que v2.1.268 e aplicou o recarregamento.1116* Ausente: você não passou a opção, ou o executável do Claude Code é anterior à v2.1.268 e aplicou o recarregamento.
1112 1117
1113`cache_impact` está presente apenas junto com `held: true`. `mcp_servers_added` e `mcp_servers_removed` nomeiam os servidores MCP do plugin que o recarregamento registraria ou descartaria, como nomes com escopo `plugin:<plugin>:<server>`. Os nomes são criados pelo plugin, então valide-os antes de mostrá-los. `lsp_tool_change` diz se aplicar adicionaria ou removeria a ferramenta LSP, ou `null` quando não faria nenhum dos dois. As formas `may-` significam que a verificação não conseguiu ver completamente o conjunto de plugins pendente.1118`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, portanto 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 enxergar completamente o conjunto de plugins pendente.
1114 1119
1115<h3 id="sdkcontrolreloadskillsresponse">1120<h3 id="sdkcontrolreloadskillsresponse">
1116 `SDKControlReloadSkillsResponse`1121 `SDKControlReloadSkillsResponse`
1124};1129};
1125```1130```
1126 1131
1127`skills` lista as skills disponíveis após o recarregamento, na mesma forma [`SlashCommand`](#slashcommand) que `supportedCommands()` retorna.1132`skills` lista as skills disponíveis após o recarregamento, no mesmo formato [`SlashCommand`](#slashcommand) que `supportedCommands()` retorna.
1128 1133
1129<h3 id="sdkcontrolreloadoutputstylesresponse">1134<h3 id="sdkcontrolreloadoutputstylesresponse">
1130 `SDKControlReloadOutputStylesResponse`1135 `SDKControlReloadOutputStylesResponse`
1144 `SDKControlMcpReadResourceResponse`1149 `SDKControlMcpReadResourceResponse`
1145</h3>1150</h3>
1146 1151
1147Tipo de retorno de [`readMcpResource()`](#query-object), carregando o resultado `resources/read` do servidor MCP. Requer TypeScript Agent SDK v0.3.280 ou posterior.1152Tipo de retorno de [`readMcpResource()`](#query-object), contendo o resultado de `resources/read` do servidor MCP. Requer o TypeScript Agent SDK v0.3.280 ou posterior.
1148 1153
1149```typescript theme={null}1154```typescript theme={null}
1150type SDKControlMcpReadResourceResponse = {1155type SDKControlMcpReadResourceResponse = {
1158};1163};
1159```1164```
1160 1165
1161Passe `readMcpResource()` o nome do servidor conforme `mcpServerStatus()` o relata e um URI `ui://`, como o `ui.resourceUri` que uma ferramenta declara em sua [`_meta`](#mcpserverstatus). A chamada rejeita para qualquer outro esquema de URI, para um [servidor MCP SDK](#createsdkmcpserver) que sua aplicação hospeda a si mesma, e para um servidor que não está conectado. Está disponível quando a mensagem de inicialização [`capabilities`](#sdksystemmessage) incluem `mcp_read_resource_v1`.1166Passe para `readMcpResource()` o nome do servidor conforme `mcpServerStatus()` o informa e um URI `ui://`, como o `ui.resourceUri` que uma ferramenta declara em seu [`_meta`](#mcpserverstatus). A chamada é rejeitada para qualquer outro esquema de URI, para um [servidor MCP do SDK](#createsdkmcpserver) que seu próprio aplicativo hospeda e para um servidor que não está conectado. Está disponível quando as [`capabilities`](#sdksystemmessage) da mensagem de inicialização incluem `mcp_read_resource_v1`.
1162 1167
1163Cada entrada `contents` é um item de conteúdo conforme o servidor o enviou, menos qualquer chave `_meta` sob o prefixo `com.anthropic/`, que é reservado para Claude Code. `blob` contém dados base64 para um item binário, e `_meta` é o próprio `_meta` do item, onde um servidor MCP Apps coloca o `ui.csp` e `ui.permissions` do recurso.1168Cada entrada de `contents` é um item de conteúdo conforme o servidor o enviou, sem nenhuma chave `_meta` sob o prefixo `com.anthropic/`, que é reservado para o Claude Code. `blob` contém dados em base64 para um item binário, e `_meta` é o próprio `_meta` do item, onde um servidor MCP Apps coloca o `ui.csp` e o `ui.permissions` do recurso.
1164 1169
1165O conteúdo é HTML de terceiros não confiável, então renderize-o em um sandbox.1170O conteúdo é HTML de terceiros não confiável, portanto renderize-o em um sandbox.
1166 1171
1167<h3 id="agentdefinition">1172<h3 id="agentdefinition">
1168 `AgentDefinition`1173 `AgentDefinition`
1169</h3>1174</h3>
1170 1175
1171Configuração para um subagente definido programaticamente.1176Configuração de um subagente definido programaticamente.
1172 1177
1173```typescript theme={null}1178```typescript theme={null}
1174type AgentDefinition = {1179type AgentDefinition = {
1193| Campo | Obrigatório | Descrição |1198| Campo | Obrigatório | Descrição |
1194| :- | :- | :- |1199| :- | :- | :- |
1195| `description` | Sim | Descrição em linguagem natural de quando usar este agente |1200| `description` | Sim | Descrição em linguagem natural de quando usar este agente |
1196| `tools` | Não | Array de nomes de ferramentas permitidas. Se omitido, herda cada [ferramenta disponível para subagentes](/docs/pt/sub-agents#available-tools). Para pré-carregar Skills no contexto do agente, use o campo `skills` em vez de listar `'Skill'` aqui |1201| `tools` | Não | Array de nomes de ferramentas permitidas. Se omitido, herda todas as [ferramentas disponíveis para subagentes](/docs/pt/sub-agents#available-tools). Para pré-carregar Skills no contexto do agente, use o campo `skills` em vez de listar `'Skill'` aqui |
1197| `disallowedTools` | Não | Array de nomes de ferramentas para explicitamente desallocar para este agente. Padrões de nível de servidor MCP também são aceitos: `mcp__server` ou `mcp__server__*` remove cada ferramenta desse servidor, e `mcp__*` remove cada ferramenta MCP de qualquer servidor |1202| `disallowedTools` | Não | Array de nomes de ferramentas a proibir explicitamente para este agente. Padrões no nível de servidor MCP também são aceitos: `mcp__server` ou `mcp__server__*` remove todas as ferramentas desse servidor, e `mcp__*` remove todas as ferramentas MCP de qualquer servidor |
1198| `prompt` | Sim | O prompt do sistema do agente |1203| `prompt` | Sim | O system prompt do agente |
1199| `model` | Não | Substituição de modelo para este agente. Aceita um alias como `'fable'`, `'opus'`, `'sonnet'`, `'haiku'`, `'inherit'`, ou um ID de modelo completo. `'inherit'` usa o modelo principal. Quando você o omite, Claude Code escolhe o modelo na [ordem de modelo de subagente](/docs/pt/sub-agents#choose-a-model) |1204| `model` | Não | Substituição de modelo para este agente. Aceita um alias como `'fable'`, `'opus'`, `'sonnet'`, `'haiku'`, `'inherit'` ou um ID de modelo completo. `'inherit'` usa o modelo principal. Quando você o omite, o Claude Code escolhe o modelo na [ordem de modelos de subagentes](/docs/pt/sub-agents#choose-a-model) |
1200| `mcpServers` | Não | Especificações de servidor MCP para este agente |1205| `mcpServers` | Não | Especificações de servidores MCP para este agente |
1201| `skills` | Não | Array de nomes de skills para pré-carregar no contexto do agente |1206| `skills` | Não | Array de nomes de skills a pré-carregar no contexto do agente |
1202| `initialPrompt` | Não | Auto-enviado como o primeiro turno de usuário quando este agente é executado como o agente da thread principal |1207| `initialPrompt` | Não | Enviado automaticamente como o primeiro turno do usuário quando este agente é executado como agente da thread principal |
1203| `maxTurns` | Não | Número máximo de turnos agênticos (round-trips de API) antes de parar |1208| `maxTurns` | Não | Número máximo de turnos agênticos (idas e voltas da API) antes de parar |
1204| `background` | Não | Executar este agente como uma tarefa de fundo não-bloqueante quando invocado |1209| `background` | Não | Executa este agente como uma tarefa em segundo plano não bloqueante quando invocado |
1205| `omitClaudeMd` | Não | Executar este agente sem os arquivos CLAUDE.md de usuário, projeto e local quando ele é executado como um subagente; arquivos de política gerenciada ainda carregam. Use-o para agentes que pegam tudo o que precisam do prompt da ferramenta Agent. Ignorado quando este agente é executado como o agente da thread principal. Requer TypeScript Agent SDK v0.3.271 ou posterior |1210| `omitClaudeMd` | Não | Executa este agente sem os arquivos CLAUDE.md de usuário, de projeto e locais quando ele é executado como subagente; os arquivos de política gerenciada ainda são carregados. Use para agentes que obtêm tudo de que precisam a partir do prompt da ferramenta Agent. Ignorado quando este agente é executado como agente da thread principal. Requer o TypeScript Agent SDK v0.3.271 ou posterior |
1206| `memory` | Não | Fonte de memória para este agente: `'user'`, `'project'`, ou `'local'` |1211| `memory` | Não | Fonte de memória para este agente: `'user'`, `'project'` ou `'local'` |
1207| `effort` | Não | Nível de esforço de raciocínio para este agente. Aceita um nível nomeado ou um inteiro |1212| `effort` | Não | Nível de esforço de raciocínio para este agente. Aceita um nível nomeado ou um inteiro |
1208| `permissionMode` | Não | Modo de permissão para execução de ferramenta dentro deste agente. As [regras de herança de subagente](/docs/pt/agent-sdk/permissions#available-modes) decidem quando se aplica. Veja [`PermissionMode`](#permissionmode) |1213| `permissionMode` | Não | Modo de permissão para a execução de ferramentas dentro deste agente. As [regras de herança de subagentes](/docs/pt/agent-sdk/permissions#available-modes) decidem quando ele se aplica. Consulte [`PermissionMode`](#permissionmode) |
1209| `criticalSystemReminder_EXPERIMENTAL` | Não | Experimental: Lembrete crítico adicionado ao prompt do sistema |1214| `criticalSystemReminder_EXPERIMENTAL` | Não | Experimental: lembrete crítico adicionado ao system prompt |
1210 1215
1211<h3 id="agentmcpserverspec">1216<h3 id="agentmcpserverspec">
1212 `AgentMcpServerSpec`1217 `AgentMcpServerSpec`
1213</h3>1218</h3>
1214 1219
1215Especifica servidores MCP disponíveis para um subagente. Pode ser um nome de servidor (string referenciando um servidor da configuração `mcpServers` do pai) ou um registro de configuração de servidor inline mapeando nomes de servidor para configs.1220Especifica os servidores MCP disponíveis para um subagente. Pode ser um nome de servidor (string que referencia um servidor da configuração `mcpServers` do pai) ou um registro de configuração de servidor inline que mapeia nomes de servidores para configurações.
1216 1221
1217```typescript theme={null}1222```typescript theme={null}
1218type AgentMcpServerSpec = string | Record<string, McpServerConfigForProcessTransport>;1223type AgentMcpServerSpec = string | Record<string, McpServerConfigForProcessTransport>;
1224 `SettingSource`1229 `SettingSource`
1225</h3>1230</h3>
1226 1231
1227Controla quais fontes de configuração baseadas em sistema de arquivos o SDK carrega configurações.1232Controla de quais fontes de configuração baseadas no sistema de arquivos o SDK carrega as configurações.
1228 1233
1229```typescript theme={null}1234```typescript theme={null}
1230type SettingSource = "user" | "project" | "local";1235type SettingSource = "user" | "project" | "local";
1233| Valor | Descrição | Localização |1238| Valor | Descrição | Localização |
1234| :- | :- | :- |1239| :- | :- | :- |
1235| `'user'` | Configurações globais do usuário | `~/.claude/settings.json` |1240| `'user'` | Configurações globais do usuário | `~/.claude/settings.json` |
1236| `'project'` | Configurações de projeto compartilhadas (controladas por versão) | `.claude/settings.json` |1241| `'project'` | Configurações compartilhadas do projeto (com controle de versão) | `.claude/settings.json` |
1237| `'local'` | Configurações de projeto local, gitignored quando Claude Code salva uma configuração nela | `.claude/settings.local.json` |1242| `'local'` | Configurações locais do projeto, adicionadas ao gitignore quando o Claude Code salva uma configuração nele | `.claude/settings.local.json` |
1238 1243
1239<h4 id="default-behavior">1244<h4 id="default-behavior">
1240 Comportamento padrão1245 Comportamento padrão
1241</h4>1246</h4>
1242 1247
1243Quando `settingSources` é omitido ou `undefined`, `query()` carrega as mesmas configurações do sistema de arquivos que a CLI do Claude Code: usuário, projeto e local. Veja [O que settingSources não controla](/docs/pt/agent-sdk/claude-code-features#what-settingsources-does-not-control) para entradas que são lidas independentemente desta opção, e como desativá-las.1248Quando `settingSources` é omitido ou `undefined`, `query()` carrega as mesmas configurações do sistema de arquivos que a CLI do Claude Code: user, project e local. Consulte [O que settingSources não controla](/docs/pt/agent-sdk/claude-code-features#what-settingsources-does-not-control) para ver as entradas que são lidas independentemente desta opção e como desativá-las.
1244 1249
1245<h4 id="why-use-settingsources">1250<h4 id="why-use-settingsources">
1246 Por que usar settingSources1251 Por que usar settingSources
1251```typescript theme={null}1256```typescript theme={null}
1252import { query } from "@anthropic-ai/claude-agent-sdk";1257import { query } from "@anthropic-ai/claude-agent-sdk";
1253 1258
1254// Não carregar configurações de usuário, projeto ou local do disco1259// Do not load user, project, or local settings from disk
1255const result = query({1260const result = query({
1256 prompt: "Analyze this code",1261 prompt: "Analyze this code",
1257 options: { settingSources: [] }1262 options: { settingSources: [] }
1263```typescript theme={null}1268```typescript theme={null}
1264import { query } from "@anthropic-ai/claude-agent-sdk";1269import { query } from "@anthropic-ai/claude-agent-sdk";
1265 1270
1266// Carregar apenas configurações de projeto, ignorar usuário e local1271// Load only project settings, ignore user and local
1267const result = query({1272const result = query({
1268 prompt: "Run CI checks",1273 prompt: "Run CI checks",
1269 options: {1274 options: {
1270 settingSources: ["project"] // Apenas .claude/settings.json1275 settingSources: ["project"] // Only .claude/settings.json
1271 }1276 }
1272});1277});
1273```1278```
1274 1279
1275Para carregar instruções de projeto CLAUDE.md, inclua `"project"` em `settingSources`. Veja [Modificar prompts do sistema](/docs/pt/agent-sdk/modifying-system-prompts#claude-md-files-for-project-level-instructions) para como o carregamento de CLAUDE.md interage com as opções de prompt do sistema.1280Para carregar as instruções de projeto do CLAUDE.md, inclua `"project"` em `settingSources`. Consulte [Modificar system prompts](/docs/pt/agent-sdk/modifying-system-prompts#claude-md-files-for-project-level-instructions) para saber como o carregamento do CLAUDE.md interage com as opções de system prompt.
1276 1281
1277<h4 id="settings-precedence">1282<h4 id="settings-precedence">
1278 Precedência de configurações1283 Precedência das configurações
1279</h4>1284</h4>
1280 1285
1281Quando múltiplas fontes são carregadas, as configurações são mescladas com esta precedência (maior para menor):1286Quando várias fontes são carregadas, as configurações são mescladas com esta precedência (da mais alta para a mais baixa):
1282 1287
12831. Configurações locais (`.claude/settings.local.json`)12881. Configurações locais (`.claude/settings.local.json`)
12842. Configurações de projeto (`.claude/settings.json`)12892. Configurações do projeto (`.claude/settings.json`)
12853. Configurações do usuário (`~/.claude/settings.json`)12903. Configurações do usuário (`~/.claude/settings.json`)
1286 1291
1287Opções programáticas como `agents`, `allowedTools`, e `settings` substituem configurações do sistema de arquivos de usuário, projeto e local. Configurações de política gerenciada têm precedência sobre opções programáticas.1292Opções programáticas como `agents`, `allowedTools` e `settings` sobrescrevem as configurações de user, project e local do sistema de arquivos. As configurações de política gerenciada têm precedência sobre as opções programáticas.
1288 1293
1289<h3 id="permissionmode">1294<h3 id="permissionmode">
1290 `PermissionMode`1295 `PermissionMode`
1292 1297
1293```typescript theme={null}1298```typescript theme={null}
1294type PermissionMode =1299type PermissionMode =
1295 | "default" // Comportamento de permissão padrão1300 | "default" // Standard permission behavior
1296 | "acceptEdits" // Auto-aceitar edições de arquivo1301 | "acceptEdits" // Auto-accept file edits
1297 | "bypassPermissions" // Bypass de verificações de permissão; regras de solicitação explícita ainda solicitam1302 | "bypassPermissions" // Bypass permission checks; explicit ask rules still prompt
1298 | "plan" // Plan Mode - explorar sem editar1303 | "plan" // Planning mode - explore without editing
1299 | "dontAsk" // Não solicitar permissões, negar se não pré-aprovado1304 | "dontAsk" // Don't prompt for permissions, deny if not pre-approved
1300 | "auto"; // Classificador de modelo aprova ou nega prompts de permissão1305 | "auto"; // A model classifier reviews actions such as shell commands and network requests
1301```1306```
1302 1307
1303<h3 id="canusetool">1308<h3 id="canusetool">
1306 1311
1307Tipo de função de permissão personalizada para controlar o uso de ferramentas.1312Tipo de função de permissão personalizada para controlar o uso de ferramentas.
1308 1313
1309A função é a substituição do SDK para o prompt de permissão interativo: é invocada apenas quando o [fluxo de avaliação de permissão](/docs/pt/agent-sdk/permissions#how-permissions-are-evaluated) se resolve em um prompt. Chamadas de ferramenta já aprovadas por uma entrada `allowedTools`, uma regra de configurações de permissão, ou o modo de permissão, como `acceptEdits` ou `bypassPermissions`, nunca a invocam. Para controlar cada chamada de ferramenta, use um [hook `PreToolUse`](/docs/pt/agent-sdk/hooks) em vez disso.1314A função é a substituta, no SDK, do prompt de permissão interativo: ela é invocada somente quando o [fluxo de avaliação de permissões](/docs/pt/agent-sdk/permissions#how-permissions-are-evaluated) resulta em um prompt. Chamadas de ferramenta já aprovadas por uma entrada de `allowedTools`, por uma regra de permissão de allow nas configurações ou pelo modo de permissão, como `acceptEdits` ou `bypassPermissions`, nunca a invocam. Para controlar todas as chamadas de ferramenta, use um [hook `PreToolUse`](/docs/pt/agent-sdk/hooks).
1310 1315
1311Uma regra de permissão não pré-aprova as [ações que nenhum modo auto-aprova](/docs/pt/permission-modes#actions-no-mode-auto-approves); veja [Como permissões são avaliadas](/docs/pt/agent-sdk/permissions#how-permissions-are-evaluated) para qual delas alcança o callback e o que acontece em modo `dontAsk` e `auto`.1316Uma regra de allow não pré-aprova as [ações que nenhum modo aprova automaticamente](/docs/pt/permission-modes#actions-no-mode-auto-approves); consulte [Como as permissões são avaliadas](/docs/pt/agent-sdk/permissions#how-permissions-are-evaluated) para saber quais delas chegam ao callback e o que acontece nos modos `dontAsk` e `auto`.
1312 1317
1313```typescript theme={null}1318```typescript theme={null}
1314type CanUseTool = (1319type CanUseTool = (
1332| Opção | Tipo | Descrição |1337| Opção | Tipo | Descrição |
1333| :- | :- | :- |1338| :- | :- | :- |
1334| `signal` | `AbortSignal` | Sinalizado se a operação deve ser abortada |1339| `signal` | `AbortSignal` | Sinalizado se a operação deve ser abortada |
1335| `suggestions` | [`PermissionUpdate`](#permissionupdate)`[]` | Atualizações de permissão sugeridas para que o usuário não seja solicitado novamente para esta ferramenta. Prompts de Bash incluem uma sugestão com o destino `localSettings` [destination](#permissionupdatedestination), então retorná-la em `updatedPermissions` escreve a regra em `.claude/settings.local.json` e persiste entre sessões. |1340| `suggestions` | [`PermissionUpdate`](#permissionupdate)`[]` | Atualizações de permissão sugeridas para que o usuário não seja solicitado novamente para esta ferramenta. Prompts do Bash incluem uma sugestão com o [destino](#permissionupdatedestination) `localSettings`, de modo que retorná-la em `updatedPermissions` grava a regra em `.claude/settings.local.json` e ela persiste entre sessões. |
1336| `blockedPath` | `string` | O caminho do arquivo que acionou a solicitação de permissão, se aplicável |1341| `blockedPath` | `string` | O caminho do arquivo que acionou a requisição de permissão, se aplicável |
1337| `mcpServer` | `{ name: string; source: string }` | Para uma ferramenta `mcp__*`, o servidor MCP que a serve e de onde a definição desse servidor veio, com os campos de [`McpServerProvenance`](#mcpserverprovenance). Ausente para outras ferramentas. Requer Agent SDK v0.3.274 ou posterior |1342| `mcpServer` | `{ name: string; source: string }` | Para uma ferramenta `mcp__*`, o servidor MCP que a fornece e a origem da definição desse servidor, com os campos de [`McpServerProvenance`](#mcpserverprovenance). Ausente para outras ferramentas. Requer Agent SDK v0.3.274 ou posterior |
1338| `decisionReason` | `string` | Explica por que esta solicitação de permissão foi acionada |1343| `decisionReason` | `string` | Explica por que esta requisição de permissão foi acionada |
1339| `defaultToNo` | `boolean` | Quando `true`, um único toque errado não deve aprovar esta solicitação: abra seu prompt na opção de declínio, não pré-selecione aprovar, e não ofereça nenhum atalho de aprovação de uma tecla. Requer Agent SDK v0.3.268 ou posterior |1344| `defaultToNo` | `boolean` | Quando `true`, um único pressionamento de tecla acidental não deve aprovar esta requisição: abra seu prompt na opção de recusa, não pré-selecione a aprovação e não ofereça atalho de aprovação com uma única tecla. Requer Agent SDK v0.3.268 ou posterior |
1340| `suppressAlwaysAllowRule` | `boolean` | Quando `true`, não ofereça uma escolha de sempre-permitir persistente para esta solicitação, porque a regra que ela escreveria concede mais do que a ação da própria solicitação. Requer Agent SDK v0.3.268 ou posterior |1345| `suppressAlwaysAllowRule` | `boolean` | Quando `true`, não ofereça uma opção persistente de sempre permitir para esta requisição. Requer Agent SDK v0.3.268 ou posterior |
1341| `toolUseID` | `string` | Identificador único para esta chamada de ferramenta específica dentro da mensagem do assistente |1346| `toolUseID` | `string` | Identificador único para esta chamada de ferramenta específica dentro da mensagem do assistente |
1342| `agentID` | `string` | Se executando dentro de um sub-agente, o ID do sub-agente |1347| `agentID` | `string` | Se estiver em execução dentro de um subagente, o ID do subagente |
1343| `requestId` | `string` | O `request_id` do envelope `control_request`. Uma `control_response` que sua aplicação envia fora do SDK, como um POST HTTP assinado, deve ecoar este valor para que o processo Claude Code possa corresponder a resposta à solicitação |1348| `requestId` | `string` | O `request_id` do envelope `control_request`. Um `control_response` que sua aplicação envia fora do SDK, como um HTTP POST assinado, deve repetir este valor para que o processo do Claude Code possa associar a resposta à requisição |
1344 1349
1345O callback normalmente resolve a solicitação retornando um [`PermissionResult`](#permissionresult), que o SDK escreve de volta sobre seu transporte como a `control_response`. Retorne `null` apenas quando sua aplicação já enviou a `control_response` para esta solicitação sobre seu próprio canal, ecoando `requestId`; o SDK então pula escrever a resposta em seu transporte. Retornar `null` em qualquer outro caso deixa a chamada de ferramenta bloqueada indefinidamente, porque nenhuma `control_response` é jamais enviada e prompts de permissão não expiram.1350O callback normalmente resolve a requisição retornando um [`PermissionResult`](#permissionresult), que o SDK grava de volta em seu transporte como o `control_response`. Retorne `null` somente quando sua aplicação já tiver enviado o `control_response` para esta requisição por seu próprio canal, repetindo `requestId`; o SDK então deixa de gravar a resposta em seu transporte. Retornar `null` em qualquer outro caso deixa a chamada de ferramenta bloqueada indefinidamente, porque nenhum `control_response` é enviado e os prompts de permissão não atingem timeout.
1346 1351
1347A opção `requestId` e o valor de retorno `null` requerem Claude Code v2.1.199 ou posterior.1352A opção `requestId` e o valor de retorno `null` requerem o Claude Code v2.1.199 ou posterior.
1348 1353
1349<h3 id="permissionresult">1354<h3 id="permissionresult">
1350 `PermissionResult`1355 `PermissionResult`
1372 `ToolConfig`1377 `ToolConfig`
1373</h3>1378</h3>
1374 1379
1375Configuração para comportamento de ferramenta integrada.1380Configuração do comportamento das ferramentas integradas.
1376 1381
1377```typescript theme={null}1382```typescript theme={null}
1378type ToolConfig = {1383type ToolConfig = {
1384 1389
1385| Campo | Tipo | Descrição |1390| Campo | Tipo | Descrição |
1386| :- | :- | :- |1391| :- | :- | :- |
1387| `askUserQuestion.previewFormat` | `'markdown' \| 'html'` | Opta pelo campo `preview` em opções [`AskUserQuestion`](/docs/pt/agent-sdk/user-input#question-format) e define seu formato de conteúdo. Quando não definido, Claude não emite visualizações |1392| `askUserQuestion.previewFormat` | `'markdown' \| 'html'` | Ativa o campo `preview` nas opções de [`AskUserQuestion`](/docs/pt/agent-sdk/user-input#question-format) e define o formato do seu conteúdo. Quando não definido, o Claude não emite pré-visualizações |
1388 1393
1389<h3 id="mcpserverconfig">1394<h3 id="mcpserverconfig">
1390 `McpServerConfig`1395 `McpServerConfig`
1478 1483
1479| Campo | Tipo | Descrição |1484| Campo | Tipo | Descrição |
1480| :- | :- | :- |1485| :- | :- | :- |
1481| `type` | `'local'` | Deve ser `'local'` (apenas plugins locais atualmente suportados) |1486| `type` | `'local'` | Deve ser `'local'` (atualmente, apenas plugins locais são suportados) |
1482| `path` | `string` | Caminho absoluto ou relativo para o diretório do plugin |1487| `path` | `string` | Caminho absoluto ou relativo para o diretório do plugin |
1483| `skipMcpDiscovery` | `boolean` | Quando `true`, o SDK carrega skills, hooks, agentes e comandos deste plugin mas não lê seu `.mcp.json` ou manifest `mcpServers`. Defina isso quando sua aplicação possui as conexões MCP do plugin. |1488| `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. |
1484 1489
1485**Exemplo:**1490**Exemplo:**
1486 1491
1491];1496];
1492```1497```
1493 1498
1494Para informações completas sobre criação e uso de plugins, veja [Plugins](/docs/pt/agent-sdk/plugins).1499Para informações completas sobre como criar e usar plugins, consulte [Plugins](/docs/pt/agent-sdk/plugins).
1495 1500
1496<h2 id="message-types">1501<h2 id="message-types">
1497 Tipos de Mensagem1502 Tipos de Mensagem
3790};3795};
3791```3796```
3792 3797
3793Relata descobertas de revisão de código como uma lista estruturada para que Claude Code possa renderizá-las em vez de imprimi-las como texto. `level` é o nível de esforço em que a revisão foi executada. As descobertas são ordenadas mais graves primeiro, com no máximo 32 por chamada, e o array está vazio quando nenhuma sobreviveu. Requer Claude Code v2.1.196 ou posterior.3798Relata descobertas de revisão de código como uma lista estruturada para que Claude Code possa renderizá-las em vez de imprimi-las como texto. As descobertas são ordenadas mais graves primeiro, com no máximo 32 por chamada, e o array está vazio quando nenhuma sobreviveu. Requer Claude Code v2.1.196 ou posterior.
3799
3800`level` é opcional e contém o nível de esforço que Claude relata para a revisão. Claude Code não o compara com o nível em que a revisão foi executada, então os dois podem diferir.
3794 3801
3795Cada descoberta carrega esses campos:3802Cada descoberta carrega esses campos:
3796 3803
4840};4847};
4841```4848```
4842 4849
4843Retorna o número de descobertas relatadas, o nível de esforço em que a revisão foi executada e as descobertas ecoadas de volta para o corpo do resultado. Requer Claude Code v2.1.196 ou posterior. O campo `short_summary` ecoado requer Claude Code v2.1.212 ou posterior.4850Retorna o número de descobertas relatadas, o valor de `level` que Claude passou e as descobertas ecoadas de volta para o corpo do resultado. Requer Claude Code v2.1.196 ou posterior. O campo `short_summary` ecoado requer Claude Code v2.1.212 ou posterior.
4844 4851
4845<h3 id="artifact-2">4852<h3 id="artifact-2">
4846 Artifact4853 Artifact
5461 | { type: "disabled" }; // Sem pensamento estendido5468 | { type: "disabled" }; // Sem pensamento estendido
5462```5469```
5463 5470
5464O campo `display` opcional controla se o texto de pensamento é retornado `"summarized"` ou `"omitted"`. No Claude Opus 4.7 e posterior, o padrão da API é `"omitted"`, então defina `"summarized"` para receber conteúdo de pensamento em blocos `thinking`. Claude Code não envia `display` para Amazon Bedrock ou Google Cloud's Agent Platform, então nesses provedores Opus 4.7 e posterior retornam blocos `thinking` vazios mesmo quando você define `display` para `"summarized"`.5471O campo `display` opcional controla se o texto de pensamento é retornado `"summarized"` ou `"omitted"`. No Claude Opus 4.7 e posterior, o padrão da API é `"omitted"`, então defina `"summarized"` para receber conteúdo de pensamento em blocos `thinking`. Claude Code omite `display` das requisições para alguns provedores, como Amazon Bedrock e Google Cloud's Agent Platform. Nesses provedores, Opus 4.7 e posterior retornam blocos `thinking` vazios mesmo quando você define `display` para `"summarized"`.
5465 5472
5466<h3 id="spawnedprocess">5473<h3 id="spawnedprocess">
5467 `SpawnedProcess`5474 `SpawnedProcess`
5532 5539
5533Quando você chama `setMcpServers()`, Claude Code aplica estas regras:5540Quando você chama `setMcpServers()`, Claude Code aplica estas regras:
5534 5541
5535* **Servidores que a chamada não nomeia**: Claude Code mantém servidores fornecidos por plugin em execução. Requer Agent SDK v0.3.210 ou posterior.5542* **Servidores que a chamada não nomeia**: fora de uma [sessão na nuvem](/docs/pt/claude-code-on-the-web), 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.
5536* **Servidores que a chamada nomeia**: exceto para servidores integrados que a CLI iniciou na inicialização, Claude Code substitui um servidor em execução apenas quando sua configuração difere da que você passou.5543* **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.
5537* **Servidores integrados que a CLI iniciou na inicialização**: se a chamada nomear um, Claude Code descarta essa entrada e a relata em `errors`.5544* **Servidores integrados que a CLI iniciou na inicialização**: se a chamada nomear um, Claude Code descarta essa entrada e a relata em `errors`.
5538 5545
5539A promise é resolvida após novos servidores stdio, HTTP e SSE adicionados se conectarem ou falharem, então ferramentas de servidores que se conectaram estão disponíveis no próximo turno.5546A promise é resolvida após novos servidores stdio, HTTP e SSE adicionados se conectarem ou falharem, então ferramentas de servidores que se conectaram estão disponíveis no próximo turno.
