Documentation — Spybara

agent-sdk/typescript.md +222 −222

Details

540| :- | :- | :- | :- |540| :- | :- | :- | :- |

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) |542| `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) |

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 |545| `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'` |546| `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) |547| `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) |

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 |549| `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 |

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) |554| `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) |

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 |557| `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 |

560| `extraArgs` | `Record<string, string \| null>` | `{}` | Argumentos adicionais |560| `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) |561| `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) |

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 |563| `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 |564| `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 |565| `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 |

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 |567| `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 |568| `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) |569| `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) |

572| `mcpServers` | `Record<string, [`McpServerConfig`](#mcpserverconfig)>` | `{}` | Configurações de servidor MCP |572| `mcpServers` | `Record<string, [`McpServerConfig`](#mcpserverconfig)>` | `{}` | Configurações de servidores MCP |

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 |574| `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 |575| `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) |576| `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 |577| `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 |578| `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 |

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 |580| `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 |

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 |582| `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 |

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 |584| `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) |585| `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) |

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 |587| `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 |

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) |591| `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) |

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) |593| `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) |594| `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) |595| `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 |596| `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 |

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) |598| `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 |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 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 |600| `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 |601| `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 |602| `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' }` |603| `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' }` |

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 |605| `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 |606| `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 607

608<h4 id="handle-slow-or-stalled-api-responses">608<h4 id="handle-slow-or-stalled-api-responses">

609 Lidar com respostas de API lentas ou travadas609 Lidar com respostas de API lentas ou travadas

610</h4>610</h4>

611 611

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`:612O 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 613

614```typescript theme={null}614```typescript theme={null}

615import { query } from "@anthropic-ai/claude-agent-sdk";615import { query } from "@anthropic-ai/claude-agent-sdk";

627});627});

628```628```

629 629

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.630* `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.631* `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`.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, 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 633

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.634 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.635* `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 636

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.637 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 638

639<h3 id="query-object">639<h3 id="query-object">

640 Objeto `Query`640 Objeto `Query`

696 696

697| Método | Descrição |697| Método | Descrição |

698| :- | :- |698| :- | :- |

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 |699| `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) |700| `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) |

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) |702| `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 |703| `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) |704| `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 |705| `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 |706| `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 |707| `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) |708| `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) |

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 |712| `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 |713| `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 |714| `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 |715| `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 |716| `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 |

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 |718| `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 |719| `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 |720| `setMcpServers(servers)` | Substitui dinamicamente o conjunto de servidores MCP desta sessão. Resolve com um [`McpSetServersResult`](#mcpsetserversresult) indicando quais servidores foram adicionados e removidos, além de quaisquer erros |

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 |721| `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 |

725 725

726<h4 id="applyflagsettings">726<h4 id="applyflagsettings">

727 `applyFlagSettings()`727 `applyFlagSettings()`

728</h4>728</h4>

729 729

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()`.730Altera [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 731

732Apenas algumas chaves têm efeito no meio da sessão:732Apenas algumas chaves têm efeito no meio da sessão:

733 733

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.734* **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.735* **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.736* **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 737

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`.738`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 739

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.740Os 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 741

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.742Chamadas 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 743

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.744Para 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 745

746Três chaves além de `model` redefinem o estado da sessão em vez de voltar:746Três chaves além de `model` redefinem o estado da sessão em vez de recorrer a um fallback:

747 747

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.748* `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.749* `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.750* `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 751

752Apenas disponível em modo de entrada de transmissão, a mesma restrição que `setModel()` e `setPermissionMode()`.752Disponível apenas no modo de entrada por streaming, a mesma restrição de `setModel()` e `setPermissionMode()`.

753 753

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).754O 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 755

756```typescript theme={null}756```typescript theme={null}

757import { query } from "@anthropic-ai/claude-agent-sdk";757import { query } from "@anthropic-ai/claude-agent-sdk";

758 758

759const q = query({ prompt: messageStream });759const q = query({ prompt: messageStream });

760 760

761// Substituir o modelo para o resto da sessão761// Override the model for the rest of the session

762await q.applyFlagSettings({ model: "claude-opus-4-6" });762await q.applyFlagSettings({ model: "claude-opus-4-6" });

763 763

764// Depois: limpar a substituição; o modelo redefine para o modelo padrão do Claude Code764// Later: clear the override; the model resets to Claude Code's default

765await q.applyFlagSettings({ model: null });765await q.applyFlagSettings({ model: null });

766```766```

767 767

768<Note>768<Note>

769 `applyFlagSettings()` é apenas TypeScript. O SDK Python não expõe um método equivalente.769 `applyFlagSettings()` é exclusivo do TypeScript. O Python SDK não expõe um método equivalente.

770</Note>770</Note>

771 771

772<h4 id="updatesettings">772<h4 id="updatesettings">

773 `updateSettings()`773 `updateSettings()`

774</h4>774</h4>

775 775

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:776Grava 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 777

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.778* **`"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.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, 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 780

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.781A 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 782

783<h4 id="togglemcpserver">783<h4 id="togglemcpserver">

784 `toggleMcpServer()`784 `toggleMcpServer()`

785</h4>785</h4>

786 786

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:787Desabilitar 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 788

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.789* 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.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 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 791

792<h3 id="warmquery">792<h3 id="warmquery">

793 `WarmQuery`793 `WarmQuery`

794</h3>794</h3>

795 795

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.796Handle 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 797

798```typescript theme={null}798```typescript theme={null}

799interface WarmQuery extends AsyncDisposable {799interface WarmQuery extends AsyncDisposable {

808 808

809| Método | Descrição |809| Método | Descrição |

810| :- | :- |810| :- | :- |

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` |811| `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 |812| `close()` | Fecha o subprocesso sem enviar um prompt. Use para descartar uma consulta pré-aquecida que não é mais necessária |

813 813

814`WarmQuery` implementa `AsyncDisposable`, então pode ser usado com `await using` para limpeza automática.814`WarmQuery` implementa `AsyncDisposable`, portanto pode ser usado com `await using` para limpeza automática.

815 815

816<h3 id="spareprocess">816<h3 id="spareprocess">

817 `SpareProcess`817 `SpareProcess`

818</h3>818</h3>

819 819

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.820*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 821

822```typescript theme={null}822```typescript theme={null}

823interface SpareProcess extends AsyncDisposable {823interface SpareProcess extends AsyncDisposable {

837 837

838| Membro | Descrição |838| Membro | Descrição |

839| :- | :- |839| :- | :- |

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 |840| `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 |841| `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 |842| `exited` | É concluído quando o processo termina, reivindicado ou não. Substitua um processo reserva que termine antes de você reivindicá-lo |

844 844

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`.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`.

846 846

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.847O Claude Code pode recusar uma reivindicação, por exemplo, para uma pasta que não existe ou para uma cujas configurações de projeto definem `env`, `agent` ou `model`. Quando `claimed` é rejeitado com uma mensagem que começa com `option_not_applied`, a sessão está em execução sem o `model` ou o `maxThinkingTokens` que você solicitou. Após qualquer outra rejeição, seu prompt não foi executado, portanto inicie a sessão com `query()` em vez disso.

848 848

849<h3 id="sdkcontrolinitializeresponse">849<h3 id="sdkcontrolinitializeresponse">

850 `SDKControlInitializeResponse`850 `SDKControlInitializeResponse`

851</h3>851</h3>

852 852

853Tipo de retorno de `initializationResult()`. Contém dados de inicialização de sessão.853Tipo de retorno de `initializationResult()`. Contém os dados de inicialização da sessão.

854 854

855```typescript theme={null}855```typescript theme={null}

856type SDKControlInitializeResponse = {856type SDKControlInitializeResponse = {

874};874};

875```875```

876 876

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.877`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 878

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:879O 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 880

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.881* `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.882* `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 883

884Antes do Agent SDK v0.3.238, a resposta nunca carregava o campo, e Claude Code ignorava `hooks` em cada inicialização repetida.884Antes do Agent SDK v0.3.238, a resposta nunca continha o campo, e o Claude Code ignorava `hooks` em todo initialize repetido.

885 885

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.886O 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 887

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.888A 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 889

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.890O 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 891

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.892O 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 893

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.894O 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 895

896<h3 id="sdkcontrolinterruptresponse">896<h3 id="sdkcontrolinterruptresponse">

897 `SDKControlInterruptResponse`897 `SDKControlInterruptResponse`

898</h3>898</h3>

899 899

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`.900O 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 901

902```typescript theme={null}902```typescript theme={null}

903type SDKControlInterruptResponse = {903type SDKControlInterruptResponse = {

906};906};

907```907```

908 908

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.909`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 910

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.911Use 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 912

913Interprete a lista com estas ressalvas:913Interprete a lista com estas ressalvas:

914 914

915* Apenas mensagens que foram enfileiradas com um UUID aparecem. Um array vazio não significa que nada mais será executado.915* 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.916* 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.917* 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 918

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.919Um 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 920

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`.921A 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 922

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.923O 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 924

925<h3 id="sdkcontrolgetcontextusageresponse">925<h3 id="sdkcontrolgetcontextusageresponse">

926 `SDKControlGetContextUsageResponse`926 `SDKControlGetContextUsageResponse`

927</h3>927</h3>

928 928

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`.929Tipo 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 930

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.931O 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 932

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.933* **`'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.934* **`'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 935

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.936Quando 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 937

938```typescript theme={null}938```typescript theme={null}

939type SDKControlGetContextUsageResponse = {939type SDKControlGetContextUsageResponse = {

1030};1030};

1031```1031```

1032 1032

1033Leia atribuição de token da coleção de campos:1033Leia a atribuição de tokens a partir dos campos de coleção:

1034 1034

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.1035* `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.1036* `mcpTools` e `agents` atribuem tokens a ferramentas MCP e subagentes individuais.

1037* `memoryFiles` lista cada arquivo de memória carregado com seu custo.1037* `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.1038* `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 1039

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.1040`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 1041

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.1042O Claude Code deixa sem definir os diagnósticos opcionais `deferredBuiltinTools`, `systemTools` e `systemPromptSections`, portanto espere que estejam ausentes, embora o tipo os declare.

1043 1043

1044<h3 id="sdkcontrolreadfileresponse">1044<h3 id="sdkcontrolreadfileresponse">

1045 `SDKControlReadFileResponse`1045 `SDKControlReadFileResponse`

1056};1056};

1057```1057```

1058 1058

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.1059`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 1060

1061<h4 id="what-readfile-can-read">1061<h4 id="what-readfile-can-read">

1062 O que `readFile()` pode ler1062 O que `readFile()` pode ler

1063</h4>1063</h4>

1064 1064

1065`readFile()` serve um conjunto mais estreito de arquivos do que a ferramenta Read:1065`readFile()` fornece um conjunto de arquivos mais restrito que a ferramenta Read:

1066 1066

1067* Um arquivo regular dentro de um dos diretórios de trabalho da sessão, como `cwd` e `additionalDirectories`1067* 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 ferramentas1068* Alguns dos próprios arquivos do Claude Code para a sessão, como resultados de ferramentas

1069 1069

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`.1070Regras 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 1071

1072<h3 id="sdkcontrolreloadpluginsresponse">1072<h3 id="sdkcontrolreloadpluginsresponse">

1073 `SDKControlReloadPluginsResponse`1073 `SDKControlReloadPluginsResponse`

1098 1098

1099Os campos de coleção descrevem a sessão após a chamada:1099Os campos de coleção descrevem a sessão após a chamada:

1100 1100

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 recarregamento1101* `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 nenhum1102* `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 plugins1103* `error_count`: o número de erros ao carregar plugins

1104 1104

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.1105Passe `{ 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 1106

1107Quando você passa a opção, leia `held` para aprender o que aconteceu:1107Quando você passa a opção, leia `held` para saber o que aconteceu:

1108 1108

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.1109* `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.1110* `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.1111* Ausente: você não passou a opção, ou o executável do Claude Code é anterior à v2.1.268 e aplicou o recarregamento.

1112 1112

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.1113`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 1114

1115<h3 id="sdkcontrolreloadskillsresponse">1115<h3 id="sdkcontrolreloadskillsresponse">

1116 `SDKControlReloadSkillsResponse`1116 `SDKControlReloadSkillsResponse`

1124};1124};

1125```1125```

1126 1126

