Documentation — Spybara

agent-sdk/agent-loop.md +7 −1

Details

217| :- | :- | :- |217| :- | :- | :- |

220 220

221Quando qualquer um dos limites é atingido, o SDK retorna uma `ResultMessage` com um subtipo de erro correspondente (`error_max_turns` ou `error_max_budget_usd`). Veja [Handle the result](#handle-the-result) para saber como verificar esses subtipos e [`ClaudeAgentOptions`](/docs/pt/agent-sdk/python#claudeagentoptions) / [`Options`](/docs/pt/agent-sdk/typescript#options) para sintaxe.221Quando qualquer um dos limites é atingido, o SDK retorna uma `ResultMessage` com um subtipo de erro correspondente (`error_max_turns` ou `error_max_budget_usd`). Veja [Handle the result](#handle-the-result) para saber como verificar esses subtipos e [`ClaudeAgentOptions`](/docs/pt/agent-sdk/python#claudeagentoptions) / [`Options`](/docs/pt/agent-sdk/typescript#options) para sintaxe.

222 222

224 224

225Com [streaming input](/docs/pt/agent-sdk/streaming-vs-single-mode), uma mensagem que ainda está na fila quando uma volta termina no limite de max-turns permanece na fila. Claude Code não a adiciona à última chamada de modelo dessa volta. Ele inicia uma nova volta para a mensagem, e a contagem de max-turns recomeça para essa volta. O total de orçamento continua acumulando entre mensagens, e uma vez que o gasto atinge `maxBudgetUsd`, mensagens posteriores na mesma conversa terminam com o resultado `error_max_budget_usd`. Um [`/clear`](/docs/pt/agent-sdk/cost-tracking) reinicia o orçamento.225Com [streaming input](/docs/pt/agent-sdk/streaming-vs-single-mode), uma mensagem que ainda está na fila quando uma volta termina no limite de max-turns permanece na fila. Claude Code não a adiciona à última chamada de modelo dessa volta. Ele inicia uma nova volta para a mensagem, e a contagem de max-turns recomeça para essa volta. O total de orçamento continua acumulando entre mensagens, e uma vez que o gasto atinge `maxBudgetUsd`, mensagens posteriores na mesma conversa terminam com o resultado `error_max_budget_usd`. Um [`/clear`](/docs/pt/agent-sdk/cost-tracking) reinicia o orçamento.

226 226

227<h4 id="budget-headroom">

228 Margem de orçamento

229</h4>

230

231Claude Code compara o gasto com o limite `max_budget_usd` / `maxBudgetUsd` depois que as respostas do modelo chegam, porque o custo de cada resposta vem do uso de tokens que a API retorna com ela. A resposta que atinge o limite ainda é concluída e conta para [`total_cost_usd`](/docs/pt/agent-sdk/cost-tracking#get-the-total-cost-of-a-query). Portanto, o gasto pode ultrapassar o limite em até o custo dessa única resposta, mais o que os subagentes ainda em execução naquele momento gastarem antes de parar. Deixe margem para isso ao definir o limite.

232

227<h3 id="effort-level">233<h3 id="effort-level">

228 Nível de esforço234 Nível de esforço

229</h3>235</h3>

agent-sdk/permissions.md +1 −1

Details

146| `auto` | Aprovações classificadas pelo modelo | Um classificador de modelo revisa ações como comandos shell e solicitações de rede, permitindo ou bloqueando cada uma que revisa. Consulte [Modo Auto](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode) para disponibilidade e a ordem de decisão |146| `auto` | Aprovações classificadas pelo modelo | Um classificador de modelo revisa ações como comandos shell e solicitações de rede, permitindo ou bloqueando cada uma que revisa. Consulte [Modo Auto](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode) para disponibilidade e a ordem de decisão |

147 147

148<Warning>148<Warning>

149 **Herança de subagente:** Um subagente é executado no modo de permissão da sessão pai, a menos que você defina `permissionMode` em sua [`AgentDefinition`](/docs/pt/agent-sdk/typescript#agentdefinition) e a sessão pai esteja em modo `default`, `dontAsk` ou `plan`. Mesmo assim, Claude Code nunca aplica um valor `"bypassPermissions"`. Um subagente é executado em modo `bypassPermissions` apenas quando a sessão pai também está. A exceção `bypassPermissions` requer Claude Code v2.1.267 ou posterior.149 **Herança de subagente:** Um subagente é executado no modo de permissão da sessão pai, a menos que você defina `permissionMode` em sua [`AgentDefinition`](/docs/pt/agent-sdk/typescript#agentdefinition) e a sessão pai esteja em modo `default`, `dontAsk` ou `plan`. Mesmo assim, Claude Code nunca aplica um valor `"bypassPermissions"` e aplica um valor `"auto"` somente quando o [modo auto está disponível](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode) para esse subagente. Um subagente é executado em modo `bypassPermissions` apenas quando a sessão pai também está. A exceção `bypassPermissions` requer Claude Code v2.1.267 ou posterior.

150 150

151 Subagentes podem ter prompts de sistema diferentes e comportamento menos restrito do que seu agente principal, portanto herdar `bypassPermissions` concede a eles acesso completo e autônomo ao sistema. As [ações que nenhum modo aprova automaticamente](/docs/pt/permission-modes#actions-no-mode-auto-approves) ainda se aplicam.151 Subagentes podem ter prompts de sistema diferentes e comportamento menos restrito do que seu agente principal, portanto herdar `bypassPermissions` concede a eles acesso completo e autônomo ao sistema. As [ações que nenhum modo aprova automaticamente](/docs/pt/permission-modes#actions-no-mode-auto-approves) ainda se aplicam.

152</Warning>152</Warning>

agent-sdk/python.md +5 −2

Details

931| `max_budget_usd` | `float \| None` | `None` | Parar a consulta quando a estimativa de custo do lado do cliente atingir 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, veja [Rastrear custo e uso](/docs/pt/agent-sdk/cost-tracking) |931| `max_budget_usd` | `float \| None` | `None` | Parar a consulta quando a estimativa de custo do lado do cliente atingir este valor em USD. A estimativa pode ultrapassar este valor, então [deixe uma margem](/docs/pt/agent-sdk/agent-loop#budget-headroom). 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, veja [Rastrear custo e uso](/docs/pt/agent-sdk/cost-tracking) |

932| `disallowed_tools` | `list[str]` | `[]` | 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) |932| `disallowed_tools` | `list[str]` | `[]` | 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) |

987```987```

988 988

989* `API_TIMEOUT_MS`: timeout por requisição no cliente Anthropic, em milissegundos. Padrão `600000`. Aplica-se ao loop principal e todos os subagentes.989* `API_TIMEOUT_MS`: timeout por requisição no cliente Anthropic, em milissegundos. Padrão `600000`. Aplica-se ao loop principal e todos os subagentes.

990* `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 esperar por interrupções mais longas, defina [`CLAUDE_CODE_RETRY_WATCHDOG=1`](/docs/pt/errors#tune-retry-behavior): ele tenta novamente 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.990* `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`.

991

992 Para execuções sem supervisão que precisam esperar por interrupções mais longas, defina [`CLAUDE_CODE_RETRY_WATCHDOG=1`](/docs/pt/errors#tune-retry-behavior): ele tenta novamente 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.

991* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`: watchdog de travamento para subagentes. Enquanto o watchdog de stream está ativo, 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 de v2.1.257, o padrão era sempre `600000`.993* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`: watchdog de travamento para subagentes. Enquanto o watchdog de stream está ativo, 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 de v2.1.257, o padrão era sempre `600000`.

992 994

993 O temporizador é redefinido em cada evento de stream. Em um 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.995 O temporizador é redefinido em cada evento de stream. Em um 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.

3327{3329{

3328 "url": str, # A URL para buscar conteúdo3330 "url": str, # A URL para buscar conteúdo

3329 "prompt": str, # O prompt a executar no conteúdo buscado3331 "prompt": str, # O prompt a executar no conteúdo buscado

3332 "offset": int | None, # Número de caracteres a pular a partir do início da página. Requer Python Agent SDK 0.2.164 ou posterior

3330}3333}

3331```3334```

3332 3335

agent-sdk/subagents.md +9 −2

Details

323 Detectar invocação de subagente323 Detectar invocação de subagente

324</h2>324</h2>

325 325

326Claude invoca subagentes através da ferramenta Agent. Para detectar quando um subagente é invocado, procure por blocos `tool_use` onde `name` é `"Agent"`. Mensagens de dentro do contexto de um subagente incluem um campo `parent_tool_use_id`.326Claude invoca subagentes através da ferramenta Agent. Para detectar quando um subagente é invocado, procure por blocos `tool_use` onde `name` é `"Agent"`.

327

328Mensagens de dentro do contexto de um subagente incluem um campo `parent_tool_use_id`. Em TypeScript, cada mensagem de assistente e de usuário que um subagente produz também carrega [`agent_id`](/docs/pt/agent-sdk/typescript#sdkassistantmessage): o `task_id` dos [eventos de tarefa](/docs/pt/agent-sdk/typescript#sdktaskstartedmessage) desse subagente. `agent_id` requer o TypeScript Agent SDK v0.3.292 ou posterior.

327 329

328<Note>330<Note>

329 A ferramenta aparece como `"Agent"` em blocos `tool_use`, mas como `"Task"` na lista de ferramentas `system:init`. Antes do Claude Code v2.1.63, blocos `tool_use` também a nomeavam como `"Task"`. Para manter a detecção funcionando em diferentes versões do SDK, corresponda ambos os valores em `block.name`.331 A ferramenta aparece como `"Agent"` em blocos `tool_use`, mas como `"Task"` na lista de ferramentas `system:init`. Antes do Claude Code v2.1.63, blocos `tool_use` também a nomeavam como `"Task"`. Para manter a detecção funcionando em diferentes versões do SDK, corresponda ambos os valores em `block.name`.

331 333

332A estrutura da mensagem difere entre SDKs. Em Python, você acessa blocos de conteúdo diretamente via `message.content`. Em TypeScript, `SDKAssistantMessage` envolve a mensagem da API Claude, então você acessa o conteúdo via `message.message.content`.334A estrutura da mensagem difere entre SDKs. Em Python, você acessa blocos de conteúdo diretamente via `message.content`. Em TypeScript, `SDKAssistantMessage` envolve a mensagem da API Claude, então você acessa o conteúdo via `message.message.content`.

333 335

334Este exemplo itera através de mensagens transmitidas, registrando quando um subagente é invocado e quando mensagens subsequentes originam-se de dentro do contexto de execução desse subagente.336Este exemplo itera através de mensagens transmitidas, registrando quando um subagente é invocado e quando mensagens subsequentes originam-se de dentro do contexto de execução desse subagente. A versão em TypeScript também registra o `agent_id` de cada mensagem de subagente que o contém.

335 337

336<CodeGroup>338<CodeGroup>

337 ```python Python theme={null}339 ```python Python theme={null}

403 // Check if this message is from within a subagent's context405 // Check if this message is from within a subagent's context

404 if (msg.parent_tool_use_id) {406 if (msg.parent_tool_use_id) {

405 console.log(" (running inside subagent)");407 console.log(" (running inside subagent)");

408 // On assistant and user messages, agent_id matches the task_id

409 // on that subagent's task_started and other task events

410 if (msg.agent_id) {

411 console.log(` agent_id: ${msg.agent_id}`);

412 }

406 }413 }

407 414

408 if ("result" in message) {415 if ("result" in message) {

agent-sdk/typescript.md +30 −5

Details

570| `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 query falha em vez de travar. Ignorado quando `sessionStore` não está definido |570| `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 query falha em vez de travar. Ignorado quando `sessionStore` não está definido |

571| `managedSettings` | `Settings` | `undefined` | Configurações de nível de política que seu processo host fornece à sessão iniciada. 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 processo pai](/docs/pt/claude-apps-gateway#restrict-parent-settings) explica 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, em vez disso, 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 no v2.1.246 ou posterior, e sua entrada de env `ENABLE_TOOL_SEARCH` no v2.1.247 ou posterior |571| `managedSettings` | `Settings` | `undefined` | Configurações de nível de política que seu processo host fornece à sessão iniciada. 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 processo pai](/docs/pt/claude-apps-gateway#restrict-parent-settings) explica 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, em vez disso, 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 no v2.1.246 ou posterior, e sua entrada de env `ENABLE_TOOL_SEARCH` no v2.1.247 ou posterior |

572| `maxBudgetUsd` | `number` | `undefined` | Interrompe a query 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| `maxBudgetUsd` | `number` | `undefined` | Interrompe a consulta quando a estimativa de custo do lado do cliente atinge este valor em USD. A estimativa pode ultrapassar esse valor, então [deixe uma margem](/docs/pt/agent-sdk/agent-loop#budget-headroom). 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) |

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

631```631```

632 632

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

634* `CLAUDE_CODE_MAX_RETRIES`: máximo de novas tentativas na API. Padrão `10`, limitado a `15`. Cada nova tentativa tem sua própria janela de `API_TIMEOUT_MS`, então o tempo total no pior caso é aproximadamente `API_TIMEOUT_MS × (CLAUDE_CODE_MAX_RETRIES + 1)` mais o backoff. Para execuções não assistidas que precisam aguardar interrupções mais longas, defina [`CLAUDE_CODE_RETRY_WATCHDOG=1`](/docs/pt/errors#tune-retry-behavior): ele tenta novamente indefinidamente em erros transitórios de capacidade e, no Claude Code v2.1.199 ou posterior, aumenta o padrão para outros erros transitórios para `300` e remove o limite desta variável.634* `CLAUDE_CODE_MAX_RETRIES`: máximo de novas tentativas da API. Padrão `10`, limitado a `15`. Cada nova tentativa recebe sua própria janela de `API_TIMEOUT_MS`.

635

636 Para execuções autônomas que precisam aguardar interrupções mais longas, defina [`CLAUDE_CODE_RETRY_WATCHDOG=1`](/docs/pt/errors#tune-retry-behavior): isso tenta novamente de forma indefinida em erros transitórios de capacidade e, no Claude Code v2.1.199 ou posterior, eleva o padrão para outros erros transitórios para `300` e remove o limite desta variável.

635* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`: watchdog de travamento para subagentes. Enquanto o watchdog de stream está ativo, 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 do v2.1.257, o padrão era sempre `600000`.637* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`: watchdog de travamento para subagentes. Enquanto o watchdog de stream está ativo, 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 do v2.1.257, o padrão era sempre `600000`.

636 638

637 O temporizador é reiniciado a cada evento do stream. Em um travamento, o Claude Code aborta o subagente e informa o travamento ao agente pai. Para um subagente em segundo plano, ele também marca a tarefa como falha e anexa qualquer resultado parcial.639 O temporizador é reiniciado a cada evento do stream. Em um travamento, o Claude Code aborta o subagente e informa o travamento ao agente pai. Para um subagente em segundo plano, ele também marca a tarefa como falha e anexa qualquer resultado parcial.

1561 parent_tool_use_id: string | null;1563 parent_tool_use_id: string | null;

1562 error?: SDKAssistantMessageError;1564 error?: SDKAssistantMessageError;

1563 aborted?: true;1565 aborted?: true;

1566 agent_id?: string;

1564 timestamp?: string;1567 timestamp?: string;

1565 context_usage?: SDKContextUsage;1568 context_usage?: SDKContextUsage;

1566 user_message_uuid?: string;1569 user_message_uuid?: string;

1580 1583

1581`aborted` é `true` quando uma interrupção ou cancelamento truncou a mensagem do assistente antes da conclusão do stream: a mensagem não tem `stop_reason` e o conteúdo pode terminar no meio de uma palavra. O campo está ausente em mensagens normalmente concluídas. Requer Agent SDK v0.3.214 ou posterior.1584`aborted` é `true` quando uma interrupção ou cancelamento truncou a mensagem do assistente antes da conclusão do stream: a mensagem não tem `stop_reason` e o conteúdo pode terminar no meio de uma palavra. O campo está ausente em mensagens normalmente concluídas. Requer Agent SDK v0.3.214 ou posterior.

1582 1585

1586`agent_id` identifica o subagente que produziu a mensagem e está ausente em mensagens da thread principal. O valor é igual ao `task_id` no [`task_started`](#sdktaskstartedmessage) desse subagente e em outros eventos de tarefa, e permanece inalterado quando o subagente é [retomado](/docs/pt/agent-sdk/subagents#resume-subagents). O campo requer o Agent SDK v0.3.292 ou posterior.

1587

1588Associe as mensagens de um subagente aos seus eventos de tarefa pelo `agent_id`, em vez de parear o `parent_tool_use_id` de uma mensagem com o `tool_use_id` de um evento de tarefa. Quando uma chamada de ferramenta retoma o subagente, os eventos de tarefa carregam o `tool_use_id` dessa chamada, enquanto as mensagens mantêm o `parent_tool_use_id` da chamada de ferramenta que iniciou o subagente pela primeira vez, de modo que os dois deixam de corresponder.

1589

1583Claude Code define `user_message_uuid` e `user_message_uuids` na primeira mensagem do assistente do turno, sob as condições em [`user_message_uuid`](#user_message_uuid). Quando Claude Code re-executa um turno que uma reinicialização interrompeu, as mensagens do assistente da re-execução que carregam esses campos também carregam [`resume_reason`](#resume_reason).1590Claude Code define `user_message_uuid` e `user_message_uuids` na primeira mensagem do assistente do turno, sob as condições em [`user_message_uuid`](#user_message_uuid). Quando Claude Code re-executa um turno que uma reinicialização interrompeu, as mensagens do assistente da re-execução que carregam esses campos também carregam [`resume_reason`](#resume_reason).

1584 1591

1585`timestamp` é a hora ISO 8601 quando o conteúdo da mensagem terminou de ser gerado no processo que o produziu. O valor vem do relógio dessa máquina, portanto use-o apenas para exibição e não ordene mensagens por ele. Um turno de API pode produzir várias mensagens do assistente que compartilham um `message.id`, cada uma com seu próprio `timestamp`. Quando o campo está ausente, recorra à hora em que você recebeu a mensagem.1592`timestamp` é a hora ISO 8601 quando o conteúdo da mensagem terminou de ser gerado no processo que o produziu. O valor vem do relógio dessa máquina, portanto use-o apenas para exibição e não ordene mensagens por ele. Um turno de API pode produzir várias mensagens do assistente que compartilham um `message.id`, cada uma com seu próprio `timestamp`. Quando o campo está ausente, recorra à hora em que você recebeu a mensagem.

1597 type: "user";1604 type: "user";

1598 uuid?: UUID;1605 uuid?: UUID;

1599 session_id?: string;1606 session_id?: string;

1607 agent_id?: string;

1600 message: MessageParam; // From Anthropic SDK1608 message: MessageParam; // From Anthropic SDK

1601 pasted_content?: MessageParam["content"][];1609 pasted_content?: MessageParam["content"][];

1602 parent_tool_use_id: string | null;1610 parent_tool_use_id: string | null;

1636};1644};

1637```1645```

1638 1646

1647Uma mensagem de usuário que um subagente produz, como o `tool_result` de uma de suas próprias chamadas de ferramenta, carrega `agent_id`. Consulte [`SDKAssistantMessage`](#sdkassistantmessage), que define o campo e seu requisito de versão.

1648

1639Em uma mensagem que carrega um bloco `tool_result`, `tool_use_result` é o objeto de saída estruturada da ferramenta, e não o texto enviado ao modelo. Seu formato depende da ferramenta nomeada pelo bloco `tool_use` correspondente, por isso o campo é tipado como `unknown`; os formatos integrados estão listados em [Tipos de saída de ferramentas](#tool-output-types). Estes resultados exigem tratamento além do formato listado:1649Em uma mensagem que carrega um bloco `tool_result`, `tool_use_result` é o objeto de saída estruturada da ferramenta, e não o texto enviado ao modelo. Seu formato depende da ferramenta nomeada pelo bloco `tool_use` correspondente, por isso o campo é tipado como `unknown`; os formatos integrados estão listados em [Tipos de saída de ferramentas](#tool-output-types). Estes resultados exigem tratamento além do formato listado:

1640 1650

1641* A ferramenta `Agent`: `tool_use_result` é [`AgentOutput`](#agent-2). Renderize a partir dele em vez de analisar o texto de `tool_result`. O `content` de um resultado `completed` contém o relatório do subagente ou, no caso de um subagente cujo relatório passa por uma chamada de ferramenta `SubagentHandback`, uma breve nota sobre essa devolução no lugar do relatório. No [modo auto](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode) no Claude Code v2.1.271 ou posterior, todo subagente que produz um resultado `completed` reporta dessa forma, a menos que seja um [fork](/docs/pt/sub-agents#fork-the-current-conversation), e o Claude recebe o relatório como uma mensagem separada do subagente.1651* A ferramenta `Agent`: `tool_use_result` é [`AgentOutput`](#agent-2). Renderize a partir dele em vez de analisar o texto de `tool_result`. O `content` de um resultado `completed` contém o relatório do subagente ou, no caso de um subagente cujo relatório passa por uma chamada de ferramenta `SubagentHandback`, uma breve nota sobre essa devolução no lugar do relatório. No [modo auto](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode) no Claude Code v2.1.271 ou posterior, todo subagente que produz um resultado `completed` reporta dessa forma, a menos que seja um [fork](/docs/pt/sub-agents#fork-the-current-conversation), e o Claude recebe o relatório como uma mensagem separada do subagente.

1992 `SDKPartialAssistantMessage`2002 `SDKPartialAssistantMessage`

1993</h3>2003</h3>

1994 2004

1995Mensagem parcial de streaming (apenas quando `includePartialMessages` é true). O campo `parent_tool_use_id` é sempre `null`: eventos de stream são emitidos apenas para a sessão principal. Para atribuição de subagente, use mensagens completas, que carregam `parent_tool_use_id`, ou ative [`forwardSubagentText`](#options) para receber texto e pensamento de subagente como mensagens completas.2005Mensagem parcial de streaming (apenas quando `includePartialMessages` é true).

2006

2007O campo `parent_tool_use_id` é sempre `null`: eventos de stream são emitidos apenas para a sessão principal. Para atribuição a subagentes, use mensagens completas, que carregam [`agent_id`](#sdkassistantmessage) e `parent_tool_use_id`, ou ative [`forwardSubagentText`](#options) para receber o texto e o pensamento dos subagentes como mensagens completas.

1996 2008

1997```typescript theme={null}2009```typescript theme={null}

1998type SDKPartialAssistantMessage = {2010type SDKPartialAssistantMessage = {

3418type WebFetchInput = {3430type WebFetchInput = {

3419 url: string;3431 url: string;

3420 prompt: string;3432 prompt: string;

3433 offset?: number;

3421};3434};

3422```3435```

3423 3436

3424Busca conteúdo de uma URL e o processa com um modelo de IA.3437Busca conteúdo de uma URL e o processa com um modelo de IA.

3425 3438

3439`offset` é o número de caracteres a pular a partir do início da página. Claude o define para continuar lendo uma página longa. O campo requer Agent SDK v0.3.290 ou posterior.

3440

3426<h3 id="websearch">3441<h3 id="websearch">

3427 WebSearch3442 WebSearch

3428</h3>3443</h3>

5777 task_type?: string;5792 task_type?: string;

5778 is_backgrounded?: boolean;5793 is_backgrounded?: boolean;

5779 spawn_depth?: number;5794 spawn_depth?: number;

5795 parent_task_id?: string;

5780 ambient?: boolean;5796 ambient?: boolean;

5781 uuid: UUID;5797 uuid: UUID;

5782 session_id: string;5798 session_id: string;

5794 5810

5795Um [subagente retomado](/docs/pt/agent-sdk/subagents#resume-subagents) sempre relata `is_backgrounded: true`, porque Claude Code executa cada subagente retomado em segundo plano. Quando uma tarefa em primeiro plano se move para segundo plano depois, Claude Code relata o novo valor `is_backgrounded` em uma mensagem [`task_updated`](#sdktaskupdatedmessage) em vez de enviar um segundo `task_started`.5811Um [subagente retomado](/docs/pt/agent-sdk/subagents#resume-subagents) sempre relata `is_backgrounded: true`, porque Claude Code executa cada subagente retomado em segundo plano. Quando uma tarefa em primeiro plano se move para segundo plano depois, Claude Code relata o novo valor `is_backgrounded` em uma mensagem [`task_updated`](#sdktaskupdatedmessage) em vez de enviar um segundo `task_started`.

5796 5812

5813`parent_task_id` contém o `task_id` do subagente que iniciou esta tarefa. Use-o para agrupar cada tarefa sob o subagente que a iniciou. Claude Code o define em tarefas de subagente, Bash e [Monitor](#monitor). O campo requer Agent SDK v0.3.292 ou posterior. Ele está ausente quando:

5814

5815* A thread principal iniciou a tarefa

5816* Claude Code não rastreia mais a tarefa pai

5817* Um [colega de equipe](/docs/pt/agent-teams) ou um agente dentro de um fluxo de trabalho iniciou a tarefa

5818

5819O pai pode ser uma tarefa em primeiro plano ou uma que já terminou, então trate um ID que você não reconheça como ausência de pai.

5820

5797<h3 id="sdktaskprogressmessage">5821<h3 id="sdktaskprogressmessage">

5798 `SDKTaskProgressMessage`5822 `SDKTaskProgressMessage`

5799</h3>5823</h3>

5850 `SDKBackgroundTasksChangedMessage`5874 `SDKBackgroundTasksChangedMessage`

5851</h3>5875</h3>

5852 5876

5853Emitido sempre que o conjunto de tarefas em segundo plano ativas muda: uma tarefa inicia, é concluída, é eliminada, um agente em primeiro plano é colocado em segundo plano, ou o campo `description` ou `ambient` de uma tarefa muda.5877Emitido sempre que o conjunto de tarefas em segundo plano ativas muda: uma tarefa inicia, é concluída ou é eliminada; um agente em primeiro plano é colocado em segundo plano; ou o campo `description`, `ambient` ou `parent_task_id` de uma tarefa muda. Para o campo `parent_task_id` em cada entrada, veja [`SDKTaskStartedMessage`](#sdktaskstartedmessage), que o define e seu requisito de versão.

5854 5878

5855O array `tasks` é o conjunto completo ativo. Substitua qualquer conjunto em cache por cada payload em vez de emparelhar eventos `task_started` e `task_notification`, para que a próxima mudança de associação corrija qualquer evento que você tenha perdido.5879O array `tasks` é o conjunto completo ativo. Substitua qualquer conjunto em cache por cada payload em vez de emparelhar eventos `task_started` e `task_notification`, para que a próxima mudança de associação corrija qualquer evento que você tenha perdido.

5856 5880

5857A ordenação relativa a esses eventos por tarefa é não especificada, então não correlacione os dois fluxos.5881Quando uma tarefa termina, seus [`task_updated`](#sdktaskupdatedmessage) e [`task_notification`](#sdktasknotificationmessage) chegam antes do `background_tasks_changed` que a remove da lista. Fora isso, a ordenação relativa aos eventos por tarefa é não especificada.

5858 5882

5859Nada é emitido na inicialização. Redefina para um conjunto vazio sempre que o processo CLI da sessão inicia ou reinicia e deixe a próxima mudança de associação repopulá-lo.5883Nada é emitido na inicialização. Redefina para um conjunto vazio sempre que o processo CLI da sessão inicia ou reinicia e deixe a próxima mudança de associação repopulá-lo.

5860 5884

5871 task_type: string;5895 task_type: string;

5872 subagent_type?: string;5896 subagent_type?: string;

5873 description: string;5897 description: string;

5898 parent_task_id?: string;

5874 ambient?: boolean;5899 ambient?: boolean;

5875 }[];5900 }[];

5876 uuid: UUID;5901 uuid: UUID;

agent-sdk/user-input.md +10 −5

Details

36 ```36 ```

37 37

38 ```typescript TypeScript theme={null}38 ```typescript TypeScript theme={null}

~~39 async function handleToolRequest(toolName, input, options) {~~39 import type { CanUseTool } from "@anthropic-ai/claude-agent-sdk";

41 const handleToolRequest: CanUseTool = async (toolName, input, options) => {

40 // options inclui { signal: AbortSignal, suggestions?: PermissionUpdate[] }42 // options inclui { signal: AbortSignal, suggestions?: PermissionUpdate[] }

~~41 // Solicite ao usuário e retorne permitir ou negar~~43 // Solicite ao usuário aqui e, em seguida, retorne permitir ou negar

~~42 }~~44 return { behavior: "deny", message: "User declined" };

45 };

43 46

44 const options = { canUseTool: handleToolRequest };47 const options = { canUseTool: handleToolRequest };

45 ```48 ```

440 // Inclua AskUserQuestion em sua lista de ferramentas443 // Inclua AskUserQuestion em sua lista de ferramentas

441 tools: ["Read", "Glob", "Grep", "AskUserQuestion"],444 tools: ["Read", "Glob", "Grep", "AskUserQuestion"],

442 canUseTool: async (toolName, input) => {445 canUseTool: async (toolName, input) => {

443 // Lidar com perguntas de esclarecimento aqui446 // Marcador provisório que aprova todas as chamadas. O passo Detecte AskUserQuestion o substitui.

447 return { behavior: "allow", updatedInput: input };

444 }448 }

445 }449 }

446 })) {450 })) {

763 767

764 ```typescript TypeScript theme={null}768 ```typescript TypeScript theme={null}

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

770 import type { PermissionResult } from "@anthropic-ai/claude-agent-sdk";

766 import * as readline from "readline/promises";771 import * as readline from "readline/promises";

767 772

768 // Auxiliar para solicitar entrada do usuário no terminal773 // Auxiliar para solicitar entrada do usuário no terminal

783 }788 }

784 789

785 // Exiba as perguntas do Claude e colete respostas do usuário790 // Exiba as perguntas do Claude e colete respostas do usuário

786 async function handleAskUserQuestion(input: any) {791 async function handleAskUserQuestion(input: any): Promise<PermissionResult> {

787 const answers: Record<string, string> = {};792 const answers: Record<string, string> = {};

788 793

789 for (const q of input.questions) {794 for (const q of input.questions) {

agent-view.md +7 −4

Details

603 603

604Fora de um repositório git, as sessões escrevem no diretório de trabalho diretamente e não são isoladas uma da outra, portanto evite despachar sessões paralelas que editam os mesmos arquivos. Se você usar um sistema de controle de versão diferente, configure um [`WorktreeCreate` hook](/docs/pt/worktrees#non-git-version-control) e Claude isola edits da mesma forma que faz para git.604Fora de um repositório git, as sessões escrevem no diretório de trabalho diretamente e não são isoladas uma da outra, portanto evite despachar sessões paralelas que editam os mesmos arquivos. Se você usar um sistema de controle de versão diferente, configure um [`WorktreeCreate` hook](/docs/pt/worktrees#non-git-version-control) e Claude isola edits da mesma forma que faz para git.

605 605

606Quando o hook falha em um diretório que não é um repositório git, Claude pula o isolamento para esse diretório e edita o diretório de trabalho no local. Dentro de um repositório git, uma sessão que Claude move para um worktree antes de editar não pode editar arquivos no checkout compartilhado até que essa mudança aconteça.606Quando o hook falha em um diretório que não é um repositório git, Claude pula o isolamento para esse diretório e edita o diretório de trabalho no local. Dentro de um repositório git, uma sessão que Claude move para um worktree antes de editar não pode usar as ferramentas `Edit`, `Write` ou `NotebookEdit` no checkout compartilhado até que essa mudança aconteça.

607 607

608Para encontrar o caminho do worktree de uma sessão, anexe e verifique seu diretório de trabalho.608Para encontrar o caminho do worktree de uma sessão, anexe e verifique seu diretório de trabalho.

609 609

979 Opening a session says it has no saved transcript979 Opening a session says it has no saved transcript

980</h3>980</h3>

981 981

982Uma sessão parada que foi [backgrounded from another conversation](#from-inside-a-session) e parou antes de sua primeira resposta terminar não tem nada para retomar: até que essa primeira resposta termine, a conversa ainda vive apenas na sessão de que foi backgrounded. `claude attach` recusa abrir com `This session has no saved transcript`.982Quando você abre uma sessão que você [colocou em background a partir de outra conversa](#from-inside-a-session) e que parou antes de executar um turno próprio, Claude Code retoma essa conversa. Se Claude Code não conseguir encontrar a conversa, ele recusa abrir a sessão:

983 983

984Em agent view, abrir essa linha mostra `Press enter again to restart this session fresh` abaixo da lista. Pressione `Enter` na mesma linha novamente para reiniciar a sessão com uma conversa vazia, ou execute `claude respawn <id>` do shell.984* `claude attach` imprime `This session has no saved transcript`.

985* Agent view mostra `Press enter again to restart this session fresh` abaixo da lista.

985 986

986A conversa original está intacta; retome-a com `claude --resume` ou continue trabalhando nela. Veja a [referência de erro](/docs/pt/errors#this-session-has-no-saved-transcript) para detalhes.987Pressione `Enter` na mesma linha novamente para reiniciar a sessão com uma conversa vazia, ou execute `claude respawn <id>` do shell.

988

989Veja a [referência de erro](/docs/pt/errors#this-session-has-no-saved-transcript) para detalhes.

987 990

988<h3 id="the-terminal-host-died-or-the-session-stopped-responding">991<h3 id="the-terminal-host-died-or-the-session-stopped-responding">

989 The terminal host died or the session stopped responding992 The terminal host died or the session stopped responding

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

Details

1237 1237

1238O CLI envia métricas, logs e, quando habilitado, rastreamentos para o gateway, que os retransmite verbatim para cada destino configurado. As exportações usam OpenTelemetry Protocol (OTLP) sobre HTTP. Para pular o relé e ter sessões exportar diretamente para seu coletor, [nomeie o coletor em uma política](#export-directly-to-your-collector). Veja [Monitoring usage](/docs/pt/monitoring-usage) para as métricas e eventos que o CLI emite.1238O CLI envia métricas, logs e, quando habilitado, rastreamentos para o gateway, que os retransmite verbatim para cada destino configurado. As exportações usam OpenTelemetry Protocol (OTLP) sobre HTTP. Para pular o relé e ter sessões exportar diretamente para seu coletor, [nomeie o coletor em uma política](#export-directly-to-your-collector). Veja [Monitoring usage](/docs/pt/monitoring-usage) para as métricas e eventos que o CLI emite.

1239 1239

1240Em sessões conectadas através de `/login`, o CLI carimba cada exportação com a identidade do usuário autenticado, lida do JWT emitido pelo gateway: os atributos `user.id`, `user.email` e `user.groups`. A atribuição de custo e uso por desenvolvedor portanto funciona sem nenhuma configuração no lado do desenvolvedor.1240Em sessões conectadas através de `/login`, o CLI carimba cada exportação com a identidade do usuário autenticado, lida do JWT emitido pelo gateway: os atributos `user.id`, `user.email` e `user.groups`. A atribuição de custo e uso por desenvolvedor portanto funciona sem nenhuma configuração no lado do desenvolvedor. Eventos que Claude Code registra em log antes de o desenvolvedor se conectar [não carregam essa identidade](/docs/pt/monitoring-usage#standard-attributes).

1241 1241

1242[Claude Desktop](#claude-desktop-overlay) e sessões Cowork conectadas através do gateway carimbam sua telemetria com `user.email` e `user.groups` ao lado de `enduser.id`, então você pode cobrir uso de terminal, Desktop e Cowork com uma consulta em `user.email` ou `user.groups`. `user.groups` é a lista de grupo do IdP separada por vírgula.1242[Claude Desktop](#claude-desktop-overlay) e sessões Cowork conectadas através do gateway carimbam sua telemetria com `user.email` e `user.groups` ao lado de `enduser.id`, então você pode cobrir uso de terminal, Desktop e Cowork com uma consulta em `user.email` ou `user.groups`. `user.groups` é a lista de grupo do IdP separada por vírgula.

1243 1243

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

Details

516 Telemetria516 Telemetria

517</h2>517</h2>

518 518

519O gateway fornece métricas de uso por desenvolvedor sem qualquer configuração OTEL por máquina. Claude Code emite métricas, logs e traces com opt-in do OpenTelemetry (OTLP); [Monitorar uso](/docs/pt/monitoring-usage) cobre tudo o que a CLI relata. Em sessões autenticadas através de `/login`, a CLI marca cada exportação com os atributos de identidade do IdP autenticado `user.id`, `user.email` e `user.groups`, para que o uso seja agregado por desenvolvedor.519O gateway fornece métricas de uso por desenvolvedor sem qualquer configuração OTEL por máquina. Claude Code emite métricas, logs e traces com opt-in do OpenTelemetry (OTLP); [Monitorar uso](/docs/pt/monitoring-usage) cobre tudo o que a CLI relata. Em sessões autenticadas através de `/login`, a CLI [marca cada exportação](/docs/pt/monitoring-usage#standard-attributes) com os atributos de identidade do IdP autenticado `user.id`, `user.email` e `user.groups`, para que o uso seja agregado por desenvolvedor.

520 520

521O gateway em si é um relay OTLP autenticado. Configure [`telemetry.forward_to`](/docs/pt/claude-apps-gateway-config#telemetry) junto com `listen.public_url`, e ele envia as configurações do exportador OTEL para cada cliente conectado e encaminha seu tráfego OTLP verbatim para cada destino que você listar. Cada destino opta por métricas, logs e traces independentemente, e o padrão é apenas métricas; consulte a [referência `telemetry`](/docs/pt/claude-apps-gateway-config#telemetry) para os campos por sinal e seus trade-offs de sensibilidade. O gateway não armazena em buffer, agrega ou armazena telemetria, portanto, onde os dados chegam é inteiramente a configuração do exportador do coletor.521O gateway em si é um relay OTLP autenticado. Configure [`telemetry.forward_to`](/docs/pt/claude-apps-gateway-config#telemetry) junto com `listen.public_url`, e ele envia as configurações do exportador OTEL para cada cliente conectado e encaminha seu tráfego OTLP verbatim para cada destino que você listar. Cada destino opta por métricas, logs e traces independentemente, e o padrão é apenas métricas; consulte a [referência `telemetry`](/docs/pt/claude-apps-gateway-config#telemetry) para os campos por sinal e seus trade-offs de sensibilidade. O gateway não armazena em buffer, agrega ou armazena telemetria, portanto, onde os dados chegam é inteiramente a configuração do exportador do coletor.

522 522

claude-projects.md +1 −1

Details

489* **Routines**: quando você pede trabalho agendado em um projeto, Claude cria uma [routine](/docs/pt/routines) que é executada como threads nesse projeto e aparece em sua aba **Routines**. Routines que você cria fora de um projeto continuam funcionando por conta própria.489* **Routines**: quando você pede trabalho agendado em um projeto, Claude cria uma [routine](/docs/pt/routines) que é executada como threads nesse projeto e aparece em sua aba **Routines**. Routines que você cria fora de um projeto continuam funcionando por conta própria.

490* **Remote Control**: [Remote Control](/docs/pt/remote-control) conecta claude.ai a uma sessão Claude Code em execução na sua máquina. Quando você pede a Claude em um projeto para executar uma thread no seu computador, o projeto [usa Remote Control para fazer isso](#run-a-thread-on-your-own-computer).490* **Remote Control**: [Remote Control](/docs/pt/remote-control) conecta claude.ai a uma sessão Claude Code em execução na sua máquina. Quando você pede a Claude em um projeto para executar uma thread no seu computador, o projeto [usa Remote Control para fazer isso](#run-a-thread-on-your-own-computer).

491* **Sessões locais e agent view**: uma sessão que você inicia na sua máquina em seu terminal, IDE ou no ambiente local do aplicativo desktop não pode ser adicionada a um projeto. [Agent view](/docs/pt/agent-view) é uma tela para rastrear várias sessões locais lado a lado, e você ainda inicia cada uma e dá sua tarefa a ela mesmo.491* **Sessões locais e agent view**: uma sessão que você inicia na sua máquina em seu terminal, IDE ou no ambiente local do aplicativo desktop não pode ser adicionada a um projeto. [Agent view](/docs/pt/agent-view) é uma tela para rastrear várias sessões locais lado a lado, e você ainda inicia cada uma e dá sua tarefa a ela mesmo.

492* **Worktrees**: um [worktree](/docs/pt/worktrees) dá a cada sessão local sua própria cópia de trabalho de um repositório para que sessões paralelas na sua máquina não se sobrescrevam. As threads em nuvem não precisam deles: cada uma clona seus repositórios em seu próprio sandbox em nuvem e funciona em seu próprio branch.492* **Worktrees**: um [worktree](/docs/pt/worktrees) dá a cada sessão local sua própria cópia de trabalho de um repositório. As threads na nuvem não precisam deles: cada uma clona seus repositórios em seu próprio sandbox na nuvem e trabalha em seu próprio branch.

493* **Agent teams**: um [agent team](/docs/pt/agent-teams) é uma sessão que inicia sessões de colega de trabalho para uma única tarefa, na sua máquina ou dentro de uma sessão em nuvem, e termina com essa tarefa.493* **Agent teams**: um [agent team](/docs/pt/agent-teams) é uma sessão que inicia sessões de colega de trabalho para uma única tarefa, na sua máquina ou dentro de uma sessão em nuvem, e termina com essa tarefa.

494* **Subagents**: um [subagent](/docs/pt/sub-agents) é executado dentro de uma sessão, faz uma tarefa secundária em sua própria janela de contexto e retorna um resumo para essa sessão. As threads de um projeto são sessões completas que Claude inicia e que reportam de volta para a conversa do projeto, e uma thread ainda pode usar subagents para suas próprias tarefas secundárias.494* **Subagents**: um [subagent](/docs/pt/sub-agents) é executado dentro de uma sessão, faz uma tarefa secundária em sua própria janela de contexto e retorna um resumo para essa sessão. As threads de um projeto são sessões completas que Claude inicia e que reportam de volta para a conversa do projeto, e uma thread ainda pode usar subagents para suas próprias tarefas secundárias.

495* **Projects no chat claude.ai e Cowork**: a [experiência anterior de Projects](https://support.claude.com/en/articles/9517075-what-are-projects), que agrupa conversas e arquivos de referência sem threads ou um coordenador. Esses projetos continuam funcionando como fazem hoje até que a experiência redesenhada os alcance.495* **Projects no chat claude.ai e Cowork**: a [experiência anterior de Projects](https://support.claude.com/en/articles/9517075-what-are-projects), que agrupa conversas e arquivos de referência sem threads ou um coordenador. Esses projetos continuam funcionando como fazem hoje até que a experiência redesenhada os alcance.

cli-reference.md +1 −1

Details

107| `--json-schema` | Obter saída JSON validada correspondendo a um JSON Schema após o agente completar seu fluxo de trabalho (apenas modo print). Veja [saídas estruturadas](/docs/pt/agent-sdk/structured-outputs). Claude Code sai com um erro em um schema inválido e aceita a palavra-chave `format` como uma anotação sem validação do lado do cliente | `claude -p --json-schema '{"type":"object","properties":{...}}' "query"` |107| `--json-schema` | Obter saída JSON validada correspondendo a um JSON Schema após o agente completar seu fluxo de trabalho (apenas modo print). Veja [saídas estruturadas](/docs/pt/agent-sdk/structured-outputs). Claude Code sai com um erro em um schema inválido e aceita a palavra-chave `format` como uma anotação sem validação do lado do cliente | `claude -p --json-schema '{"type":"object","properties":{...}}' "query"` |

108| `--maintenance` | Executar hooks de [Setup](/docs/pt/hooks#setup) com o matcher `maintenance` antes da sessão (apenas modo print) | `claude -p --maintenance "query"` |108| `--maintenance` | Executar hooks de [Setup](/docs/pt/hooks#setup) com o matcher `maintenance` antes da sessão (apenas modo print) | `claude -p --maintenance "query"` |

109| `--max-budget-usd` | Valor máximo em dólares a gastar em chamadas de API antes de parar (apenas modo print). Claude Code compara o limite com sua [estimativa de custo do lado do cliente](/docs/pt/agent-sdk/cost-tracking#estimates-not-billing), que pode diferir da sua fatura. Gastos de [subagentes](/docs/pt/sub-agents) contam para o limite. Quando você retorna a uma conversa com `--continue` ou `--resume`, totais [restaurados de execuções anteriores](/docs/pt/agent-sdk/cost-tracking#accumulate-costs-across-multiple-calls) não contam para ele. Uma vez que o gasto atinge o limite, gerar outro subagente falha com `Budget limit reached`, e Claude Code para subagentes de fundo que ainda estão em execução; os comportamentos de aplicação do limite requerem Claude Code v2.1.217 ou posterior | `claude -p --max-budget-usd 5.00 "query"` |109| `--max-budget-usd` | Interromper a execução quando o gasto estimado em chamadas de API atingir este valor (apenas modo print). Claude Code compara o limite com sua [estimativa de custo do lado do cliente](/docs/pt/agent-sdk/cost-tracking#estimates-not-billing), que pode diferir da sua fatura. Gastos de [subagentes](/docs/pt/sub-agents) contam para o limite. O gasto pode ultrapassar o limite, portanto [deixe uma margem](/docs/pt/agent-sdk/agent-loop#budget-headroom). Quando você retorna a uma conversa com `--continue` ou `--resume`, totais [restaurados de execuções anteriores](/docs/pt/agent-sdk/cost-tracking#accumulate-costs-across-multiple-calls) não contam para ele. Uma vez que o gasto atinge o limite, gerar outro subagente falha com `Budget limit reached`, e Claude Code para subagentes de fundo que ainda estão em execução; os comportamentos de aplicação do limite requerem Claude Code v2.1.217 ou posterior | `claude -p --max-budget-usd 5.00 "query"` |

110| `--max-turns` | Limitar o número de turnos de agente (apenas modo print). Sai com um erro quando o limite é atingido. Sem limite por padrão. Com `--input-format stream-json`, uma mensagem ainda enfileirada quando o limite termina um turno permanece enfileirada e inicia um novo turno com seu próprio limite | `claude -p --max-turns 3 "query"` |110| `--max-turns` | Limitar o número de turnos de agente (apenas modo print). Sai com um erro quando o limite é atingido. Sem limite por padrão. Com `--input-format stream-json`, uma mensagem ainda enfileirada quando o limite termina um turno permanece enfileirada e inicia um novo turno com seu próprio limite | `claude -p --max-turns 3 "query"` |

111| `--mcp-config` | Carregar servidores MCP de arquivos JSON ou strings (separados por espaço). Quando você passa este sinalizador com `-p`, Claude Code aguarda servidores ainda pendentes se conectarem antes de executar o primeiro turno, até o tempo limite de inicialização [`MCP_TIMEOUT`](/docs/pt/env-vars), 30 segundos por padrão; um servidor com uma [lista de ferramentas em cache](/docs/pt/mcp#managing-your-servers) pula a espera e se conecta no primeiro uso. A espera requer Claude Code v2.1.221 ou posterior | `claude --mcp-config ./mcp.json` |111| `--mcp-config` | Carregar servidores MCP de arquivos JSON ou strings (separados por espaço). Quando você passa este sinalizador com `-p`, Claude Code aguarda servidores ainda pendentes se conectarem antes de executar o primeiro turno, até o tempo limite de inicialização [`MCP_TIMEOUT`](/docs/pt/env-vars), 30 segundos por padrão; um servidor com uma [lista de ferramentas em cache](/docs/pt/mcp#managing-your-servers) pula a espera e se conecta no primeiro uso. A espera requer Claude Code v2.1.221 ou posterior | `claude --mcp-config ./mcp.json` |

112| `--model` | Define o modelo para a sessão atual com um [alias de modelo](/docs/pt/model-config#model-aliases) como `sonnet`, `opus`, `haiku` ou `fable`, ou o nome completo de um modelo. Substitui a configuração [`model`](/docs/pt/settings-reference#model) e [`ANTHROPIC_MODEL`](/docs/pt/model-config#environment-variables) | `claude --model claude-sonnet-5` |112| `--model` | Define o modelo para a sessão atual com um [alias de modelo](/docs/pt/model-config#model-aliases) como `sonnet`, `opus`, `haiku` ou `fable`, ou o nome completo de um modelo. Substitui a configuração [`model`](/docs/pt/settings-reference#model) e [`ANTHROPIC_MODEL`](/docs/pt/model-config#environment-variables) | `claude --model claude-sonnet-5` |

cloud-environments.md +3 −3

Details

307| | Disponível em sessões na nuvem | Por quê |307| | Disponível em sessões na nuvem | Por quê |

308| :- | :- | :- |308| :- | :- | :- |

309| Seu `CLAUDE.md` do repositório | Sim | Parte do clone |309| Seu `CLAUDE.md` do repositório | Sim | Parte do clone |

310| Seus hooks `.claude/settings.json` do repositório e regras de permissão | Sim, em uma sessão com um repositório | Parte do clone. Uma sessão com vários repositórios, incluindo um thread de [projeto](/docs/pt/claude-projects#what-threads-pick-up-from-your-repositories), começa acima dos clones e não os lê |310| Seus hooks `.claude/settings.json` do repositório e regras de permissão | Sim, em uma sessão com um repositório | Parte do clone. Para uma sessão com vários repositórios, veja [quais configurações ela lê](/docs/pt/settings#settings-in-cloud-sessions) |

311| Seus servidores MCP `.mcp.json` do repositório | Sim, em uma sessão com um repositório | Parte do clone, encontrado a partir do diretório de trabalho da sessão |311| Seus servidores MCP `.mcp.json` do repositório | Sim, em uma sessão com um repositório | Parte do clone, encontrado a partir do diretório de trabalho da sessão. Para um ambiente auto-hospedado, veja [quais configurações de repositório se aplicam](/docs/pt/self-hosted-environments-configuration#repository-settings-in-sessions-with-several-repositories) |

312| Seu `.claude/rules/` do repositório | Sim | Parte do clone |312| Seu `.claude/rules/` do repositório | Sim | Parte do clone |

313| Seu `.claude/skills/`, `.claude/agents/`, `.claude/commands/` do repositório | Sim | Parte do clone |313| Seu `.claude/skills/`, `.claude/agents/`, `.claude/commands/` do repositório | Sim | Parte do clone |

314| Plugins e marketplaces declarados em seu `.claude/settings.json` do repositório | Não | Uma sessão na nuvem não instala os plugins que um repositório ativa em [`enabledPlugins`](/docs/pt/settings-reference#enabledplugins), incluindo aqueles dos marketplaces que lista em [`extraKnownMarketplaces`](/docs/pt/settings-reference#extraknownmarketplaces) |314| Plugins e marketplaces declarados em seu `.claude/settings.json` do repositório | Não | Uma sessão na nuvem não instala os plugins que um repositório ativa em [`enabledPlugins`](/docs/pt/settings-reference#enabledplugins), incluindo aqueles dos marketplaces que lista em [`extraKnownMarketplaces`](/docs/pt/settings-reference#extraknownmarketplaces) |

575 575

576Os hooks SessionStart se comportam da mesma forma na nuvem que localmente, com essas ressalvas:576Os hooks SessionStart se comportam da mesma forma na nuvem que localmente, com essas ressalvas:

577 577

578* **Um repositório por sessão**: uma sessão com vários repositórios não carrega hooks de nenhum `.claude/settings.json` do repositório, portanto um hook SessionStart que você define lá não é executado. Instale dependências para essas sessões com um [script de configuração](#setup-scripts) em vez disso.578* **Um repositório por sessão**: em um ambiente hospedado pela Anthropic, uma sessão com vários repositórios não carrega hooks de nenhum `.claude/settings.json` do repositório, portanto um hook SessionStart que você define lá não é executado. Instale dependências para essas sessões com um [script de configuração](#setup-scripts) em vez disso. Para um ambiente auto-hospedado, veja [quais configurações do repositório se aplicam](/docs/pt/self-hosted-environments-configuration#repository-settings-in-sessions-with-several-repositories).

579* **Sem escopo apenas na nuvem**: os hooks são executados em sessões locais e na nuvem. Para pular a execução local, saia cedo a menos que a variável de ambiente `CLAUDE_CODE_REMOTE` seja `true`, da forma que o [script de instalação de dependência](#install-dependencies-with-a-sessionstart-hook) faz.579* **Sem escopo apenas na nuvem**: os hooks são executados em sessões locais e na nuvem. Para pular a execução local, saia cedo a menos que a variável de ambiente `CLAUDE_CODE_REMOTE` seja `true`, da forma que o [script de instalação de dependência](#install-dependencies-with-a-sessionstart-hook) faz.

580* **Requer acesso à rede**: os comandos de instalação precisam alcançar registros de pacotes. Se seu ambiente usa acesso à rede **None**, esses hooks falham. A [lista de permissões padrão](#default-allowed-domains) em **Trusted** cobre npm, PyPI, RubyGems e crates.io.580* **Requer acesso à rede**: os comandos de instalação precisam alcançar registros de pacotes. Se seu ambiente usa acesso à rede **None**, esses hooks falham. A [lista de permissões padrão](#default-allowed-domains) em **Trusted** cobre npm, PyPI, RubyGems e crates.io.

581* **Compatibilidade de proxy**: em ambientes hospedados pela Anthropic, todo o tráfego de saída passa por um [proxy de segurança](#security-proxy), e alguns gerenciadores de pacotes não funcionam corretamente com isso; Bun é um exemplo conhecido. Em um [ambiente auto-hospedado](/docs/pt/self-hosted-environments-deploy#default-deny-egress), o tráfego de saída vai através de seu próprio limite de rede em vez disso.581* **Compatibilidade de proxy**: em ambientes hospedados pela Anthropic, todo o tráfego de saída passa por um [proxy de segurança](#security-proxy), e alguns gerenciadores de pacotes não funcionam corretamente com isso; Bun é um exemplo conhecido. Em um [ambiente auto-hospedado](/docs/pt/self-hosted-environments-deploy#default-deny-egress), o tráfego de saída vai através de seu próprio limite de rede em vez disso.

desktop.md +1 −1

Details

396 Trabalhar em paralelo com sessões396 Trabalhar em paralelo com sessões

397</h3>397</h3>

398 398

399Clique em **+ New session** na barra lateral, ou pressione **Cmd+N** no macOS ou **Ctrl+N** no Windows, para trabalhar em múltiplas tarefas em paralelo. Pressione **Ctrl+Tab** e **Ctrl+Shift+Tab** para ciclar através de sessões na barra lateral. Para repositórios Git, selecione a opção **worktree** ao lado do nome do branch para dar à sessão sua própria cópia isolada do seu projeto usando [Git worktrees](/docs/pt/worktrees), para que alterações em uma sessão não afetem outras sessões até que você as faça commit.399Clique em **+ New session** na barra lateral, ou pressione **Cmd+N** no macOS ou **Ctrl+N** no Windows, para trabalhar em múltiplas tarefas em paralelo. Pressione **Ctrl+Tab** e **Ctrl+Shift+Tab** para ciclar através de sessões na barra lateral. Para repositórios Git, selecione a opção **worktree** ao lado do nome do branch para dar à sessão sua própria cópia isolada do seu projeto usando [Git worktrees](/docs/pt/worktrees).

400 400

401Para visualizar duas sessões ao mesmo tempo, mantenha **Cmd** no macOS ou **Ctrl** no Windows e clique em uma sessão na barra lateral. A sessão abre em um segundo painel ao lado daquele que você já tem aberto. Enquanto a divisão está ativa, clicar em outra sessão da barra lateral substitui o painel que tem foco. Pressione **Cmd+\\** no macOS ou **Ctrl+\\** no Windows para fechar o painel focado e retornar a uma única sessão.401Para visualizar duas sessões ao mesmo tempo, mantenha **Cmd** no macOS ou **Ctrl** no Windows e clique em uma sessão na barra lateral. A sessão abre em um segundo painel ao lado daquele que você já tem aberto. Enquanto a divisão está ativa, clicar em outra sessão da barra lateral substitui o painel que tem foco. Pressione **Cmd+\\** no macOS ou **Ctrl+\\** no Windows para fechar o painel focado e retornar a uma única sessão.

402 402

env-vars.md +2 −2

Details

204| `CLAUDE_AFK_TIMEOUT_MS` | Quantos milissegundos de inatividade antes que uma caixa de diálogo [`AskUserQuestion`](/docs/pt/tools-reference) não respondida continue automaticamente sem você. A continuação automática fica desativada por padrão; ative-a com a configuração [`askUserQuestionTimeout`](/docs/pt/settings-reference#askuserquestiontimeout). Esta variável é uma substituição para demonstrações e testes automatizados: quando definida, tem precedência sobre essa configuração e ativa a continuação automática mesmo quando a configuração não está definida ou é `never`. Definir `0` não desativa o timeout; fecha a caixa de diálogo imediatamente. Ignorado em [configurações de projeto e locais](/docs/pt/settings-reference#variables-claude-code-ignores-in-env). Antes da v2.1.200, a continuação automática ficava ativada por padrão com um timeout de `60000` (60 segundos). Requer o Claude Code v2.1.198 ou posterior |204| `CLAUDE_AFK_TIMEOUT_MS` | Quantos milissegundos de inatividade antes que uma caixa de diálogo [`AskUserQuestion`](/docs/pt/tools-reference) não respondida continue automaticamente sem você. A continuação automática fica desativada por padrão; ative-a com a configuração [`askUserQuestionTimeout`](/docs/pt/settings-reference#askuserquestiontimeout). Esta variável é uma substituição para demonstrações e testes automatizados: quando definida, tem precedência sobre essa configuração e ativa a continuação automática mesmo quando a configuração não está definida ou é `never`. Definir `0` não desativa o timeout; fecha a caixa de diálogo imediatamente. Ignorado em [configurações de projeto e locais](/docs/pt/settings-reference#variables-claude-code-ignores-in-env). Antes da v2.1.200, a continuação automática ficava ativada por padrão com um timeout de `60000` (60 segundos). Requer o Claude Code v2.1.198 ou posterior |

205| `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS` | Defina como `1` para desativar todos os tipos de [subagente](/docs/pt/sub-agents) integrados, como Explore e Plan. Aplica-se apenas no modo não interativo (a flag `-p`). Útil para usuários do SDK que querem começar do zero. Isso também remove `general-purpose`, o subagente que o Claude Code executa quando uma chamada da ferramenta Agent omite `subagent_type`. Essa chamada então falha com [`subagent_type is required`](/docs/pt/errors#subagent-type-is-required) |205| `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS` | Defina como `1` para desativar todos os tipos de [subagente](/docs/pt/sub-agents) integrados, como Explore e Plan. Aplica-se apenas no modo não interativo (a flag `-p`). Útil para usuários do SDK que querem começar do zero. Isso também remove `general-purpose`, o subagente que o Claude Code executa quando uma chamada da ferramenta Agent omite `subagent_type`. Essa chamada então falha com [`subagent_type is required`](/docs/pt/errors#subagent-type-is-required) |

206| `CLAUDE_AGENT_SDK_MCP_NO_PREFIX` | Defina como `1` para omitir o prefixo `mcp__<server>__` nos nomes de ferramentas de servidores MCP criados pelo SDK. As ferramentas usam seus nomes originais. Apenas para uso com o SDK |206| `CLAUDE_AGENT_SDK_MCP_NO_PREFIX` | Defina como `1` para omitir o prefixo `mcp__<server>__` nos nomes de ferramentas de servidores MCP criados pelo SDK. As ferramentas usam seus nomes originais. Apenas para uso com o SDK |

207| `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS` | Timeout de travamento em milissegundos para subagentes. Padrão `600000` (10 minutos); se você aumentar `CLAUDE_STREAM_IDLE_TIMEOUT_MS` enquanto o watchdog de stream estiver ativo, o padrão aumenta junto, conforme descrito em [Lidar com respostas lentas ou travadas da API](/docs/pt/agent-sdk/typescript#handle-slow-or-stalled-api-responses). O timer é reiniciado a cada evento de progresso do streaming; se nenhum progresso chegar dentro da janela, o Claude Code aborta o subagente e relata o travamento ao pai |207| `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS` | Timeout de travamento em milissegundos para subagentes. Também abrange [agentes de workflow](/docs/pt/workflows#when-an-agent-stalls-and-restarts) no Claude Code v2.1.286 ou posterior. Padrão `600000` (10 minutos); se você aumentar `CLAUDE_STREAM_IDLE_TIMEOUT_MS` enquanto o watchdog de stream está ativo, o padrão aumenta junto, conforme descrito em [Lidar com respostas de API lentas ou travadas](/docs/pt/agent-sdk/typescript#handle-slow-or-stalled-api-responses) |

208| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | Define a porcentagem (1-100) da janela de compactação automática na qual a compactação automática é acionada. Use valores menores, como `50`, para compactar mais cedo; a variável não pode elevar o limite, então valores acima da porcentagem padrão são ignorados. Aplica-se apenas em sessões que [compactam antes do limite de contexto do modelo](/docs/pt/model-config#context-window-and-auto-compaction). Aplica-se tanto às conversas principais quanto aos subagentes |208| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | Define a porcentagem (1-100) da janela de compactação automática na qual a compactação automática é acionada. Use valores menores, como `50`, para compactar mais cedo; a variável não pode elevar o limite, então valores acima da porcentagem padrão são ignorados. Aplica-se apenas em sessões que [compactam antes do limite de contexto do modelo](/docs/pt/model-config#context-window-and-auto-compaction). Aplica-se tanto às conversas principais quanto aos subagentes |

209| `CLAUDE_AUTO_BACKGROUND_TASKS` | Defina como `1` para forçar a ativação do envio automático para segundo plano de tarefas de agente de longa duração. Quando ativado, os subagentes são movidos para segundo plano após cerca de dois minutos de execução. Também ativa o [envio automático para segundo plano de chamadas longas de ferramentas MCP](/docs/pt/mcp#automatic-backgrounding-of-long-tool-calls) no modo não interativo no Claude Code v2.1.212 ou posterior |209| `CLAUDE_AUTO_BACKGROUND_TASKS` | Defina como `1` para forçar a ativação do envio automático para segundo plano de tarefas de agente de longa duração. Quando ativado, os subagentes são movidos para segundo plano após cerca de dois minutos de execução. Também ativa o [envio automático para segundo plano de chamadas longas de ferramentas MCP](/docs/pt/mcp#automatic-backgrounding-of-long-tool-calls) no modo não interativo no Claude Code v2.1.212 ou posterior |

210| `CLAUDE_AX_PREPARK_MS` | No [modo de leitor de tela](/docs/pt/accessibility), quantos milissegundos o Claude Code aguarda antes de escrever uma linha nova ou alterada. Padrão `0`, então o Claude Code não aguarda. Antes da v2.1.287, o padrão era `50`. O Claude Code limita a espera a `5000`. Requer o Claude Code v2.1.233 ou posterior |210| `CLAUDE_AX_PREPARK_MS` | No [modo de leitor de tela](/docs/pt/accessibility), quantos milissegundos o Claude Code aguarda antes de escrever uma linha nova ou alterada. Padrão `0`, então o Claude Code não aguarda. Antes da v2.1.287, o padrão era `50`. O Claude Code limita a espera a `5000`. Requer o Claude Code v2.1.233 ou posterior |

378| `CLAUDE_CODE_RESUME_INTERRUPTED_TURN_MAX_AGE_MS` | Idade máxima, em milissegundos, da última mensagem da transcrição para que uma sessão que terminou no meio de um turno continue automaticamente ao ser retomada. Quando a última mensagem é mais antiga que esse limite, o Claude Code pula a retomada automática de `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` e sua mensagem de continuação `CLAUDE_CODE_RESUME_PROMPT`, e a sessão começa ociosa para que você continue explicitamente. Não definida ou `0` significa sem limite, exceto que um turno cuja última requisição falhou com um erro de API só é retomado enquanto esse erro tiver menos de seis horas. Um valor positivo limita todos os turnos, incluindo esses; um valor negativo ou não numérico aplica um limite de uma hora. Scripts de inicialização para agentes de longa duração podem defini-la para que uma reinicialização com uma transcrição antiga não execute novamente um prompt obsoleto. O próprio Claude Code define um limite de uma hora quando reinicia uma sessão do [agent view](/docs/pt/agent-view) que travou e que herdou sua conversa de uma sessão interativa. Requer Claude Code v2.1.211 ou posterior |378| `CLAUDE_CODE_RESUME_INTERRUPTED_TURN_MAX_AGE_MS` | Idade máxima, em milissegundos, da última mensagem da transcrição para que uma sessão que terminou no meio de um turno continue automaticamente ao ser retomada. Quando a última mensagem é mais antiga que esse limite, o Claude Code pula a retomada automática de `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` e sua mensagem de continuação `CLAUDE_CODE_RESUME_PROMPT`, e a sessão começa ociosa para que você continue explicitamente. Não definida ou `0` significa sem limite, exceto que um turno cuja última requisição falhou com um erro de API só é retomado enquanto esse erro tiver menos de seis horas. Um valor positivo limita todos os turnos, incluindo esses; um valor negativo ou não numérico aplica um limite de uma hora. Scripts de inicialização para agentes de longa duração podem defini-la para que uma reinicialização com uma transcrição antiga não execute novamente um prompt obsoleto. O próprio Claude Code define um limite de uma hora quando reinicia uma sessão do [agent view](/docs/pt/agent-view) que travou e que herdou sua conversa de uma sessão interativa. Requer Claude Code v2.1.211 ou posterior |

379| `CLAUDE_CODE_RESUME_PROMPT` | Sobrescreve a mensagem de continuação que o Claude Code envia a Claude quando `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` continua um turno interrompido em vez de reenviar seu prompt, ou quando você retoma uma [chamada de ferramenta adiada](/docs/pt/hooks#defer-a-tool-call-for-later) com `-p`. O padrão é `Continue from where you left off.`. Uma string vazia usa o padrão |379| `CLAUDE_CODE_RESUME_PROMPT` | Sobrescreve a mensagem de continuação que o Claude Code envia a Claude quando `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` continua um turno interrompido em vez de reenviar seu prompt, ou quando você retoma uma [chamada de ferramenta adiada](/docs/pt/hooks#defer-a-tool-call-for-later) com `-p`. O padrão é `Continue from where you left off.`. Uma string vazia usa o padrão |

380| `CLAUDE_CODE_RETRY_WATCHDOG` | Defina como `1` para sessões não supervisionadas, como harnesses de avaliação, jobs de CI ou workers remotos. Tenta novamente erros de capacidade `429` e `529` indefinidamente em vez de falhar após `CLAUDE_CODE_MAX_RETRIES` tentativas. O Claude Code falha imediatamente quando uma requisição de velocidade padrão recebe um `429` que informa um limite de gastos ou créditos de uso esgotados, mesmo um vindo de um [limite de gastos do gateway](/docs/pt/errors#spend-limit-reached) que é redefinido segundo uma programação. Antes da v2.1.239, o watchdog tentava novamente esses erros indefinidamente. Para requisições no modo rápido, consulte [Lidar com rate limits](/docs/pt/fast-mode#handle-rate-limits). O watchdog aguarda até 5 minutos entre as tentativas, ou até que o limite seja redefinido quando a resposta traz um horário de redefinição do rate limit, para que uma sessão que atinge um limite de uso aguarde o restante da janela. Na v2.1.199 ou posterior, ele também aumenta a contagem padrão de novas tentativas para outros erros transitórios, como erros de servidor, timeouts e conexões interrompidas, para 300, aproximadamente três horas de backoff, e remove o limite de 15 em `CLAUDE_CODE_MAX_RETRIES` se você definir essa variável explicitamente. Requer Claude Code v2.1.186 ou posterior |380| `CLAUDE_CODE_RETRY_WATCHDOG` | Defina como `1` para sessões não supervisionadas, como harnesses de avaliação, jobs de CI ou workers remotos. Tenta novamente erros de capacidade `429` e `529` indefinidamente em vez de falhar após `CLAUDE_CODE_MAX_RETRIES` tentativas. O Claude Code falha imediatamente quando uma requisição de velocidade padrão recebe um `429` que informa um limite de gastos ou créditos de uso esgotados, mesmo um vindo de um [limite de gastos do gateway](/docs/pt/errors#spend-limit-reached) que é redefinido segundo uma programação. Antes da v2.1.239, o watchdog tentava novamente esses erros indefinidamente. Para requisições no modo rápido, consulte [Lidar com rate limits](/docs/pt/fast-mode#handle-rate-limits). O watchdog aguarda até 5 minutos entre as tentativas, ou até que o limite seja redefinido quando a resposta traz um horário de redefinição do rate limit, para que uma sessão que atinge um limite de uso aguarde o restante da janela. Na v2.1.199 ou posterior, ele também aumenta a contagem padrão de novas tentativas para outros erros transitórios, como erros de servidor, timeouts e conexões interrompidas, para 300, aproximadamente três horas de backoff, e remove o limite de 15 em `CLAUDE_CODE_MAX_RETRIES` se você definir essa variável explicitamente. Requer Claude Code v2.1.186 ou posterior |

381| `CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS` | Tempo máximo, em milissegundos, que cada requisição à API passa aguardando erros `429` e `529` quando `CLAUDE_CODE_RETRY_WATCHDOG` está definida. Depois que esse tempo se esgota, o próximo erro desse tipo encerra a requisição. Informe um número inteiro positivo em dígitos simples, como `1800000` para 30 minutos. Quando não definida, a espera não tem limite. Requer o Claude Code v2.1.295 ou posterior |

381| `CLAUDE_CODE_SAFE_MODE` | Defina como `1` para iniciar no modo de segurança: CLAUDE.md, skills, plugins, hooks, servidores MCP, comandos e agentes personalizados, estilos de saída, workflows, temas personalizados, atalhos de teclado personalizados, comandos da linha de status e de sugestão de arquivos, servidores LSP e memória automática não são carregados, para solucionar problemas de uma configuração quebrada. A política de configurações gerenciadas ainda se aplica, incluindo hooks, linha de status e comandos de sugestão de arquivos configurados por política; plugins gerenciados, skills gerenciadas, CLAUDE.md gerenciado e servidores MCP configurados por política não. Equivalente a passar [`--safe-mode`](/docs/pt/cli-reference#cli-flags). Processos filhos iniciados diretamente herdam a variável |382| `CLAUDE_CODE_SAFE_MODE` | Defina como `1` para iniciar no modo de segurança: CLAUDE.md, skills, plugins, hooks, servidores MCP, comandos e agentes personalizados, estilos de saída, workflows, temas personalizados, atalhos de teclado personalizados, comandos da linha de status e de sugestão de arquivos, servidores LSP e memória automática não são carregados, para solucionar problemas de uma configuração quebrada. A política de configurações gerenciadas ainda se aplica, incluindo hooks, linha de status e comandos de sugestão de arquivos configurados por política; plugins gerenciados, skills gerenciadas, CLAUDE.md gerenciado e servidores MCP configurados por política não. Equivalente a passar [`--safe-mode`](/docs/pt/cli-reference#cli-flags). Processos filhos iniciados diretamente herdam a variável |

382| `CLAUDE_CODE_SCRIPT_CAPS` | Objeto JSON que limita quantas vezes scripts específicos podem ser invocados por sessão quando `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` está definida. As chaves são substrings comparadas com o texto do comando; os valores são limites inteiros de chamadas. Por exemplo, `{"deploy.sh": 2}` permite que `deploy.sh` seja chamado no máximo duas vezes. A correspondência é baseada em substrings, então truques de expansão do shell como `./scripts/deploy.sh $(evil)` ainda contam para o limite. A multiplicação em tempo de execução via `xargs` ou `find -exec` não é detectada; este é um controle de defesa em profundidade |383| `CLAUDE_CODE_SCRIPT_CAPS` | Objeto JSON que limita quantas vezes scripts específicos podem ser invocados por sessão quando `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` está definida. As chaves são substrings comparadas com o texto do comando; os valores são limites inteiros de chamadas. Por exemplo, `{"deploy.sh": 2}` permite que `deploy.sh` seja chamado no máximo duas vezes. A correspondência é baseada em substrings, então truques de expansão do shell como `./scripts/deploy.sh $(evil)` ainda contam para o limite. A multiplicação em tempo de execução via `xargs` ou `find -exec` não é detectada; este é um controle de defesa em profundidade |

383| `CLAUDE_CODE_SCROLL_SPEED` | Define o multiplicador de rolagem da roda do mouse na [renderização em tela cheia](/docs/pt/fullscreen#mouse-wheel-scrolling). Aceita qualquer valor positivo até 20, incluindo valores fracionários abaixo de 1, como `0.5`, para desacelerar a rolagem acelerada do trackpad e da roda em terminais que já amplificam eventos da roda. Defina como `3` para corresponder ao `vim` se o seu terminal envia um evento da roda por entalhe sem amplificação. Ignorada no terminal do IDE JetBrains, onde o Claude Code usa seu próprio tratamento de rolagem |384| `CLAUDE_CODE_SCROLL_SPEED` | Define o multiplicador de rolagem da roda do mouse na [renderização em tela cheia](/docs/pt/fullscreen#mouse-wheel-scrolling). Aceita qualquer valor positivo até 20, incluindo valores fracionários abaixo de 1, como `0.5`, para desacelerar a rolagem acelerada do trackpad e da roda em terminais que já amplificam eventos da roda. Defina como `3` para corresponder ao `vim` se o seu terminal envia um evento da roda por entalhe sem amplificação. Ignorada no terminal do IDE JetBrains, onde o Claude Code usa seu próprio tratamento de rolagem |

590* Usar [a ferramenta advisor](/docs/pt/advisor#requirements)591* Usar [a ferramenta advisor](/docs/pt/advisor#requirements)

591* Ler ou responder a [comentários em um artefato](/docs/pt/artifacts#collect-comments-on-an-artifact)592* Ler ou responder a [comentários em um artefato](/docs/pt/artifacts#collect-comments-on-an-artifact)

592* Fazer o Claude ler [o artefato público de outra organização](/docs/pt/artifacts#read-an-artifact-shared-with-you)593* Fazer o Claude ler [o artefato público de outra organização](/docs/pt/artifacts#read-an-artifact-shared-with-you)

593* Fazer o Claude Code sondar servidores de conectores do claude.ai para a [revisão 2026-07-28 do protocolo MCP](/docs/pt/mcp#mcp-client-runtimes), a menos que você defina `MCP_PROTOCOL_NEGOTIATION=auto`

594* Obter a [ferramenta PowerShell](/docs/pt/tools-reference#powershell-tool) por padrão para contas do claude.ai e do Console no Windows com o Git Bash instalado; o Claude Code encaminha os comandos de shell pelo Git Bash, a menos que você defina `CLAUDE_CODE_USE_POWERSHELL_TOOL=1`. No Windows sem o Git Bash, a ferramenta permanece ativada594* Obter a [ferramenta PowerShell](/docs/pt/tools-reference#powershell-tool) por padrão para contas do claude.ai e do Console no Windows com o Git Bash instalado; o Claude Code encaminha os comandos de shell pelo Git Bash, a menos que você defina `CLAUDE_CODE_USE_POWERSHELL_TOOL=1`. No Windows sem o Git Bash, a ferramenta permanece ativada

595* Obter [feedback rascunhado pelo Claude](/docs/pt/tools-reference#sendfeedback-tool-behavior), que o Claude Code ativa por meio de uma flag buscada595* Obter [feedback rascunhado pelo Claude](/docs/pt/tools-reference#sendfeedback-tool-behavior), que o Claude Code ativa por meio de uma flag buscada

596* Fazer o Claude [tratar colagens grandes como texto colado em vez de digitado](/docs/pt/terminal-config#how-claude-treats-pasted-text); o conteúdo por trás de um placeholder `[Pasted text #N]` chega ao Claude sem marcação596* Fazer o Claude [tratar colagens grandes como texto colado em vez de digitado](/docs/pt/terminal-config#how-claude-treats-pasted-text); o conteúdo por trás de um placeholder `[Pasted text #N]` chega ao Claude sem marcação

errors.md +6 −9

Details

386* Um erro de servidor ou resposta sobrecarregada que chega depois que Claude terminou de pensar, mas antes de ter iniciado qualquer texto ou chamada de ferramenta. Claude Code tenta novamente um erro de servidor nesse ponto até duas vezes. Antes da v2.1.284, Claude Code encerrava o turno com o erro nesse ponto.386* Um erro de servidor ou resposta sobrecarregada que chega depois que Claude terminou de pensar, mas antes de ter iniciado qualquer texto ou chamada de ferramenta. Claude Code tenta novamente um erro de servidor nesse ponto até duas vezes. Antes da v2.1.284, Claude Code encerrava o turno com o erro nesse ponto.

387* Conexões perdidas. Quando uma conexão cai no meio de uma requisição antes de Claude ter completado qualquer parte de sua resposta, incluindo seu pensamento, Claude Code reemite a requisição com o mesmo backoff e o turno continua, mesmo que algum texto já tivesse começado a ser transmitido. Quando cai depois que Claude terminou de pensar mas antes de ter iniciado qualquer texto ou chamada de ferramenta, Claude Code em vez disso reemite a requisição até duas vezes em rápida sucessão, e encerra o turno com `Connection lost before a response was produced` se a conexão continuar caindo nesse ponto.387* Conexões perdidas. Quando uma conexão cai no meio de uma requisição antes de Claude ter completado qualquer parte de sua resposta, incluindo seu pensamento, Claude Code reemite a requisição com o mesmo backoff e o turno continua, mesmo que algum texto já tivesse começado a ser transmitido. Quando cai depois que Claude terminou de pensar mas antes de ter iniciado qualquer texto ou chamada de ferramenta, Claude Code em vez disso reemite a requisição até duas vezes em rápida sucessão, e encerra o turno com `Connection lost before a response was produced` se a conexão continuar caindo nesse ponto.

388* Uma conexão que Claude Code detecta que foi quebrada pelo seu computador entrando em modo de suspensão no meio de uma requisição. Claude Code a conta como uma conexão perdida sob as regras acima; uma vez que o rótulo de nova tentativa nomeia a razão específica, ele exibe `Connection lost while your computer was asleep`, e se o turno terminar depois que Claude terminou de pensar mas antes de qualquer texto ou chamada de ferramenta, a mensagem exibe `Your computer went to sleep before a response was produced`.388* Uma conexão que Claude Code detecta que foi quebrada pelo seu computador entrando em modo de suspensão no meio de uma requisição. Claude Code a conta como uma conexão perdida sob as regras acima; uma vez que o rótulo de nova tentativa nomeia a razão específica, ele exibe `Connection lost while your computer was asleep`, e se o turno terminar depois que Claude terminou de pensar mas antes de qualquer texto ou chamada de ferramenta, a mensagem exibe `Your computer went to sleep before a response was produced`.

389* Um fluxo de resposta travado, quando os cabeçalhos de resposta chegaram mas nenhuma parte da resposta do Claude chegou, ou quando Claude terminou de pensar mas não iniciou qualquer texto ou chamada de ferramenta: Claude Code aborta a conexão travada e reemite a requisição no máximo uma vez, fora do orçamento de 10 tentativas acima. Se a resposta travar uma segunda vez depois que Claude terminou de pensar mas antes de qualquer texto ou chamada de ferramenta, Claude Code encerra o turno com `The response stalled before a response was produced`.389* Um fluxo de resposta travado, quando os cabeçalhos de resposta chegaram mas nenhuma parte da resposta do Claude chegou, ou quando Claude terminou de pensar mas não iniciou qualquer texto ou chamada de ferramenta: Claude Code aborta a conexão travada e transmite a requisição novamente no máximo uma vez. Se a resposta travar uma segunda vez depois que Claude terminou de pensar mas antes de qualquer texto ou chamada de ferramenta, Claude Code encerra o turno com `The response stalled before a response was produced`.

390* Uma requisição de streaming que a API nunca responde com cabeçalhos de resposta, em uma conexão onde o [prazo de primeiro byte é executado](/docs/pt/network-config#streaming-idle-watchdogs): Claude Code a aborta no prazo e a reenvia no máximo uma vez por requisição de modelo, dentro do orçamento de tentativas, depois encerra o turno com [No response from API](#no-response-from-api) se essa tentativa também ficar sem resposta. Em outras conexões, a requisição aguarda `API_TIMEOUT_MS`. Quando você define `CLAUDE_CODE_RETRY_WATCHDOG`, o limite de uma nova tentativa não se aplica.390* Uma requisição de streaming que a API nunca responde com cabeçalhos de resposta, em uma conexão onde o [prazo de primeiro byte é executado](/docs/pt/network-config#streaming-idle-watchdogs): Claude Code a aborta no prazo e a reenvia no máximo uma vez por requisição de modelo, dentro do orçamento de tentativas, depois encerra o turno com [No response from API](#no-response-from-api) se essa tentativa também ficar sem resposta. Em outras conexões, a requisição aguarda `API_TIMEOUT_MS`. Quando você define `CLAUDE_CODE_RETRY_WATCHDOG`, o limite de uma nova tentativa não se aplica.

391* Uma resposta de streaming que o filtro de conteúdo de saída da API interrompe antes de Claude ter terminado de pensar ou iniciado qualquer texto ou chamada de ferramenta. Claude Code reenvia a requisição uma vez, dentro do orçamento de tentativas, e mostra [Output blocked by content filtering policy](#output-blocked-by-content-filtering-policy) se o filtro também interromper a segunda resposta.391* Uma resposta de streaming que o filtro de conteúdo de saída da API interrompe antes de Claude ter terminado de pensar ou iniciado qualquer texto ou chamada de ferramenta. Claude Code reenvia a requisição uma vez, dentro do orçamento de tentativas, e mostra [Output blocked by content filtering policy](#output-blocked-by-content-filtering-policy) se o filtro também interromper a segunda resposta.

392* Throttles 429 temporários, mas não o `429` de limite de gastos de um gateway, que não é um throttle; veja [Spend limit reached](#spend-limit-reached).392* Throttles 429 temporários, mas não o `429` de limite de gastos de um gateway, que não é um throttle; veja [Spend limit reached](#spend-limit-reached).

4064 Marketplace is already added from a different source4064 Marketplace is already added from a different source

4065</h3>4065</h3>

4066 4066

4067Você confirmou adicionar um marketplace através de [`/plugin install <plugin> --marketplace <source>`](/docs/pt/plugins/install#add-a-marketplace-and-install-in-one-command), e o catálogo que Claude Code buscou dessa fonte nomeia a si mesmo igual a um marketplace que você já adicionou de uma fonte diferente. Claude Code mantém o marketplace existente em vez de substituí-lo, e o plugin não é instalado.4067Você indicou uma nova fonte de marketplace com [`--marketplace <source>` no comando de instalação](/docs/pt/plugins/install#add-a-marketplace-and-install-in-one-command), em uma sessão ou a partir do seu shell. O catálogo que Claude Code buscou dessa fonte tem o mesmo nome de um marketplace que você já adicionou de uma fonte diferente. Claude Code mantém o marketplace existente em vez de substituí-lo, e o plugin não é instalado.

4068 4068

4069```text theme={null}4069```text theme={null}

4070Marketplace "acme-tools" is already added from a different source (github:acme/plugins). To use this source instead, remove that marketplace first with /plugin marketplace remove acme-tools.4070Marketplace "acme-tools" is already added from a different source (github:acme/plugins). To use this source instead, remove that marketplace first with /plugin marketplace remove acme-tools.

4079 Plugin command references user\_config in a shell command4079 Plugin command references user\_config in a shell command

4080</h3>4080</h3>

4081 4081

4082Um hook de plugin, [monitor](/docs/pt/plugins/components#monitors), ou comando MCP [`headersHelper`](/docs/pt/mcp#use-dynamic-headers-for-custom-authentication) referencia uma opção de plugin `${user_config.KEY}` [plugin option](/docs/pt/plugins/manifest-reference#user-configuration), e a string substituída seria passada para um shell. Um valor configurado contendo `$(...)`, backticks, ou `;` seria executado como código lá, então Claude Code recusa iniciar o componente em vez de substituir o valor. A verificação é executada no modelo de comando, então o erro aparece mesmo quando nenhum valor está configurado ainda. Antes da v2.1.207, o valor era substituído no comando shell.4082Um hook de plugin, [monitor](/docs/pt/plugins/components#monitors), ou comando MCP [`headersHelper`](/docs/pt/mcp#use-dynamic-headers-for-custom-authentication) referencia uma `${user_config.KEY}` [opção de plugin](/docs/pt/plugins/manifest-reference#user-configuration), e a string substituída seria passada para um shell. Um valor configurado contendo `$(...)`, backticks, ou `;` seria executado como código lá, então Claude Code recusa iniciar o componente em vez de substituir o valor. A verificação é executada no modelo de comando, então o erro aparece mesmo quando nenhum valor está configurado ainda. Antes da v2.1.207, o valor era substituído no comando shell.

4083 4083

4084A redação depende de qual superfície referenciou a opção. Um hook de forma shell relata:4084A redação depende de qual superfície referenciou a opção. Um hook de forma shell relata:

4085 4085

4226 4226

4227Claude Code mantém os marketplaces de plugin que você adicionou em um arquivo de registro em `~/.claude/plugins/known_marketplaces.json`. Um comando de plugin que precisa do registro, como `claude plugin install`, falha com uma de duas mensagens quando Claude Code não consegue usar o arquivo:4227Claude Code mantém os marketplaces de plugin que você adicionou em um arquivo de registro em `~/.claude/plugins/known_marketplaces.json`. Um comando de plugin que precisa do registro, como `claude plugin install`, falha com uma de duas mensagens quando Claude Code não consegue usar o arquivo:

4228 4228

4229* `Failed to load marketplace configuration`: o arquivo não é JSON válido, ou não pode ser lido. Um arquivo vazio falha dessa forma também.4229* `Failed to load marketplace configuration`: o arquivo existe, mas não é JSON válido ou não pode ser lido. Um arquivo vazio falha dessa forma também.

4230* `Marketplace configuration file is corrupted`: o arquivo é JSON válido mas seu conteúdo não corresponde ao esquema do registro.4230* `Marketplace configuration file is corrupted`: o arquivo é JSON válido mas seu conteúdo não corresponde ao esquema do registro.

4231 4231

4232Um arquivo ausente não é uma falha: Claude Code o trata como um registro sem marketplaces.

~~4233~~

4234Com um arquivo vazio, `claude plugin install` relata:4232Com um arquivo vazio, `claude plugin install` relata:

4235 4233

4236```text theme={null}4234```text theme={null}

4819 Esta sessão não tem transcrição salva4817 Esta sessão não tem transcrição salva

4820</h3>4818</h3>

4821 4819

4822Você conectou a uma [sessão em background](/docs/pt/agent-view) parada que foi colocada em background de outra conversa com `←` ou `/background` e parada antes de sua primeira resposta terminar. Até que essa primeira resposta termine, a conversa ainda vive apenas na sessão de onde foi colocada em background, portanto `claude attach` recusa iniciar a sessão parada em vez de começar uma conversa em branco sob o mesmo ID de sessão. A mensagem termina com o comando `claude respawn` para esta sessão:4820Você se conectou a uma sessão que você [moveu para background](/docs/pt/agent-view#from-inside-a-session) com `←` ou `/background` e que parou antes de executar um turno próprio. Claude Code não conseguiu encontrar a conversa de onde você a moveu, portanto a sessão não tem nada para retomar. A mensagem termina com o comando `claude respawn` para esta sessão:

4823 4821

4824```text theme={null}4822```text theme={null}

4825This session has no saved transcript — it was stopped before its first response finished. If it was backgrounded from another conversation, that one is still intact; `claude respawn <id>` starts this one fresh.4823This session has no saved transcript — it was stopped before its first response finished. If it was backgrounded from another conversation, that one is still intact; `claude respawn <id>` starts this one fresh.

4829 4827

4830**O que fazer:**4828**O que fazer:**

4831 4829

4832* A conversa que você colocou em background está intacta: retome-a com [`claude --resume`](/docs/pt/sessions) ou continue trabalhando nela4830* Para iniciar a sessão parada do zero, execute `claude respawn <id>` com o ID da mensagem, ou pressione `Enter` duas vezes na sua linha na agent view

4833* Para iniciar a sessão parada do zero mesmo assim, execute `claude respawn <id>` com o ID da mensagem, ou pressione `Enter` duas vezes na sua linha na agent view

4834* Se a sessão terminou uma resposta e você ainda vê essa recusa em uma versão anterior à v2.1.214, uma pasta ilegível em `~/.claude/projects` poderia fazer a varredura de transcrição perder a conversa salva; atualize para v2.1.214 ou posterior, que tolera pastas ilegíveis durante a varredura4831* Se a sessão terminou uma resposta e você ainda vê essa recusa em uma versão anterior à v2.1.214, uma pasta ilegível em `~/.claude/projects` poderia fazer a varredura de transcrição perder a conversa salva; atualize para v2.1.214 ou posterior, que tolera pastas ilegíveis durante a varredura

4835 4832

4836<h3 id="this-session-is-running-in-another-terminal">4833<h3 id="this-session-is-running-in-another-terminal">

glossary.md +1 −1

Details

511 Worktree isolation511 Worktree isolation

512</h3>512</h3>

513 513

514Um modo de isolamento que executa Claude em um git worktree separado em `.claude/worktrees/`, habilitado com a flag `-w` ou `isolation: worktree` na config de subagent. Alterações ficam em um branch separado em um diretório separado, para que agentes paralelos não sobrescrevam os arquivos uns dos outros.514Um modo de isolamento que executa Claude em um git worktree separado em `.claude/worktrees/`, habilitado com a flag `-w` ou `isolation: worktree` na config de subagente. Alterações ficam em um branch separado em um diretório separado, para que cada agente paralelo edite sua própria cópia dos arquivos.

515 515

516Saiba mais: [Run parallel sessions with git worktrees](/docs/pt/worktrees)516Saiba mais: [Run parallel sessions with git worktrees](/docs/pt/worktrees)

517 517

goal.md +1 −1

Details

127claude -p "/goal CHANGELOG.md has an entry for every PR merged this week"127claude -p "/goal CHANGELOG.md has an entry for every PR merged this week"

128```128```

129 129

130Com a saída de texto padrão, nada é impresso até que a execução termine, portanto um objetivo que executa muitos turnos pode parecer travado. Adicione `--output-format stream-json --verbose` para emitir cada mensagem conforme o loop é executado.130Com a saída de texto padrão, a resposta final de Claude é impressa quando o loop termina, portanto um objetivo que executa muitos turnos pode parecer travado. Adicione `--output-format stream-json --verbose` para emitir cada mensagem conforme o loop é executado.

131 131

132Interrompa o processo com Ctrl+C para parar um objetivo não interativo antes que ele seja resolvido.132Interrompa o processo com Ctrl+C para parar um objetivo não interativo antes que ele seja resolvido.

133 133

headless.md +16 −14

Details

20 Uso básico20 Uso básico

21</h2>21</h2>

22 22

23Adicione o sinalizador `-p` (ou `--print`) a qualquer comando `claude` para executá-lo de forma não interativa. Nem todas as [opções de CLI](/docs/pt/cli-reference) se combinam com `-p`. Claude Code rejeita `--bg` e rejeita `--cloud` com uma descrição de tarefa, com um erro nomeando o conflito; `--cloud` com um ID de sessão e `-p` em vez disso [enfileira uma mensagem nessa sessão na nuvem](/docs/pt/claude-code-on-the-web#send-follow-ups-from-the-cli) e sai. As opções que você combinará com `-p` geralmente incluem:23Adicione a flag `-p` (ou `--print`) a qualquer comando `claude` para executá-lo de forma não interativa. Nem todas as [opções de CLI](/docs/pt/cli-reference) se combinam com `-p`. Claude Code rejeita `--bg` e rejeita `--cloud` com uma descrição de tarefa, com um erro nomeando o conflito; `--cloud` com um ID de sessão e `-p` em vez disso [enfileira uma mensagem nessa sessão na nuvem](/docs/pt/claude-code-on-the-web#send-follow-ups-from-the-cli) e sai. As opções que você combinará com `-p` geralmente incluem:

24 24

25* `--continue` para [continuar conversas](#continue-conversations)25* `--continue` para [continuar conversas](#continue-conversations)

26* `--allowedTools` para [aprovar ferramentas automaticamente](#auto-approve-tools)26* `--allowedTools` para [aprovar ferramentas automaticamente](#auto-approve-tools)

32claude -p "What does the auth module do?"32claude -p "What does the auth module do?"

33```33```

34 34

35Claude Code sai com código 0 em caso de sucesso e com um código diferente de zero quando a execução falha, para que seus scripts possam ramificar no status de saída. Se você passar um sinalizador inválido, Claude Code relata o erro para stderr antes do início da execução. Quando uma falha ocorre dentro da execução, como autenticação ausente, Claude Code imprime a falha como resultado em stdout.35Claude Code sai com código 0 em caso de sucesso e com um código diferente de zero quando a execução falha, para que seus scripts possam tomar decisões com base no status de saída. Se você passar uma flag inválida, Claude Code relata o erro para stderr antes do início da execução. Quando uma falha ocorre dentro da execução, como autenticação ausente, Claude Code imprime a falha como resultado em stdout.

36 36

37<h3 id="start-faster-with-bare-mode">37<h3 id="start-faster-with-bare-mode">

38 Comece mais rápido com modo bare38 Comece mais rápido com modo bare

39</h3>39</h3>

40 40

41Adicione `--bare` para reduzir o tempo de inicialização pulando a descoberta automática de hooks, skills, comandos personalizados, [subagentos](/docs/pt/sub-agents), plugins instalados, servidores MCP, memória automática e CLAUDE.md. Sem ele, `claude -p` carrega o mesmo [contexto](/docs/pt/how-claude-code-works#the-context-window) que uma sessão interativa carregaria, incluindo qualquer coisa configurada no diretório de trabalho ou `~/.claude`.41Adicione `--bare` para reduzir o tempo de inicialização pulando a descoberta automática de hooks, skills, comandos personalizados, [subagentes](/docs/pt/sub-agents), plugins instalados, servidores MCP, memória automática e CLAUDE.md. Sem ele, `claude -p` carrega o mesmo [contexto](/docs/pt/how-claude-code-works#the-context-window) que uma sessão interativa carregaria, incluindo qualquer coisa configurada no diretório de trabalho ou `~/.claude`.

42 42

43O modo bare é útil para CI e scripts onde você precisa do mesmo resultado em cada máquina. Um hook no `~/.claude` de um colega de trabalho ou um servidor MCP no `.mcp.json` do projeto não serão executados, porque o modo bare nunca os lê. Um diretório que você nomeia com `--add-dir` é uma exceção parcial: o modo bare carrega skills de sua pasta `.claude/skills/`, mas ainda pula suas pastas `.claude/commands/` e `.claude/agents/`. [Skills de diretórios adicionais](/docs/pt/skills#skills-from-additional-directories) cobre o que carrega e o que não carrega.43O modo bare é útil para CI e scripts onde você precisa do mesmo resultado em cada máquina. Um hook no `~/.claude` de um colega de trabalho ou um servidor MCP no `.mcp.json` do projeto não serão executados, porque o modo bare nunca os lê. Um diretório que você nomeia com `--add-dir` é uma exceção parcial: o modo bare carrega skills de sua pasta `.claude/skills/`, mas ainda pula suas pastas `.claude/commands/` e `.claude/agents/`. [Skills de diretórios adicionais](/docs/pt/skills#skills-from-additional-directories) cobre o que carrega e o que não carrega.

44 44

45Sem `--bare`, uma sessão `-p` executa os hooks no `settings.json` de um projeto e conecta os servidores em seu `.mcp.json`, mesmo em uma pasta que você nunca confiou. Uma sessão `-p` não mostra nenhum diálogo de confiança de workspace e nenhum prompt de aprovação por servidor. [O que é executado antes de você confiar em uma pasta](/docs/pt/permissions#what-runs-before-you-trust-a-folder) cobre cada tipo de conteúdo de repositório sob `-p` e como mantê-lo fora.45Sem `--bare`, uma sessão `-p` executa os hooks no `.claude/settings.json` de um projeto e conecta os servidores em seu `.mcp.json`, mesmo em uma pasta que você nunca confiou. Uma sessão `-p` não mostra nenhum diálogo de confiança de workspace e nenhum prompt de aprovação por servidor. [O que é executado antes de você confiar em uma pasta](/docs/pt/permissions#what-runs-before-you-trust-a-folder) cobre cada tipo de conteúdo de repositório sob `-p` e como mantê-lo fora.

46 46

47Este exemplo executa uma tarefa de resumo única em modo bare e pré-aprova a ferramenta Read para que a chamada seja concluída sem um prompt de permissão. Defina `ANTHROPIC_API_KEY` antes de executá-lo, porque o modo bare não usa seu login de assinatura:47Este exemplo executa uma tarefa de resumo única em modo bare e pré-aprova a ferramenta Read para que a chamada seja concluída sem um prompt de permissão. Defina `ANTHROPIC_API_KEY` antes de executá-lo, porque o modo bare não usa seu login de assinatura:

48 48

52 52

53No modo bare, Claude Code nunca lê credenciais OAuth ou o keychain do sistema. Para a API Anthropic, defina `ANTHROPIC_API_KEY` no ambiente, com uma chave criada no [Claude Console](https://platform.claude.com), ou forneça um `apiKeyHelper` no JSON `--settings`. Amazon Bedrock, Google Cloud's Agent Platform e Microsoft Foundry continuam a ler suas próprias credenciais de provedor como de costume.53No modo bare, Claude Code nunca lê credenciais OAuth ou o keychain do sistema. Para a API Anthropic, defina `ANTHROPIC_API_KEY` no ambiente, com uma chave criada no [Claude Console](https://platform.claude.com), ou forneça um `apiKeyHelper` no JSON `--settings`. Amazon Bedrock, Google Cloud's Agent Platform e Microsoft Foundry continuam a ler suas próprias credenciais de provedor como de costume.

54 54

~~55No modo bare Claude tem acesso às ferramentas Bash, leitura de arquivo e edição de arquivo. Passe qualquer contexto que você precise com um sinalizador:~~55No modo bare Claude tem acesso às ferramentas Bash, leitura de arquivo e edição de arquivo. Passe qualquer contexto que você precise com uma flag:

56 56

57| Para carregar | Use |57| Para carregar | Use |

58| - | - |58| - | - |

60| Configurações | `--settings <file-or-json>` |60| Configurações | `--settings <file-or-json>` |

61| Servidores MCP | `--mcp-config <file-or-json>` |61| Servidores MCP | `--mcp-config <file-or-json>` |

62| [Agentes personalizados](/docs/pt/sub-agents#choose-the-subagent-scope) | `--agents <file-or-json>` |62| [Agentes personalizados](/docs/pt/sub-agents#choose-the-subagent-scope) | `--agents <file-or-json>` |

84 84

85A execução aguarda trabalho em segundo plano, como comandos em segundo plano, subagentes e fluxos de trabalho, observações do Monitor e despertares pendentes do `/loop`:85A execução aguarda trabalho em segundo plano, como comandos em segundo plano, subagentes e fluxos de trabalho, observações do Monitor e despertares pendentes do `/loop`:

86 86

87* **[Comandos em segundo plano](/docs/pt/tools-reference#background-commands)**: para um comando que a conversa principal iniciou, por exemplo um servidor de desenvolvimento ou um build em modo de observação, a execução aguarda até que o comando saia ou atinja seu [limite de tempo](/docs/pt/tools-reference#time-limit-for-background-commands). Claude então faz mais um turno com o resultado, e o resultado desse turno se torna o último da execução, que é o que as saídas `text` e `json` imprimem. Enquanto o comando é executado, o limite de 10 minutos não encerra a espera.87* **[Comandos em segundo plano](/docs/pt/tools-reference#background-commands)**: para um comando que a conversa principal iniciou, por exemplo um servidor de desenvolvimento ou um build em modo de observação, a execução aguarda até que o comando saia ou atinja seu [limite de tempo](/docs/pt/tools-reference#time-limit-for-background-commands). Claude então faz mais um turno com o resultado. Enquanto o comando é executado, o limite de 10 minutos não encerra a espera.

88* **[Subagentes](/docs/pt/sub-agents) e fluxos de trabalho em segundo plano**: a execução permanece aberta até que esse trabalho seja concluído, porque seu resultado faz parte da saída final.88* **[Subagentes](/docs/pt/sub-agents) e fluxos de trabalho em segundo plano**: a execução permanece aberta até que esse trabalho seja concluído, porque seu resultado faz parte da saída final.

89* **Observações do [Monitor](/docs/pt/tools-reference#monitor-tool)**: a execução aguarda até que a observação expire ou o limite de 10 minutos encerre a espera, o que vier primeiro. Enquanto aguarda, Claude continua respondendo ao que a observação relata. Por padrão, uma observação expira cinco minutos após Claude iniciá-la.89* **Observações do [Monitor](/docs/pt/tools-reference#monitor-tool)**: a execução aguarda até que a observação atinja o timeout ou o limite de 10 minutos encerre a espera, o que vier primeiro. Enquanto aguarda, Claude continua respondendo ao que a observação relata. Por padrão, uma observação atinge o timeout cinco minutos após Claude iniciá-la.

90* **Despertares pendentes**: em uma execução cujo prompt você passou como texto em vez de com `--input-format stream-json`, quando Claude agendou um [despertar de `/loop` com ritmo próprio](/docs/pt/scheduled-tasks#let-claude-choose-the-interval), a execução aguarda cada despertar disparar e executa sua iteração até que o [loop termine](/docs/pt/scheduled-tasks#stop-a-loop), mesmo além do limite de 10 minutos.90* **Despertares pendentes**: em uma execução cujo prompt você passou como texto em vez de com `--input-format stream-json`, quando Claude agendou um [despertar de `/loop` com ritmo próprio](/docs/pt/scheduled-tasks#let-claude-choose-the-interval), a execução aguarda cada despertar disparar e executa sua iteração até que o [loop termine](/docs/pt/scheduled-tasks#stop-a-loop), mesmo além do limite de 10 minutos.

91 91

92Se a execução atingir seu limite de [`--max-budget-usd`](/docs/pt/cli-reference#cli-flags), Claude Code para o trabalho em segundo plano restante em vez de aguardar.92Se a execução atingir seu limite de [`--max-budget-usd`](/docs/pt/cli-reference#cli-flags), Claude Code para o trabalho em segundo plano restante em vez de aguardar.

93 93

94Quando o trabalho em segundo plano inicia outro turno, a execução imprime o resultado de cada turno com a saída `text` padrão e o resultado do último turno com a saída `json`. Antes da v2.1.295, a execução imprimia apenas o resultado do último turno também com a saída `text`.

94<h3 id="stop-a-run-with-sigterm">96<h3 id="stop-a-run-with-sigterm">

95 Parar uma execução com SIGTERM97 Parar uma execução com SIGTERM

96</h3>98</h3>

97 99

98Se você parar uma execução de `claude -p` com SIGTERM, por exemplo com `kill` ou de um supervisor de processo, Claude Code sai com código 143. Claude Code deixa a volta que estava em progresso inacabada e não registra nenhum resultado para ela. Para encerrar a volta em vez disso, envie SIGINT ou chame `interrupt()` do Agent SDK, antes de parar o processo.100Se você parar uma execução de `claude -p` com SIGTERM, por exemplo com `kill` ou de um supervisor de processo, Claude Code sai com código 143. Claude Code deixa o turno que estava em progresso inacabado e não registra nenhum resultado para ele. Para encerrar o turno em vez disso, envie SIGINT ou chame `interrupt()` do Agent SDK, antes de parar o processo.

99 101

100No SIGTERM, Claude Code encerra a árvore de processos de qualquer comando Bash que ainda está em execução. Claude Code então executa [hooks `SessionEnd`](/docs/pt/hooks#sessionend) e sai. Ao sair, Claude Code não inicia nenhuma nova chamada de ferramenta, não envia nenhuma nova solicitação de modelo e não executa nenhum hook além de `SessionEnd`. Se a execução estava no meio de um comando ou aguardando uma resposta a um prompt de permissão quando o sinal chegou, Claude Code trata essa etapa da seguinte forma:102No SIGTERM, Claude Code encerra a árvore de processos de qualquer comando Bash que ainda está em execução. Claude Code então executa [hooks `SessionEnd`](/docs/pt/hooks#sessionend) e sai. Ao sair, Claude Code não inicia nenhuma nova chamada de ferramenta, não envia nenhuma nova requisição ao modelo e não executa nenhum hook além de `SessionEnd`. Se a execução estava no meio de um comando ou aguardando um prompt de permissão quando o sinal chegou, Claude Code trata essa etapa da seguinte forma:

101 103

102* **Executando um comando**: Claude Code registra o comando como eliminado na sessão.104* **Executando um comando**: Claude Code registra o comando como eliminado na sessão.

103* **Aguardando uma resposta a um prompt de permissão**: se você enviar SIGTERM para o processo, Claude Code deixa o prompt sem resposta. Se seu programa fechar a sessão através do Agent SDK, o SDK encerra a entrada de Claude Code antes de enviar qualquer sinal, e Claude Code cancela o prompt assim que a entrada termina.105* **Aguardando uma resposta a um prompt de permissão**: se você enviar SIGTERM para o processo, Claude Code deixa o prompt sem resposta. Se seu programa fechar a sessão através do Agent SDK, o SDK encerra a entrada de Claude Code antes de enviar qualquer sinal, e Claude Code cancela o prompt assim que a entrada termina.

104 106

105Quando você [retoma a sessão](#continue-conversations), Claude Code deixa a volta que estava em progresso inacabada e seu próximo prompt conduz a conversa. Para fazer com que Claude Code continue a volta inacabada ao retomar, defina [`CLAUDE_CODE_RESUME_INTERRUPTED_TURN=1`](/docs/pt/env-vars).107Quando você [retoma a sessão](#continue-conversations), Claude Code deixa o turno interrompido como está, e seu próximo prompt conduz a conversa. Para fazer com que Claude Code continue o turno interrompido ao retomar, defina [`CLAUDE_CODE_RESUME_INTERRUPTED_TURN=1`](/docs/pt/env-vars).

106 108

107<h3 id="if-the-working-directory-is-deleted">109<h3 id="if-the-working-directory-is-deleted">

108 Se o diretório de trabalho for excluído110 Se o diretório de trabalho for excluído

109</h3>111</h3>

110 112

111Se o diretório de trabalho de uma sessão `claude -p` ou Agent SDK for excluído durante a sessão, a sessão continua em execução. Quando uma volta começa enquanto o diretório está faltando, Claude Code emite uma [mensagem de aviso](/docs/pt/agent-sdk/typescript#sdkinformationalmessage) na saída `stream-json`, e os comandos shell falham até que o diretório exista novamente.113Se o diretório de trabalho de uma sessão `claude -p` ou Agent SDK for excluído durante a sessão, a sessão continua em execução. Quando um turno começa enquanto o diretório está faltando, Claude Code emite uma [mensagem de aviso](/docs/pt/agent-sdk/typescript#sdkinformationalmessage) na saída `stream-json`, e os comandos shell falham até que o diretório exista novamente.

112 114

113<h2 id="examples">115<h2 id="examples">

114 Exemplos116 Exemplos

268| `no_response` | objeto, opcional | presente apenas quando a tentativa falhada obteve [nenhum cabeçalho de resposta a tempo](/docs/pt/errors#no-response-from-api). `waited_ms` é quanto tempo essa tentativa aguardou e `retry_wait_ms` é quanto tempo a repetição aguardará. Nesses eventos, `max_retries` reflete a uma repetição que essa causa normalmente obtém, não o orçamento de toda a sessão. Requer Claude Code v2.1.261 ou posterior |270| `no_response` | objeto, opcional | presente apenas quando a tentativa falhada obteve [nenhum cabeçalho de resposta a tempo](/docs/pt/errors#no-response-from-api). `waited_ms` é quanto tempo essa tentativa aguardou e `retry_wait_ms` é quanto tempo a repetição aguardará. Requer Claude Code v2.1.261 ou posterior |

269| `error` | string | categoria de erro: `authentication_failed`, `oauth_org_not_allowed`, `account_on_hold`, `billing_error`, `rate_limit`, `overloaded`, `invalid_request`, `model_not_found`, `server_error`, `max_output_tokens`, `cloud_credential_error`, ou `unknown` |271| `error` | string | categoria de erro: `authentication_failed`, `oauth_org_not_allowed`, `account_on_hold`, `billing_error`, `rate_limit`, `overloaded`, `invalid_request`, `model_not_found`, `server_error`, `max_output_tokens`, `cloud_credential_error`, ou `unknown` |

hooks.md +19 −8

Details

1237 Controle de decisão do SessionStart1237 Controle de decisão do SessionStart

1238</h4>1238</h4>

1239 1239

1240O Claude Code adiciona ao contexto do Claude o stdout que ele [trata como texto simples](#exit-code-0). Além dos [campos de saída JSON](#json-output) disponíveis para todos os hooks, você pode retornar estes campos específicos do evento:1240Um hook SessionStart pode adicionar contexto para o Claude, fornecer a primeira mensagem do usuário, definir o título da sessão, observar arquivos e recarregar skills. Retorne o campo correspondente a cada um, além dos [campos de saída JSON](#json-output) disponíveis para todos os hooks:

1241 1241

1242| Campo | Descrição |1242| Campo | Descrição |

1243| :- | :- |1243| :- | :- |

1244| `additionalContext` | String adicionada ao contexto do Claude no início da conversa, antes do primeiro prompt. Consulte [Adicionar contexto para o Claude](#add-context-for-claude) para saber como o texto é entregue e o que colocar nele |1244| `additionalContext` | String adicionada ao contexto do Claude no início da conversa, antes do primeiro prompt. Consulte [Adicionar contexto para o Claude](#add-context-for-claude) para saber como o texto é entregue e o que colocar nele |

1245| `initialUserMessage` | String usada como a primeira mensagem do usuário da sessão. Aplica-se no [modo não interativo](/docs/pt/headless) com a flag `-p`, onde se torna o primeiro turno mesmo que nenhum prompt seja fornecido. Se um prompt for fornecido, ele vem como o próximo turno. Ao contrário de `additionalContext`, que se anexa a um turno existente, isto cria o turno |1245| `initialUserMessage` | String usada como a primeira mensagem do usuário da sessão, no [modo não interativo](/docs/pt/headless) com a flag `-p`. Ela se torna o primeiro turno mesmo que você não passe nenhum prompt. Um prompt que você passar vem em seguida como o próximo turno |

1246| `sessionTitle` | Define o título da sessão, com o mesmo efeito de `/rename`. Use para nomear sessões automaticamente a partir da pasta de inicialização, do branch do git ou do nome do worktree. Aplica-se quando `source` é `"startup"`, `"resume"` ou `"fork"`; ignorado em `"clear"` e `"compact"` |1246| `sessionTitle` | Define o título da sessão, com o mesmo efeito de `/rename`. Aplica-se quando `source` é `"startup"`, `"resume"` ou `"fork"` |

1248| `reloadSkills` | Booleano. Quando `true`, o Claude Code examina novamente os diretórios de [skills](/docs/pt/skills) e comandos após a conclusão dos hooks SessionStart, para que as skills instaladas pelo hook fiquem disponíveis na mesma sessão, a partir do primeiro prompt |1248| `reloadSkills` | Booleano. Quando `true`, o Claude Code verifica novamente os diretórios de [skills](/docs/pt/skills) e comandos após a conclusão dos hooks SessionStart. Consulte [Recarregar skills que um hook instala](#reload-skills-that-a-hook-installs) |

1249

1250Esta saída adiciona contexto e nomeia a sessão:

1249 1251

1250```json theme={null}1252```json theme={null}

1251{1253{

1257}1259}

1258```1260```

1259 1261

1260Como o stdout simples já chega ao Claude neste evento, um hook que apenas carrega contexto pode imprimir diretamente no stdout sem montar JSON. Use o formato JSON quando precisar combinar contexto com outros campos, como `sessionTitle`.1262Um hook que apenas adiciona contexto pode imprimi-lo sem construir JSON, porque o Claude Code adiciona o [stdout em texto simples](#exit-code-0) de um hook SessionStart ao contexto do Claude.

1263

1264Se o hook SessionStart do seu plugin fornecer `initialUserMessage` ou `sessionTitle`, instale o plugin antes de a sessão começar. O Claude Code ignora ambos os campos de um plugin cuja instalação termina depois que os hooks SessionStart já foram executados.

1265

1266<h4 id="reload-skills-that-a-hook-installs">

1267 Recarregar skills que um hook instala

1268</h4>

1269

1270Para disponibilizar na mesma sessão as skills que um hook SessionStart instala, retorne `reloadSkills`. A descoberta de skills normalmente é executada antes de os hooks SessionStart terminarem, então, sem isso, arquivos que um hook grava em `~/.claude/skills/` ou `.claude/skills/` podem estar ausentes quando o primeiro prompt for executado.

1261 1271

1262Use `reloadSkills` quando um hook SessionStart instalar ou atualizar skills. A descoberta de skills normalmente é executada antes de os hooks SessionStart terminarem, então arquivos que o hook grava em `~/.claude/skills/` ou `.claude/skills/` só apareceriam na próxima sessão. Este exemplo sincroniza um repositório de skills compartilhado e solicita a nova varredura:1272Este exemplo sincroniza um repositório compartilhado de skills e solicita a nova verificação:

1263 1273

1264```bash theme={null}1274```bash theme={null}

1265#!/bin/bash1275#!/bin/bash

1270echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "reloadSkills": true}}'1280echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "reloadSkills": true}}'

1271```1281```

1272 1282

1273A URL do repositório é um espaço reservado; substitua-a pelo seu próprio repositório de skills. Com o espaço reservado, o clone falha e imprime uma mensagem `fatal:` no stderr. O stderr de um hook SessionStart que sai com 0 é apenas informativo, portanto a solicitação de `reloadSkills` ainda se aplica.1283A URL do repositório é um espaço reservado. Substitua-a pelo seu próprio repositório de skills.

1274 1284

1275<h4 id="persist-environment-variables">1285<h4 id="persist-environment-variables">

1276 Persistir variáveis de ambiente1286 Persistir variáveis de ambiente

1860| :- | :- | :- | :- |1870| :- | :- | :- | :- |

1863 1874

1864<h5 id="websearch">1875<h5 id="websearch">

1865 WebSearch1876 WebSearch

4279Hooks assíncronos têm restrições adicionais comparados a hooks síncronos:4290Hooks assíncronos têm restrições adicionais comparados a hooks síncronos:

4280 4291

4281* Saída de hook é entregue no próximo turno de conversa. Se a sessão está ociosa, a resposta espera até a próxima interação do usuário. Exceção: um hook `asyncRewake` que sai com código 2 acorda Claude imediatamente mesmo quando a sessão está ociosa.4292* Saída de hook é entregue no próximo turno de conversa. Se a sessão está ociosa, a resposta espera até a próxima interação do usuário. Exceção: um hook `asyncRewake` que sai com código 2 acorda Claude imediatamente mesmo quando a sessão está ociosa.

4282* Cada execução cria um processo em background separado. Não há desduplicação através de múltiplos disparos do mesmo hook assíncrono.4293* Cada execução cria um processo em background separado.

4283 4294

4284<h2 id="security-considerations">4295<h2 id="security-considerations">

4285 Considerações de segurança4296 Considerações de segurança

mcp.md +1 −1

Details

367 367

368No v2, Claude Code também:368No v2, Claude Code também:

369 369

370* Pergunta aos servidores HTTP e stdio se eles suportam a revisão mais recente, e a usa com aqueles que suportam. Em sessões onde ele busca sinalizadores de recurso, ele também pergunta aos servidores conectores claude.ai. Ele se conecta a todos os outros servidores como v1 faz.370* Pergunta aos servidores HTTP, stdio e conectores claude.ai se eles suportam a revisão mais recente, e a usa com aqueles que suportam. Ele se conecta a todos os outros servidores como v1 faz.

371* Recebe notificações `list_changed` de servidores na revisão mais recente sobre um [stream que mantém aberto](#notification-streams-on-the-v2-runtime).371* Recebe notificações `list_changed` de servidores na revisão mais recente sobre um [stream que mantém aberto](#notification-streams-on-the-v2-runtime).

372* Não registra um servidor de [canal](#push-messages-with-channels) que se conecta na revisão mais recente, porque essa revisão não pode carregar mensagens de canal.372* Não registra um servidor de [canal](#push-messages-with-channels) que se conecta na revisão mais recente, porque essa revisão não pode carregar mensagens de canal.

373* Falha em um [login OAuth MCP](#authenticate-with-remote-mcp-servers) cuja resposta de autorização nomeia um emissor inesperado.373* Falha em um [login OAuth MCP](#authenticate-with-remote-mcp-servers) cuja resposta de autorização nomeia um emissor inesperado.

monitoring-usage.md +9 −3

Details

599 599

600Em sessões conectadas a um [gateway de aplicativos Claude](/docs/pt/claude-apps-gateway) através de `/login`, a CLI marca as exportações com a identidade autenticada: `user.id` é o assunto do IdP, `user.email` é o email conectado, e `user.groups` carrega a associação de grupo do IdP como uma string separada por vírgulas. Cada exportação também carrega `identity.source: gateway-oidc`. A identidade do gateway é aplicada por último, então as chaves `user.*` e `identity.*` definidas através de `OTEL_RESOURCE_ATTRIBUTES` são ignoradas nessas sessões.600Em sessões conectadas a um [gateway de aplicativos Claude](/docs/pt/claude-apps-gateway) através de `/login`, a CLI marca as exportações com a identidade autenticada: `user.id` é o assunto do IdP, `user.email` é o email conectado, e `user.groups` carrega a associação de grupo do IdP como uma string separada por vírgulas. Cada exportação também carrega `identity.source: gateway-oidc`. A identidade do gateway é aplicada por último, então as chaves `user.*` e `identity.*` definidas através de `OTEL_RESOURCE_ATTRIBUTES` são ignoradas nessas sessões.

601 601

602<Note>

603 Eventos que o Claude Code registra antes de um desenvolvedor fazer login não trazem a identidade do gateway. Quando o Claude Code abre uma sessão desconectada do gateway, por exemplo depois que [o gateway encerra o login](/docs/pt/errors#cloud-gateway-session-expired), os eventos de inicialização registrados antes do login trazem o `user.id` anônimo e nenhum `identity.source`. Eles incluem [`managed_settings_resolved`](#managed-settings-resolved-event), [`plugin_loaded`](#plugin-loaded-event) e [`mcp_server_connection`](#mcp-server-connection-event).

604</Note>

605

602Para os atributos de identidade em sessões Claude Desktop e Cowork que se conectam através de um gateway, veja a [referência de telemetria do gateway](/docs/pt/claude-apps-gateway-config#telemetry).606Para os atributos de identidade em sessões Claude Desktop e Cowork que se conectam através de um gateway, veja a [referência de telemetria do gateway](/docs/pt/claude-apps-gateway-config#telemetry).

603 607

604Os eventos incluem adicionalmente os seguintes atributos. Estes nunca são anexados a métricas porque causariam cardinalidade ilimitada:608Os eventos incluem adicionalmente os seguintes atributos. Estes nunca são anexados a métricas porque causariam cardinalidade ilimitada:

917* `error`: Mensagem de erro921* `error`: Mensagem de erro

918* `status_code`: Código de status HTTP como um número. Ausente para erros não-HTTP como falhas de conexão.922* `status_code`: Código de status HTTP como um número. Ausente para erros não-HTTP como falhas de conexão.

919* `duration_ms`: Duração da requisição em milissegundos923* `duration_ms`: Duração da requisição em milissegundos

920* `attempt`: Número total de tentativas feitas, incluindo a requisição inicial (`1` significa que nenhuma retentativa ocorreu)924* `attempt`: Número de tentativas feitas, incluindo a requisição inicial. [Detectar o esgotamento de novas tentativas](#detect-retry-exhaustion) informa quando a contagem recomeça

921* `request_id`: ID de requisição de API, como `"req_011..."`, descrito em [Atributos de correlação de eventos](#event-correlation-attributes).925* `request_id`: ID de requisição de API, como `"req_011..."`, descrito em [Atributos de correlação de eventos](#event-correlation-attributes).

922* `client_request_id`: UUID gerado pelo cliente enviado como cabeçalho de requisição `x-client-request-id`. Disponível mesmo quando uma falha como timeout ou erro de conexão nunca produziu um `request_id` de servidor; veja a tabela [atributos de correlação de eventos](#event-correlation-attributes) para quando está presente. Requer Claude Code v2.1.214 ou posterior926* `client_request_id`: UUID gerado pelo cliente enviado como cabeçalho de requisição `x-client-request-id`. Disponível mesmo quando uma falha como timeout ou erro de conexão nunca produziu um `request_id` de servidor; veja a tabela [atributos de correlação de eventos](#event-correlation-attributes) para quando está presente. Requer Claude Code v2.1.214 ou posterior

923* `speed`: `"fast"` ou `"normal"`, indicando se o modo rápido estava ativo927* `speed`: `"fast"` ou `"normal"`, indicando se o modo rápido estava ativo

1528 1532

1529Claude Code retenta solicitações de API falhadas internamente e emite um único evento `claude_code.api_error` apenas depois de desistir, então o evento em si é o sinal terminal para essa solicitação. Tentativas de repetição intermediárias não são registradas como eventos separados.1533Claude Code retenta solicitações de API falhadas internamente e emite um único evento `claude_code.api_error` apenas depois de desistir, então o evento em si é o sinal terminal para essa solicitação. Tentativas de repetição intermediárias não são registradas como eventos separados.

1530 1534

1531O atributo `attempt` no evento registra o número total de tentativas. `CLAUDE_CODE_MAX_RETRIES` tem como padrão 10 e é limitado a 15. A partir da v2.1.199, você pode definir `CLAUDE_CODE_RETRY_WATCHDOG` para aumentar o padrão e remover o limite.1535O atributo `attempt` no evento registra o número de tentativas. `CLAUDE_CODE_MAX_RETRIES` tem como padrão 10 e é limitado a 15. A partir da v2.1.199, você pode definir `CLAUDE_CODE_RETRY_WATCHDOG` para aumentar o padrão e remover o limite.

1536

1537Quando a requisição esgota todas as novas tentativas em um erro transitório, `attempt` é no máximo um a mais do que esse limite efetivo: 11 por padrão.

1532 1538

1533Quando a solicitação esgota todas as tentativas em um erro transitório, `attempt` é igual a um a mais do que esse limite efetivo: 11 por padrão, e nunca mais de 16 a menos que o watchdog esteja definido. Um valor menor indica um erro não retentável, como uma resposta `400`, ou uma causa com seu próprio orçamento de tentativas menor. Por exemplo, Claude Code retenta uma falha ao carregar credenciais da AWS ou Google Cloud no máximo duas vezes.1539Um valor menor ainda pode significar que as novas tentativas se esgotaram: `attempt` recomeça a partir de `1` cada vez que Claude Code reenvia a requisição após uma falha de streaming.

1534 1540

1535Para distinguir uma sessão que se recuperou de uma que travou, agrupe eventos por `session.id` e verifique se um evento `api_request` posterior existe após o erro.1541Para distinguir uma sessão que se recuperou de uma que travou, agrupe eventos por `session.id` e verifique se um evento `api_request` posterior existe após o erro.

1536 1542

plugins/cli-reference.md +1 −0

Details

91| `-y, --yes` | Aceite o comando de instalação exibido sem o prompt `Run this command now?`. Ignorado quando o comando é executado dentro de uma sessão Claude Code, como da ferramenta Bash ou um hook. Requer Claude Code v2.1.229 ou posterior |91| `-y, --yes` | Aceite o comando de instalação exibido sem o prompt `Run this command now?`. Ignorado quando o comando é executado dentro de uma sessão Claude Code, como da ferramenta Bash ou um hook. Requer Claude Code v2.1.229 ou posterior |

92| `--accept-command <sha256>` | Aceite o comando de instalação exibido cujo `sha256` uma execução anterior [`--json`](#plugin-json-result) relatou em `shownCommand`, no lugar de `-y`. Não pode ser combinado com `-y`. Veja [Aceitar um comando de instalação exibido](#accept-a-displayed-install-command). Requer Claude Code v2.1.271 ou posterior |92| `--accept-command <sha256>` | Aceite o comando de instalação exibido cujo `sha256` uma execução anterior [`--json`](#plugin-json-result) relatou em `shownCommand`, no lugar de `-y`. Não pode ser combinado com `-y`. Veja [Aceitar um comando de instalação exibido](#accept-a-displayed-install-command). Requer Claude Code v2.1.271 ou posterior |

93| `--json` | Imprima o resultado como um objeto JSON na última linha de stdout em vez da mensagem legível por humanos, para uso em scripts. Veja [Formato de resultado JSON](#plugin-json-result). Requer Claude Code v2.1.268 ou posterior |93| `--json` | Imprima o resultado como um objeto JSON na última linha de stdout em vez da mensagem legível por humanos, para uso em scripts. Veja [Formato de resultado JSON](#plugin-json-result). Requer Claude Code v2.1.268 ou posterior |

94| `--marketplace <source>` | Instale `<plugin>`, dado por seu nome simples, a partir do marketplace em `<source>`, adicionando o marketplace primeiro se você ainda não o adicionou. Veja [Adicionar um marketplace e instalar em um único comando](/docs/pt/plugins/install#add-a-marketplace-and-install-in-one-command). Requer Claude Code v2.1.292 ou posterior |

94 95

95Execute `claude plugin install --help` em seu shell para ver todas as opções que sua versão suporta.96Execute `claude plugin install --help` em seu shell para ver todas as opções que sua versão suporta.

96 97

plugins/install.md +20 −4

Details

189 189

190* **Scope**: escopo de usuário por padrão. Passe `--scope project` ou `--scope local` para alterá-lo.190* **Scope**: escopo de usuário por padrão. Passe `--scope project` ou `--scope local` para alterá-lo.

191* **Quando os plugins carregam**: plugins que ele instala carregam na próxima vez que você inicia o Claude Code, ou quando você executa `/reload-plugins` em uma sessão que já está aberta.191* **Quando os plugins carregam**: plugins que ele instala carregam na próxima vez que você inicia o Claude Code, ou quando você executa `/reload-plugins` em uma sessão que já está aberta.

192* **O marketplace deve ser adicionado primeiro**: em uma máquina onde ninguém abriu uma sessão interativa do Claude Code ainda, o marketplace oficial não está registrado, então um script que instala a partir dele executa `claude plugin marketplace add anthropics/claude-plugins-official` antes da instalação.192* **O marketplace em uma máquina nova**: em uma máquina onde ninguém abriu uma sessão interativa do Claude Code ainda, o marketplace oficial não está registrado, então um script que instala a partir dele executa `claude plugin marketplace add anthropics/claude-plugins-official` antes da instalação. Veja [Adicionar e instalar do seu shell](#add-and-install-from-your-shell).

193 193

194```bash theme={null}194```bash theme={null}

195claude plugin install formatter@your-org --scope project195claude plugin install formatter@your-org --scope project

232 Adicionar um marketplace e instalar em um comando232 Adicionar um marketplace e instalar em um comando

233</h3>233</h3>

234 234

235Para instalar um plugin de um marketplace que você ainda não adicionou, execute `/plugin install` em uma sessão do Claude Code e nomeie a fonte do marketplace com `--marketplace`. Requer Claude Code v2.1.275 ou posterior.235Para instalar um plugin de um marketplace que você ainda não adicionou, nomeie a fonte do marketplace com `--marketplace` no comando de instalação, em uma sessão ou no seu shell. A fonte aceita [as mesmas formas que `/plugin marketplace add`](#add-a-marketplace), como GitHub `owner/repo`, uma URL git ou um caminho local. Dê o nome do plugin por si só, sem um sufixo `@marketplace`.

236

237<h4 id="add-and-install-in-a-session">

238 Adicionar e instalar em uma sessão

239</h4>

240

241Execute `/plugin install` em uma sessão do Claude Code com o plugin e a fonte. Requer Claude Code v2.1.275 ou posterior. Em uma sessão, a fonte não pode conter espaços.

236 242

237```text theme={null}243```text theme={null}

238/plugin install deploy-helper --marketplace your-org/plugins244/plugin install deploy-helper --marketplace your-org/plugins

239```245```

240 246

241A fonte aceita [as mesmas formas que `/plugin marketplace add`](#add-a-marketplace), como GitHub `owner/repo`, uma URL git ou um caminho local, exceto que não pode conter espaços. Dê o nome do plugin por si só, sem um sufixo `@marketplace`.

~~242~~

243Se você ainda não adicionou esse marketplace, o Claude Code mostra a fonte que resolveu e pede que você confirme antes de adicioná-lo. Uma vez que o marketplace é adicionado, os detalhes do plugin abrem e você escolhe um [escopo de instalação](#install-a-plugin). Se a fonte corresponder a um marketplace que você já adicionou, o Claude Code pula a confirmação e abre os detalhes do plugin nesse marketplace.247Se você ainda não adicionou esse marketplace, o Claude Code mostra a fonte que resolveu e pede que você confirme antes de adicioná-lo. Uma vez que o marketplace é adicionado, os detalhes do plugin abrem e você escolhe um [escopo de instalação](#install-a-plugin). Se a fonte corresponder a um marketplace que você já adicionou, o Claude Code pula a confirmação e abre os detalhes do plugin nesse marketplace.

244 248

249<h4 id="add-and-install-from-your-shell">

250 Adicionar e instalar no seu shell

251</h4>

252

253No seu shell, sem iniciar uma sessão, execute `claude plugin install` com o plugin e a fonte. Requer Claude Code v2.1.292 ou posterior.

254

255```bash theme={null}

256claude plugin install deploy-helper --marketplace your-org/plugins

257```

258

259O comando do shell adiciona o marketplace sem uma etapa de confirmação. Um marketplace que você já adicionou a partir dessa fonte é reutilizado. Um novo é adicionado sob as mesmas [verificações de política da organização](/docs/pt/plugins/org#restrict-what-users-can-install) que `claude plugin marketplace add`, e é declarado nas suas configurações de usuário mesmo quando você passa `--scope project`.

260

245<h3 id="add-a-private-marketplace">261<h3 id="add-a-private-marketplace">

246 Adicionar um marketplace privado262 Adicionar um marketplace privado

247</h3>263</h3>

plugins/mods/admin.md +1 −1

Details

142 142

143Na linha `hooks:`, [`tool.call`](/docs/pt/plugins/mods/reference#tools) e [`prompt.submit`](/docs/pt/plugins/mods/reference#prompts-and-what-claude-reads) significam que o mod vê cada chamada de ferramenta e cada prompt, e pode mudá-los. [`session.append`](/docs/pt/plugins/mods/reference#session) significa que o mod pode reescrever cada linha da conversa antes de ser armazenada. [`ui.render{component=AskUserQuestion}`](/docs/pt/plugins/mods/interface#change-what-claude-code-already-draws) significa que o mod pode redesenhar o diálogo que Claude usa para fazer uma pergunta ao usuário. `tool.check` significa que o mod pode aprovar ou negar uma chamada de ferramenta antes de um prompt de permissão aparecer. [Saiba o que acontece por padrão](#know-what-happens-by-default) lista quais de suas regras e hooks têm precedência sobre sua resposta.143Na linha `hooks:`, [`tool.call`](/docs/pt/plugins/mods/reference#tools) e [`prompt.submit`](/docs/pt/plugins/mods/reference#prompts-and-what-claude-reads) significam que o mod vê cada chamada de ferramenta e cada prompt, e pode mudá-los. [`session.append`](/docs/pt/plugins/mods/reference#session) significa que o mod pode reescrever cada linha da conversa antes de ser armazenada. [`ui.render{component=AskUserQuestion}`](/docs/pt/plugins/mods/interface#change-what-claude-code-already-draws) significa que o mod pode redesenhar o diálogo que Claude usa para fazer uma pergunta ao usuário. `tool.check` significa que o mod pode aprovar ou negar uma chamada de ferramenta antes de um prompt de permissão aparecer. [Saiba o que acontece por padrão](#know-what-happens-by-default) lista quais de suas regras e hooks têm precedência sobre sua resposta.

144 144

plugins/mods/api.md +10 −2

Details

140| Chamada | O que o usuário vê |140| Chamada | O que o usuário vê |

141| :- | :- |141| :- | :- |

142| `$.ui.status(text)` | Uma linha sob o prompt que permanece até você alterá-la. Começa com `⚠` e o nome do mod, como em `⚠ my-mod: checks: 3 passing`. |142| `$.ui.status(text)` | Uma linha sob o prompt que permanece até você alterá-la. Começa com `⚠` e o nome do mod, como em `⚠ my-mod: checks: 3 passing`. |

143| `$.ui.toast(text)` | Uma notificação toast no canto superior direito, com o nome do mod acima do texto, que desaparece após alguns segundos |143| `$.ui.toast(text)` | Uma notificação toast com o nome do mod que desaparece após alguns segundos. É uma caixa no canto superior direito na [renderização em tela cheia](/docs/pt/fullscreen) e uma linha à direita sob o prompt no renderizador clássico. |

144| `$.ui.log(text)` | Uma linha fraca na transcrição que Claude não lê. Começa com `●` e o nome do mod, como em `● my-mod: build finished`. |144| `$.ui.log(text)` | Uma linha fraca na transcrição que Claude não lê. Começa com `●` e o nome do mod, como em `● my-mod: build finished`. |

145 145

146<h3 id="start-a-turn-from-a-background-job">146<h3 id="start-a-turn-from-a-background-job">

159 Envie e receba mensagens entre sessões159 Envie e receba mensagens entre sessões

160</h2>160</h2>

161 161

162Um mod pode enviar uma mensagem em texto simples para outra de suas sessões ou para um dos subagentes desta sessão e observar as mensagens que chegam e saem. `$.session.send({ to, text })` envia uma, a mesma entrega que a ferramenta SendMessage faz. `to` é `{ sessionId }` para uma sessão, `{ agentId }` para um subagente de `$.agent.list()` ou o endereço de string de onde uma mensagem recebida veio. A chamada resolve uma vez que a mensagem é enfileirada, com `{ isDelivered: true }`. Quando nada foi entregue, ela resolve com `{ isDelivered: false, reason }`, e `reason` diz por quê.162Um mod pode enviar uma mensagem em texto simples para outra de suas sessões, para um dos subagentes desta sessão ou para um colega de equipe em sua [equipe de agentes](/docs/pt/agent-teams). Ele também pode observar as mensagens que chegam e saem.

163

164Para enviar uma, chame `$.session.send({ to, text })`, que faz a mesma entrega que a ferramenta SendMessage faz. Defina `to` de acordo com quem recebe a mensagem:

165

166* **Outra de suas sessões**: `{ sessionId }`

167* **Um subagente ou colega de equipe**: `{ agentId }`, com um id de `$.agent.list()`

168* **O remetente de uma mensagem que você recebeu**: o endereço de string de onde essa mensagem veio

169

170A chamada resolve uma vez que a mensagem é enfileirada, com `{ isDelivered: true }`. Quando nada foi entregue, ela resolve com `{ isDelivered: false, reason }`, e `reason` diz por quê.

163 171

164Este hook responde a um comando `/ping`, [registrado como um comando](#add-a-command), pedindo à sessão cujo id você digita após ele um status:172Este hook responde a um comando `/ping`, [registrado como um comando](#add-a-command), pedindo à sessão cujo id você digita após ele um status:

165 173

plugins/mods/events.md +2 −0

Details

281 281

282`result.usage` contém as contagens de tokens que a API do Claude informa para uma requisição, mais o `model` que respondeu: `input_tokens`, `output_tokens`, `cache_read_input_tokens` e `cache_creation_input_tokens`. O hook também é executado para as requisições de subagentes, então verifique `e.agentId` quando quiser apenas a conversa principal.282`result.usage` contém as contagens de tokens que a API do Claude informa para uma requisição, mais o `model` que respondeu: `input_tokens`, `output_tokens`, `cache_read_input_tokens` e `cache_creation_input_tokens`. O hook também é executado para as requisições de subagentes, então verifique `e.agentId` quando quiser apenas a conversa principal.

283 283

284Para ver as chamadas de ferramenta que a própria API executou durante a requisição, como chamadas à [ferramenta advisor](/docs/pt/advisor), leia `result.serverToolUses`. O Claude Code não executa essas chamadas, então nenhum hook `tool.call` ou `tool.check` é disparado para elas. O campo está ausente quando a resposta não tem chamadas desse tipo, e requer o Claude Code v2.1.290 ou posterior.

285

284<h3 id="hook-the-settings-hook-events">286<h3 id="hook-the-settings-hook-events">

285 Tratar os eventos de hooks de configuração287 Tratar os eventos de hooks de configuração

286</h3>288</h3>

plugins/mods/interface.md +11 −3

Details

10 10

11Este mapa mostra onde um mod pode desenhar em uma sessão de terminal:11Este mapa mostra onde um mod pode desenhar em uma sessão de terminal:

12 12

13<img src="https://mintcdn.com/claude-code/dgiVO_Od1X1faduV/images/mods-screen-map.svg?fit=max&auto=format&n=dgiVO_Od1X1faduV&q=85&s=5fda26b6609c62b68c6f9e528c1590ea" className="dark:hidden" alt="Mapa de uma sessão de terminal Claude Code. Um mod pode adicionar um painel como uma barra lateral à direita, um toast no canto superior direito da transcrição, uma linha de log na transcrição, uma faixa acima do prompt e uma linha de status sob o prompt. Um mod pode redesenhar mensagens, linhas de chamada de ferramenta e o spinner. O prompt é do próprio Claude Code." width="600" height="336" data-path="images/mods-screen-map.svg" />13<img src="https://mintcdn.com/claude-code/dgiVO_Od1X1faduV/images/mods-screen-map.svg?fit=max&auto=format&n=dgiVO_Od1X1faduV&q=85&s=5fda26b6609c62b68c6f9e528c1590ea" className="dark:hidden" alt="Mapa de uma sessão de terminal Claude Code com renderização em tela cheia. Um mod pode adicionar um painel como uma barra lateral à direita, um toast no canto superior direito da transcrição, uma linha de log na transcrição, uma faixa acima do prompt e uma linha de status sob o prompt. Um mod pode redesenhar mensagens, linhas de chamada de ferramenta e o spinner. O prompt é do próprio Claude Code." width="600" height="336" data-path="images/mods-screen-map.svg" />

14 14

15<img src="https://mintcdn.com/claude-code/dgiVO_Od1X1faduV/images/mods-screen-map-dark.svg?fit=max&auto=format&n=dgiVO_Od1X1faduV&q=85&s=5b4161581a1bd2c0450b0c8b57bc1225" className="hidden dark:block" alt="Mapa de uma sessão de terminal Claude Code. Um mod pode adicionar um painel como uma barra lateral à direita, um toast no canto superior direito da transcrição, uma linha de log na transcrição, uma faixa acima do prompt e uma linha de status sob o prompt. Um mod pode redesenhar mensagens, linhas de chamada de ferramenta e o spinner. O prompt é do próprio Claude Code." width="600" height="336" data-path="images/mods-screen-map-dark.svg" />15<img src="https://mintcdn.com/claude-code/dgiVO_Od1X1faduV/images/mods-screen-map-dark.svg?fit=max&auto=format&n=dgiVO_Od1X1faduV&q=85&s=5b4161581a1bd2c0450b0c8b57bc1225" className="hidden dark:block" alt="Mapa de uma sessão de terminal Claude Code com renderização em tela cheia. Um mod pode adicionar um painel como uma barra lateral à direita, um toast no canto superior direito da transcrição, uma linha de log na transcrição, uma faixa acima do prompt e uma linha de status sob o prompt. Um mod pode redesenhar mensagens, linhas de chamada de ferramenta e o spinner. O prompt é do próprio Claude Code." width="600" height="336" data-path="images/mods-screen-map-dark.svg" />

16 16

17Em um terminal mais estreito, o painel fica acima do prompt em vez de ao lado da transcrição.17Em um terminal mais estreito, o painel fica acima do prompt em vez de ao lado da transcrição.

18 18

327| `holdToasts` | Mantém toasts, os pequenos avisos de [`$.ui.toast`](/docs/pt/plugins/mods/api#show-something-without-starting-a-turn), até o painel fechar |327| `holdToasts` | No terminal, retém toasts enquanto este painel é o que está sendo exibido. Consulte [Reter toasts atrás de um diálogo](#hold-toasts-behind-a-dialog). |

330 330

337 337

338Para deixar um comando abrir o painel enquanto o Claude está trabalhando, adicione `immediate: true` quando você [registra o comando](/docs/pt/plugins/mods/api#add-a-command). Sem isso, um comando digitado durante um turno espera o turno terminar.338Para deixar um comando abrir o painel enquanto o Claude está trabalhando, adicione `immediate: true` quando você [registra o comando](/docs/pt/plugins/mods/api#add-a-command). Sem isso, um comando digitado durante um turno espera o turno terminar.

339 339

340<h4 id="hold-toasts-behind-a-dialog">

341 Reter toasts atrás de um diálogo

342</h4>

343

344Passe `holdToasts: true` para `$.ui.open` quando o painel for um diálogo que o usuário responde e deixa, para que toasts não apareçam enquanto ele decide. No terminal, a retenção dura enquanto esse painel é o que está sendo exibido, e um toast disparado nesse tempo espera até a retenção terminar.

345

346O Claude Code retém os toasts de outros mods e suas próprias notificações de curta duração, assim como os que seu mod dispara com [`$.ui.toast`](/docs/pt/plugins/mods/api#show-something-without-starting-a-turn). Deixe o campo de fora em um painel que permanece aberto, para que o usuário continue vendo-os.

347

340<h4 id="when-a-pane-waits-for-a-wider-terminal">348<h4 id="when-a-pane-waits-for-a-wider-terminal">

341 Quando um painel espera por um terminal mais amplo349 Quando um painel espera por um terminal mais amplo

342</h4>350</h4>

plugins/mods/reference.md +2 −1

Details

209| [`$.ui`](/docs/pt/plugins/mods/interface#pick-where-to-draw) | `resolve`, `invalidate`, `open`, `close`, `panes`, `focus`, `scroll`, `toast`, `status`, `log`, `notice`, `ask`, `copy`, `selection`, `blit` |209| [`$.ui`](/docs/pt/plugins/mods/interface#pick-where-to-draw) | `resolve`, `invalidate`, `open`, `close`, `panes`, `focus`, `scroll`, `toast`, `status`, `log`, `notice`, `ask`, `copy`, `selection`, `blit` |

212| `$.agent` | `register`, `spawn`, `list` |212| `$.agent` | `register`, `spawn`, `list`. `list()` retorna os subagentes e colegas de equipe desta sessão, cada um com um `status` de `pending`, `running`, `waiting`, `idle`, `completed`, `failed` ou `killed`, sendo que `idle` e `waiting` exigem o Claude Code v2.1.289 ou posterior. |

214| [`$.prompt`](/docs/pt/plugins/mods/api#start-a-turn-from-a-background-job) | `submit`, `read`, `fill`, `suggest`, `compose`. O Claude lê o texto de `submit({ text })` após uma frase que indica o seu mod como remetente. `submit({ text, asUser: true })` envia o texto como se fossem palavras do próprio usuário, sem essa frase. |214| [`$.prompt`](/docs/pt/plugins/mods/api#start-a-turn-from-a-background-job) | `submit`, `read`, `fill`, `suggest`, `compose`. O Claude lê o texto de `submit({ text })` após uma frase que indica o seu mod como remetente. `submit({ text, asUser: true })` envia o texto como se fossem palavras do próprio usuário, sem essa frase. |

320| O motivo de `drop` de um hook ou o motivo de `deny` de `config.set` | 4.096 caracteres. O final de um motivo mais longo é cortado, e o drop ou deny ainda se aplica. O corte requer o Claude Code v2.1.292 ou posterior e, em versões anteriores, o hook [falha](/docs/pt/plugins/mods/events#handle-a-hook-that-fails) em vez disso. |

320| Texto em uma árvore | Os primeiros 100.000 caracteres são desenhados |321| Texto em uma árvore | Os primeiros 100.000 caracteres são desenhados |

321| O `language` ou `path` de um `Code`, o `value` de uma opção de `Select` ou o `module` de um `Client` | 10.000 caracteres. Se algum for mais longo, o Claude Code [desenha sua própria versão do site](/docs/pt/plugins/mods/interface#build-a-tree-from-elements). |322| O `language` ou `path` de um `Code`, o `value` de uma opção de `Select` ou o `module` de um `Client` | 10.000 caracteres. Se algum for mais longo, o Claude Code [desenha sua própria versão do site](/docs/pt/plugins/mods/interface#build-a-tree-from-elements). |

plugins/mods/test.md +7 −2

Details

110* `returned neither { value } nor { deny }`: um stub para uma chamada de mods API retornou um valor simples, o que faz o teste falhar110* `returned neither { value } nor { deny }`: um stub para uma chamada de mods API retornou um valor simples, o que faz o teste falhar

111* `no implementation for` seguido por um nome: seu mod fez essa chamada e nenhum stub a responde111* `no implementation for` seguido por um nome: seu mod fez essa chamada e nenhum stub a responde

112 112

113O kit também exporta mocks em memória que respondem um namespace inteiro para você. `mock.clock(on)` responde [`$.clock`](/docs/pt/plugins/mods/api#run-work-in-the-background), `mock.store(on, { count: 7 })` responde `$.store` de um armazenamento que começa com essas entradas, e `mock.env(on, { CI: 'true' })` responde `$.env.get` dessas variáveis. `mock.clock` retorna um relógio simulado que seu teste avança, então um teste de um temporizador não espera. `mock.store` não retorna nada, então para verificar o que seu mod salvou, escreva os dois stubs `store` você mesmo como o [drawing test](#test-a-drawing) faz.113O kit também exporta mocks prontos para o relógio, o armazenamento, as variáveis de ambiente e as linhas anexadas à conversa:

114

115* **`mock.clock(on)`**: responde [`$.clock`](/docs/pt/plugins/mods/api#run-work-in-the-background) e retorna um relógio simulado que seu teste avança, então um teste de um temporizador não espera.

116* **`mock.store(on, { count: 7 })`**: responde `$.store` de um armazenamento que começa com essas entradas. Não retorna nada, então para verificar o que seu mod salvou, escreva os dois stubs `store` você mesmo como o [drawing test](#test-a-drawing) faz.

117* **`mock.env(on, { CI: 'true' })`**: responde `$.env.get` dessas variáveis.

118* **`mock.session(on)`**: retorna uma sessão simulada cujo método `appended()` lista as linhas que seu mod adicionou com [`$.session.append`](/docs/pt/plugins/mods/reference#session), da mais antiga para a mais recente; requer Claude Code v2.1.293 ou posterior.

114 119

115<h3 id="follow-the-test-kit’s-rules">120<h3 id="follow-the-test-kit’s-rules">

116 Seguir as regras do test kit121 Seguir as regras do test kit

168 Procurar o que um stub retorna173 Procurar o que um stub retorna

169</h3>174</h3>

170 175

171Cada chamada de mods API que seu mod faz em um teste precisa de um stub que responda no lugar do Claude Code, exceto as poucas que o kit responde por si: chamadas [`$.ui.invalidate`](/docs/pt/plugins/mods/interface#redraw-when-something-changes) e [`$.state`](/docs/pt/plugins/mods/interface#keep-state). Para chamadas `$.clock`, use `mock.clock(on)`, ou seu `$.clock.now()` do mod falha com `no implementation for clock.now`.176Cada chamada de mods API que seu mod faz em um teste precisa de um stub que responda no lugar do Claude Code, exceto as poucas que o kit responde por si: chamadas [`$.ui.invalidate`](/docs/pt/plugins/mods/interface#redraw-when-something-changes), [`$.state`](/docs/pt/plugins/mods/interface#keep-state) e `$.session.append`. Para chamadas `$.clock`, use `mock.clock(on)`, ou seu `$.clock.now()` do mod falha com `no implementation for clock.now`.

172 177

173Esta tabela lista as que mods usam mais. A primeira coluna é a chamada que seu mod faz ou o evento que passa com `next(e)`. A segunda é a função para passar para `on` sob esse nome, então a linha `$.store.get` se torna `on('store.get', ($, e) => ({ value: saved.get(e.key) }))`. Um `'...'` em um stub marca texto para você preencher:178Esta tabela lista as que mods usam mais. A primeira coluna é a chamada que seu mod faz ou o evento que passa com `next(e)`. A segunda é a função para passar para `on` sob esse nome, então a linha `$.store.get` se torna `on('store.get', ($, e) => ({ value: saved.get(e.key) }))`. Um `'...'` em um stub marca texto para você preencher:

174 179

plugins/mods/troubleshoot.md +15 −1

Details

209 Um desenho não aparece ou responde209 Um desenho não aparece ou responde

210</h2>210</h2>

211 211

212O mod carregou e seu painel, banda ou controles não se comportam como você espera.212O mod carregou e seu painel, banda, toast ou controles não se comportam como você espera.

213 213

214<h3 id="a-pane-or-band-is-empty-or-shows-claude-code’s-usual-content">214<h3 id="a-pane-or-band-is-empty-or-shows-claude-code’s-usual-content">

215 Um painel ou banda está vazio ou mostra o conteúdo usual de Claude Code215 Um painel ou banda está vazio ou mostra o conteúdo usual de Claude Code

247 247

248Abra o painel a partir de um comando ou botão, ou verifique o resultado `isPlaced` da chamada. Veja [Abrir um painel no momento certo](/docs/pt/plugins/mods/interface#open-a-pane-at-the-right-time).248Abra o painel a partir de um comando ou botão, ou verifique o resultado `isPlaced` da chamada. Veja [Abrir um painel no momento certo](/docs/pt/plugins/mods/interface#open-a-pane-at-the-right-time).

249 249

250<h3 id="a-toast-doesn’t-appear">

251 Um toast não aparece

252</h3>

253

254Seu mod chama [`$.ui.toast`](/docs/pt/plugins/mods/api#show-something-without-starting-a-turn) em uma sessão interativa do terminal e você não vê o toast. Para confirmar que a chamada foi executada, procure no [log de depuração](#read-the-debug-log) uma linha com o nome do seu mod e o texto do toast, como em `$.ui.toast (first-mod): build finished`. Depois, verifique causas como estas:

255

256* **A linha da chamada está ausente**: procure uma linha que diga por que Claude Code recusou a chamada, como em `first-mod: $.ui.toast dropped: timeoutMs is a whole number of ms, 1 to 60000`.

257* **Um painel está retendo os toasts**: seu mod ou outro passou [`holdToasts`](/docs/pt/plugins/mods/interface#hold-toasts-behind-a-dialog) ao abrir o painel que está sendo exibido. Feche o painel para encerrar a retenção. Se o painel for seu e deve permanecer aberto, remova `holdToasts` da chamada `$.ui.open` dele e abra o painel novamente.

258* **O toast está abaixo do prompt**: no [renderizador clássico](/docs/pt/fullscreen#enable-fullscreen-rendering), olhe à direita, abaixo do prompt. Um toast ali é uma linha que começa com o nome do mod, em vez de uma caixa no canto superior direito.

259* **Seu mod gerou um toast mais recente**: no renderizador clássico, um toast mais recente do seu mod pode tomar o lugar de um que está sendo exibido ou aguardando para ser exibido. O log de depuração tem outra linha para o toast mais antigo, que termina com `gave way, cut short` quando ele estava sendo exibido, ou `gave way, unseen` quando nunca apareceu. Para mostrar as duas mensagens, coloque-as em um único toast.

260* **O tempo do toast esgotou antes de ser desenhado**: na renderização em tela cheia, Claude Code desenha no máximo três toasts por vez, então o tempo de um toast pode se esgotar antes de ele ser desenhado. O log de depuração tem outra linha para esse toast, que termina com `left the stack, never drawn`. Quando seu mod gerar vários ao mesmo tempo, coloque as mensagens em um único toast.

261

262Antes da v2.1.290, Claude Code descartava um toast gerado dentro de dois segundos após o último que exibiu para o seu mod, e a linha do log de depuração para o toast descartado dizia `within 2000ms of the last; dropped`.

263

250<h3 id="hotkeys-do-nothing">264<h3 id="hotkeys-do-nothing">

251 Hotkeys não fazem nada265 Hotkeys não fazem nada

252</h3>266</h3>

plugins/publish.md +1 −0

Details

129* Adicione o marketplace uma vez: `claude plugin marketplace add your-org/your-marketplace`, onde o argumento é um atalho GitHub `owner/repo`, uma URL ou um caminho129* Adicione o marketplace uma vez: `claude plugin marketplace add your-org/your-marketplace`, onde o argumento é um atalho GitHub `owner/repo`, uma URL ou um caminho

130* Instale o plugin: `claude plugin install deploy-helper@your-marketplace`130* Instale o plugin: `claude plugin install deploy-helper@your-marketplace`

131* Ou faça ambos de dentro de uma sessão: `/plugin install deploy-helper --marketplace your-org/your-marketplace`. Requer Claude Code v2.1.275 ou posterior. Veja [Adicione um marketplace e instale em um comando](/docs/pt/plugins/install#add-a-marketplace-and-install-in-one-command)131* Ou faça ambos de dentro de uma sessão: `/plugin install deploy-helper --marketplace your-org/your-marketplace`. Requer Claude Code v2.1.275 ou posterior. Veja [Adicione um marketplace e instale em um comando](/docs/pt/plugins/install#add-a-marketplace-and-install-in-one-command)

132* Ou faça ambos a partir do shell em um único comando: `claude plugin install deploy-helper --marketplace your-org/your-marketplace`. Requer Claude Code v2.1.292 ou posterior

132 133

133<h3 id="ship-updates-to-users">134<h3 id="ship-updates-to-users">

134 Envie atualizações aos usuários135 Envie atualizações aos usuários

plugins/troubleshooting.md +2 −2

Details

163 `Invalid marketplace source format`163 `Invalid marketplace source format`

164</h3>164</h3>

165 165

166Você executou `/plugin marketplace add <source>` ou `claude plugin marketplace add <source>`, e Claude Code respondeu `Invalid marketplace source format. Try: owner/repo, https://..., or ./path`.166Você executou `/plugin marketplace add <source>`, `claude plugin marketplace add <source>` ou `claude plugin install <plugin> --marketplace <source>`, e Claude Code respondeu `Invalid marketplace source format. Try: owner/repo, https://..., or ./path`.

167 167

168Claude Code aceita uma fonte em uma destas formas:168Claude Code aceita uma fonte em uma destas formas:

169 169

568 `Marketplace "<name>" is already added from a different source`568 `Marketplace "<name>" is already added from a different source`

569</h3>569</h3>

570 570

571Você confirmou adicionar um marketplace através de [`/plugin install <plugin> --marketplace <source>`](/docs/pt/plugins/install#add-a-marketplace-and-install-in-one-command), e o catálogo que Claude Code buscou dessa fonte tem o mesmo nome que um marketplace que você já adicionou a partir de uma fonte diferente. Claude Code mantém o marketplace existente em vez de substituí-lo, e o plugin não é instalado.571Você nomeou uma nova fonte de marketplace com [`--marketplace <source>` no comando de instalação](/docs/pt/plugins/install#add-a-marketplace-and-install-in-one-command), em uma sessão ou a partir do seu shell. O catálogo que Claude Code buscou dessa fonte tem o mesmo nome que um marketplace que você já adicionou a partir de uma fonte diferente. Claude Code mantém o marketplace existente em vez de substituí-lo, e o plugin não é instalado.

572 572

573A mensagem completa se parece com isto:573A mensagem completa se parece com isto:

574 574

self-hosted-environments-configuration.md +16 −3

Details

403 403

404* O [arquivo MCP gerenciado](/docs/pt/managed-mcp) de escopo enterprise em seu caminho padrão do sistema: `/etc/claude-code/managed-mcp.json` em hosts de runner Linux, `/Library/Application Support/ClaudeCode/managed-mcp.json` em hosts macOS. Use-o para frotas restritas em que apenas servidores listados pelo administrador podem ser carregados. Consulte [controle exclusivo com managed-mcp.json](/docs/pt/managed-mcp#exclusive-control-with-managed-mcp-json) para as regras de precedência. Quando esse arquivo está no host do runner, o Claude Code ignora os servidores MCP que o plano de controle da Anthropic entrega a uma sessão, incluindo conectores do claude.ai, e os nomeia em um aviso no stderr do processo filho da sessão, que o runner registra no nível de log `debug`. Antes da v2.1.229, essas sessões encerravam na inicialização com `You cannot dynamically configure MCP servers when an enterprise MCP config is present`.404* O [arquivo MCP gerenciado](/docs/pt/managed-mcp) de escopo enterprise em seu caminho padrão do sistema: `/etc/claude-code/managed-mcp.json` em hosts de runner Linux, `/Library/Application Support/ClaudeCode/managed-mcp.json` em hosts macOS. Use-o para frotas restritas em que apenas servidores listados pelo administrador podem ser carregados. Consulte [controle exclusivo com managed-mcp.json](/docs/pt/managed-mcp#exclusive-control-with-managed-mcp-json) para as regras de precedência. Quando esse arquivo está no host do runner, o Claude Code ignora os servidores MCP que o plano de controle da Anthropic entrega a uma sessão, incluindo conectores do claude.ai, e os nomeia em um aviso no stderr do processo filho da sessão, que o runner registra no nível de log `debug`. Antes da v2.1.229, essas sessões encerravam na inicialização com `You cannot dynamically configure MCP servers when an enterprise MCP config is present`.

405* A chave [`managedMcpServers`](/docs/pt/settings-reference#managedmcpservers) nas [configurações gerenciadas](/docs/pt/managed-settings) no host do runner: fornece servidores HTTP e SSE sem assumir controle exclusivo, de modo que os servidores das outras fontes ainda são carregados. Requer o Claude Code v2.1.259 ou posterior.405* A chave [`managedMcpServers`](/docs/pt/settings-reference#managedmcpservers) nas [configurações gerenciadas](/docs/pt/managed-settings) no host do runner: fornece servidores HTTP e SSE sem assumir controle exclusivo, de modo que os servidores das outras fontes ainda são carregados. Requer o Claude Code v2.1.259 ou posterior.

406* `<repo>/.mcp.json`: escopo de projeto. Faça commit do arquivo no repositório; seus servidores são aprovados automaticamente em sessões na nuvem.406* `<repo>/.mcp.json`: escopo de projeto. Faça commit do arquivo no repositório; seus servidores são aprovados automaticamente em sessões na nuvem. Em uma sessão com vários repositórios, [no máximo o arquivo de um repositório é carregado](#repository-settings-in-sessions-with-several-repositories).

407 407

408Quando a entrega de conectores está habilitada para sua organização, o plano de controle da Anthropic entrega os conectores que você configurou no claude.ai para sessões criadas interativamente por meio de configuração MCP fornecida pelo servidor, roteada através de `api.anthropic.com`. Sessões criadas programaticamente, como [despachos pela CLI](/docs/pt/self-hosted-environments-testing#run-the-test-loop), não recebem a entrega de conectores; forneça servidores MCP a elas por meio de qualquer uma das outras fontes listadas nesta seção. O token OAuth do processo filho não carrega um escopo para buscar conectores diretamente, então o processo filho não tenta fazer essa busca por conta própria; a entrega é conduzida pelo servidor.408Quando a entrega de conectores está habilitada para sua organização, o plano de controle da Anthropic entrega os conectores que você configurou no claude.ai para sessões criadas interativamente por meio de configuração MCP fornecida pelo servidor, roteada através de `api.anthropic.com`. Sessões criadas programaticamente, como [despachos pela CLI](/docs/pt/self-hosted-environments-testing#run-the-test-loop), não recebem a entrega de conectores; forneça servidores MCP a elas por meio de qualquer uma das outras fontes listadas nesta seção. O token OAuth do processo filho não carrega um escopo para buscar conectores diretamente, então o processo filho não tenta fazer essa busca por conta própria; a entrega é conduzida pelo servidor.

409 409

542exit 0542exit 0

543```543```

544 544

545O hook solicita a Claude fazer commit e push antes da sessão terminar, e fica silencioso quando o diretório não é um repositório git ou não tem remoto.545O hook solicita a Claude fazer commit e push antes da sessão terminar, e fica silencioso quando o diretório não é um repositório git ou não tem remoto. Para uma sessão com vários repositórios, consulte [o que `$CLAUDE_PROJECT_DIR` nomeia](#repository-settings-in-sessions-with-several-repositories).

546 546

547<h2 id="permissions-and-tool-approval">547<h2 id="permissions-and-tool-approval">

548 Permissions and tool approval548 Permissions and tool approval

571 571

572Defina `SELF_HOSTED_RUNNER_HOST_CONFIG_DIR` para semear de um caminho diferente, ou aponte-o para um diretório vazio para desabilitar a semeadura.572Defina `SELF_HOSTED_RUNNER_HOST_CONFIG_DIR` para semear de um caminho diferente, ou aponte-o para um diretório vazio para desabilitar a semeadura.

573 573

574`.claude/settings.json` confirmado no repositório se sobrepõe como configurações de projeto. Sessões também leem [`managed-settings.json`](/docs/pt/settings#where-settings-live) do caminho de sistema padrão em sua imagem do runner. Se suas chaves se aplicam ao lado de [server-managed settings](/docs/pt/server-managed-settings) segue [como Claude Code combina fontes gerenciadas](/docs/pt/managed-settings#how-claude-code-combines-managed-sources): por padrão, quando sua organização entrega quaisquer chaves gerenciadas pelo servidor, sessões ignoram o arquivo da imagem do runner além das [chaves que Claude Code lê de cada fonte de administrador](/docs/pt/managed-settings#keys-read-from-every-admin-source), como o bloco `env`, os locks de sandbox, os caminhos binários de sandbox e `forceRemoteSettingsRefresh`. Consulte [settings precedence](/docs/pt/settings#settings-precedence).574O `.claude/settings.json` com commit no repositório se sobrepõe como configurações de projeto. Em uma sessão com vários repositórios, [no máximo o arquivo de um repositório tem efeito](#repository-settings-in-sessions-with-several-repositories). Sessões também leem [`managed-settings.json`](/docs/pt/settings#where-settings-live) do caminho de sistema padrão em sua imagem do runner. Se suas chaves se aplicam ao lado de [server-managed settings](/docs/pt/server-managed-settings) segue [como Claude Code combina fontes gerenciadas](/docs/pt/managed-settings#how-claude-code-combines-managed-sources): por padrão, quando sua organização entrega quaisquer chaves gerenciadas pelo servidor, sessões ignoram o arquivo da imagem do runner além das [chaves que Claude Code lê de cada fonte de administrador](/docs/pt/managed-settings#keys-read-from-every-admin-source), como o bloco `env`, os locks de sandbox, os caminhos binários de sandbox e `forceRemoteSettingsRefresh`. Consulte [settings precedence](/docs/pt/settings#settings-precedence).

575 575

576Quando o plano de controle da Anthropic fornece uma sessão com [Claude Code hooks](/docs/pt/hooks), o runner os instala ao lado, não sobre, sua própria configuração. Requer Claude Code v2.1.229 ou posterior.576Quando o plano de controle da Anthropic fornece uma sessão com [Claude Code hooks](/docs/pt/hooks), o runner os instala ao lado, não sobre, sua própria configuração. Requer Claude Code v2.1.229 ou posterior.

577 577

583 583

584O snapshot do `~/.claude/` do host feito pelo runner deixa de fora o diretório `projects/`. O local de armazenamento padrão da memória automática fica sob esse diretório. Se você colocar arquivos de memória lá, o runner não os semeia nas sessões, e eles não ativam a memória automática.584O snapshot do `~/.claude/` do host feito pelo runner deixa de fora o diretório `projects/`. O local de armazenamento padrão da memória automática fica sob esse diretório. Se você colocar arquivos de memória lá, o runner não os semeia nas sessões, e eles não ativam a memória automática.

585 585

586<h3 id="repository-settings-in-sessions-with-several-repositories">

587 Repository settings in sessions with several repositories

588</h3>

589

590Em uma sessão com vários repositórios, o Claude Code lê as configurações de projeto do diretório em que a sessão inicia, então no máximo o `.claude/settings.json` de um repositório tem efeito como configurações de projeto. Um hook definido no arquivo de outro repositório não é executado, uma regra deny nele não se aplica, e seu `env` não é definido.

591

592* **`--capacity 1`, o padrão, com o checkout integrado**: a sessão inicia no primeiro repositório de sua lista de repositórios. O `.claude/settings.json` desse repositório tem efeito como configurações de projeto e seu `.mcp.json` é carregado, e os dos outros repositórios não.

593* **Um `--capacity` acima de um, ou um [hook `checkout`](#checkout)**: a sessão inicia em um diretório por sessão que contém os checkouts. Nenhum `.claude/settings.json` de repositório tem efeito como configurações de projeto, nenhum `.mcp.json` de repositório é carregado, e [`$CLAUDE_PROJECT_DIR`](/docs/pt/hooks#reference-scripts-by-path) em um comando de hook é esse diretório, não um checkout.

594

595O `CLAUDE.md` e as skills de cada repositório são carregados onde quer que a sessão inicie. O runner passa cada repositório para o Claude Code como um [diretório adicional](/docs/pt/permissions#additional-directories-grant-file-access-not-configuration), então o Claude Code também lê as chaves `enabledPlugins` e `extraKnownMarketplaces` do `.claude/settings.json` de cada repositório.

596

597Para executar um hook ou aplicar uma regra de permissão em todas as sessões, coloque-o em `~/.claude/settings.json` no host do runner. O runner [semeia o arquivo do host em cada sessão](#how-each-session’s-config-is-assembled), onde quer que a sessão inicie. Escreva um caminho em uma regra `Read` ou `Edit` como um [padrão](/docs/pt/permissions#read-and-edit) absoluto `//` ou relativo ao diretório home `~/`, porque outros padrões se ancoram na origem das configurações ou no diretório atual.

598

586<h3 id="repository-committed-permission-rules">599<h3 id="repository-committed-permission-rules">

587 Repository-committed permission rules600 Repository-committed permission rules

588</h3>601</h3>

server-managed-settings.md +5 −1

Details

87 87

88 Como hooks executam comandos shell, os usuários em sessões interativas veem uma [caixa de diálogo de aprovação de segurança](#security-approval-dialogs) antes de Claude Code aplicá-los.88 Como hooks executam comandos shell, os usuários em sessões interativas veem uma [caixa de diálogo de aprovação de segurança](#security-approval-dialogs) antes de Claude Code aplicá-los.

89 89

90 Para configurar o classificador do [modo automático](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode) para que ele saiba quais repositórios, buckets e domínios sua organização confia, entregue um bloco `autoMode` da mesma forma; veja [Configurar modo automático](/docs/pt/auto-mode-config) para saber como as entradas `autoMode` afetam o que o classificador bloqueia e avisos importantes sobre os campos `environment`, `allow`, `soft_deny` e `hard_deny`.90 Para configurar o classificador do [modo auto](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode) para que ele saiba quais repositórios, buckets e domínios sua organização confia, entregue um bloco `autoMode` da mesma forma; veja [Configurar modo auto](/docs/pt/auto-mode-config) para saber como as entradas `autoMode` afetam o que o classificador bloqueia e avisos importantes sobre os campos `environment`, `allow`, `soft_deny` e `hard_deny`.

91 </Step>91 </Step>

92 92

93 <Step title="Salvar e implantar">93 <Step title="Salvar e implantar">

94 Salve suas alterações. Os clientes do Claude Code recebem as configurações atualizadas na próxima inicialização ou ciclo de polling por hora.94 Salve suas alterações. Os clientes do Claude Code recebem as configurações atualizadas na próxima inicialização ou ciclo de polling por hora.

96 O editor verifica seu JSON em relação ao esquema JSON publicado para as configurações do Claude Code. Se encontrar um problema em um JSON que pode ser analisado, ele exibe um aviso e renomeia o botão de salvar. O rótulo é **Update with errors** quando já há configurações salvas, e **Add with errors** quando ainda não há configurações salvas. Esse botão ainda salva, porque um aviso de esquema não bloqueia o salvamento.

98 O esquema [pode ficar defasado em relação às versões mais recentes](/docs/pt/settings#edit-a-settings-file), então o editor pode sinalizar uma chave ou valor que a [referência de configurações](/docs/pt/settings-reference#all-settings) documenta. Claude Code recebe as chaves e valores que você salvou e executa [sua própria validação](#invalid-entries-in-delivered-settings) quando os carrega.

95 </Step>99 </Step>

96</Steps>100</Steps>

97 101

settings.md +2 −2

Details

521 521

522Em uma sessão [Cowork](https://claude.com/docs/cowork/overview) que é executada em sua máquina no aplicativo Claude Desktop, o Claude Code não busca configurações gerenciadas pelo servidor do console de administração claude.ai, e lê a política implantada em seu dispositivo a menos que a configuração Claude Desktop da sua organização defina `requireCoworkFullVmSandbox`. [Onde e quando uma política se aplica](/docs/pt/managed-settings#where-and-when-a-policy-applies) cobre Cowork e sessões na nuvem.522Em uma sessão [Cowork](https://claude.com/docs/cowork/overview) que é executada em sua máquina no aplicativo Claude Desktop, o Claude Code não busca configurações gerenciadas pelo servidor do console de administração claude.ai, e lê a política implantada em seu dispositivo a menos que a configuração Claude Desktop da sua organização defina `requireCoworkFullVmSandbox`. [Onde e quando uma política se aplica](/docs/pt/managed-settings#where-and-when-a-policy-applies) cobre Cowork e sessões na nuvem.

523 523

524Se você é o administrador, [Configure o Claude Code para sua organização](/docs/pt/admin-setup) o guia através da escolha do que impor, e [Implante configurações gerenciadas](/docs/pt/managed-settings) cobre entrega e como confirmar que uma política está em vigor.524Se você é o administrador, [Configure o Claude Code para sua organização](/docs/pt/admin-setup) o guia através da escolha do que impor, e [Implante configurações gerenciadas](/docs/pt/managed-settings) cobre entrega e como confirmar que uma política está em vigor. Para o aviso que o editor de configurações gerenciadas no console de administração claude.ai pode mostrar, veja [Configurar configurações gerenciadas pelo servidor](/docs/pt/server-managed-settings#configure-server-managed-settings).

525 525

526<h2 id="change-a-setting">526<h2 id="change-a-setting">

527 Altere uma configuração527 Altere uma configuração

809 809

810Uma [sessão em nuvem](/docs/pt/claude-code-on-the-web) é executada em um [ambiente em nuvem](/docs/pt/cloud-environments) em um clone fresco do seu repositório, não em sua máquina. Isso muda quais configurações a alcançam:810Uma [sessão em nuvem](/docs/pt/claude-code-on-the-web) é executada em um [ambiente em nuvem](/docs/pt/cloud-environments) em um clone fresco do seu repositório, não em sua máquina. Isso muda quais configurações a alcançam:

811 811

812* **Configurações compartilhadas de projeto** (`.claude/settings.json`): lidas em uma sessão com um repositório, porque o arquivo faz parte do clone e a sessão começa dentro dele. Confirme uma configuração lá para aplicá-la nessas sessões. Uma sessão com vários repositórios começa acima dos clones e lê apenas as chaves `enabledPlugins` e `extraKnownMarketplaces` do `.claude/settings.json` de cada repositório, não regras de permissão, hooks, `env` ou outras chaves. Os marketplaces e plugins que essas duas chaves declaram ainda [não carregam em uma sessão em nuvem](/docs/pt/cloud-environments#what-carries-over-from-your-setup).812* **Configurações compartilhadas de projeto** (`.claude/settings.json`): lidas em uma sessão com um repositório, porque o arquivo faz parte do clone e a sessão começa dentro dele. Faça commit de uma configuração lá para aplicá-la nessas sessões. Em um ambiente hospedado pela Anthropic, uma sessão com vários repositórios começa acima dos clones e lê apenas as chaves `enabledPlugins` e `extraKnownMarketplaces` do `.claude/settings.json` de cada repositório, não regras de permissão, hooks, `env` ou outras chaves. Os marketplaces e plugins que essas duas chaves declaram ainda [não carregam em uma sessão na nuvem](/docs/pt/cloud-environments#what-carries-over-from-your-setup). Para um ambiente auto-hospedado, consulte [quais configurações de repositório se aplicam](/docs/pt/self-hosted-environments-configuration#repository-settings-in-sessions-with-several-repositories).

813* **Configurações de usuário e projeto local** (`~/.claude/settings.json` e `.claude/settings.local.json`): não lidas. Ambas permanecem em sua máquina, e o arquivo local não está no clone.813* **Configurações de usuário e projeto local** (`~/.claude/settings.json` e `.claude/settings.local.json`): não lidas. Ambas permanecem em sua máquina, e o arquivo local não está no clone.

814* **Configurações gerenciadas**: um arquivo `managed-settings.json` ou perfil MDM em seu dispositivo não alcança uma sessão em nuvem. As [configurações gerenciadas pelo servidor](/docs/pt/server-managed-settings) da sua organização alcançam; [cobertura de superfície](/docs/pt/model-config#surface-coverage) lista quais sessões em nuvem as recebem. Um [ambiente auto-hospedado](/docs/pt/self-hosted-environments) também lê o arquivo de configurações gerenciadas em sua imagem de runner. [Como o Claude Code combina fontes gerenciadas](/docs/pt/managed-settings#how-claude-code-combines-managed-sources) diz quando esse arquivo se aplica.814* **Configurações gerenciadas**: um arquivo `managed-settings.json` ou perfil MDM em seu dispositivo não alcança uma sessão em nuvem. As [configurações gerenciadas pelo servidor](/docs/pt/server-managed-settings) da sua organização alcançam; [cobertura de superfície](/docs/pt/model-config#surface-coverage) lista quais sessões em nuvem as recebem. Um [ambiente auto-hospedado](/docs/pt/self-hosted-environments) também lê o arquivo de configurações gerenciadas em sua imagem de runner. [Como o Claude Code combina fontes gerenciadas](/docs/pt/managed-settings#how-claude-code-combines-managed-sources) diz quando esse arquivo se aplica.

815* **`/config`**: no seu navegador em claude.ai/code, abre a seção Claude Code de suas configurações claude.ai em vez de alterar um valor. Para alterar uma configuração para uma sessão em nuvem, defina uma [variável de ambiente](/docs/pt/cloud-environments#set-environment-variables) no ambiente, ou em uma sessão com um repositório, confirme a chave no `.claude/settings.json` desse repositório.815* **`/config`**: no seu navegador em claude.ai/code, abre a seção Claude Code de suas configurações claude.ai em vez de alterar um valor. Para alterar uma configuração para uma sessão em nuvem, defina uma [variável de ambiente](/docs/pt/cloud-environments#set-environment-variables) no ambiente, ou em uma sessão com um repositório, confirme a chave no `.claude/settings.json` desse repositório.

skills.md +2 −0

Details

97| `managed-agents-onboard <url>` | Crie o Managed Agent que a página na URL descreve, como uma página na [documentação de Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview) | v2.1.290 ou posterior |

98| `managed-agents-onboard <quickstart-name>` | Crie um dos modelos de início rápido do Console, como `deep-researcher`. Se você fornecer uma palavra que não seja o nome de um modelo, Claude lista os nomes válidos | v2.1.290 ou posterior |

98| `cost-optimize` | Perfil onde o gasto da Claude API do seu projeto vai e proponha economias de opções como prompt caching, redução de tokens de entrada e saída desnecessários, processamento em lote, esforço e escolha de modelo, uma alteração por vez | v2.1.247 ou posterior |100| `cost-optimize` | Perfil onde o gasto da Claude API do seu projeto vai e proponha economias de opções como prompt caching, redução de tokens de entrada e saída desnecessários, processamento em lote, esforço e escolha de modelo, uma alteração por vez | v2.1.247 ou posterior |

sub-agents.md +4 −2

Details

609O modo de permissão da conversa principal decide se o Claude Code usa o valor que você definiu:609O modo de permissão da conversa principal decide se o Claude Code usa o valor que você definiu:

610 610

611* Quando a conversa principal está em `bypassPermissions`, `acceptEdits` ou no [modo auto](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode), o subagente é executado nesse mesmo modo e o Claude Code ignora o `permissionMode` que você definiu. No modo auto, o classificador avalia as chamadas de ferramenta do subagente com as regras de bloqueio e de permissão da conversa principal. Quando o subagente termina, o classificador também revisa seu trabalho e seu relatório final antes que o relatório seja entregue, conforme descrito em [Como o modo auto lida com subagentes](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode).611* Quando a conversa principal está em `bypassPermissions`, `acceptEdits` ou no [modo auto](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode), o subagente é executado nesse mesmo modo e o Claude Code ignora o `permissionMode` que você definiu. No modo auto, o classificador avalia as chamadas de ferramenta do subagente com as regras de bloqueio e de permissão da conversa principal. Quando o subagente termina, o classificador também revisa seu trabalho e seu relatório final antes que o relatório seja entregue, conforme descrito em [Como o modo auto lida com subagentes](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode).

612* Quando a conversa principal está no modo `default`, `dontAsk` ou `plan`, o subagente é executado no modo de permissão que você definiu, exceto `bypassPermissions`. Um subagente que declara `bypassPermissions` mantém, em vez disso, o modo da conversa principal. A exceção de `bypassPermissions` requer o Claude Code v2.1.267 ou posterior.612* Quando a conversa principal está no modo `default`, `dontAsk` ou `plan`, o subagente é executado no modo de permissão que você definiu. Em vez disso, ele mantém o modo de permissão da conversa principal nestes casos:

613 * Você define `bypassPermissions`. A exceção de `bypassPermissions` requer o Claude Code v2.1.267 ou posterior.

614 * Você define `auto` e o [modo auto não está disponível](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode) para o subagente, como quando um arquivo de configurações define [`disableAutoMode`](/docs/pt/settings-reference#disableautomode) ou o modelo do subagente não suporta o modo auto.

613 615

614`permissionMode` aceita estes valores, e `manual` como alias para `default`:616`permissionMode` aceita estes valores, e `manual` como alias para `default`:

615 617

640Implement API endpoints. Follow the conventions and patterns from the preloaded skills.642Implement API endpoints. Follow the conventions and patterns from the preloaded skills.

641```643```

642 644

643O conteúdo completo de cada skill listada é injetado no contexto do subagente na inicialização. Este campo controla quais skills são pré-carregadas, e não quais skills o subagente pode acessar: sem ele, o subagente ainda pode descobrir e invocar skills de projeto, de usuário e de plugin por meio da ferramenta Skill durante a execução. Para impedir totalmente que um subagente invoque skills, omita `Skill` da lista [`tools`](#available-tools) ou adicione-a a `disallowedTools`.645O conteúdo completo de cada skill listada é injetado no contexto do subagente na inicialização, até os primeiros 32 nomes distintos da lista. Este campo controla quais skills são pré-carregadas, e não quais skills o subagente pode acessar: sem ele, o subagente ainda pode descobrir e invocar skills de projeto, de usuário e de plugin por meio da ferramenta Skill durante a execução. Para impedir totalmente que um subagente invoque skills, omita `Skill` da lista [`tools`](#available-tools) ou adicione-a a `disallowedTools`.

644 646

645Você não pode pré-carregar skills que definem [`disable-model-invocation: true`](/docs/pt/skills#control-who-invokes-a-skill), pois o pré-carregamento usa o mesmo conjunto de skills que o Claude pode invocar. Isso inclui a skill integrada `/verify`, que o Claude não pode executar por conta própria.647Você não pode pré-carregar skills que definem [`disable-model-invocation: true`](/docs/pt/skills#control-who-invokes-a-skill), pois o pré-carregamento usa o mesmo conjunto de skills que o Claude pode invocar. Isso inclui a skill integrada `/verify`, que o Claude não pode executar por conta própria.

646 648

tools-reference.md +1 −1

Details

666 666

667* WebFetch recusa `localhost` e qualquer outro nome de host sem um ponto, como um nome de intranet simples, antes de fazer uma solicitação. O [erro que retorna](/docs/pt/errors#webfetch-cannot-fetch-localhost) diz a Claude para alcançar servidores locais com `curl` através do Bash.667* WebFetch recusa `localhost` e qualquer outro nome de host sem um ponto, como um nome de intranet simples, antes de fazer uma solicitação. O [erro que retorna](/docs/pt/errors#webfetch-cannot-fetch-localhost) diz a Claude para alcançar servidores locais com `curl` através do Bash.

668* URLs HTTP são automaticamente atualizadas para HTTPS.668* URLs HTTP são automaticamente atualizadas para HTTPS.

669* Páginas grandes são truncadas para um limite de caracteres fixo antes do processamento.669* WebFetch lê até 100.000 caracteres do conteúdo de uma página por chamada. No Claude Code v2.1.290 ou posterior, o resultado para uma página mais longa informa a Claude quanto ficou sem ser lido, para que Claude possa buscar a próxima parte.

670* WebFetch armazena em cache cada resposta por 15 minutos por padrão, então buscas repetidas da mesma URL retornam rapidamente. No Claude Code v2.1.233 ou posterior, defina [`CLAUDE_CODE_WEBFETCH_CACHE_TTL_MS`](/docs/pt/env-vars#variables) para alterar quanto tempo WebFetch mantém cada resposta.670* WebFetch armazena em cache cada resposta por 15 minutos por padrão, então buscas repetidas da mesma URL retornam rapidamente. No Claude Code v2.1.233 ou posterior, defina [`CLAUDE_CODE_WEBFETCH_CACHE_TTL_MS`](/docs/pt/env-vars#variables) para alterar quanto tempo WebFetch mantém cada resposta.

671* Uma página que não terminou de fazer download em cinco minutos, incluindo qualquer redirecionamento que WebFetch segue, falha com um erro de deadline. No Claude Code v2.1.268 ou posterior, defina [`CLAUDE_CODE_WEBFETCH_DEADLINE_MS`](/docs/pt/env-vars#variables) para alterar o limite, ou para `0` para removê-lo.671* Uma página que não terminou de fazer download em cinco minutos, incluindo qualquer redirecionamento que WebFetch segue, falha com um erro de deadline. No Claude Code v2.1.268 ou posterior, defina [`CLAUDE_CODE_WEBFETCH_DEADLINE_MS`](/docs/pt/env-vars#variables) para alterar o limite, ou para `0` para removê-lo.

672* Quando uma URL redireciona para um host diferente, WebFetch retorna um resultado de texto que nomeia a URL original e o alvo de redirecionamento em vez de segui-lo. Claude então busca a nova URL com uma segunda chamada WebFetch.672* Quando uma URL redireciona para um host diferente, WebFetch retorna um resultado de texto que nomeia a URL original e o alvo de redirecionamento em vez de segui-lo. Claude então busca a nova URL com uma segunda chamada WebFetch.

ultrareview.md +6 −6

Details

56 Revisar uma pull request56 Revisar uma pull request

57</h3>57</h3>

58 58

~~59Para revisar uma pull request do GitHub em vez de uma branch local, passe o número da PR:~~59Para revisar um pull request em `github.com` em vez de um branch local, passe o número do PR:

60 60

61```text theme={null}61```text theme={null}

62/code-review ultra 123462/code-review ultra 1234

64 64

65O comando também aceita `#1234`, `PR 1234` e URLs de PR coladas; uma URL colada deve apontar para o repositório em seu diretório atual.65O comando também aceita `#1234`, `PR 1234` e URLs de PR coladas; uma URL colada deve apontar para o repositório em seu diretório atual.

66 66

67No modo PR, o sandbox remoto clona a pull request diretamente do host em vez de agrupar sua árvore de trabalho local. O modo PR funciona com repositórios em `github.com` e em instâncias do [GitHub Enterprise Server](/docs/pt/github-enterprise-server) que um proprietário conectou ao Claude Code.67O modo PR requer um repositório em `github.com`. Para um repositório em uma instância do [GitHub Enterprise Server](/docs/pt/github-enterprise-server), execute `/code-review ultra` sem um número de PR para revisar seu branch local em vez disso.

68 68

~~69Para repositórios em `github.com`, o sandbox clona com a conta do GitHub conectada à sua conta Claude, portanto a conta deve ser capaz de ler o repositório da PR.~~69No modo PR, o sandbox na nuvem clona o pull request de `github.com` em vez de carregar sua árvore de trabalho. Ele usa a conta do GitHub conectada à sua conta Claude, portanto essa conta precisa de acesso de leitura ao repositório.

70 70

71Execute [`/web-setup`](/docs/pt/web-quickstart#connect-from-your-terminal) para conectar seu login do GitHub CLI à sua conta Claude.71Execute [`/web-setup`](/docs/pt/web-quickstart#connect-from-your-terminal) para conectar seu login do GitHub CLI à sua conta Claude.

72 72

74 Postar descobertas na pull request74 Postar descobertas na pull request

75</h3>75</h3>

76 76

77No Claude Code v2.1.227 ou posterior, quando você revisa uma pull request em `github.com`, você pode fazer com que Claude poste as descobertas concluídas na PR como um único comentário simples de sua própria conta GitHub. O comentário não é uma revisão ou uma aprovação, e termina com uma nota "Gerado por Claude Code". Quando você revisa uma branch ou uma pull request do GitHub Enterprise Server, Claude Code mostra as descobertas em sua sessão apenas.77No Claude Code v2.1.227 ou posterior, quando você revisa um pull request em `github.com`, você pode fazer com que Claude poste as descobertas concluídas no PR como um único comentário simples de sua própria conta GitHub. O comentário não é uma revisão ou uma aprovação, e termina com uma nota "Generated by Claude Code". Quando você revisa um branch, Claude Code mostra as descobertas apenas em sua sessão.

78 78

79Claude Code nunca posta a menos que você escolha nessa execução, e `--no-post` é o padrão. Postar é uma escolha que você faz para cada execução:79Claude Code nunca posta a menos que você escolha nessa execução, e `--no-post` é o padrão. Postar é uma escolha que você faz para cada execução:

80 80

106Claude Code trata seu texto como uma nota apenas quando tem mais de uma palavra e não é um nome de branch ou referência de PR. Ele lê uma única palavra como um nome de branch ou referência de PR, portanto um nome de branch digitado incorretamente recebe o erro de branch mais próximo de [Revisar contra uma base diferente](#review-against-a-different-base) em vez de iniciar com uma nota. Se seu texto combinar uma referência de PR com outras palavras, como `check PR 123 again`, Claude Code também não inicia; ele pede que você execute novamente com apenas o número da PR para revisar essa PR, ou sem a referência para revisar sua branch atual.106Claude Code trata seu texto como uma nota apenas quando tem mais de uma palavra e não é um nome de branch ou referência de PR. Ele lê uma única palavra como um nome de branch ou referência de PR, portanto um nome de branch digitado incorretamente recebe o erro de branch mais próximo de [Revisar contra uma base diferente](#review-against-a-different-base) em vez de iniciar com uma nota. Se seu texto combinar uma referência de PR com outras palavras, como `check PR 123 again`, Claude Code também não inicia; ele pede que você execute novamente com apenas o número da PR para revisar essa PR, ou sem a referência para revisar sua branch atual.

107 107

108<Tip>108<Tip>

109 Se seu repositório for muito grande para agrupar, Claude Code o solicita a usar o modo PR. Envie sua branch e abra uma PR de rascunho, depois execute `/code-review ultra <PR-number>`.109 Se seu repositório for muito grande para agrupar, Claude Code pede que você use o modo PR em vez disso. Para um repositório em `github.com`, envie seu branch e abra um PR de rascunho, depois execute `/code-review ultra <PR-number>`.

110</Tip>110</Tip>

111 111

112<h3 id="diff-limits-and-fallbacks">112<h3 id="diff-limits-and-fallbacks">

173claude ultrareview origin/main173claude ultrareview origin/main

174```174```

175 175

176Sem argumentos, o subcomando revisa o diff entre sua branch atual e a branch padrão, com o mesmo [fallback de repositório inteiro](#diff-limits-and-fallbacks) que `/code-review ultra` quando não existe base de mesclagem. Passe um número de PR para revisar uma pull request, ou uma branch base para revisar em relação a ela; o [tratamento de branch base](#review-against-a-different-base) corresponde ao comando interativo.176Sem argumentos, o subcomando revisa o diff entre sua branch atual e a branch padrão, com o mesmo [fallback de repositório inteiro](#diff-limits-and-fallbacks) que `/code-review ultra` quando não existe base de mesclagem. Passe um número de PR para [revisar um pull request no `github.com`](#review-a-pull-request), ou uma branch base para revisar em relação a ela; o [tratamento de branch base](#review-against-a-different-base) corresponde ao comando interativo.

177 177

178Você consente com o fallback de repositório inteiro e com o aviso de faturamento e termos quando executa o subcomando, portanto a execução começa sem aguardar entrada. Executar você mesmo é o que conta como consentimento. Quando Claude executa o subcomando para você, por exemplo através da ferramenta Bash, Claude Code recusa a revisão de repositório inteiro.178Você consente com o fallback de repositório inteiro e com o aviso de faturamento e termos quando executa o subcomando, portanto a execução começa sem aguardar entrada. Executar você mesmo é o que conta como consentimento. Quando Claude executa o subcomando para você, por exemplo através da ferramenta Bash, Claude Code recusa a revisão de repositório inteiro.

179 179

workflows.md +27 −1

Details

354 354

355O corpo é JavaScript simples com `await` no nível superior. `agent()` gera um subagente, `pipeline()` executa um por item em uma lista, e `parallel()` executa um conjunto de tarefas de agente ao mesmo tempo e aguarda todas elas.355O corpo é JavaScript simples com `await` no nível superior. `agent()` gera um subagente, `pipeline()` executa um por item em uma lista, e `parallel()` executa um conjunto de tarefas de agente ao mesmo tempo e aguarda todas elas.

356 356

357Uma chamada `agent()` é resolvida para `null` se você a interromper no meio da execução ou se ela atingir um erro de API irrecuperável. `pipeline()` mantém cada `null` na matriz de resultados, e é por isso que o exemplo termina com `.filter(Boolean)` para descartar essas entradas.357Uma chamada `agent()` é resolvida para `null` se você a interromper no meio da execução ou se ela atingir um erro de API irrecuperável. `pipeline()` mantém cada `null` na matriz de resultados, e é por isso que o exemplo termina com `.filter(Boolean)` para descartar essas entradas, incluindo a posição de [um agente que travou em todas as tentativas](#when-an-agent-stalls-and-restarts).

358 358

359No [modo automático](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode), o prompt que seu script passa para `agent()` não conta como uma solicitação sua quando o classificador revisa as ações desse subagente, porque Claude Code o marca como texto que o script calculou.359No [modo automático](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode), o prompt que seu script passa para `agent()` não conta como uma solicitação sua quando o classificador revisa as ações desse subagente, porque Claude Code o marca como texto que o script calculou.

360 360

463* O limite é redefinido dentro de 24 horas. Um limite semanal pode ser redefinido mais adiante.463* O limite é redefinido dentro de 24 horas. Um limite semanal pode ser redefinido mais adiante.

464* A execução ainda não aguardou duas vezes. Quando atinge o limite pela terceira vez, o agente falha.464* A execução ainda não aguardou duas vezes. Quando atinge o limite pela terceira vez, o agente falha.

465 465

466<h3 id="when-an-agent-stalls-and-restarts">

467 Quando um agente trava e reinicia

468</h3>

469

470Um agente cuja saída para de chegar por tempo suficiente começa novamente a partir do mesmo prompt. Em [`/workflows`](#watch-the-run), seu nome ganha um sufixo `(retry 1)` e seu detalhe mostra `attempt 2 (stalled)`. A reinicialização é automática, então você não precisa fazer nada.

471

472A nova tentativa começa sem a transcrição da tentativa travada. Arquivos que a tentativa travada já alterou permanecem alterados, e os tokens que ela gastou permanecem no total da execução. A janela de travamento é quanto tempo Claude Code aguarda por saída de um agente antes de encerrar a tentativa. O tempo que o agente passa aguardando suas próprias chamadas de ferramenta ou uma [redefinição do limite de uso](#when-a-run-hits-your-usage-limit) não conta para a janela de travamento.

473

474Um agente reinicia no máximo cinco vezes, contando qualquer reinicialização que você solicite com `r`. Se a sexta tentativa também travar, a chamada `agent()` falha, e o início do erro diz o motivo:

475

476* `agent stalled on all 6 attempts`: todas as tentativas passaram a janela inteira sem saída. Se o trabalho do agente o mantém em silêncio por tanto tempo, aumente a janela

477* `agent lost its reply on all 6 attempts`: o stream de resposta de cada tentativa ficou em silêncio e Claude Code desistiu de aguardá-lo. Aumentar a janela de travamento não ajuda, já que um [watchdog de inatividade de streaming](/docs/pt/network-config#streaming-idle-watchdogs) encerrou a resposta primeiro e `CLAUDE_STREAM_IDLE_TIMEOUT_MS` define o timeout desse watchdog

478* `agent abandoned after 6 attempts`: as tentativas terminaram de maneiras diferentes, que o erro lista em ordem

479

480Para dar a um agente mais tempo para produzir saída antes que a janela termine:

481

482* **Um agente**: passe `stallMs` em milissegundos na sua chamada `agent()`, como `agent(prompt, { stallMs: 1800000 })` para 30 minutos

483* **Todos os agentes**: defina [`CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`](/docs/pt/env-vars#variables), que também se aplica a subagentes fora de fluxos de trabalho

484

485Se a execução continua após a falha depende de como seu script chamou o agente:

486

487* **Dentro de [`parallel()` ou `pipeline()`](#what-the-saved-script-looks-like)**: a execução prossegue com `null` no lugar do resultado do agente

488* **Aguardado diretamente**: a execução termina com o erro

489

490Para tentar novamente, peça a Claude para relançar o fluxo de trabalho. [Retomar após uma pausa](#resume-after-a-pause) cobre o que é executado novamente.

491

466<h3 id="cost">492<h3 id="cost">

467 Custo493 Custo

468</h3>494</h3>

worktrees.md +1 −1

Details

104* **Redirecionamentos git**: Claude Code bloqueia um comando Bash ou Monitor que redireciona git para o checkout principal. O redirecionamento pode vir através de `git -C`, `--git-dir`, uma variável `GIT_DIR` ou `GIT_WORK_TREE`, ou um `cd` para o checkout principal antes de executar git.104* **Redirecionamentos git**: Claude Code bloqueia um comando Bash ou Monitor que redireciona git para o checkout principal. O redirecionamento pode vir através de `git -C`, `--git-dir`, uma variável `GIT_DIR` ou `GIT_WORK_TREE`, ou um `cd` para o checkout principal antes de executar git.

105* **Forma do comando**: Claude Code bloqueia um comando Bash ou Monitor quando não pode verificar do texto do comando que qualquer git que o comando executa fica dentro da worktree. Isso acontece, por exemplo, quando o nome do comando é computado em tempo de execução, quando a sintaxe não pode ser analisada, ou quando uma expansão como `${!name}` ou `${ command; }` poderia executar um comando que o texto não especifica. Claude Code diz a Claude como reescrever o comando recusado, como dividi-lo em comandos simples e separados. Você não pode desativar essa verificação.105* **Forma do comando**: Claude Code bloqueia um comando Bash ou Monitor quando não pode verificar do texto do comando que qualquer git que o comando executa fica dentro da worktree. Isso acontece, por exemplo, quando o nome do comando é computado em tempo de execução, quando a sintaxe não pode ser analisada, ou quando uma expansão como `${!name}` ou `${ command; }` poderia executar um comando que o texto não especifica. Claude Code diz a Claude como reescrever o comando recusado, como dividi-lo em comandos simples e separados. Você não pode desativar essa verificação.

106 106

107Essas verificações leem o caminho que uma edição visa, o diretório em que um comando é executado e o texto do comando. Nenhuma delas rastreia quais arquivos um comando de shell escreve, então um comando que escreve no checkout principal sem executar git lá, como `cp` ou um redirecionamento do shell, não é recusado por elas. Claude Code trata esse comando como qualquer outro comando de shell, então se ele é executado ou pede sua confirmação depende do seu [modo de permissão](/docs/pt/permission-modes) e das suas regras.107Essas verificações leem o caminho que uma edição visa, o diretório em que um comando é executado e o texto do comando. Nenhuma delas rastreia quais arquivos um comando de shell escreve, então um comando que escreve no checkout principal sem executar git lá, como `cp` ou um redirecionamento do shell, não é recusado por elas. Claude Code trata esse comando como qualquer outro comando de shell sob suas configurações de [permissões](/docs/pt/permissions) e [sandboxing](/docs/pt/sandboxing).

108 108

109As verificações se aplicam ao repositório de onde você iniciou Claude Code. Elas também cobrem o checkout principal que uma worktree vinculada está vinculada de. Para comandos PowerShell, Claude Code aplica apenas a verificação de diretório de trabalho.109As verificações se aplicam ao repositório de onde você iniciou Claude Code. Elas também cobrem o checkout principal que uma worktree vinculada está vinculada de. Para comandos PowerShell, Claude Code aplica apenas a verificação de diretório de trabalho.

110 110

Documentation 2026-10-08 22:58 UTC to 2026-10-09 15:58 UTC