1127`skills` lista as skills disponíveis após o recarregamento, na mesma forma [`SlashCommand`](#slashcommand) que `supportedCommands()` retorna.1127`skills` lista as skills disponíveis após o recarregamento, no mesmo formato [`SlashCommand`](#slashcommand) que `supportedCommands()` retorna.

1128 1128

1129<h3 id="sdkcontrolreloadoutputstylesresponse">1129<h3 id="sdkcontrolreloadoutputstylesresponse">

1130 `SDKControlReloadOutputStylesResponse`1130 `SDKControlReloadOutputStylesResponse`

1144 `SDKControlMcpReadResourceResponse`1144 `SDKControlMcpReadResourceResponse`

1145</h3>1145</h3>

1146 1146

1147Tipo de retorno de [`readMcpResource()`](#query-object), carregando o resultado `resources/read` do servidor MCP. Requer TypeScript Agent SDK v0.3.280 ou posterior.1147Tipo 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 1148

1149```typescript theme={null}1149```typescript theme={null}

1150type SDKControlMcpReadResourceResponse = {1150type SDKControlMcpReadResourceResponse = {

1158};1158};

1159```1159```

1160 1160

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`.1161Passe 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 1162

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.1163Cada 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 1164

1165O conteúdo é HTML de terceiros não confiável, então renderize-o em um sandbox.1165O conteúdo é HTML de terceiros não confiável, portanto renderize-o em um sandbox.

1166 1166

1167<h3 id="agentdefinition">1167<h3 id="agentdefinition">

1168 `AgentDefinition`1168 `AgentDefinition`

1169</h3>1169</h3>

1170 1170

1171Configuração para um subagente definido programaticamente.1171Configuração de um subagente definido programaticamente.

1172 1172

1173```typescript theme={null}1173```typescript theme={null}

1174type AgentDefinition = {1174type AgentDefinition = {

1194| :- | :- | :- |1194| :- | :- | :- |

1195| `description` | Sim | Descrição em linguagem natural de quando usar este agente |1195| `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 |1196| `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 |1197| `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 |1198| `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) |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, 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 |1200| `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 |1201| `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 |1202| `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 |1203| `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 |1204| `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 |1205| `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'` |1206| `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 |1207| `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) |1208| `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 |1209| `criticalSystemReminder_EXPERIMENTAL` | Não | Experimental: lembrete crítico adicionado ao system prompt |

1210 1210

1211<h3 id="agentmcpserverspec">1211<h3 id="agentmcpserverspec">

1212 `AgentMcpServerSpec`1212 `AgentMcpServerSpec`

1213</h3>1213</h3>

1214 1214

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.1215Especifica 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 1216

1217```typescript theme={null}1217```typescript theme={null}

1218type AgentMcpServerSpec = string | Record<string, McpServerConfigForProcessTransport>;1218type AgentMcpServerSpec = string | Record<string, McpServerConfigForProcessTransport>;

1224 `SettingSource`1224 `SettingSource`

1225</h3>1225</h3>

1226 1226

1227Controla quais fontes de configuração baseadas em sistema de arquivos o SDK carrega configurações.1227Controla de quais fontes de configuração baseadas no sistema de arquivos o SDK carrega as configurações.

1228 1228

1229```typescript theme={null}1229```typescript theme={null}

1230type SettingSource = "user" | "project" | "local";1230type SettingSource = "user" | "project" | "local";

1234| :- | :- | :- |1234| :- | :- | :- |

1238 1238

1239<h4 id="default-behavior">1239<h4 id="default-behavior">

1240 Comportamento padrão1240 Comportamento padrão

1241</h4>1241</h4>

1242 1242

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.1243Quando `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 1244

1245<h4 id="why-use-settingsources">1245<h4 id="why-use-settingsources">

1246 Por que usar settingSources1246 Por que usar settingSources

1251```typescript theme={null}1251```typescript theme={null}

1252import { query } from "@anthropic-ai/claude-agent-sdk";1252import { query } from "@anthropic-ai/claude-agent-sdk";

1253 1253

1254// Não carregar configurações de usuário, projeto ou local do disco1254// Do not load user, project, or local settings from disk

1255const result = query({1255const result = query({

1256 prompt: "Analyze this code",1256 prompt: "Analyze this code",

1257 options: { settingSources: [] }1257 options: { settingSources: [] }

1263```typescript theme={null}1263```typescript theme={null}

1264import { query } from "@anthropic-ai/claude-agent-sdk";1264import { query } from "@anthropic-ai/claude-agent-sdk";

1265 1265

1266// Carregar apenas configurações de projeto, ignorar usuário e local1266// Load only project settings, ignore user and local

1267const result = query({1267const result = query({

1268 prompt: "Run CI checks",1268 prompt: "Run CI checks",

1269 options: {1269 options: {

1270 settingSources: ["project"] // Apenas .claude/settings.json1270 settingSources: ["project"] // Only .claude/settings.json

1271 }1271 }

1272});1272});

1273```1273```

1274 1274

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.1275Para 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 1276

1277<h4 id="settings-precedence">1277<h4 id="settings-precedence">

1278 Precedência de configurações1278 Precedência das configurações

1279</h4>1279</h4>

1280 1280

1281Quando múltiplas fontes são carregadas, as configurações são mescladas com esta precedência (maior para menor):1281Quando várias fontes são carregadas, as configurações são mescladas com esta precedência (da mais alta para a mais baixa):

1282 1282

12831. Configurações locais (`.claude/settings.local.json`)12831. Configurações locais (`.claude/settings.local.json`)

12842. Configurações de projeto (`.claude/settings.json`)12842. Configurações do projeto (`.claude/settings.json`)

12853. Configurações do usuário (`~/.claude/settings.json`)12853. Configurações do usuário (`~/.claude/settings.json`)

1286 1286

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.1287Opçõ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 1288

1289<h3 id="permissionmode">1289<h3 id="permissionmode">

1290 `PermissionMode`1290 `PermissionMode`

1292 1292

1293```typescript theme={null}1293```typescript theme={null}

1294type PermissionMode =1294type PermissionMode =

1295 | "default" // Comportamento de permissão padrão1295 | "default" // Standard permission behavior

1296 | "acceptEdits" // Auto-aceitar edições de arquivo1296 | "acceptEdits" // Auto-accept file edits

1297 | "bypassPermissions" // Bypass de verificações de permissão; regras de solicitação explícita ainda solicitam1297 | "bypassPermissions" // Bypass permission checks; explicit ask rules still prompt

1298 | "plan" // Plan Mode - explorar sem editar1298 | "plan" // Planning mode - explore without editing

1299 | "dontAsk" // Não solicitar permissões, negar se não pré-aprovado1299 | "dontAsk" // Don't prompt for permissions, deny if not pre-approved

1300 | "auto"; // Classificador de modelo aprova ou nega prompts de permissão1300 | "auto"; // A model classifier reviews actions such as shell commands and network requests

1301```1301```

1302 1302

1303<h3 id="canusetool">1303<h3 id="canusetool">

1306 1306

1307Tipo de função de permissão personalizada para controlar o uso de ferramentas.1307Tipo de função de permissão personalizada para controlar o uso de ferramentas.

1308 1308

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.1309A 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 1310

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`.1311Uma 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 1312

1313```typescript theme={null}1313```typescript theme={null}

1314type CanUseTool = (1314type CanUseTool = (

1333| :- | :- | :- |1333| :- | :- | :- |

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. |1335| `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. |

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 |1337| `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 |

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 |1339| `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 |1340| `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 |

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 |1343| `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 1344

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.1345O 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 1346

1347A opção `requestId` e o valor de retorno `null` requerem Claude Code v2.1.199 ou posterior.1347A opção `requestId` e o valor de retorno `null` requerem o Claude Code v2.1.199 ou posterior.

1348 1348

1349<h3 id="permissionresult">1349<h3 id="permissionresult">

1350 `PermissionResult`1350 `PermissionResult`

1372 `ToolConfig`1372 `ToolConfig`

1373</h3>1373</h3>

1374 1374

1375Configuração para comportamento de ferramenta integrada.1375Configuração do comportamento das ferramentas integradas.

1376 1376

1377```typescript theme={null}1377```typescript theme={null}

1378type ToolConfig = {1378type ToolConfig = {

1384 1384

1386| :- | :- | :- |1386| :- | :- | :- |

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 |1387| `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 1388

1389<h3 id="mcpserverconfig">1389<h3 id="mcpserverconfig">

1390 `McpServerConfig`1390 `McpServerConfig`

1478 1478

1480| :- | :- | :- |1480| :- | :- | :- |

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. |1483| `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 1484

1485**Exemplo:**1485**Exemplo:**

1486 1486

1491];1491];

1492```1492```

1493 1493

1494Para informações completas sobre criação e uso de plugins, veja [Plugins](/docs/pt/agent-sdk/plugins).1494Para informações completas sobre como criar e usar plugins, consulte [Plugins](/docs/pt/agent-sdk/plugins).

1495 1495

1496<h2 id="message-types">1496<h2 id="message-types">

1497 Tipos de Mensagem1497 Tipos de Mensagem

agent-view.md +1 −0

Details

819| `claude rm <id> --discard-unpushed <commit>@<worktree-id>` | Deletar uma sessão cuja exclusão foi recusada sobre commits não enviados, descartando o worktree junto com seu branch e commits. Passe o valor exato que a recusa imprimiu; veja [O que deletar uma sessão remove](#what-deleting-a-session-removes). Requer v2.1.260 ou posterior |819| `claude rm <id> --discard-unpushed <commit>@<worktree-id>` | Deletar uma sessão cuja exclusão foi recusada sobre commits não enviados, descartando o worktree junto com seu branch e commits. Passe o valor exato que a recusa imprimiu; veja [O que deletar uma sessão remove](#what-deleting-a-session-removes). Requer v2.1.260 ou posterior |

820| `claude rm <id> --force-remove-worktree <worktree-id>` | Deletar uma sessão cuja exclusão foi recusada porque git ou o hook `WorktreeRemove` não conseguiu remover seu worktree, deletando o diretório worktree mesmo assim e deixando seu branch no repositório. Passe o valor exato que a recusa imprimiu; veja [O que deletar uma sessão remove](#what-deleting-a-session-removes). Requer v2.1.268 ou posterior |820| `claude rm <id> --force-remove-worktree <worktree-id>` | Deletar uma sessão cuja exclusão foi recusada porque git ou o hook `WorktreeRemove` não conseguiu remover seu worktree, deletando o diretório worktree mesmo assim e deixando seu branch no repositório. Passe o valor exato que a recusa imprimiu; veja [O que deletar uma sessão remove](#what-deleting-a-session-removes). Requer v2.1.268 ou posterior |

821| `claude daemon status` | Imprimir o estado do [supervisor](#the-supervisor-process), versão, diretório de socket e contagem de workers |821| `claude daemon status` | Imprimir o estado do [supervisor](#the-supervisor-process), versão, diretório de socket e contagem de workers |

822| `claude daemon logs` | Acompanhar o arquivo de log do supervisor, [`~/.claude/daemon.log`](#where-state-is-stored), imprimindo novas linhas à medida que chegam até você pressionar `Ctrl+C` |

822| `claude daemon stop --any` | Parar o processo supervisor e as sessões em background que ele hospeda. Passe `--keep-workers` para deixar as sessões em background em execução para que o próximo supervisor se reconecte a elas. O próximo `claude agents` ou `claude --bg` inicia um novo supervisor |823| `claude daemon stop --any` | Parar o processo supervisor e as sessões em background que ele hospeda. Passe `--keep-workers` para deixar as sessões em background em execução para que o próximo supervisor se reconecte a elas. O próximo `claude agents` ou `claude --bg` inicia um novo supervisor |

823 824

824`claude attach` e `claude logs` podem receber parte do nome de uma sessão em execução no lugar do ID, como em `claude logs "auth refactor"`. Passar um nome requer Claude Code v2.1.290 ou posterior.825`claude attach` e `claude logs` podem receber parte do nome de uma sessão em execução no lugar do ID, como em `claude logs "auth refactor"`. Passar um nome requer Claude Code v2.1.290 ou posterior.

claude-apps-gateway.md +9 −7

Details

75| - | - |75| - | - |

76| Claude Code v2.1.195 ou posterior | O subcomando `claude gateway` e o fluxo de sign-in do gateway são enviados na v2.1.195. Compilações públicas anteriores não as incluem. Tanto a máquina executando o servidor gateway quanto a máquina de cada desenvolvedor devem estar na v2.1.195 ou posterior; execute `claude update` para obter a versão mais recente. O [upstream Claude Platform on AWS](/docs/pt/claude-apps-gateway-config#claude-platform-on-aws) requer Claude Code v2.1.198 ou posterior no servidor gateway. |76| Claude Code v2.1.195 ou posterior | O subcomando `claude gateway` e o fluxo de sign-in do gateway são enviados na v2.1.195. Compilações públicas anteriores não as incluem. Tanto a máquina executando o servidor gateway quanto a máquina de cada desenvolvedor devem estar na v2.1.195 ou posterior; execute `claude update` para obter a versão mais recente. O [upstream Claude Platform on AWS](/docs/pt/claude-apps-gateway-config#claude-platform-on-aws) requer Claude Code v2.1.198 ou posterior no servidor gateway. |

77| Provedor de identidade OpenID Connect (OIDC) | Okta, Microsoft Entra ID, Google Workspace, Keycloak ou Dex, ou qualquer outro IdP compatível com OIDC, como PingFederate. O gateway executa descoberta OIDC padrão e o fluxo de código de autorização contra ele. SAML e LDAP não são suportados. |77| Provedor de identidade OpenID Connect (OIDC) | Okta, Microsoft Entra ID, Google Workspace, Keycloak ou Dex, ou qualquer outro IdP compatível com OIDC, como PingFederate. O gateway executa descoberta OIDC padrão e o fluxo de código de autorização contra ele. SAML e LDAP não são suportados. |

78| PostgreSQL 14 ou posterior | Faz backup do fluxo de sign-in do dispositivo, onde o callback do navegador escreve e a CLI de polling lê, além de contadores de limite de taxa. Qualquer Postgres gerenciado funciona, incluindo o menor nível. Sem limites de gastos configurados, o gateway armazena alguns KB de estado de autenticação de curta duração; com [limites de gastos](/docs/pt/claude-apps-gateway-spend-limits), também mantém tabelas de gastos, auditoria e identidade duráveis que devem ser feitas backup. TLS via `?sslmode=require` é recomendado. |78| PostgreSQL 11 ou posterior | Dá suporte ao fluxo de sign-in do dispositivo e aos contadores de rate limit. Um serviço PostgreSQL gerenciado funciona, incluindo o menor nível; consulte [quais bancos de dados são suportados](/docs/pt/claude-apps-gateway-deploy#postgres). Com [limites de gastos](/docs/pt/claude-apps-gateway-spend-limits), também mantém tabelas de gastos, auditoria e identidade duráveis que devem ter backup. TLS via `?sslmode=require` é recomendado. PostgreSQL 11, 12 e 13 requerem Claude Code v2.1.290 ou posterior no servidor gateway. O projeto PostgreSQL não mantém mais essas versões, então use uma mais recente sempre que possível. |

79| Upstream de modelo | Credenciais do Amazon Bedrock, credenciais do Claude Platform on AWS, credenciais do Google Cloud, um recurso Microsoft Foundry ou uma chave de API Anthropic. Múltiplos upstreams são suportados com failover. |79| Upstream de modelo | Credenciais do Amazon Bedrock, credenciais do Claude Platform on AWS, credenciais do Google Cloud, um recurso Microsoft Foundry ou uma chave de API Anthropic. Múltiplos upstreams são suportados com failover. |

80| HTTPS | O gateway deve ser acessível via `https://` de laptops de desenvolvedores e de qualquer navegador usado para sign-in; o gateway serve a página de verificação do dispositivo no mesmo listener. Forneça um certificado TLS via `listen.tls` ou execute atrás de um ingress que termina TLS e defina `listen.public_url` para a origem externa em ambos os casos. Uma origem `http://` simples é aceita apenas quando o host do gateway é loopback: `localhost`, `127.0.0.1` ou `::1`. |80| HTTPS | O gateway deve ser acessível via `https://` de laptops de desenvolvedores e de qualquer navegador usado para sign-in; o gateway serve a página de verificação do dispositivo no mesmo listener. Forneça um certificado TLS via `listen.tls` ou execute atrás de um ingress que termina TLS e defina `listen.public_url` para a origem externa em ambos os casos. Em `/login`, Claude Code aceita uma origem `http://` simples apenas quando o host do gateway é loopback: `localhost`, `127.0.0.1` ou `::1`. |

81| Endereço de rede privada | Em `/login`, Claude Code requer que o nome de host ou endereço IP do gateway resolva apenas para endereços privados: RFC 1918, link-local, CGNAT `100.64.0.0/10`, ULA IPv6 `fc00::/7` ou loopback. Para um gateway que você hospeda, qualquer endereço público fora de um bloco que você declara é rejeitado; consulte o [modelo de ameaça](/docs/pt/claude-apps-gateway-deploy#threat-model-summary) no guia de implantação. Se máquinas de desenvolvedores rotear HTTPS através de um proxy corporativo, o sign-in também requer que o host proxy resolva para endereços privados; se não resolver, adicione o host do gateway a `NO_PROXY` para que a CLI se conecte diretamente. Se sua rede interna for numerada a partir do espaço IPv4 público que sua organização possui, [declare esses blocos](#allow-a-gateway-on-public-address-space-you-own) para que `/login` aceite um gateway lá. |81| Endereço de rede privada | Em `/login`, Claude Code requer que o nome de host ou endereço IP do gateway resolva apenas para endereços privados: RFC 1918, link-local, CGNAT `100.64.0.0/10`, ULA IPv6 `fc00::/7` ou loopback. Para um gateway que você hospeda, qualquer endereço público fora de um bloco que você declara é rejeitado; consulte o [modelo de ameaça](/docs/pt/claude-apps-gateway-deploy#threat-model-summary) no guia de implantação. Se máquinas de desenvolvedores rotear HTTPS através de um proxy corporativo, o sign-in também requer que o host proxy resolva para endereços privados; se não resolver, adicione o host do gateway a `NO_PROXY` para que a CLI se conecte diretamente. Se sua rede interna for numerada a partir do espaço IPv4 público que sua organização possui, [declare esses blocos](#allow-a-gateway-on-public-address-space-you-own) para que `/login` aceite um gateway lá. |

82| Runtime Linux | O servidor gateway é executado apenas no binário Linux nativo. macOS funciona para desenvolvimento local. Windows não é suportado como plataforma de servidor. |82| Runtime Linux | O servidor gateway é executado apenas no binário Linux nativo. macOS funciona para desenvolvimento local. Windows não é suportado como plataforma de servidor. |

83 83

91 </Step>91 </Step>

92 92

93 <Step title="Provisione um banco de dados PostgreSQL">93 <Step title="Provisione um banco de dados PostgreSQL">

94 Qualquer Postgres 14 ou posterior funciona, incluindo o menor nível gerenciado. O gateway executa suas próprias migrações de esquema na inicialização, então o usuário do banco de dados precisa de direitos para criar e alterar tabelas; consulte [`store`](/docs/pt/claude-apps-gateway-config#store).94 Use PostgreSQL 11 ou posterior. O menor nível gerenciado é suficiente. O gateway executa suas próprias migrações de esquema na inicialização, então a função do banco de dados precisa de direitos para criar e alterar tabelas; consulte [`store`](/docs/pt/claude-apps-gateway-config#store).

95 </Step>95 </Step>

96 96

97 <Step title="Escreva gateway.yaml">97 <Step title="Escreva gateway.yaml">

132 auto_include_builtin_models: true132 auto_include_builtin_models: true

133 ```133 ```

134 134

135 Esta configuração é suficiente para um loop de sign-in funcionando com o catálogo de modelos Bedrock padrão. Uma vez em execução, adicione RBAC por grupo e configurações gerenciadas via [`managed.policies`](/docs/pt/claude-apps-gateway-config#managed), fan-out de telemetria via [`telemetry`](/docs/pt/claude-apps-gateway-config#telemetry), e failover multi-upstream, ARNs de throughput provisionado ou regiões não-US via [`models`](/docs/pt/claude-apps-gateway-config#models).135 Esta configuração é suficiente para um loop de sign-in funcionando com o catálogo de modelos Amazon Bedrock padrão. Uma vez em execução, adicione RBAC por grupo e configurações gerenciadas via [`managed.policies`](/docs/pt/claude-apps-gateway-config#managed), fan-out de telemetria via [`telemetry`](/docs/pt/claude-apps-gateway-config#telemetry), e failover multi-upstream, ARNs de throughput provisionado ou regiões não-US via [`models`](/docs/pt/claude-apps-gateway-config#models).

136 136

137 <Note>137 <Note>

138 O upstream Amazon Bedrock precisa de um principal AWS com `bedrock:InvokeModel` e `bedrock:InvokeModelWithResponseStream` nos ARNs `inference-profile/us.anthropic.*` e nos ARNs `foundation-model/anthropic.*` subjacentes. Ele também precisa do formulário de caso de uso único da Anthropic enviado para a conta a partir do catálogo de modelos do console Bedrock.138 O upstream Amazon Bedrock precisa de um principal AWS com `bedrock:InvokeModel` e `bedrock:InvokeModelWithResponseStream` nos ARNs `inference-profile/us.anthropic.*` e nos ARNs `foundation-model/anthropic.*` subjacentes. Ele também precisa do formulário de caso de uso único da Anthropic enviado para a conta a partir do catálogo de modelos do console Bedrock.

172 volumes: { pgdata: }172 volumes: { pgdata: }

173 ```173 ```

174 174

175 O gateway é um único binário Linux que lê a configuração, se conecta ao Postgres e aplica suas migrações de esquema, executa descoberta OIDC contra seu IdP, constrói clientes upstream e começa a escutar. A inicialização é fail-closed para a configuração, a conexão Postgres, descoberta OIDC e construção de cliente upstream. Se qualquer um desses for inacessível ou mal configurado, o gateway sai com um erro em vez de servir tráfego em um estado degradado.175 O gateway é um único binário Linux que lê a configuração, se conecta ao Postgres e aplica suas migrações de esquema, executa descoberta OIDC contra seu IdP, constrói clientes upstream e começa a escutar.

176 176

177 Uma inicialização bem-sucedida não valida o caminho de inferência, porque credenciais de instância Bedrock e Agent Platform resolvem na primeira solicitação, não na inicialização.177 A inicialização é fail-closed para a configuração, a conexão Postgres, descoberta OIDC e construção de cliente upstream. Se qualquer um desses for inacessível ou mal configurado, o gateway sai com um erro em vez de servir tráfego em um estado degradado.

178

179 Uma inicialização bem-sucedida não valida o caminho de inferência, porque credenciais de instância do Amazon Bedrock e da Agent Platform do Google Cloud resolvem na primeira requisição, não na inicialização.

178 180

179 Observe stderr para a sequência de inicialização. As linhas de log usam o formato `[gateway] <timestamp> <level> <message>`, eventos de auditoria são JSON de linha única com um campo `evt`, e um banner de inicialização, omitido abaixo, é impresso entre as linhas de migração e escuta. Um banco de dados novo imprime uma linha `migration N applied` por migração de esquema; um banco de dados já migrado não imprime nenhuma. Você deve ver, em ordem:181 Observe stderr para a sequência de inicialização. As linhas de log usam o formato `[gateway] <timestamp> <level> <message>`, eventos de auditoria são JSON de linha única com um campo `evt`, e um banner de inicialização, omitido abaixo, é impresso entre as linhas de migração e escuta. Um banco de dados novo imprime uma linha `migration N applied` por migração de esquema; um banco de dados já migrado não imprime nenhuma. Você deve ver, em ordem:

180 182

206 208

207 Os exemplos usam a URL pública do gateway; para a configuração local do Compose sem um ingress, substitua `http://localhost:8080` nas duas primeiras verificações. A terceira verificação abre `verification_uri_complete`, que é construída a partir de `public_url`, então para Compose local defina `public_url: http://localhost:8080` em `gateway.yaml` e adicione `http://localhost:8080/oauth/callback` como um segundo URI de redirecionamento no cliente OAuth da etapa 1, porque o gateway constrói o `redirect_uri` do IdP a partir de `public_url`. O link de verificação então abre em seu navegador local.209 Os exemplos usam a URL pública do gateway; para a configuração local do Compose sem um ingress, substitua `http://localhost:8080` nas duas primeiras verificações. A terceira verificação abre `verification_uri_complete`, que é construída a partir de `public_url`, então para Compose local defina `public_url: http://localhost:8080` em `gateway.yaml` e adicione `http://localhost:8080/oauth/callback` como um segundo URI de redirecionamento no cliente OAuth da etapa 1, porque o gateway constrói o `redirect_uri` do IdP a partir de `public_url`. O link de verificação então abre em seu navegador local.

208 210

209 No Windows PowerShell, execute `curl.exe`; o `curl` simples é um alias para `Invoke-WebRequest` e rejeita esses sinalizadores.211 No Windows PowerShell, execute `curl.exe`; o `curl` simples é um alias para `Invoke-WebRequest` e rejeita essas flags.

210 212

211 Primeiro, busque o documento de descoberta, que confirma que o gateway está ativo, a configuração é válida e todas as verificações de inicialização passaram:213 Primeiro, busque o documento de descoberta, que confirma que o gateway está ativo, a configuração é válida e todas as verificações de inicialização passaram:

212 214

claude-apps-gateway-config.md +3 −3

Details

158O gateway lê a chave e o certificado uma vez na inicialização, portanto um arquivo alterado só tem efeito após uma reinicialização. Faça a rotação nesta ordem para que nenhuma requisição de token apresente um certificado que o IdP não tenha:158O gateway lê a chave e o certificado uma vez na inicialização, portanto um arquivo alterado só tem efeito após uma reinicialização. Faça a rotação nesta ordem para que nenhuma requisição de token apresente um certificado que o IdP não tenha:

159 159

1601. Envie o novo certificado para o IdP junto com o antigo.1601. Envie o novo certificado para o IdP junto com o antigo.

1612. Substitua os arquivos de chave e certificado que o `gateway.yaml` carrega e, em seguida, reinicie o gateway.1612. Substitua os arquivos de chave e certificado que o `gateway.yaml` carrega e, em seguida, reinicie o gateway. Se você executa várias réplicas, uma [reinicialização gradual](/docs/pt/claude-apps-gateway-deploy#upgrades) funciona, porque o IdP tem ambos os certificados até que você remova o antigo.

1623. Remova o certificado antigo do IdP.1623. Depois que todas as réplicas tiverem reiniciado, remova o certificado antigo do IdP.

163 163

164<h4 id="idp-requests-through-a-forward-proxy">164<h4 id="idp-requests-through-a-forward-proxy">

165 Solicitações do IdP através de um proxy de encaminhamento165 Solicitações do IdP através de um proxy de encaminhamento

227 227

229| - | - | - |229| - | - | - |

230| `postgres_url` | Sim | URL `postgres://` ou `postgresql://`. Obrigatório: o encontro de concessão de dispositivo, onde o callback do navegador escreve e o CLI de sondagem lê, precisa de estado entre réplicas. O gateway executa suas próprias migrações de esquema na inicialização e na atualização, portanto a função precisa de direitos para criar e alterar tabelas no esquema de destino. Consulte [Atualizações](/docs/pt/claude-apps-gateway-deploy#upgrades) e [Postgres](/docs/pt/claude-apps-gateway-deploy#postgres). |230| `postgres_url` | Sim | URL `postgres://` ou `postgresql://` com um único host, não uma lista separada por vírgulas. O gateway executa suas próprias migrações de esquema na inicialização e na atualização, portanto a função precisa de direitos para criar e alterar tabelas no esquema de destino. Consulte [Atualizações](/docs/pt/claude-apps-gateway-deploy#upgrades) e [Postgres](/docs/pt/claude-apps-gateway-deploy#postgres). |

231| `username` | Não | Substitui o usuário em `postgres_url` |231| `username` | Não | Substitui o usuário em `postgres_url` |

232| `password` | Não | Credencial do banco de dados. Defina aqui em vez de em `postgres_url` para que a credencial fique fora da URL. Aceita qualquer caractere e tem precedência sobre credenciais de URL. |232| `password` | Não | Credencial do banco de dados. Defina aqui em vez de em `postgres_url` para que a credencial fique fora da URL. Aceita qualquer caractere e tem precedência sobre credenciais de URL. |

233| `max_connections` | Não | Tamanho do pool de conexão Postgres por réplica. Padrão `5`, que é conservador e amigável para bancos de dados compartilhados. Com [limites de gastos](#admin) habilitados, o caminho quente faz algumas operações por solicitação de inferência, portanto aumente para um banco de dados dedicado sob carga e mantenha réplicas × isto abaixo do `max_connections` do banco de dados. |233| `max_connections` | Não | Tamanho do pool de conexão Postgres por réplica. Padrão `5`, que é conservador e amigável para bancos de dados compartilhados. Com [limites de gastos](#admin) habilitados, o caminho quente faz algumas operações por solicitação de inferência, portanto aumente para um banco de dados dedicado sob carga e mantenha réplicas × isto abaixo do `max_connections` do banco de dados. |

claude-apps-gateway-deploy.md +7 −1

Details

249 Postgres249 Postgres

250</h3>250</h3>

251 251

252O gateway armazena seu estado em um banco de dados PostgreSQL:

253

254* **Banco de dados**: o próprio PostgreSQL, auto-hospedado ou gerenciado, na [versão mínima](/docs/pt/claude-apps-gateway#prerequisites) ou posterior. Bancos de dados que apenas implementam o protocolo Postgres, como bancos de dados SQL distribuídos, não são suportados.

255* **Endereço**: `store.postgres_url` aceita um único host. Se o banco de dados tiver vários nós, use o endereço que fica na frente deles, como o endpoint do seu serviço gerenciado, um balanceador de carga ou um IP virtual. Defina um [período de carência de prontidão](#readiness-grace-period) mais longo do que um failover leva.

256

252O gateway mantém cinco tabelas de dados mais uma tabela `_migrations`, todas criadas por suas migrações de tempo de inicialização:257O gateway mantém cinco tabelas de dados mais uma tabela `_migrations`, todas criadas por suas migrações de tempo de inicialização:

253 258

396| CLI `/login`: `Could not resolve the configured HTTP proxy` | O nome do host em `HTTPS_PROXY` ou `HTTP_PROXY` não resolve da máquina do desenvolvedor, tipicamente porque não está conectado à rede corporativa | Peça ao desenvolvedor para conectar à sua rede ou VPN e tentar novamente, ou corrija a URL do proxy |401| CLI `/login`: `Could not resolve the configured HTTP proxy` | O nome do host em `HTTPS_PROXY` ou `HTTP_PROXY` não resolve da máquina do desenvolvedor, tipicamente porque não está conectado à rede corporativa | Peça ao desenvolvedor para conectar à sua rede ou VPN e tentar novamente, ou corrija a URL do proxy |

397| CLI `/login`: `Could not resolve gateway host <host>` | A máquina não consegue resolver o nome DNS interno do gateway, tipicamente porque não está na rede corporativa | Peça ao desenvolvedor para conectar à sua rede ou VPN, depois execute `/login` novamente |402| CLI `/login`: `Could not resolve gateway host <host>` | A máquina não consegue resolver o nome DNS interno do gateway, tipicamente porque não está na rede corporativa | Peça ao desenvolvedor para conectar à sua rede ou VPN, depois execute `/login` novamente |

398| A inicialização sai com um erro de validação de configuração que nomeia `store.postgres_url` | Nenhum Postgres configurado; o gateway requer Postgres | Defina `store.postgres_url`. Para desenvolvimento local, use um container descartável: `docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres`. |403| A inicialização sai com um erro de validação de configuração que nomeia `store.postgres_url` | Nenhum Postgres configurado; o gateway requer Postgres | Defina `store.postgres_url`. Para desenvolvimento local, use um container descartável: `docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres`. |

404| A inicialização sai: `store.postgres_url in <path> is not a URL the gateway can read`, ou, antes da v2.1.290, um simples `Invalid URL` ou `URI error` | A URL não pode ser analisada, por exemplo porque lista mais de um host ou sua senha tem um `/`, `?`, `#` ou `%` não codificado | Nomeie [um host](#postgres), e mova a senha para [`store.password`](/docs/pt/claude-apps-gateway-config#store) |

399| A inicialização sai: `requires the native binary` | Executando sob Node em vez do binário nativo | Instale Claude Code com um dos [métodos de instalação autônomos](/docs/pt/setup) |405| A inicialização sai: `requires the native binary` | Executando sob Node em vez do binário nativo | Instale Claude Code com um dos [métodos de instalação autônomos](/docs/pt/setup) |

400| A inicialização sai com um erro de descoberta OIDC após `config.load` | `oidc.issuer` inacessível, ou cadeia TLS não confiável | Verifique se o emissor é acessível do pod e serve `/.well-known/openid-configuration`. Defina `ca_cert_pem` para PKI privada. Se o pod alcança o IdP apenas através de um forward proxy, defina [`oidc.use_proxy: true`](/docs/pt/claude-apps-gateway-config#idp-requests-through-a-forward-proxy); em versões anteriores a v2.1.227, dê ao pod uma rota direta para cada um dos endpoints do IdP em vez disso. Se o pod também não conseguir resolver o nome do host do IdP, ou o proxy recusar `CONNECT` para um endereço IP, veja [Proxy-only egress](/docs/pt/claude-apps-gateway-config#proxy-only-egress), que requer v2.1.277 ou posterior. |406| A inicialização sai com um erro de descoberta OIDC após `config.load` | `oidc.issuer` inacessível, ou cadeia TLS não confiável | Verifique se o emissor é acessível do pod e serve `/.well-known/openid-configuration`. Defina `ca_cert_pem` para PKI privada. Se o pod alcança o IdP apenas através de um forward proxy, defina [`oidc.use_proxy: true`](/docs/pt/claude-apps-gateway-config#idp-requests-through-a-forward-proxy); em versões anteriores a v2.1.227, dê ao pod uma rota direta para cada um dos endpoints do IdP em vez disso. Se o pod também não conseguir resolver o nome do host do IdP, ou o proxy recusar `CONNECT` para um endereço IP, veja [Proxy-only egress](/docs/pt/claude-apps-gateway-config#proxy-only-egress), que requer v2.1.277 ou posterior. |

401| A inicialização sai com um erro de permissão do Postgres | O papel do banco de dados carece de direitos DDL em seu esquema | Conceda ao papel `CREATE` no esquema do gateway para que possa criar e alterar suas tabelas na inicialização |407| A inicialização sai com um erro de permissão do Postgres | O papel do banco de dados carece de direitos DDL em seu esquema | Conceda ao papel `CREATE` no esquema do gateway para que possa criar e alterar suas tabelas na inicialização |

402| Log: `could not connect to Postgres at boot, attempt 1 of 3` | O banco de dados não estava acessível quando o gateway iniciou, por exemplo em uma instância fria cuja rede ainda está se iniciando | Se o gateway então terminar de inicializar, nenhuma ação é necessária. Quando o banco de dados não está acessível, o gateway tenta a conexão três vezes, dois segundos de intervalo, antes de sair. Se sair com `could not connect to Postgres`, verifique `store.postgres_url` e o caminho de rede para o banco de dados. Se as tentativas atingirem o timeout em vez de serem recusadas, aumente [`store.connect_timeout_seconds`](/docs/pt/claude-apps-gateway-config#store) para dar a cada uma mais tempo. |408| Log: `could not connect to Postgres at boot, attempt 1 of 3` | O banco de dados não estava acessível quando o gateway iniciou, por exemplo em uma instância fria cuja rede ainda está se iniciando | Se o gateway então terminar de inicializar, nenhuma ação é necessária. Quando o banco de dados não está acessível, o gateway tenta a conexão três vezes, dois segundos de intervalo, antes de sair. Se sair com `could not connect to Postgres`, verifique `store.postgres_url`, incluindo se ela nomeia um único host, e o caminho de rede para o banco de dados. Se as tentativas atingirem o timeout em vez de serem recusadas, aumente [`store.connect_timeout_seconds`](/docs/pt/claude-apps-gateway-config#store) para dar a cada uma mais tempo. |

403| `/oauth/callback` mostra "Sign-in could not be completed" | Domínio de email rejeitado, validação de id\_token falhou, ou `email_verified` é explicitamente `false`, que o gateway sempre rejeita sem possibilidade de sobrescrever | Verifique `allowed_email_domains` e que o IdP retorna uma reivindicação `email` verificada. Para `email_verified: false`, corrija a verificação do lado do IdP. Se seu IdP emite email sob um nome de reivindicação diferente, defina `oidc.email_claim`. |409| `/oauth/callback` mostra "Sign-in could not be completed" | Domínio de email rejeitado, validação de id\_token falhou, ou `email_verified` é explicitamente `false`, que o gateway sempre rejeita sem possibilidade de sobrescrever | Verifique `allowed_email_domains` e que o IdP retorna uma reivindicação `email` verificada. Para `email_verified: false`, corrija a verificação do lado do IdP. Se seu IdP emite email sob um nome de reivindicação diferente, defina `oidc.email_claim`. |

404| Log: `token exchange failed request_id=<id>: id_token missing email claim` | O IdP não está incluindo `email` no id\_token por padrão. Essa rejeição dispara apenas quando `allowed_email_domains` está definido; sem ele, um email ausente cria uma sessão sem email | Configure o IdP para emitir `email` no id\_token. Okta: adicione `email` às reivindicações de token de ID de um servidor de autorização personalizado. Entra: adicione `email` como uma reivindicação opcional no registro do aplicativo. PingFederate: ative uma Política OpenID Connect que emita `email`. Se o IdP serve `email` do endpoint userinfo mas não o incluirá no id\_token, como o servidor de autorização da organização Okta, defina `oidc.userinfo_fallback: true`. |410| Log: `token exchange failed request_id=<id>: id_token missing email claim` | O IdP não está incluindo `email` no id\_token por padrão. Essa rejeição dispara apenas quando `allowed_email_domains` está definido; sem ele, um email ausente cria uma sessão sem email | Configure o IdP para emitir `email` no id\_token. Okta: adicione `email` às reivindicações de token de ID de um servidor de autorização personalizado. Entra: adicione `email` como uma reivindicação opcional no registro do aplicativo. PingFederate: ative uma Política OpenID Connect que emita `email`. Se o IdP serve `email` do endpoint userinfo mas não o incluirá no id\_token, como o servidor de autorização da organização Okta, defina `oidc.userinfo_fallback: true`. |

405| Log: `refresh failed request_id=<id>: invalid_token (…) (at userinfo_no_id_token, …)`, e desenvolvedores veem `Cloud gateway session expired` a cada `session.ttl_hours` | O IdP aceitou o token de atualização mas não retornou id\_token com ele, então o gateway perguntou ao endpoint userinfo do IdP pelas reivindicações do usuário. O IdP rejeitou o token de acesso atualizado lá. O gateway responde `temporarily_unavailable`, então Claude Code mantém o token de atualização mas não consegue renovar a sessão. Versões do gateway anteriores a v2.1.260 registram a mesma linha sem o detalhe `(at …)`. | Defina [`oidc.scope_on_refresh: true`](/docs/pt/claude-apps-gateway-config#oidc), disponível no gateway v2.1.260 ou posterior, para que a requisição de atualização peça por `openid` novamente. Alguns IdPs, como Okta, retornam um id\_token na atualização apenas quando solicitado. No PingFederate, ative **Return ID Token On Refresh Grant** sob **Applications > OAuth > OpenID Connect Policy Management** em vez disso. A chave não muda o comportamento do PingFederate. Para outros IdPs que ainda o omitem, verifique se o endpoint userinfo aceita tokens de acesso emitidos por uma atualização. Como uma solução temporária, aumente [`session.ttl_hours`](/docs/pt/claude-apps-gateway-config#session). Veja [Identity provider setup](#identity-provider-setup) para o tradeoff de desprovisionamento. |411| Log: `refresh failed request_id=<id>: invalid_token (…) (at userinfo_no_id_token, …)`, e desenvolvedores veem `Cloud gateway session expired` a cada `session.ttl_hours` | O IdP aceitou o token de atualização mas não retornou id\_token com ele, então o gateway perguntou ao endpoint userinfo do IdP pelas reivindicações do usuário. O IdP rejeitou o token de acesso atualizado lá. O gateway responde `temporarily_unavailable`, então Claude Code mantém o token de atualização mas não consegue renovar a sessão. Versões do gateway anteriores a v2.1.260 registram a mesma linha sem o detalhe `(at …)`. | Defina [`oidc.scope_on_refresh: true`](/docs/pt/claude-apps-gateway-config#oidc), disponível no gateway v2.1.260 ou posterior, para que a requisição de atualização peça por `openid` novamente. Alguns IdPs, como Okta, retornam um id\_token na atualização apenas quando solicitado. No PingFederate, ative **Return ID Token On Refresh Grant** sob **Applications > OAuth > OpenID Connect Policy Management** em vez disso. A chave não muda o comportamento do PingFederate. Para outros IdPs que ainda o omitem, verifique se o endpoint userinfo aceita tokens de acesso emitidos por uma atualização. Como uma solução temporária, aumente [`session.ttl_hours`](/docs/pt/claude-apps-gateway-config#session). Veja [Identity provider setup](#identity-provider-setup) para o tradeoff de desprovisionamento. |

claude-apps-gateway-on-aws.md +1 −1

Details

169 </Step>169 </Step>

170 170

171 <Step title="Provisione Amazon RDS para PostgreSQL">171 <Step title="Provisione Amazon RDS para PostgreSQL">

172 A instância é executada nas subnets privadas sem endereço público e com criptografia de armazenamento ativada. A versão do mecanismo é fixada em Postgres 16, que satisfaz o piso suportado do gateway de PostgreSQL 14 e garante que a família do grupo de parâmetros abaixo corresponda à instância.172 A instância executa o Postgres 16 nas subnets privadas, sem endereço público e com criptografia de armazenamento ativada.

173 173

174 Primeiro, crie o grupo de subnets que coloca o banco de dados nas subnets privadas e um grupo de parâmetros com `rds.force_ssl=1` para que o servidor rejeite conexões em texto simples. A versão do mecanismo é fixada uma vez porque a família do grupo de parâmetros deve corresponder à versão principal do mecanismo que a instância executa:174 Primeiro, crie o grupo de subnets que coloca o banco de dados nas subnets privadas e um grupo de parâmetros com `rds.force_ssl=1` para que o servidor rejeite conexões em texto simples. A versão do mecanismo é fixada uma vez porque a família do grupo de parâmetros deve corresponder à versão principal do mecanismo que a instância executa:

175 175

claude-code-on-the-web.md +4 −2

Details

442`claude --cloud` e `claude --teleport` requerem entrada com uma conta claude.ai. Se você autenticar com uma chave de API, ou se seus detalhes de conta armazenados estiverem obsoletos, você verá uma destas mensagens:442`claude --cloud` e `claude --teleport` requerem entrada com uma conta claude.ai. Se você autenticar com uma chave de API, ou se seus detalhes de conta armazenados estiverem obsoletos, você verá uma destas mensagens:

443 443

444* `Unable to get organization UUID`444* `Unable to get organization UUID`

445* Uma mensagem de que a autenticação com chave de API não é suficiente445* ``Cloud sessions need a claude.ai sign-in. Run `claude auth login` (or /login in a local session), then try again.``

446* `Error loading Claude Code sessions` no seletor de sessão, quando você executa `claude --teleport` sem um ID de sessão446* `Error loading Claude Code sessions` no seletor de sessão, quando você executa `claude --teleport` sem um ID de sessão

447 447

448Execute `/login` para entrar com sua conta claude.ai, depois tente novamente o comando. Se o erro nomear seu provedor em vez disso, veja a [tabela de erros](#errors-when-sending-to-a-cloud-session): as sessões na nuvem não estão disponíveis através de provedores de terceiros.448Execute [`claude auth login`](/docs/pt/cli-reference#cli-commands) no seu shell para entrar com sua conta claude.ai, depois tente novamente o comando. Dentro de uma sessão em execução, `/login` faz o mesmo. Se o erro nomear seu provedor em vez disso, veja a [tabela de erros](#errors-when-sending-to-a-cloud-session): as sessões na nuvem não estão disponíveis através de provedores de terceiros.

449

450Da v2.1.274 até a v2.1.289, a mensagem de entrada dizia `Claude Code cloud sessions require authentication with a Claude.ai account. API key authentication is not sufficient. Please run /login to authenticate, or check your authentication status with /status.`

449 451

450<h3 id="remote-control-session-expired-or-access-denied">452<h3 id="remote-control-session-expired-or-access-denied">

451 Remote Control session expired or access denied453 Remote Control session expired or access denied

cli-reference.md +2 −0

Details

31| `claude attach <id\|name>` | Anexar a uma [sessão de fundo](/docs/pt/agent-view#manage-sessions-from-the-shell) neste terminal. Passar parte do nome de uma sessão em execução no lugar do ID requer Claude Code v2.1.290 ou posterior | `claude attach 7c5dcf5d` |31| `claude attach <id\|name>` | Anexar a uma [sessão de fundo](/docs/pt/agent-view#manage-sessions-from-the-shell) neste terminal. Passar parte do nome de uma sessão em execução no lugar do ID requer Claude Code v2.1.290 ou posterior | `claude attach 7c5dcf5d` |

32| `claude auto-mode defaults` | Imprimir as regras do classificador do [modo auto](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode) integradas como JSON. Use `claude auto-mode config` para ver sua configuração efetiva com as configurações aplicadas. `--label <prefix>` imprime apenas as regras cujo rótulo começa com esse prefixo, correspondência sem distinção de maiúsculas e minúsculas. Requer Claude Code v2.1.208 ou posterior | `claude auto-mode defaults --label 'Git Destructive'` |32| `claude auto-mode defaults` | Imprimir as regras do classificador do [modo auto](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode) integradas como JSON. Use `claude auto-mode config` para ver sua configuração efetiva com as configurações aplicadas. `--label <prefix>` imprime apenas as regras cujo rótulo começa com esse prefixo, correspondência sem distinção de maiúsculas e minúsculas. Requer Claude Code v2.1.208 ou posterior | `claude auto-mode defaults --label 'Git Destructive'` |

33| `claude auto-mode reset` | Restaurar a configuração padrão do [modo auto](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode) removendo a seção `autoMode` do seu arquivo de configurações do usuário. Solicita confirmação antes de escrever; passe `-y`/`--yes` para pular o prompt. As regras de [configurações gerenciadas](/docs/pt/server-managed-settings) ou a flag `--settings` ainda se aplicam. Requer Claude Code v2.1.212 ou posterior. Veja [Inspecionar os padrões e sua configuração efetiva](/docs/pt/auto-mode-config#inspect-the-defaults-and-your-effective-config) | `claude auto-mode reset --yes` |33| `claude auto-mode reset` | Restaurar a configuração padrão do [modo auto](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode) removendo a seção `autoMode` do seu arquivo de configurações do usuário. Solicita confirmação antes de escrever; passe `-y`/`--yes` para pular o prompt. As regras de [configurações gerenciadas](/docs/pt/server-managed-settings) ou a flag `--settings` ainda se aplicam. Requer Claude Code v2.1.212 ou posterior. Veja [Inspecionar os padrões e sua configuração efetiva](/docs/pt/auto-mode-config#inspect-the-defaults-and-your-effective-config) | `claude auto-mode reset --yes` |

34| `claude daemon logs` | Acompanhar o arquivo de log do [supervisor](/docs/pt/agent-view#the-supervisor-process) de sessão de fundo, `~/.claude/daemon.log`, imprimindo novas linhas à medida que chegam até você pressionar `Ctrl+C` | `claude daemon logs` |

35| `claude daemon run` | Executar o [supervisor](/docs/pt/agent-view#the-supervisor-process) de sessão de fundo em primeiro plano neste terminal, imprimindo seu log | `claude daemon run` |

34| `claude daemon status` | Imprimir o estado do [supervisor](/docs/pt/agent-view#the-supervisor-process) de sessão de fundo, versão, diretório de socket e contagem de workers para diagnósticos. Sai com 1 se o supervisor não estiver em execução | `claude daemon status` |36| `claude daemon status` | Imprimir o estado do [supervisor](/docs/pt/agent-view#the-supervisor-process) de sessão de fundo, versão, diretório de socket e contagem de workers para diagnósticos. Sai com 1 se o supervisor não estiver em execução | `claude daemon status` |

35| `claude daemon stop --any` | Parar o [supervisor](/docs/pt/agent-view#the-supervisor-process) de sessão de fundo e as sessões que ele hospeda. Passe `--keep-workers` para deixar as sessões de fundo em execução para que o próximo supervisor se reconecte a elas. `--any` confirma a parada de um supervisor sob demanda, que é o padrão. Use isto para recuperar de um [supervisor não responsivo](/docs/pt/agent-view#agent-view-says-the-background-service-did-not-respond) | `claude daemon stop --any --keep-workers` |37| `claude daemon stop --any` | Parar o [supervisor](/docs/pt/agent-view#the-supervisor-process) de sessão de fundo e as sessões que ele hospeda. Passe `--keep-workers` para deixar as sessões de fundo em execução para que o próximo supervisor se reconecte a elas. `--any` confirma a parada de um supervisor sob demanda, que é o padrão. Use isto para recuperar de um [supervisor não responsivo](/docs/pt/agent-view#agent-view-says-the-background-service-did-not-respond) | `claude daemon stop --any --keep-workers` |

36| `claude doctor` | Imprimir diagnósticos de instalação e configurações somente leitura do terminal sem iniciar uma sessão, incluindo saúde da instalação, erros de validação de arquivo de configurações e elegibilidade de Remote Control. Para a verificação de configuração em sessão que também pode aplicar correções, execute [`/doctor`](/docs/pt/commands#all-commands) | `claude doctor` |38| `claude doctor` | Imprimir diagnósticos de instalação e configurações somente leitura do terminal sem iniciar uma sessão, incluindo saúde da instalação, erros de validação de arquivo de configurações e elegibilidade de Remote Control. Para a verificação de configuração em sessão que também pode aplicar correções, execute [`/doctor`](/docs/pt/commands#all-commands) | `claude doctor` |

desktop.md +1 −1

Details

1092Para ver qual versão do aplicativo desktop você está executando:1092Para ver qual versão do aplicativo desktop você está executando:

1093 1093

1094* **macOS**: clique em **Claude** na barra de menu, depois **About Claude**1094* **macOS**: clique em **Claude** na barra de menu, depois **About Claude**

1095* **Windows**: clique em **Help**, depois **About**1095* **Windows**: clique em **Help**, depois **About Claude**

1096 1096

1097Clique no número da versão para copiá-lo para sua área de transferência.1097Clique no número da versão para copiá-lo para sua área de transferência.

1098 1098

desktop-ios-simulator.md +1 −1

Details

92* Salvar uma captura de tela com **Cmd+S** ou uma gravação de tela com **Cmd+R**, usando os botões de captura do painel ou os atalhos de teclado; os arquivos são salvos em sua Desktop92* Salvar uma captura de tela com **Cmd+S** ou uma gravação de tela com **Cmd+R**, usando os botões de captura do painel ou os atalhos de teclado; os arquivos são salvos em sua Desktop

93* Parar de transmitir um dispositivo sem desligá-lo clicando em **Detach simulator**, que retorna o painel ao estado **Attach simulator**93* Parar de transmitir um dispositivo sem desligá-lo clicando em **Detach simulator**, que retorna o painel ao estado **Attach simulator**

94 94

95Para ajustar o streaming de vídeo do simulador, abra o menu **Display** do painel. Reduza **Frame rate** ou **Resolution** se o painel sobrecarregar seu Mac. Ambas as configurações alteram como o painel exibe o dispositivo, não como o aplicativo é executado.95Se o painel mostrar um menu **Display**, use-o para ajustar o streaming de vídeo do simulador. Reduza **Frame rate** ou **Resolution** se o painel sobrecarregar seu Mac. Ambas as configurações alteram como o painel exibe o dispositivo, não como o aplicativo é executado.

96 96

97Você e Claude controlam o mesmo dispositivo, portanto seus toques alteram o estado do aplicativo que Claude vê. Para fazer Claude verificar uma tela específica, navegue até ela tocando e depois pergunte. Enquanto Claude está controlando o dispositivo, o painel mostra um crachá **Claude is using this device** acima da tela; espere tocar até que o crachá desapareça, para que o resultado reflita o aplicativo em vez de sua entrada.97Você e Claude controlam o mesmo dispositivo, portanto seus toques alteram o estado do aplicativo que Claude vê. Para fazer Claude verificar uma tela específica, navegue até ela tocando e depois pergunte. Enquanto Claude está controlando o dispositivo, o painel mostra um crachá **Claude is using this device** acima da tela; espere tocar até que o crachá desapareça, para que o resultado reflita o aplicativo em vez de sua entrada.

98 98

env-vars.md +1 −0

Details

354| `CLAUDE_CODE_PERFORCE_MODE` | Defina como `1` para ativar a proteção de gravação compatível com o Perforce. Quando definida, Edit, Write e NotebookEdit falham com uma dica `p4 edit <file>` se o arquivo de destino não tiver o bit de gravação do proprietário, que o Perforce remove dos arquivos sincronizados até que `p4 edit` os abra. Isso impede que o Claude Code contorne o rastreamento de alterações do Perforce |354| `CLAUDE_CODE_PERFORCE_MODE` | Defina como `1` para ativar a proteção de gravação compatível com o Perforce. Quando definida, Edit, Write e NotebookEdit falham com uma dica `p4 edit <file>` se o arquivo de destino não tiver o bit de gravação do proprietário, que o Perforce remove dos arquivos sincronizados até que `p4 edit` os abra. Isso impede que o Claude Code contorne o rastreamento de alterações do Perforce |

355| `CLAUDE_CODE_PLUGIN_CACHE_DIR` | Sobrescreve o diretório raiz de plugins. Apesar do nome, isto define o diretório pai, não o cache em si: os marketplaces e o cache de plugins ficam em subdiretórios sob este caminho. O padrão é `~/.claude/plugins` |355| `CLAUDE_CODE_PLUGIN_CACHE_DIR` | Sobrescreve o diretório raiz de plugins. Apesar do nome, isto define o diretório pai, não o cache em si: os marketplaces e o cache de plugins ficam em subdiretórios sob este caminho. O padrão é `~/.claude/plugins` |

356| `CLAUDE_CODE_PLUGIN_DIRS` | Diretórios de plugins a carregar para a sessão, cada um carregado da mesma forma que uma flag [`--plugin-dir`](/docs/pt/plugins/cli-reference#flags-that-load-a-plugin-for-one-session) o carrega. Separe vários caminhos com `:` no Unix ou `;` no Windows. Informe cada caminho como um caminho absoluto ou comece-o com `~`, porque o Claude Code ignora caminhos relativos. Requer o Claude Code v2.1.280 ou posterior. Consulte [Carregar um plugin para uma sessão](/docs/pt/plugins/create#load-a-directory-or-archive-for-one-session) |356| `CLAUDE_CODE_PLUGIN_DIRS` | Diretórios de plugins a carregar para a sessão, cada um carregado da mesma forma que uma flag [`--plugin-dir`](/docs/pt/plugins/cli-reference#flags-that-load-a-plugin-for-one-session) o carrega. Separe vários caminhos com `:` no Unix ou `;` no Windows. Informe cada caminho como um caminho absoluto ou comece-o com `~`, porque o Claude Code ignora caminhos relativos. Requer o Claude Code v2.1.280 ou posterior. Consulte [Carregar um plugin para uma sessão](/docs/pt/plugins/create#load-a-directory-or-archive-for-one-session) |

357| `CLAUDE_CODE_PLUGIN_DIR_WATCH` | Controla se o Claude Code recarrega um [mod](/docs/pt/plugins/mods/overview) quando os arquivos do mod mudam. O recarregamento se aplica a um mod que você carrega de um diretório com `--plugin-dir`, e fica ativado por padrão em sessões interativas. Defina como `1` para ativá-lo também em sessões não interativas, ou `0` para desativá-lo em todas as sessões. Requer Claude Code v2.1.287 ou posterior. Consulte [configurações e variáveis de ambiente de mods](/docs/pt/plugins/mods/reference#settings-and-environment-variables) |

357| `CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS` | Timeout em milissegundos para clonar ou atualizar um marketplace de plugins (padrão: 120000). Aumente este valor para repositórios grandes ou conexões de rede lentas. Consulte [Git clone timed out](/docs/pt/plugins/troubleshooting#git-clone-timed-out-after-120s) |358| `CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS` | Timeout em milissegundos para clonar ou atualizar um marketplace de plugins (padrão: 120000). Aumente este valor para repositórios grandes ou conexões de rede lentas. Consulte [Git clone timed out](/docs/pt/plugins/troubleshooting#git-clone-timed-out-after-120s) |

358| `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE` | Defina como `1` para pular a tentativa de clonar novamente e continuar usando o checkout existente do marketplace quando uma atualização do marketplace não consegue alcançar o remoto ou autenticar-se nele. Útil em ambientes offline ou isolados, onde clonar novamente falharia da mesma forma. Consulte [Atualizações do marketplace falham em ambientes offline](/docs/pt/plugins/troubleshooting#marketplace-updates-keep-failing-offline) |359| `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE` | Defina como `1` para pular a tentativa de clonar novamente e continuar usando o checkout existente do marketplace quando uma atualização do marketplace não consegue alcançar o remoto ou autenticar-se nele. Útil em ambientes offline ou isolados, onde clonar novamente falharia da mesma forma. Consulte [Atualizações do marketplace falham em ambientes offline](/docs/pt/plugins/troubleshooting#marketplace-updates-keep-failing-offline) |

359| `CLAUDE_CODE_PLUGIN_PREFER_HTTPS` | Defina como `1` para clonar fontes na forma abreviada `owner/repo` do GitHub via HTTPS em vez de SSH. Aplica-se à instalação e atualização de plugins e a `/plugin marketplace add` e `update`. Útil em runners de CI, contêineres ou qualquer ambiente sem uma chave SSH configurada para `github.com` |360| `CLAUDE_CODE_PLUGIN_PREFER_HTTPS` | Defina como `1` para clonar fontes na forma abreviada `owner/repo` do GitHub via HTTPS em vez de SSH. Aplica-se à instalação e atualização de plugins e a `/plugin marketplace add` e `update`. Útil em runners de CI, contêineres ou qualquer ambiente sem uma chave SSH configurada para `github.com` |

errors.md +1 −0

Details

197| `Cloud sessions cannot be created from a --restricted session` | [Command-line errors](#cloud-sessions-cannot-be-created-from-a-restricted-session) |197| `Cloud sessions cannot be created from a --restricted session` | [Command-line errors](#cloud-sessions-cannot-be-created-from-a-restricted-session) |

198| `Cloud sessions are disabled by your organization's policy` | [Command-line errors](#cloud-sessions-are-disabled-by-your-organizations-policy) |198| `Cloud sessions are disabled by your organization's policy` | [Command-line errors](#cloud-sessions-are-disabled-by-your-organizations-policy) |

199| `Couldn't verify your organization's policy for cloud sessions` | [Command-line errors](#cloud-sessions-are-disabled-by-your-organizations-policy) |199| `Couldn't verify your organization's policy for cloud sessions` | [Command-line errors](#cloud-sessions-are-disabled-by-your-organizations-policy) |

200| `Cloud sessions need a claude.ai sign-in` | [Unable to get organization UUID](/docs/pt/claude-code-on-the-web#unable-to-get-organization-uuid) |

200| `Error: --json-schema is not a valid JSON Schema` | [Command-line errors](#the-json-schema-value-is-not-a-valid-json-schema) |201| `Error: --json-schema is not a valid JSON Schema` | [Command-line errors](#the-json-schema-value-is-not-a-valid-json-schema) |

202| `Error: --agents takes a JSON object, or a file path only with --print (-p)` | [Command-line errors](#invalid-agents-configuration) |203| `Error: --agents takes a JSON object, or a file path only with --print (-p)` | [Command-line errors](#invalid-agents-configuration) |

plugins/components.md +1 −1

Details

733You are a security reviewer. Read the changed files and report injection, authentication, and secrets-handling risks.733You are a security reviewer. Read the changed files and report injection, authentication, and secrets-handling risks.

734```734```

735 735

736Este agente é nomeado `my-plugin:security-reviewer`, e o usuário pode [invocá-lo explicitamente](/docs/pt/sub-agents#invoke-subagents-explicitly) com `@agent-my-plugin:security-reviewer`. A forma do nome é `<plugin>:<name>`, onde `<name>` vem do frontmatter, ou do nome do arquivo quando não há.736Este agente é nomeado `my-plugin:security-reviewer`, e o usuário pode [invocá-lo explicitamente](/docs/pt/sub-agents#invoke-subagents-explicitly) com `@agent-my-plugin:security-reviewer`. A forma do nome é `<plugin>:<name>`, onde `<name>` vem do campo `name` do frontmatter, ou do nome do arquivo quando esse campo está ausente.

737 737

738A chave `agents` substitui a varredura `agents/`.738A chave `agents` substitui a varredura `agents/`.

739 739

plugins/mods/interface.md +5 −3

Details

428 428

430| :- | :- | :- |430| :- | :- | :- |

431| `Box` | Um contêiner flex. Leva propriedades de layout como `flexDirection`, `columnGap`, `padding`, `borderStyle` e `width`. | Em todos os lugares |431| `Box` | Um contêiner flex. Leva props de layout como `flexDirection`, `columnGap`, `padding`, [`borderStyle`](/docs/pt/plugins/mods/reference#box-border-styles) e `width`. | Em todos os lugares |

432| `Text` | Texto estilizado. Leva `color`, `bold`, `dimColor`, `italic` e `wrap`. Uma `color` é uma chave de tema ou uma cor como `'red'`. Um `wrap` é `'wrap'`, `'truncate'`, `'truncate-start'`, `'truncate-middle'` ou `'truncate-end'`. | Em todos os lugares |432| `Text` | Texto estilizado. Leva `color`, `bold`, `dimColor`, `italic` e `wrap`. Uma `color` é uma chave de tema ou uma cor como `'red'`. Um `wrap` é `'wrap'`, `'truncate'`, `'truncate-start'`, `'truncate-middle'` ou `'truncate-end'`. | Em todos os lugares |

434| `Link`, `Code`, `Markdown` | Um link com `href` e um `label` opcional, um bloco de código e texto formatado da forma que as respostas do Claude são. `Markdown` leva seu conteúdo em uma propriedade `text`, não em `children`, e precisa de uma `key` quando você passa `onLinkPress`. | Em todos os lugares |434| `Link`, `Code`, `Markdown` | Um link com `href` e um `label` opcional, um bloco de código e texto formatado da forma que as respostas do Claude são. `Markdown` leva seu conteúdo em uma propriedade `text`, não em `children`, e precisa de uma `key` quando você passa `onLinkPress`. | Em todos os lugares |

563Muitos painéis são um campo de texto com uma lista sob ele. O exemplo nesta seção é um painel de notas: você digita uma nota e pressiona Enter para adicioná-la, e cada nota tem um botão `x` que a deleta. Com duas notas adicionadas, o terminal desenha o painel desta forma:563Muitos painéis são um campo de texto com uma lista sob ele. O exemplo nesta seção é um painel de notas: você digita uma nota e pressiona Enter para adicioná-la, e cada nota tem um botão `x` que a deleta. Com duas notas adicionadas, o terminal desenha o painel desta forma:

564 564

565```text theme={null}565```text theme={null}

566╭──────────────────────────────────────────────────────────╮566╭────────────────────────────────────────────────────────✕─╮

567│ Note: Type a note and press Enter ⏎ add ✕ │567│ Note: Type a note and press Enter ⏎ add │

568│ x buy milk │568│ x buy milk │

569│ x call bob │569│ x call bob │

570╰──────────────────────────────────────────────────────────╯570╰──────────────────────────────────────────────────────────╯

571```571```

572 572

573O `✕` na borda superior é a marca própria do Claude Code para fechar o painel.

574

573O exemplo usa estas técnicas:575O exemplo usa estas técnicas:

574 576

575* **Tomar entrada digitada**: um `Input` chama `onSubmit(value)` com o texto do campo quando o usuário pressiona Enter, e `onInput(value)` em cada mudança577* **Tomar entrada digitada**: um `Input` chama `onSubmit(value)` com o texto do campo quando o usuário pressiona Enter, e `onInput(value)` em cada mudança

plugins/mods/reference.md +23 −2

Details

242Para ajustar uma árvore ao seu ponto, leia estas props no hook:242Para ajustar uma árvore ao seu ponto, leia estas props no hook:

243 243

244* **Largura de um `Pane` ou da faixa**: desenhe até `e.props.bodyColumns`244* **Largura de um `Pane` ou da faixa**: desenhe até `e.props.bodyColumns`

245* **Altura de um `Pane` ao lado da transcrição**: quando `e.props.placement` é `'dock'`, `e.props.scroll.bodyRows` é o número de linhas que o painel tem245* **Altura de um `Pane` ao lado da transcrição**: quando `e.props.placement` é `'dock'`, `e.props.scroll.bodyRows` é o número de linhas que o painel tem para a sua árvore

246* **Altura de um `Pane` acima do prompt**: quando `e.props.placement` é `'inline'`, o painel cresce com a sua árvore até um limite, e `bodyRows` é esse limite. O [campo `rows` de `$.ui.open`](/docs/pt/plugins/mods/interface#open-a-pane-at-the-right-time) solicita um limite diferente.246* **Altura de um `Pane` acima do prompt**: quando `e.props.placement` é `'inline'`, o painel cresce com a sua árvore até um limite, e `bodyRows` é esse limite. O [campo `rows` de `$.ui.open`](/docs/pt/plugins/mods/interface#open-a-pane-at-the-right-time) solicita um limite diferente.

247 247

248Uma árvore mais alta que o painel rola como um todo.248Uma árvore mais alta que o painel rola como um todo.

255 255

257| :- | :- | :-: | :-: |257| :- | :- | :-: | :-: |

258| [`Box`](/docs/pt/plugins/mods/interface#build-a-tree-from-elements) | `key`, layout flex, `gap`, `padding`, `margin`, `width`, `height`, `borderStyle`, `backgroundColor`, `position`, `hover` | ✓ | ✓ |258| [`Box`](/docs/pt/plugins/mods/interface#build-a-tree-from-elements) | `key`, layout flex, `gap`, `padding`, `margin`, `width`, `height`, [`borderStyle`](#box-border-styles), `backgroundColor`, `position`, `hover` | ✓ | ✓ |

259| [`Text`](/docs/pt/plugins/mods/interface#build-a-tree-from-elements) | `color`, `backgroundColor`, `bold`, `italic`, `underline`, `dimColor`, `inverse`, `wrap` | ✓ | ✓ |259| [`Text`](/docs/pt/plugins/mods/interface#build-a-tree-from-elements) | `color`, `backgroundColor`, `bold`, `italic`, `underline`, `dimColor`, `inverse`, `wrap` | ✓ | ✓ |

260| [`Button`](/docs/pt/plugins/mods/interface#respond-to-presses-and-typing) | `key`, `label`, `onPress`, `hotkey`, `plain`, `dimColor`, `autoFocus`, `action` | ✓ | ✓ |260| [`Button`](/docs/pt/plugins/mods/interface#respond-to-presses-and-typing) | `key`, `label`, `onPress`, `hotkey`, `plain`, `dimColor`, `autoFocus`, `action` | ✓ | ✓ |

261| `Link` | `href`, `label` | ✓ | ✓ |261| `Link` | `href`, `label` | ✓ | ✓ |

270 270

271Mais regras de `Button`: `action` indica uma das próprias [ações de atalho de teclado](/docs/pt/keybindings) do Claude Code, e o atalho do usuário para ela pressiona o botão quando esse atalho é um acorde ou uma tecla com modificador. Um `hotkey` numérico em um botão na faixa também é acionado quando o usuário digita apenas esse dígito em um prompt vazio e faz uma pausa. Quando dois botões em um mesmo desenho indicam o mesmo `hotkey`, o posterior fica com ele. `autoFocus` aceita apenas `true` em qualquer controle, então omita a prop para deixá-lo desativado.271Mais regras de `Button`: `action` indica uma das próprias [ações de atalho de teclado](/docs/pt/keybindings) do Claude Code, e o atalho do usuário para ela pressiona o botão quando esse atalho é um acorde ou uma tecla com modificador. Um `hotkey` numérico em um botão na faixa também é acionado quando o usuário digita apenas esse dígito em um prompt vazio e faz uma pausa. Quando dois botões em um mesmo desenho indicam o mesmo `hotkey`, o posterior fica com ele. `autoFocus` aceita apenas `true` em qualquer controle, então omita a prop para deixá-lo desativado.

272 272

273<h3 id="box-border-styles">

274 Estilos de borda de `Box`

275</h3>

276

277Para desenhar uma borda ao redor de um `Box`, defina seu `borderStyle` como um destes nomes, como em `borderStyle: 'round'`. Cada linha informa o que o terminal desenha para esse nome e mostra a borda superior.

278

279| `borderStyle` | O que o terminal desenha | Borda superior |

280| :- | :- | :- |

281| `'single'` | Linhas finas com cantos retos | `┌──┐` |

282| `'double'` | Linhas duplas | `╔══╗` |

283| `'round'` | Linhas finas com cantos arredondados | `╭──╮` |

284| `'bold'` | Linhas grossas | `┏━━┓` |

285| `'singleDouble'` | Linhas finas em cima e embaixo, linhas duplas nas laterais | `╓──╖` |

286| `'doubleSingle'` | Linhas duplas em cima e embaixo, linhas finas nas laterais | `╒══╕` |

287| `'classic'` | Os caracteres ASCII `+`, `-` e `\|` | `+--+` |

288| `'arrow'` | Setas que apontam para dentro do `Box` | `↘↓↓↙` |

289| `'dashed'` | Linhas tracejadas com cantos em branco | `╌╌` |

290| `'quote'` | Uma barra, `▎`, no lado esquerdo e células em branco nos outros três lados | Em branco |

291

292Um `Box` cujo `borderStyle` indica qualquer outro nome, como `'rounded'`, é desenhado sem borda.

293

273<h2 id="limits">294<h2 id="limits">

274 Limites295 Limites

275</h2>296</h2>

plugins/troubleshooting.md +2 −1

Details

16 Estes casos são cobertos em outras páginas:16 Estes casos são cobertos em outras páginas:

17 17

18 * **Por que escopos, o cache e precedência se comportam da maneira que fazem**: leia [Plugin loading reference](/docs/pt/plugins/loading)18 * **Por que escopos, o cache e precedência se comportam da maneira que fazem**: leia [Plugin loading reference](/docs/pt/plugins/loading)

19 * **Procurando por um sinalizador, campo ou comando**: use a [plugin commands reference](/docs/pt/plugins/cli-reference), a [manifest reference](/docs/pt/plugins/manifest-reference), ou a [marketplace reference](/docs/pt/plugins/marketplace-reference)19 * **Procurando por uma flag, campo ou comando**: use a [plugin commands reference](/docs/pt/plugins/cli-reference), a [manifest reference](/docs/pt/plugins/manifest-reference), ou a [marketplace reference](/docs/pt/plugins/marketplace-reference)

20 * **Uma mensagem `hooks module not loaded` ou `hooks module did not load`**: o plugin é um [mod](/docs/pt/plugins/mods/overview), então leia [The mod doesn't load](/docs/pt/plugins/mods/troubleshoot#the-mod-doesn’t-load)

20</Note>21</Note>

21 22

22Procure pela mensagem exata que você viu. Cada mensagem é listada sob o estágio que a produz, o que nem sempre é o comando que você executou. Por exemplo, uma instalação pode falhar porque um marketplace está faltando, então essa mensagem está sob [Add a marketplace](#add-a-marketplace).23Procure pela mensagem exata que você viu. Cada mensagem é listada sob o estágio que a produz, o que nem sempre é o comando que você executou. Por exemplo, uma instalação pode falhar porque um marketplace está faltando, então essa mensagem está sob [Add a marketplace](#add-a-marketplace).

server-managed-settings.md +1 −1

Details

43 <Step title="Abrir o console de administração">43 <Step title="Abrir o console de administração">

44 No console claude.ai, vá para [**Organization settings > Claude Code > Managed settings**](https://claude.ai/admin-settings/claude-code).44 No console claude.ai, vá para [**Organization settings > Claude Code > Managed settings**](https://claude.ai/admin-settings/claude-code).

45 45

46 Se o link o redirecionar para uma página diferente de Organization settings em vez da página Claude Code, sua conta não tem a função necessária. Funções de Admin e outras funções que não sejam Owner não podem visualizar ou editar configurações gerenciadas, portanto, peça a um Owner ou Primary Owner em sua organização para fazer a alteração. Veja [Controle de acesso](#access-control).46 Em uma organização Team ou Enterprise, se a página informar que você não tem acesso, peça a um [Owner ou Primary Owner](#access-control) para fazer a alteração.

47 </Step>47 </Step>

48 48

49 <Step title="Definir suas configurações">49 <Step title="Definir suas configurações">

sessions.md +3 −3

Details

83* Terminal: `claude --continue`, `claude --resume <session-id>` ou `claude --resume <name>` quando o nome corresponde a uma sessão, sem `-p`. Claude Code restaura o modo de permissão em que a sessão estava, exceto nos casos da tabela. Passe `--permission-mode` ou `--dangerously-skip-permissions` para substituir o modo restaurado.83* Terminal: `claude --continue`, `claude --resume <session-id>` ou `claude --resume <name>` quando o nome corresponde a uma sessão, sem `-p`. Claude Code restaura o modo de permissão em que a sessão estava, exceto nos casos da tabela. Passe `--permission-mode` ou `--dangerously-skip-permissions` para substituir o modo restaurado.

84* Não interativo: `claude -p --resume` ou `claude -p --continue`. Claude Code inicia a execução no modo de permissão em que uma nova execução `claude -p` iniciaria, exceto que uma sessão que terminou em modo de plano retoma em modo de plano sob as [condições abaixo](#resume-in-plan-mode-with-p).84* Não interativo: `claude -p --resume` ou `claude -p --continue`. Claude Code inicia a execução no modo de permissão em que uma nova execução `claude -p` iniciaria, exceto que uma sessão que terminou em modo de plano retoma em modo de plano sob as [condições abaixo](#resume-in-plan-mode-with-p).

85* VS Code: o painel de conversa da extensão. A tabela cobre apenas uma conversa que terminou em modo de plano; para o resto, veja [retomar conversas passadas](/docs/pt/vs-code#resume-past-conversations).85* VS Code: o painel de conversa da extensão. A tabela cobre apenas uma conversa que terminou em modo de plano; para o resto, veja [retomar conversas passadas](/docs/pt/vs-code#resume-past-conversations).

86* Seletor de sessão no lançamento: uma sessão que você seleciona do [seletor de sessão](#use-the-session-picker), se você o abriu com `claude --resume` sozinho, `claude --from-pr` ou um nome que corresponde a mais de uma sessão. Claude Code não restaura o modo de permissão armazenado. Ele inicia a sessão no modo de permissão em que iniciaria uma nova sessão a partir da mesma linha de comando.86* Seletor de sessão no lançamento: uma sessão que você seleciona do [seletor de sessão](#use-the-session-picker), se você o abriu com `claude --resume` sozinho, `claude --from-pr` ou um nome que corresponde a mais de uma sessão. Claude Code inicia a sessão no modo de permissão em que iniciaria uma nova sessão a partir da mesma linha de comando, exceto que uma sessão que terminou em modo de planejamento retoma em modo de planejamento, a menos que você passe `--permission-mode`, `--dangerously-skip-permissions` ou `--fork-session`. Nenhum outro modo de permissão armazenado é restaurado.

87* `/resume` dentro de uma sessão, com ou sem um argumento: Claude Code não restaura o modo de permissão armazenado. A conversa para a qual você alterna continua no modo de permissão em que sua sessão atual está.87* `/resume` dentro de uma sessão, com ou sem um argumento: a conversa para a qual você alterna continua no modo de permissão em que sua sessão atual está, exceto que uma conversa que terminou em modo de planejamento retoma em modo de planejamento, mesmo que você tenha iniciado Claude Code com `--permission-mode` ou `--dangerously-skip-permissions`. Se essa conversa já estava aberta anteriormente nesta execução de Claude Code, como a conversa em que você começou ou uma que você deixou com `/clear` ou `/resume`, ela continua no seu modo de permissão atual em vez disso.

88 88

89Restaurar modo de plano nos caminhos não interativo e VS Code requer Claude Code v2.1.246 ou posterior. Cada linha nomeia o modo de permissão em que a sessão terminou, qual dos caminhos terminal, não interativo e VS Code você a retoma, e o modo de permissão em que Claude Code inicia a sessão retomada.89Restaurar modo de plano nos caminhos não interativo e VS Code requer Claude Code v2.1.246 ou posterior. Cada linha nomeia o modo de permissão em que a sessão terminou, qual dos caminhos terminal, não interativo e VS Code você a retoma, e o modo de permissão em que Claude Code inicia a sessão retomada.

90 90

92| :- | :- | :- |92| :- | :- | :- |

93| `bypassPermissions` | Terminal | O modo de permissão em que uma nova sessão iniciaria. Para [ignorar permissões](/docs/pt/permission-modes#skip-all-checks-with-bypasspermissions-mode) novamente, ative-o no lançamento com uma de suas flags de lançamento ou `permissions.defaultMode: "bypassPermissions"` em [configurações de usuário, `--settings` ou gerenciadas](/docs/pt/settings-reference#permissions-defaultmode) |93| `bypassPermissions` | Terminal | O modo de permissão em que uma nova sessão iniciaria. Para [ignorar permissões](/docs/pt/permission-modes#skip-all-checks-with-bypasspermissions-mode) novamente, ative-o no lançamento com uma de suas flags de lançamento ou `permissions.defaultMode: "bypassPermissions"` em [configurações de usuário, `--settings` ou gerenciadas](/docs/pt/settings-reference#permissions-defaultmode) |

96| Manual | Terminal | Manual quando uma nova sessão iniciaria em modo auto a partir do [padrão integrado](/docs/pt/permission-modes#which-mode-a-session-starts-in). Quando um `defaultMode` de um arquivo de configurações [entra em vigor](/docs/pt/permission-modes#which-mode-a-session-starts-in), Claude Code inicia a sessão retomada nesse modo |96| Manual | Terminal | Manual quando uma nova sessão iniciaria em modo auto a partir do [padrão integrado](/docs/pt/permission-modes#which-mode-a-session-starts-in). Quando um `defaultMode` de um arquivo de configurações [entra em vigor](/docs/pt/permission-modes#which-mode-a-session-starts-in), Claude Code inicia a sessão retomada nesse modo |

sub-agents.md +2 −2

Details

310 310

312| :- | :- | :- |312| :- | :- | :- |

313| `name` | Sim | Identificador único, como `code-reviewer` ou `reviewer-v2`. Os [hooks](/docs/pt/hooks#subagentstart) recebem esse valor como `agent_type`. O nome do arquivo não precisa corresponder. Os nomes não podem conter `:`, que é reservado para [identificadores com escopo de plugin](/docs/pt/plugins/overview) como `my-plugin:reviewer`. O Claude Code não carrega um arquivo cujo nome contenha esse caractere e registra um erro no log de depuração. Antes da v2.1.218, esses nomes eram aceitos |313| `name` | Sim | Identificador único de no máximo 256 caracteres, como `code-reviewer` ou `reviewer-v2`. Os [hooks](/docs/pt/hooks#subagentstart) recebem esse valor como `agent_type`. O nome do arquivo não precisa corresponder. Os nomes não podem conter `:`, que é reservado para [identificadores com escopo de plugin](/docs/pt/plugins/overview) como `my-plugin:reviewer` |

314| `description` | Sim | Quando o Claude deve delegar a este subagente |314| `description` | Sim | Quando o Claude deve delegar a este subagente |

315| `tools` | Não | [Ferramentas](#available-tools) que o subagente pode usar, como uma string separada por vírgulas, como `Read, Grep, Bash`, ou uma lista YAML. Herda todas as ferramentas disponíveis para subagentes se omitido. Se nenhuma entrada da lista resolver para uma ferramenta, o subagente geralmente [falha ao iniciar](/docs/pt/errors#agent-would-be-spawned-with-zero-tools) com um erro que nomeia as entradas. Para pré-carregar Skills no contexto, use o campo `skills` em vez de listar `Skill` aqui |315| `tools` | Não | [Ferramentas](#available-tools) que o subagente pode usar, como uma string separada por vírgulas, como `Read, Grep, Bash`, ou uma lista YAML. Herda todas as ferramentas disponíveis para subagentes se omitido. Se nenhuma entrada da lista resolver para uma ferramenta, o subagente geralmente [falha ao iniciar](/docs/pt/errors#agent-would-be-spawned-with-zero-tools) com um erro que nomeia as entradas. Para pré-carregar Skills no contexto, use o campo `skills` em vez de listar `Skill` aqui |

316| `disallowedTools` | Não | Ferramentas a negar, removidas da lista herdada ou especificada. Mesmo formato de `tools`. Uma entrada com especificador, como `Bash(git push *)`, ainda [remove a ferramenta inteira](#available-tools) |316| `disallowedTools` | Não | Ferramentas a negar, removidas da lista herdada ou especificada. Mesmo formato de `tools`. Uma entrada com especificador, como `Bash(git push *)`, ainda [remove a ferramenta inteira](#available-tools) |

348 348

349* **Sem `name`**: o Claude Code trata o arquivo como documentação mantida ao lado dos seus agentes.349* **Sem `name`**: o Claude Code trata o arquivo como documentação mantida ao lado dos seus agentes.

350* **Um `---` de abertura que não está na primeira linha do arquivo**: o Claude Code lê o arquivo como se não tivesse frontmatter e o trata como documentação.350* **Um `---` de abertura que não está na primeira linha do arquivo**: o Claude Code lê o arquivo como se não tivesse frontmatter e o trata como documentação.

351* **Um `name` que começa com `-` ou contém `:`**: o Claude Code ignora o arquivo e grava um erro no log de depuração. Consulte a linha `name` na tabela acima.351* **Um `name` que começa com `-`, contém `:` ou tem mais de 256 caracteres**: o Claude Code ignora o arquivo e grava um erro no log de depuração.

352* **Um `name` mas sem `description`**: o Claude Code ignora o arquivo e grava o motivo no log de depuração.352* **Um `name` mas sem `description`**: o Claude Code ignora o arquivo e grava o motivo no log de depuração.

353* **YAML que não pode ser analisado**: o Claude Code não lê nenhum campo do arquivo, ignora-o e grava o erro de análise no log de depuração.353* **YAML que não pode ser analisado**: o Claude Code não lê nenhum campo do arquivo, ignora-o e grava o erro de análise no log de depuração.

354 354

vs-code.md +1 −1

Details

606| `environmentVariables` | `[]` | Definir variáveis de ambiente para o processo Claude. Use as configurações do Claude Code em vez disso para configuração compartilhada. Uma entrada [`CLAUDE_CONFIG_DIR`](/docs/pt/env-vars) se aplica apenas quando seu valor é um caminho absoluto; a extensão não expande `~` e ignora um valor relativo. |606| `environmentVariables` | `[]` | Definir variáveis de ambiente para o processo Claude. Use as configurações do Claude Code em vez disso para configuração compartilhada. Uma entrada [`CLAUDE_CONFIG_DIR`](/docs/pt/env-vars) se aplica apenas quando seu valor é um caminho absoluto; a extensão não expande `~` e ignora um valor relativo. |

609| `claudeProcessWrapper` | - | Executável usado para iniciar o processo Claude. O caminho do binário agrupado é passado como um argumento quando presente. Defina isso para um binário `claude` instalado separadamente se a compilação da extensão não incluir um para sua plataforma. Em uma configuração encapsulada, as conversas começam no modo Manual a menos que você defina `initialPermissionMode` ou tenha escolhido Manual, Edit automatically ou Auto em uma conversa anterior, porque a extensão pula as configurações e as etapas padrão integradas lá; veja [Switch permission modes](/docs/pt/permission-modes#switch-permission-modes). Um erro "Unsupported platform" na ativação significa que nenhum binário está agrupado para sua plataforma; veja [which platforms have prebuilt binaries](/docs/pt/troubleshoot-install#native-binary-not-found-after-npm-install). |609| `claudeProcessWrapper` | - | Executável usado para iniciar o processo Claude. O caminho do binário agrupado é passado como um argumento quando presente. Defina isso para um binário `claude` instalado separadamente se o build da extensão não incluir um para sua plataforma. |

610 610

611<h2 id="use-a-screen-reader">611<h2 id="use-a-screen-reader">

612 Use a screen reader612 Use a screen reader

Documentation 2026-10-06 23:59 UTC to 2026-10-07 05:58 UTC