Documentation — Spybara

admin-setup.md +2 −0

Details

91| [Required version range](/pt/settings) | Recusar iniciar completamente quando a versão em execução está fora de um intervalo aprovado pela organização. Mais forte que `minimumVersion`, que apenas bloqueia downgrades | `requiredMinimumVersion`, `requiredMaximumVersion` |91| [Required version range](/pt/settings) | Recusar iniciar completamente quando a versão em execução está fora de um intervalo aprovado pela organização. Mais forte que `minimumVersion`, que apenas bloqueia downgrades | `requiredMinimumVersion`, `requiredMaximumVersion` |

92 92

93As organizações cujos membros se autenticam através de claude.ai ou da API Anthropic também podem governar modelos sem implantar configurações: [restrições de modelo da organização](/pt/model-config#organization-model-restrictions) desabilitam modelos individuais, um [modelo padrão da organização](/pt/model-config#organization-default-model) define em qual modelo novas sessões começam, e [limites de esforço da organização](/pt/model-config#organization-effort-limits) limitam níveis de esforço por função. Todos os três controles exigem um plano Claude Enterprise. As restrições de modelo e limites de esforço são aplicados no servidor; o modelo padrão é um ponto de partida que os usuários podem alterar, a menos que a organização o aplique. A aplicação está disponível para um conjunto limitado de organizações; pergunte ao seu time de contas Anthropic sobre disponibilidade. Nenhum desses controles alcança sessões no Amazon Bedrock, na Agent Platform do Google Cloud, no Microsoft Foundry, ou [Claude Platform on AWS](/pt/claude-platform-on-aws); nesses provedores, use `availableModels` acima para restrições e a chave `model` em configurações gerenciadas para um padrão.

93As regras de permissão e sandboxing cobrem camadas diferentes. Negar WebFetch bloqueia a ferramenta de busca do Claude, mas se Bash for permitido, `curl` e `wget` ainda podem alcançar qualquer URL. O sandboxing fecha essa lacuna com uma lista de permissão de domínio de rede aplicada no nível do SO.95As regras de permissão e sandboxing cobrem camadas diferentes. Negar WebFetch bloqueia a ferramenta de busca do Claude, mas se Bash for permitido, `curl` e `wget` ainda podem alcançar qualquer URL. O sandboxing fecha essa lacuna com uma lista de permissão de domínio de rede aplicada no nível do SO.

94 96

95Para o modelo de ameaça que esses controles defendem, consulte [Security](/pt/security).97Para o modelo de ameaça que esses controles defendem, consulte [Security](/pt/security).

advisor.md +4 −3

Details

85O advisor deve ser pelo menos tão capaz quanto o modelo principal. Os advisors aceitos para cada modelo principal são:85O advisor deve ser pelo menos tão capaz quanto o modelo principal. Os advisors aceitos para cada modelo principal são:

86 86

88| ----------------------------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |88| ----------------------------------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

90| Sonnet 4.6 | Fable, Opus, Sonnet | |90| Sonnet 4.6 | Fable, Opus, Sonnet | |

93| Opus 4.7 ou posterior | Fable, Opus 4.7, Opus 4.8 | Opus 4.7 e Opus 4.8 são classificados como igualmente capazes, então qualquer um aceita o outro como um advisor. Um Opus 4.7 principal com um advisor Opus 4.6 ou Sonnet 5 é rejeitado |

93| Fable 5 ({/* min-version: 2.1.170 */}v2.1.170+) | Fable | Um advisor Opus ou Sonnet é rejeitado |94| Fable 5 ({/* min-version: 2.1.170 */}v2.1.170+) | Fable | Um advisor Opus ou Sonnet é rejeitado |

94 95

95Fable 5 requer Claude Code v2.1.170 ou posterior e acesso a Fable 5, seja atuando como modelo principal ou advisor.96Fable 5 requer Claude Code v2.1.170 ou posterior e acesso a Fable 5, seja atuando como modelo principal ou advisor.

174/advisor off175/advisor off

175```176```

176 177

177Para desativar a ferramenta advisor inteiramente, incluindo o comando `/advisor` e a flag `--advisor`, defina `CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1`. Veja [Environment variables](/pt/env-vars).178Para desativar a ferramenta advisor inteiramente, defina `CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1`. O comando `/advisor` fica indisponível e qualquer `advisorModel` configurado é ignorado. A flag `--advisor` é aceita mas não tem efeito; scripts existentes que a passam continuam funcionando sem erros. Veja [Environment variables](/pt/env-vars).

178 179

179<h2 id="compare-with-related-features">180<h2 id="compare-with-related-features">

180 Compare com recursos relacionados181 Compare com recursos relacionados

agent-sdk/agent-loop.md +41 −0

Details

86<Accordion title="Exemplo: Verificar tipos de mensagens e lidar com resultados">86<Accordion title="Exemplo: Verificar tipos de mensagens e lidar com resultados">

87 <CodeGroup>87 <CodeGroup>

88 ```python Python theme={null}88 ```python Python theme={null}

89 import asyncio

89 from claude_agent_sdk import query, AssistantMessage, ResultMessage90 from claude_agent_sdk import query, AssistantMessage, ResultMessage

90 91

93 async def main():

94 try:

91 async for message in query(prompt="Summarize this project"):95 async for message in query(prompt="Summarize this project"):

92 if isinstance(message, AssistantMessage):96 if isinstance(message, AssistantMessage):

93 print(f"Turn completed: {len(message.content)} content blocks")97 print(f"Turn completed: {len(message.content)} content blocks")

96 print(message.result)100 print(message.result)

97 else:101 else:

98 print(f"Stopped: {message.subtype}")102 print(f"Stopped: {message.subtype}")

103 except Exception as error:

104 # A single-shot query() raises after yielding an error result. If the

105 # failure was an error result, the error subtype branches above have

106 # already run; connection or process failures yield no result message.

107 print(f"Session ended with an error: {error}")

108

109

110 asyncio.run(main())

99 ```111 ```

100 112

101 ```typescript TypeScript theme={null}113 ```typescript TypeScript theme={null}

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

103 115

116 try {

104 for await (const message of query({ prompt: "Summarize this project" })) {117 for await (const message of query({ prompt: "Summarize this project" })) {

105 if (message.type === "assistant") {118 if (message.type === "assistant") {

106 console.log(`Turn completed: ${message.message.content.length} content blocks`);119 console.log(`Turn completed: ${message.message.content.length} content blocks`);

113 }126 }

114 }127 }

115 }128 }

129 } catch (error) {

130 // A single-shot query() throws after yielding an error result. If the

131 // failure was an error result, the error subtype branches above have

132 // already run; connection or process failures yield no result message.

133 console.log(`Session ended with an error: ${error}`);

134 }

116 ```135 ```

117 </CodeGroup>136 </CodeGroup>

118</Accordion>137</Accordion>

321 340

322O campo `result` (a saída de texto final) está presente apenas na variante `success`, então sempre verifique o subtipo antes de lê-lo. Todos os subtipos de resultado carregam `total_cost_usd`, `usage`, `num_turns` e `session_id` para que você possa rastrear custo e retomar mesmo após erros. Em Python, `total_cost_usd` e `usage` são digitados como opcionais e podem ser `None` em alguns caminhos de erro, então proteja antes de formatá-los. Veja [Rastreamento de custos e uso](/pt/agent-sdk/cost-tracking) para detalhes sobre interpretação dos campos `usage`.341O campo `result` (a saída de texto final) está presente apenas na variante `success`, então sempre verifique o subtipo antes de lê-lo. Todos os subtipos de resultado carregam `total_cost_usd`, `usage`, `num_turns` e `session_id` para que você possa rastrear custo e retomar mesmo após erros. Em Python, `total_cost_usd` e `usage` são digitados como opcionais e podem ser `None` em alguns caminhos de erro, então proteja antes de formatá-los. Veja [Rastreamento de custos e uso](/pt/agent-sdk/cost-tracking) para detalhes sobre interpretação dos campos `usage`.

323 342

343<Note>

344 Quando uma consulta termina em um resultado de erro:

345

346 * Uma chamada `query()` de uma única vez produz a mensagem de resultado final e depois lança um erro que inclui o texto de falha, como `Reached maximum number of turns`. O lançamento é intencional — envolva o loop em um bloco try se seu código precisar continuar após ele. O processo Claude Code subjacente também sai com um código diferente de zero.

347 * Uma sessão de entrada de streaming permanece ativa e você pode continuar enviando mensagens.

348</Note>

349

324O resultado também inclui um campo `stop_reason` (`string | null` em TypeScript, `str | None` em Python) indicando por que o modelo parou de gerar em sua volta final. Valores comuns são `end_turn` (modelo terminou normalmente), `max_tokens` (atingiu o limite de token de saída) e `refusal` (o modelo recusou a requisição). Em subtipos de resultado de erro, `stop_reason` carrega o valor da última resposta do assistente antes do loop terminar. Para detectar recusas, verifique `stop_reason === "refusal"` (TypeScript) ou `stop_reason == "refusal"` (Python). Veja [`SDKResultMessage`](/pt/agent-sdk/typescript#sdkresultmessage) (TypeScript) ou [`ResultMessage`](/pt/agent-sdk/python#resultmessage) (Python) para o tipo completo.350O resultado também inclui um campo `stop_reason` (`string | null` em TypeScript, `str | None` em Python) indicando por que o modelo parou de gerar em sua volta final. Valores comuns são `end_turn` (modelo terminou normalmente), `max_tokens` (atingiu o limite de token de saída) e `refusal` (o modelo recusou a requisição). Em subtipos de resultado de erro, `stop_reason` carrega o valor da última resposta do assistente antes do loop terminar. Para detectar recusas, verifique `stop_reason === "refusal"` (TypeScript) ou `stop_reason == "refusal"` (Python). Veja [`SDKResultMessage`](/pt/agent-sdk/typescript#sdkresultmessage) (TypeScript) ou [`ResultMessage`](/pt/agent-sdk/python#resultmessage) (Python) para o tipo completo.

325 351

326<h2 id="hooks">352<h2 id="hooks">

348 374

349Este exemplo combina os conceitos-chave desta página em um único agente que corrige testes falhando. Ele configura o agente com ferramentas permitidas (pré-aprovadas para que o agente seja executado autonomamente), configurações de projeto e limites de segurança em voltas e esforço de raciocínio. Conforme o loop é executado, ele captura o ID da sessão para possível retomada, lida com o resultado final e imprime o custo total.375Este exemplo combina os conceitos-chave desta página em um único agente que corrige testes falhando. Ele configura o agente com ferramentas permitidas (pré-aprovadas para que o agente seja executado autonomamente), configurações de projeto e limites de segurança em voltas e esforço de raciocínio. Conforme o loop é executado, ele captura o ID da sessão para possível retomada, lida com o resultado final e imprime o custo total.

350 376

377Como uma única chamada `query()` levanta uma exceção após produzir um resultado de erro, o loop é envolvido em um bloco try para que o script saia de forma limpa quando um limite é atingido.

378

351<CodeGroup>379<CodeGroup>

352 ```python Python theme={null}380 ```python Python theme={null}

353 import asyncio381 import asyncio

357 async def run_agent():385 async def run_agent():

358 session_id = None386 session_id = None

359 387

388 try:

360 async for message in query(389 async for message in query(

361 prompt="Find and fix the bug causing test failures in the auth module",390 prompt="Find and fix the bug causing test failures in the auth module",

362 options=ClaudeAgentOptions(391 options=ClaudeAgentOptions(

389 print(f"Stopped: {message.subtype}")418 print(f"Stopped: {message.subtype}")

390 if message.total_cost_usd is not None:419 if message.total_cost_usd is not None:

391 print(f"Cost: ${message.total_cost_usd:.4f}")420 print(f"Cost: ${message.total_cost_usd:.4f}")

421 except Exception as error:

422 # A single-shot query() raises after yielding an error result. If the

423 # failure was an error result, the error subtype branches above have

424 # already run; connection or process failures yield no result message.

425 print(f"Session ended with an error: {error}")

392 426

393 427

394 asyncio.run(run_agent())428 asyncio.run(run_agent())

399 433

400 let sessionId: string | undefined;434 let sessionId: string | undefined;

401 435

436 try {

402 for await (const message of query({437 for await (const message of query({

403 prompt: "Find and fix the bug causing test failures in the auth module",438 prompt: "Find and fix the bug causing test failures in the auth module",

404 options: {439 options: {

428 console.log(`Cost: $${message.total_cost_usd.toFixed(4)}`);463 console.log(`Cost: $${message.total_cost_usd.toFixed(4)}`);

429 }464 }

430 }465 }

466 } catch (error) {

467 // A single-shot query() throws after yielding an error result. If the

468 // failure was an error result, the error subtype branches above have

469 // already run; connection or process failures yield no result message.

470 console.log(`Session ended with an error: ${error}`);

471 }

431 ```472 ```

432</CodeGroup>473</CodeGroup>

433 474

agent-sdk/cost-tracking.md +45 −2

Details

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

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

65 65

66 try {

66 for await (const message of query({ prompt: "Summarize this project" })) {67 for await (const message of query({ prompt: "Summarize this project" })) {

67 if (message.type === "result") {68 if (message.type === "result") {

68 console.log(`Total cost: $${message.total_cost_usd}`);69 console.log(`Total cost: $${message.total_cost_usd}`);

69 }70 }

70 }71 }

72 } catch (error) {

73 // A single-shot query() throws after yielding an error result. If the

74 // failure was an error result, it still carried total_cost_usd and the

75 // branch above has already run; connection or process failures yield

76 // no result message.

77 console.error(`Session ended with an error: ${error}`);

78 }

71 ```79 ```

72 80

73 ```python Python theme={null}81 ```python Python theme={null}

76 84

77 85

78 async def main():86 async def main():

87 try:

79 async for message in query(prompt="Summarize this project"):88 async for message in query(prompt="Summarize this project"):

80 if isinstance(message, ResultMessage):89 if isinstance(message, ResultMessage):

81 print(f"Total cost: ${message.total_cost_usd or 0}")90 print(f"Total cost: ${message.total_cost_usd or 0}")

91 except Exception as error:

92 # A single-shot query() raises after yielding an error result. If the

93 # failure was an error result, it still carried total_cost_usd and the

94 # branch above has already run; connection or process failures yield

95 # no result message.

96 print(f"Session ended with an error: {error}")

82 97

83 98

84 asyncio.run(main())99 asyncio.run(main())

110let totalInputTokens = 0;125let totalInputTokens = 0;

111let totalOutputTokens = 0;126let totalOutputTokens = 0;

112 127

113for await (const message of query({ prompt: "Summarize this project" })) {128try {

129 for await (const message of query({ prompt: "Summarize this project" })) {

114 if (message.type === "assistant") {130 if (message.type === "assistant") {

115 const msgId = message.message.id;131 const msgId = message.message.id;

116 132

121 totalOutputTokens += message.message.usage.output_tokens;137 totalOutputTokens += message.message.usage.output_tokens;

122 }138 }

123 }139 }

140 }

141} catch (error) {

142 // A single-shot query() throws after yielding an error result, so the

143 // totals below still reflect the steps that ran before the failure.

144 console.error(`Session ended with an error: ${error}`);

124}145}

125 146

126console.log(`Steps: ${seenIds.size}`);147console.log(`Steps: ${seenIds.size}`);

139```typescript theme={null}160```typescript theme={null}

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

141 162

142for await (const message of query({ prompt: "Summarize this project" })) {163try {

164 for await (const message of query({ prompt: "Summarize this project" })) {

143 if (message.type !== "result") continue;165 if (message.type !== "result") continue;

144 166

145 for (const [modelName, usage] of Object.entries(message.modelUsage)) {167 for (const [modelName, usage] of Object.entries(message.modelUsage)) {

149 console.log(` Cache read: ${usage.cacheReadInputTokens}`);171 console.log(` Cache read: ${usage.cacheReadInputTokens}`);

150 console.log(` Cache creation: ${usage.cacheCreationInputTokens}`);172 console.log(` Cache creation: ${usage.cacheCreationInputTokens}`);

151 }173 }

174 }

175} catch (error) {

176 // A single-shot query() throws after yielding an error result. If the

177 // failure was an error result, the per-model breakdown above has already

178 // printed; connection or process failures yield no result message.

179 console.error(`Session ended with an error: ${error}`);

152}180}

153```181```

154 182

173 ];201 ];

174 202

175 for (const prompt of prompts) {203 for (const prompt of prompts) {

204 try {

176 for await (const message of query({ prompt })) {205 for await (const message of query({ prompt })) {

177 if (message.type === "result") {206 if (message.type === "result") {

178 totalSpend += message.total_cost_usd;207 totalSpend += message.total_cost_usd;

179 console.log(`This call: $${message.total_cost_usd}`);208 console.log(`This call: $${message.total_cost_usd}`);

180 }209 }

181 }210 }

211 } catch (error) {

212 // A single-shot query() throws after yielding an error result. If the

213 // failure was an error result, this call's cost was already counted;

214 // connection or process failures yield no result message. Continue

215 // with the next prompt.

216 console.error(`Call failed: ${error}`);

217 }

182 }218 }

183 219

184 console.log(`Total spend: $${totalSpend.toFixed(4)}`);220 console.log(`Total spend: $${totalSpend.toFixed(4)}`);

199 ]235 ]

200 236

201 for prompt in prompts:237 for prompt in prompts:

238 try:

202 async for message in query(prompt=prompt):239 async for message in query(prompt=prompt):

203 if isinstance(message, ResultMessage):240 if isinstance(message, ResultMessage):

204 cost = message.total_cost_usd or 0241 cost = message.total_cost_usd or 0

205 total_spend += cost242 total_spend += cost

206 print(f"This call: ${cost}")243 print(f"This call: ${cost}")

244 except Exception as error:

245 # A single-shot query() raises after yielding an error result. If

246 # the failure was an error result, this call's cost was already

247 # counted; connection or process failures yield no result message.

248 # Continue with the next prompt.

249 print(f"Call failed: {error}")

207 250

208 print(f"Total spend: ${total_spend:.4f}")251 print(f"Total spend: ${total_spend:.4f}")

209 252

agent-sdk/file-checkpointing.md +25 −7

Details

50 50

51Para usar checkpointing de arquivo, ative-o em suas opções, capture UUIDs de checkpoint do fluxo de resposta e, em seguida, chame `rewindFiles()` (TypeScript) ou `rewind_files()` (Python) quando precisar restaurar.51Para usar checkpointing de arquivo, ative-o em suas opções, capture UUIDs de checkpoint do fluxo de resposta e, em seguida, chame `rewindFiles()` (TypeScript) ou `rewind_files()` (Python) quando precisar restaurar.

52 52

53O exemplo a seguir mostra o fluxo completo: ativar checkpointing, capturar o UUID de checkpoint e ID de sessão do fluxo de resposta e, em seguida, retomar a sessão mais tarde para reverter arquivos. Cada etapa é explicada em detalhes abaixo.53O exemplo a seguir mostra o fluxo completo: ativar checkpointing, capturar o UUID de checkpoint e ID de sessão do fluxo de resposta e, em seguida, retomar a sessão mais tarde para reverter arquivos. Cada etapa é explicada em detalhes abaixo. Os exemplos nesta seção usam o prompt "Refactor the authentication module". Execute-os em um projeto que contenha um módulo de autenticação, ou altere o prompt para nomear arquivos que existem em seu projeto, para que você possa observar as alterações de arquivos e ver a reversão restaurá-los.

54 54

55<CodeGroup>55<CodeGroup>

56 ```python Python theme={null}56 ```python Python theme={null}

197 session_id = None197 session_id = None

198 198

199 async for message in client.receive_response():199 async for message in client.receive_response():

200 # Update checkpoint on each user message (keeps the latest)200 # Capture the first user message UUID as the checkpoint

201 if isinstance(message, UserMessage) and message.uuid:201 if isinstance(message, UserMessage) and message.uuid and checkpoint_id is None:

202 checkpoint_id = message.uuid202 checkpoint_id = message.uuid

203 # Capture session ID from the result message203 # Capture session ID from the result message

204 if isinstance(message, ResultMessage):204 if isinstance(message, ResultMessage):

210 let sessionId: string | undefined;210 let sessionId: string | undefined;

211 211

212 for await (const message of response) {212 for await (const message of response) {

213 // Update checkpoint on each user message (keeps the latest)213 // Capture the first user message UUID as the checkpoint

214 if (message.type === "user" && message.uuid) {214 if (message.type === "user" && message.uuid && !checkpointId) {

215 checkpointId = message.uuid;215 checkpointId = message.uuid;

216 }216 }

217 // Capture session ID from any message that has it217 // Capture session ID from any message that has it

250 ```250 ```

251 </CodeGroup>251 </CodeGroup>

252 252

253 Se você capturar o ID de sessão e o ID de checkpoint, você também pode reverter a partir da CLI:253 Se você capturar o ID de sessão e o ID de checkpoint, você também pode reverter a partir da CLI. Este comando requer o executável `claude`, que vem de [instalar Claude Code](/pt/setup) e não é instalado pelo pacote SDK. O SDK ativa checkpointing para você, mas quando você executa `claude -p` diretamente, você deve definir a variável de ambiente `CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING`:

254 254

255 ```bash theme={null}255 ```bash theme={null}

256 claude -p --resume <session-id> --rewind-files <checkpoint-uuid>256 CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING=true claude -p --resume <session-id> --rewind-files <checkpoint-uuid>

257 ```257 ```

258

259 O sinalizador `--rewind-files` não aparece na saída de `claude --help`, mas a CLI o aceita conforme mostrado.

258 </Step>260 </Step>

259</Steps>261</Steps>

260 262

270 272

271Este padrão mantém apenas o UUID de checkpoint mais recente, atualizando-o antes de cada turno do agente. Se algo der errado durante o processamento, você pode reverter imediatamente para o último estado seguro e sair do loop.273Este padrão mantém apenas o UUID de checkpoint mais recente, atualizando-o antes de cada turno do agente. Se algo der errado durante o processamento, você pode reverter imediatamente para o último estado seguro e sair do loop.

272 274

275Antes de executar este exemplo, substitua `your_revert_condition` (Python) ou `yourRevertCondition` (TypeScript) pela sua própria verificação, como detecção de erro ou falha de validação; o espaço reservado não está definido no exemplo.

276

273<CodeGroup>277<CodeGroup>

274 ```python Python theme={null}278 ```python Python theme={null}

275 import asyncio279 import asyncio

752 756

753**Solução**: Certifique-se de que `enable_file_checkpointing=True` (Python) ou `enableFileCheckpointing: true` (TypeScript) foi definido na sessão original, depois use o padrão mostrado nos exemplos: capture o UUID da primeira mensagem do usuário, conclua a sessão completamente e, em seguida, retome com um prompt vazio e chame `rewindFiles()` uma vez.757**Solução**: Certifique-se de que `enable_file_checkpointing=True` (Python) ou `enableFileCheckpointing: true` (TypeScript) foi definido na sessão original, depois use o padrão mostrado nos exemplos: capture o UUID da primeira mensagem do usuário, conclua a sessão completamente e, em seguida, retome com um prompt vazio e chame `rewindFiles()` uma vez.

754 758

759<h3 id="file-rewinding-is-not-enabled-error">

760 Erro "File rewinding is not enabled"

761</h3>

762

763Este erro ocorre quando você tenta um rewind não interativo sem checkpointing ativado: executar `claude -p` simples com `--rewind-files`, ou executar uma sessão SDK, incluindo uma retomada, cujas opções não ativam checkpointing. O SDK define a variável de ambiente `CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING` internamente apenas quando `enable_file_checkpointing` (Python) ou `enableFileCheckpointing` (TypeScript) está ativado na sessão que executa o rewind; a CLI simples nunca a define.

764

765**Solução**: Para a CLI simples, defina a variável de ambiente ao executar o comando:

766

767```bash theme={null}

768CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING=true claude -p --resume <session-id> --rewind-files <checkpoint-uuid>

769```

770

771Para o SDK, defina `enable_file_checkpointing=True` (Python) ou `enableFileCheckpointing: true` (TypeScript) na sessão retomada, como os exemplos nesta página fazem.

772

755<h3 id="processtransport-is-not-ready-for-writing-error">773<h3 id="processtransport-is-not-ready-for-writing-error">

756 Erro "ProcessTransport is not ready for writing"774 Erro "ProcessTransport is not ready for writing"

757</h3>775</h3>

agent-sdk/permissions.md +15 −4

Details

24 </Step>24 </Step>

25 25

26 <Step title="Regras de negação">26 <Step title="Regras de negação">

27 Verifique as regras `deny` (de `disallowed_tools` e [settings.json](/pt/settings#permission-settings)). Se uma regra de negação corresponder, a ferramenta é bloqueada, mesmo no modo `bypassPermissions`. Entradas com nome simples como `Bash` removem a ferramenta do contexto do Claude antes desta avaliação começar, portanto apenas regras com escopo como `Bash(rm *)` são verificadas neste passo.27 Verifique as regras `deny` (de `disallowed_tools` e [settings.json](/pt/settings#permission-settings)). Se uma regra de negação corresponder, a ferramenta é bloqueada, mesmo no modo `bypassPermissions`. Regras com nome simples como `Bash` removem a ferramenta do contexto do Claude antes desta avaliação começar, portanto apenas regras com escopo como `Bash(rm *)` são verificadas neste passo.

28 </Step>28 </Step>

29 29

30 <Step title="Regras de pergunta">30 <Step title="Regras de pergunta">

31 Verifique as regras `ask` de [settings.json](/pt/settings#permission-settings). Se uma regra de pergunta corresponder, a chamada passa para seu callback [`canUseTool`](/pt/agent-sdk/user-input) para confirmação, mesmo no modo `bypassPermissions`. No modo `dontAsk`, uma regra de pergunta correspondente é negada, porque esse modo nunca solicita.31 Verifique as regras `ask` de [settings.json](/pt/settings#permission-settings). Se uma regra de pergunta corresponder, a chamada passa para seu callback [`canUseTool`](/pt/agent-sdk/user-input) para confirmação, mesmo no modo `bypassPermissions`.

33 Ferramentas que requerem interação do usuário se comportam da mesma forma: `AskUserQuestion` e ferramentas MCP cujo servidor define [`_meta["anthropic/requiresUserInteraction"]`](/pt/mcp#require-approval-for-a-specific-tool) sempre passam para o callback, mesmo quando uma regra de permitir corresponde. No modo `dontAsk` ambos os casos são negados, porque esse modo nunca solicita. {/* min-version: 2.1.199 */}A anotação MCP requer Claude Code v2.1.199 ou posterior.

32 </Step>34 </Step>

33 35

34 <Step title="Modo de permissão">36 <Step title="Modo de permissão">

35 Aplique o [modo de permissão](#permission-modes) ativo. `bypassPermissions` aprova tudo que chega a este passo. `acceptEdits` aprova operações de arquivo. `plan` roteia ferramentas de edição de arquivo e escrita de shell para seu callback `canUseTool` independentemente das regras de permitir, portanto operações de escrita não podem ser aprovadas automaticamente durante o planejamento. Outros modos passam adiante.37 Aplique o [modo de permissão](#permission-modes) ativo. `bypassPermissions` aprova tudo que chega a este passo. `acceptEdits` aprova operações de arquivo. `plan` roteia ferramentas de edição de arquivo e escrita de shell para seu callback `canUseTool` independentemente das regras de permitir, portanto operações de escrita não podem ser aprovadas automaticamente durante o planejamento. Outros modos passam adiante.

36 </Step>38 </Step>

37 39

~~38 <Step title="Regras de permissão">~~40 <Step title="Regras de permitir">

39 Verifique as regras `allow` (de `allowed_tools` e settings.json). Se uma regra corresponder, a ferramenta é aprovada.41 Verifique as regras `allow` (de `allowed_tools` e settings.json). Se uma regra corresponder, a ferramenta é aprovada.

40 </Step>42 </Step>

41 43

46 48

47<img src="https://mintcdn.com/claude-code/jYgs7qigNjO1Badj/images/agent-sdk/permissions-flow.svg?fit=max&auto=format&n=jYgs7qigNjO1Badj&q=85&s=c771ad9085b1277d3708027a49c744bc" alt="Diagrama do fluxo de avaliação de permissões em seis etapas correspondendo aos passos acima: uma solicitação de ferramenta passa por hooks, regras de negação, regras de pergunta, modo de permissão, regras de permissão e canUseTool. Hooks, regras de negação e canUseTool podem rotear para Bloqueado; bypass de modo de permissão, regras de permissão e canUseTool podem rotear para Executar; regras de pergunta rotear para canUseTool." width="1180" height="260" data-path="images/agent-sdk/permissions-flow.svg" />49<img src="https://mintcdn.com/claude-code/jYgs7qigNjO1Badj/images/agent-sdk/permissions-flow.svg?fit=max&auto=format&n=jYgs7qigNjO1Badj&q=85&s=c771ad9085b1277d3708027a49c744bc" alt="Diagrama do fluxo de avaliação de permissões em seis etapas correspondendo aos passos acima: uma solicitação de ferramenta passa por hooks, regras de negação, regras de pergunta, modo de permissão, regras de permissão e canUseTool. Hooks, regras de negação e canUseTool podem rotear para Bloqueado; bypass de modo de permissão, regras de permissão e canUseTool podem rotear para Executar; regras de pergunta rotear para canUseTool." width="1180" height="260" data-path="images/agent-sdk/permissions-flow.svg" />

48 50

51A partir da v2.1.198, se você passar um callback `canUseTool` que esta ordem de avaliação nunca pode alcançar, o SDK TypeScript emite um aviso de processo Node.js uma vez quando a consulta é construída. O código do aviso é `CLAUDE_SDK_CAN_USE_TOOL_SHADOWED`. Duas configurações o acionam:

53* `permissionMode: 'bypassPermissions'`, que aprova automaticamente cada chamada que chega ao passo do modo de permissão

54* Cada entrada `allowedTools` simples como `"Read"`, que aprova automaticamente essa ferramenta inteira antes do callback ser consultado

56Entradas com um especificador como `Bash(ls *)` e o modo `acceptEdits` não o acionam, e regras de permitir provenientes de arquivos de configuração não são visíveis para a verificação.

58Ouça com `process.on('warning', ...)` e corresponda o código para registrá-lo ou suprimi-lo. Para controlar cada chamada de ferramenta independentemente do modo e das regras, use um [hook `PreToolUse`](/pt/agent-sdk/hooks) em vez disso.

49Esta página se concentra em **regras de permitir e negar** e **modos de permissão**. Para os outros passos:60Esta página se concentra em **regras de permitir e negar** e **modos de permissão**. Para os outros passos:

50 61

51* **Hooks:** execute código personalizado para permitir, negar ou modificar solicitações de ferramentas. Consulte [Controlar execução com hooks](/pt/agent-sdk/hooks).62* **Hooks:** execute código personalizado para permitir, negar ou modificar solicitações de ferramentas. Consulte [Controlar execução com hooks](/pt/agent-sdk/hooks).

67Regras de permitir aceitam globs de nome de ferramenta apenas após um prefixo literal `mcp__<server>__`. O segmento do servidor deve estar livre de glob para que a regra nomeie um servidor específico que você configurou: `mcp__puppeteer__*` corresponde a todas as ferramentas do servidor `puppeteer`, e `mcp__github__get_*` corresponde às suas ferramentas `get_`. Uma entrada não ancorada como `allowed_tools=["*"]` ou `allowed_tools=["mcp__*"]` é ignorada com um aviso de inicialização e não auto-aprova nada.78Regras de permitir aceitam globs de nome de ferramenta apenas após um prefixo literal `mcp__<server>__`. O segmento do servidor deve estar livre de glob para que a regra nomeie um servidor específico que você configurou: `mcp__puppeteer__*` corresponde a todas as ferramentas do servidor `puppeteer`, e `mcp__github__get_*` corresponde às suas ferramentas `get_`. Uma entrada não ancorada como `allowed_tools=["*"]` ou `allowed_tools=["mcp__*"]` é ignorada com um aviso de inicialização e não auto-aprova nada.

68 79

69<Warning>80<Warning>

70 **Ferramentas auto-aprovadas nunca chegam a `canUseTool`.** Uma chamada de ferramenta aprovada em qualquer etapa anterior, por `acceptEdits` ou `bypassPermissions`, ou por uma regra de permitir, ignora seu callback `canUseTool`, portanto verificações de permissão que você coloca lá são silenciosamente contornadas para essa ferramenta. A cobertura depende da forma da entrada: um nome simples como `Read` ou `mcp__github__get_issue` auto-aprova todas as chamadas para essa ferramenta, enquanto uma regra com escopo como `Bash(ls *)` auto-aprova apenas chamadas correspondentes e outras chamadas de `Bash` ainda passam para o callback. Para verificações que devem ser executadas em todas as chamadas de ferramenta, use um hook [`PreToolUse`](/pt/agent-sdk/hooks): hooks são executados antes de qualquer outra etapa, e uma negação de hook se aplica mesmo no modo `bypassPermissions`.81 **Ferramentas auto-aprovadas nunca chegam a `canUseTool`.** Uma chamada de ferramenta aprovada em qualquer etapa anterior, por `acceptEdits` ou `bypassPermissions`, ou por uma regra de permitir, ignora seu callback `canUseTool`, portanto verificações de permissão que você coloca lá são silenciosamente contornadas para essa ferramenta. A exceção são ferramentas que requerem interação do usuário, `AskUserQuestion` e ferramentas MCP marcadas com [`_meta["anthropic/requiresUserInteraction"]`](/pt/mcp#require-approval-for-a-specific-tool), que chegam ao callback mesmo quando uma regra de permitir corresponde. A cobertura depende da forma da entrada: um nome simples como `Read` ou `mcp__github__get_issue` auto-aprova todas as chamadas para essa ferramenta, enquanto uma regra com escopo como `Bash(ls *)` auto-aprova apenas chamadas correspondentes e outras chamadas de `Bash` ainda passam para o callback. Para verificações que devem ser executadas em todas as chamadas de ferramenta, use um hook [`PreToolUse`](/pt/agent-sdk/hooks): hooks são executados antes de qualquer outra etapa, e uma negação de hook se aplica mesmo no modo `bypassPermissions`.

71</Warning>82</Warning>

72 83

73Para um agente bloqueado, combine `allowedTools` com `permissionMode: "dontAsk"`. Ferramentas listadas são aprovadas; qualquer outra coisa é negada completamente em vez de solicitar:84Para um agente bloqueado, combine `allowedTools` com `permissionMode: "dontAsk"`. Ferramentas listadas são aprovadas; qualquer outra coisa é negada completamente em vez de solicitar:

agent-sdk/python.md +1 −1

Details

958```958```

959 959

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

961* `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 autônomas que precisam aguardar interrupções mais longas, defina `CLAUDE_CODE_RETRY_WATCHDOG=1` para tentar capacidade de erros indefinidamente.961* `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 autônomas que precisam aguardar interrupções mais longas, defina `CLAUDE_CODE_RETRY_WATCHDOG=1`: ele tenta erros de capacidade indefinidamente, e {/* min-version: 2.1.199 */}a partir do Claude Code v2.1.199 aumenta o padrão para outros erros transitórios para `300` e remove o limite nesta variável.

962* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`: watchdog de travamento para subagentes lançados com `run_in_background`. Padrão `600000`. Redefine em cada evento de stream; em caso de travamento, aborta o subagente, marca a tarefa como falha e expõe o erro ao pai com qualquer resultado parcial. Não se aplica a subagentes síncronos.962* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`: watchdog de travamento para subagentes lançados com `run_in_background`. Padrão `600000`. Redefine em cada evento de stream; em caso de travamento, aborta o subagente, marca a tarefa como falha e expõe o erro ao pai com qualquer resultado parcial. Não se aplica a subagentes síncronos.

963* `CLAUDE_ENABLE_STREAM_WATCHDOG` com `CLAUDE_STREAM_IDLE_TIMEOUT_MS`: aborta a solicitação quando os cabeçalhos chegaram mas o corpo da resposta para de fazer stream. O watchdog está ativado por padrão para todos os provedores; defina `CLAUDE_ENABLE_STREAM_WATCHDOG=0` para desabilitá-lo. `CLAUDE_STREAM_IDLE_TIMEOUT_MS` padrão é `300000` e é fixado nesse mínimo. A solicitação abortada passa pelo caminho de tentativa normal.963* `CLAUDE_ENABLE_STREAM_WATCHDOG` com `CLAUDE_STREAM_IDLE_TIMEOUT_MS`: aborta a solicitação quando os cabeçalhos chegaram mas o corpo da resposta para de fazer stream. O watchdog está ativado por padrão para todos os provedores; defina `CLAUDE_ENABLE_STREAM_WATCHDOG=0` para desabilitá-lo. `CLAUDE_STREAM_IDLE_TIMEOUT_MS` padrão é `300000` e é fixado nesse mínimo. A solicitação abortada passa pelo caminho de tentativa normal.

964 964

agent-sdk/subagents.md +45 −29

Details

7> Defina e invoque subagentes para isolar contexto, executar tarefas em paralelo e aplicar instruções especializadas em suas aplicações Claude Agent SDK.7> Defina e invoque subagentes para isolar contexto, executar tarefas em paralelo e aplicar instruções especializadas em suas aplicações Claude Agent SDK.

8 8

9Subagentes são instâncias de agente separadas que seu agente principal pode gerar para lidar com subtarefas focadas.9Subagentes são instâncias de agente separadas que seu agente principal pode gerar para lidar com subtarefas focadas.

~~10Use subagentes para isolar contexto para subtarefas focadas, executar múltiplas análises em paralelo e aplicar instruções especializadas sem sobrecarregar o prompt do agente principal.~~10Use subagentes para isolar contexto, executar múltiplas análises em paralelo e aplicar instruções especializadas sem adicionar ao prompt do agente principal.

11 11

12Este guia explica como definir e usar subagentes no SDK usando o parâmetro `agents`.12Este guia explica como definir e usar subagentes no SDK usando o parâmetro `agents`.

13 13

17 17

18Você pode criar subagentes de três maneiras:18Você pode criar subagentes de três maneiras:

19 19

~~20* **Programaticamente**: use o parâmetro `agents` em suas opções `query()` ([TypeScript](/pt/agent-sdk/typescript#agentdefinition), [Python](/pt/agent-sdk/python#agentdefinition))~~20* **Programaticamente**: use o parâmetro `agents` em suas opções `query()`. Veja as referências [TypeScript](/pt/agent-sdk/typescript#agentdefinition) e [Python](/pt/agent-sdk/python#agentdefinition)

~~21* **Baseado em sistema de arquivos**: defina agentes como arquivos markdown em diretórios `.claude/agents/` (veja [definindo subagentes como arquivos](/pt/sub-agents))~~21* **Baseado em sistema de arquivos**: defina agentes como arquivos markdown em diretórios `.claude/agents/`. Veja [definindo subagentes como arquivos](/pt/sub-agents)

22* **Propósito geral integrado**: Claude pode invocar o subagente integrado `general-purpose` a qualquer momento via a ferramenta Agent sem você definir nada22* **Propósito geral integrado**: Claude pode invocar o subagente integrado `general-purpose` a qualquer momento via a ferramenta Agent sem você definir nada

23 23

24Este guia se concentra na abordagem programática, que é recomendada para aplicações SDK.24Este guia se concentra na abordagem programática, que é recomendada para aplicações SDK.

25 25

26Quando você define subagentes, Claude determina se deve invocá-los com base no campo `description` de cada subagente. Escreva descrições claras que expliquem quando o subagente deve ser usado, e Claude delegará automaticamente tarefas apropriadas. Você também pode solicitar explicitamente um subagente pelo nome em seu prompt (por exemplo, "Use o agente code-reviewer para...").26Quando você define subagentes, Claude determina se deve invocá-los com base no campo `description` de cada subagente. Escreva descrições claras que expliquem quando usar o subagente, e Claude delegará automaticamente tarefas apropriadas. Você também pode solicitar explicitamente um subagente pelo nome em seu prompt, por exemplo "Use o agente code-reviewer para...".

27 27

28<h2 id="benefits-of-using-subagents">28<h2 id="benefits-of-using-subagents">

29 Benefícios de usar subagentes29 Benefícios de usar subagentes

61 61

62**Exemplo:** um subagente `doc-reviewer` pode ter acesso apenas às ferramentas Read e Grep, garantindo que possa analisar mas nunca modifique acidentalmente seus arquivos de documentação.62**Exemplo:** um subagente `doc-reviewer` pode ter acesso apenas às ferramentas Read e Grep, garantindo que possa analisar mas nunca modifique acidentalmente seus arquivos de documentação.

63 63

~~64<h2 id="creating-subagents">~~64<h2 id="create-subagents">

~~65 Criando subagentes~~65 Criar subagentes

66</h2>66</h2>

67 67

68<h3 id="programmatic-definition-recommended">68<h3 id="programmatic-definition-recommended">

69 Definição programática (recomendada)69 Definição programática (recomendada)

70</h3>70</h3>

71 71

72Defina subagentes diretamente em seu código usando o parâmetro `agents`. Este exemplo cria dois subagentes: um revisor de código com acesso somente leitura e um executor de testes que pode executar comandos. Claude invoca subagentes através da ferramenta `Agent`, portanto inclua `Agent` em `allowedTools` para aprovar automaticamente invocações de subagentes sem um prompt de permissão.72Defina subagentes diretamente em seu código usando o parâmetro `agents`. Claude invoca subagentes através da ferramenta `Agent`, portanto inclua `Agent` em `allowedTools` para aprovar automaticamente invocações de subagentes sem um prompt de permissão.

73 73

74A maioria dos exemplos nesta página imprime apenas o resultado final. Para confirmar que Claude delegou a um subagente em vez de responder diretamente, veja [Detectando invocação de subagente](#detecting-subagent-invocation).74A maioria dos exemplos nesta página imprime apenas o resultado final. Para confirmar que Claude delegou a um subagente em vez de responder diretamente, veja [Detectar invocação de subagente](#detect-subagent-invocation).

76Este exemplo cria dois subagentes: um revisor de código com acesso somente leitura e um executor de testes que pode executar comandos.

75 77

76<CodeGroup>78<CodeGroup>

77 ```python Python theme={null}79 ```python Python theme={null}

197 199

198No SDK Python, nomes de campo com múltiplas palavras como `disallowedTools` e `mcpServers` mantêm sua ortografia camelCase para corresponder ao formato de transmissão em vez de seguir a convenção snake\_case do Python. Veja a referência [`AgentDefinition`](/pt/agent-sdk/python#agentdefinition) para detalhes.200No SDK Python, nomes de campo com múltiplas palavras como `disallowedTools` e `mcpServers` mantêm sua ortografia camelCase para corresponder ao formato de transmissão em vez de seguir a convenção snake\_case do Python. Veja a referência [`AgentDefinition`](/pt/agent-sdk/python#agentdefinition) para detalhes.

199 201

202Dois comportamentos de subagente mudaram no Claude Code v2.1.198:

203

204* Subagentes são executados em fundo por padrão. Uma chamada de ferramenta Agent que omite a entrada [`run_in_background`](/pt/agent-sdk/typescript) inicia um subagente em fundo, e Claude define `run_in_background: false` quando precisa do resultado antes de continuar. Antes da v2.1.198, omitir `run_in_background` executava o subagente sincronamente. Defina o campo `background` como `true` para forçar execução em fundo para um agente específico independentemente do que Claude solicita.

205* Um subagente herda a configuração de pensamento estendido da sessão principal. Em versões anteriores, o pensamento estendido é desabilitado dentro de subagentes independentemente da configuração da sessão principal.

206

200<Note>207<Note>

201 {/* min-version: 2.1.172 */}A partir do Claude Code v2.1.172, subagentes podem gerar seus próprios subagentes. Um subagente cinco níveis abaixo do agente principal não pode gerar mais subagentes, independentemente de ser executado em primeiro plano ou em fundo. Para evitar que um subagente gere outros, omita `Agent` de seu array `tools` ou adicione-o a `disallowedTools`. Veja [subagentes aninhados](/pt/sub-agents#spawn-nested-subagents) para as regras de profundidade completas.208 {/* min-version: 2.1.172 */}A partir do Claude Code v2.1.172, subagentes podem gerar seus próprios subagentes. Um subagente cinco níveis abaixo do agente principal não pode gerar mais subagentes, independentemente de ser executado em primeiro plano ou em fundo. Para evitar que um subagente gere outros, omita `Agent` de seu array `tools` ou adicione-o a `disallowedTools`. Veja [subagentes aninhados](/pt/sub-agents#spawn-nested-subagents) para as regras de profundidade completas.

202</Note>209</Note>

215 O que subagentes herdam222 O que subagentes herdam

216</h2>223</h2>

217 224

218A janela de contexto de um subagente começa nova (sem conversa pai) mas não está vazia. O único canal do pai para o subagente é a string de prompt da ferramenta Agent, então inclua quaisquer caminhos de arquivo, mensagens de erro ou decisões que o subagente precise diretamente nesse prompt.225A janela de contexto de um subagente começa nova, sem conversa pai, mas não está vazia. O único canal do pai para o subagente é a string de prompt da ferramenta Agent, então inclua quaisquer caminhos de arquivo, mensagens de erro ou decisões que o subagente precise diretamente nesse prompt.

219 226

220| O subagente recebe | O subagente não recebe |227| O subagente recebe | O subagente não recebe |

221| :------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------- |228| :------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------- |

225 232

226<Note>233<Note>

227 O pai recebe a mensagem final do subagente verbatim como o resultado da ferramenta Agent, mas pode resumi-la em sua própria resposta. Para preservar a saída do subagente verbatim na resposta voltada para o usuário, inclua uma instrução para fazer isso no prompt ou opção `systemPrompt` que você passa para a chamada **principal** `query()`.234 O pai recebe a mensagem final do subagente verbatim como o resultado da ferramenta Agent, mas pode resumi-la em sua própria resposta. Para preservar a saída do subagente verbatim na resposta voltada para o usuário, inclua uma instrução para fazer isso no prompt ou opção `systemPrompt` que você passa para a chamada principal `query()`.

228</Note>235</Note>

229 236

230<h2 id="invoking-subagents">237{/* min-version: 2.1.199 */}A partir do Claude Code v2.1.199, um erro de API que encerra o subagente antecipadamente, como um limite de taxa, nunca é entregue como seu resultado. Se o subagente já produziu saída, a ferramenta Agent retorna essa saída parcial com uma nota de que o subagente não terminou; caso contrário, o resultado da ferramenta é uma mensagem de erro, `Agent terminated early due to an API error`, seguida pelo detalhe do erro. Veja [API errors in subagents](/pt/sub-agents#api-errors-in-subagents) para o comportamento em primeiro plano e em segundo plano.

238

239<h2 id="invoke-subagents">

231 Invocando subagentes240 Invocando subagentes

232</h2>241</h2>

233 242

329 ```338 ```

330</CodeGroup>339</CodeGroup>

331 340

332<h2 id="detecting-subagent-invocation">341<h2 id="detect-subagent-invocation">

333 Detectando invocação de subagente342 Detectar invocação de subagente

334</h2>343</h2>

335 344

336Subagentes são invocados via a ferramenta Agent. Para detectar quando um subagente é invocado, verifique blocos `tool_use` onde `name` é `"Agent"`. Mensagens de dentro do contexto de um subagente incluem um campo `parent_tool_use_id`.345Claude invoca subagentes através da ferramenta Agent. Para detectar quando um subagente é invocado, verifique blocos `tool_use` onde `name` é `"Agent"`. Mensagens de dentro do contexto de um subagente incluem um campo `parent_tool_use_id`.

337 346

338<Note>347<Note>

339 O nome da ferramenta foi renomeado de `"Task"` para `"Agent"` no Claude Code v2.1.63. Lançamentos atuais do SDK emitem `"Agent"` em blocos `tool_use` mas ainda usam `"Task"` na lista de ferramentas `system:init` e em `result.permission_denials[].tool_name`. Verificar ambos os valores em `block.name` garante compatibilidade entre versões do SDK.348 O nome da ferramenta foi renomeado de `"Task"` para `"Agent"` no Claude Code v2.1.63. Lançamentos atuais do SDK emitem `"Agent"` em blocos `tool_use` mas ainda usam `"Task"` na lista de ferramentas `system:init` e em `result.permission_denials[].tool_name`. Verificar ambos os valores em `block.name` garante compatibilidade entre versões do SDK.

422 ```431 ```

423</CodeGroup>432</CodeGroup>

424 433

425<h2 id="resuming-subagents">434<h2 id="resume-subagents">

426 Retomando subagentes435 Retomando subagentes

427</h2>436</h2>

428 437

429Subagentes podem ser retomados para continuar de onde pararam. Subagentes retomados retêm seu histórico de conversa completo, incluindo todas as chamadas de ferramentas anteriores, resultados e raciocínio. O subagente continua exatamente de onde parou em vez de começar do zero.438Você pode retomar um subagente para continuar de onde parou em vez de começar do zero. Um subagente retomado retém seu histórico de conversa completo, incluindo todas as chamadas de ferramentas anteriores, resultados e raciocínio.

430 439

431Quando um subagente é concluído, o resultado da ferramenta Agent inclui um bloco de texto contendo `agentId: <id>`. Os agentes integrados [`Explore` e `Plan`](/pt/sub-agents#built-in-subagents) são de uma única execução e não retornam um `agentId`, então use um agente personalizado ou `general-purpose` quando você precisar retomar. Para retomar um subagente programaticamente:440Quando um subagente é concluído, o resultado da ferramenta Agent inclui um bloco de texto contendo `agentId: <id>`. Os agentes integrados [`Explore` e `Plan`](/pt/sub-agents#built-in-subagents) são de uma única execução e não retornam um `agentId`, então use um agente personalizado ou `general-purpose` quando você precisar retomar. Para retomar um subagente programaticamente:

432 441

4331. **Capture o ID da sessão**: Extraia `session_id` de mensagens durante a primeira query4421. **Capture o ID da sessão**: extraia `session_id` de mensagens durante a primeira query

4342. **Extraia o ID do agente**: Analise `agentId` do texto do resultado da ferramenta Agent4432. **Extraia o ID do agente**: analise `agentId` do texto do resultado da ferramenta Agent

4353. **Retome a sessão**: Passe `resume: sessionId` nas opções da segunda query e inclua o ID do agente em seu prompt4443. **Retome a sessão**: passe `resume: sessionId` nas opções da segunda query e inclua o ID do agente em seu prompt

436 445

437<Note>446<Note>

438 Você deve retomar a mesma sessão para acessar a transcrição do subagente. Cada chamada `query()` inicia uma nova sessão por padrão, então passe `resume: sessionId` para continuar na mesma sessão.447 Você deve retomar a mesma sessão para acessar a transcrição do subagente. Cada chamada `query()` inicia uma nova sessão por padrão, então passe `resume: sessionId` para continuar na mesma sessão.

566 575

567Transcrições de subagentes persistem independentemente da conversa principal:576Transcrições de subagentes persistem independentemente da conversa principal:

568 577

569* **Compactação de conversa principal**: Quando a conversa principal se compacta, transcrições de subagentes não são afetadas. Elas são armazenadas em arquivos separados.578* **Compactação de conversa principal**: quando a conversa principal se compacta, transcrições de subagentes não são afetadas. Elas são armazenadas em arquivos separados.

570* **Persistência de sessão**: Transcrições de subagentes persistem dentro de sua sessão. Você pode retomar um subagente após reiniciar Claude Code retomando a mesma sessão.579* **Persistência de sessão**: transcrições de subagentes persistem dentro de sua sessão. Você pode retomar um subagente após reiniciar Claude Code retomando a mesma sessão.

571* **Limpeza automática**: Transcrições são limpas com base na configuração `cleanupPeriodDays` (padrão: 30 dias).580* **Limpeza automática**: transcrições são limpas com base na configuração `cleanupPeriodDays`, que tem como padrão 30 dias.

572 581

573<h2 id="tool-restrictions-1">582<h2 id="tool-restrictions-1">

574 Restrições de ferramentas583 Restrições de ferramentas

662 671

663Se Claude completa tarefas diretamente em vez de delegar para seu subagente:672Se Claude completa tarefas diretamente em vez de delegar para seu subagente:

664 673

6651. **Verifique se as invocações de Agent são aprovadas**: inclua `Agent` em `allowedTools` para aprovar automaticamente chamadas de subagentes. Sem isso, as invocações de Agent caem no seu callback `canUseTool` ou, no modo `dontAsk`, são negadas674* **Verifique se as invocações de Agent são aprovadas**: inclua `Agent` em `allowedTools` para aprovar automaticamente chamadas de subagentes. Sem isso, as invocações de Agent caem no seu callback `canUseTool` ou, no modo `dontAsk`, são negadas

6662. **Use prompting explícito**: mencione o subagente pelo nome em seu prompt (por exemplo, "Use o agente code-reviewer para...")675* **Use prompting explícito**: mencione o subagente pelo nome em seu prompt, por exemplo "Use o agente code-reviewer para..."

6673. **Escreva uma descrição clara**: explique exatamente quando o subagente deve ser usado para que Claude possa corresponder tarefas apropriadamente676* **Escreva uma descrição clara**: explique exatamente quando usar o subagente para que Claude possa corresponder tarefas apropriadamente

668 677

669<h3 id="filesystem-based-agents-not-loading">678<h3 id="filesystem-based-agents-not-loading">

670 Agentes baseados em sistema de arquivos não carregando679 Agentes baseados em sistema de arquivos não carregando

671</h3>680</h3>

672 681

673Agentes definidos em `.claude/agents/` são carregados apenas na inicialização. Se você criar um novo arquivo de agente enquanto Claude Code está em execução, reinicie a sessão para carregá-lo.682Claude Code monitora `~/.claude/agents/` e `.claude/agents/` e detecta um arquivo de agente novo ou editado em alguns segundos, sem necessidade de reinicialização. Se uma definição nunca aparecer, trabalhe através dessas causas:

683

684* **Novo diretório `agents`**: o monitor cobre apenas diretórios que existiam quando a sessão começou, então o primeiro arquivo em um novo diretório precisa de uma reinicialização de sessão. Esta é a causa mais comum.

685* **Frontmatter inválido ou um `name` duplicado**: verifique o YAML do arquivo e se um agente existente já usa o `name`.

686* **`--disable-slash-commands`**: sessões iniciadas com essa flag não monitoram esses diretórios e sempre precisam de uma reinicialização para carregar novos arquivos.

687* **Um agente programático com o mesmo nome**: `agents` passados para `query()` substituem um agente do sistema de arquivos com o mesmo nome.

688

689Para o formato do arquivo, veja [como escrever arquivos de subagente](/pt/sub-agents#write-subagent-files).

674 690

675<h3 id="windows-long-prompt-failures">691<h3 id="long-prompt-failures-on-windows">

676 Windows: falhas de prompt longo692 Falhas de prompt longo no Windows

677</h3>693</h3>

678 694

679No Windows, subagentes com prompts muito longos podem falhar devido a limites de comprimento de linha de comando (8191 caracteres). Mantenha prompts concisos ou use agentes baseados em sistema de arquivos para instruções complexas.695No Windows, subagentes com prompts muito longos podem falhar devido ao limite de comprimento de linha de comando de 8191 caracteres. Mantenha prompts concisos ou use agentes baseados em sistema de arquivos para instruções complexas.

680 696

681<h2 id="related-documentation">697<h2 id="related-documentation">

682 Documentação relacionada698 Documentação relacionada

agent-sdk/todo-tracking.md +68 −6

Details

9O rastreamento de tarefas fornece uma forma estruturada de gerenciar tarefas e exibir o progresso aos usuários. O Claude Agent SDK inclui funcionalidade integrada de tarefas que ajuda a organizar fluxos de trabalho complexos e manter os usuários informados sobre a progressão das tarefas.9O rastreamento de tarefas fornece uma forma estruturada de gerenciar tarefas e exibir o progresso aos usuários. O Claude Agent SDK inclui funcionalidade integrada de tarefas que ajuda a organizar fluxos de trabalho complexos e manter os usuários informados sobre a progressão das tarefas.

10 10

11<Note>11<Note>

12 A partir do TypeScript Agent SDK 0.3.142 e Claude Code v2.1.142, as sessões usam as ferramentas Task estruturadas `TaskCreate`, `TaskUpdate`, `TaskGet` e `TaskList` em vez de `TodoWrite`. Consulte [Migrar para ferramentas Task](#migrate-to-task-tools) para saber como o código de monitoramento muda. Os exemplos nesta página definem `CLAUDE_CODE_ENABLE_TASKS=0` para continuar mostrando `TodoWrite` para sessões que ainda não foram migradas.12 A partir do TypeScript Agent SDK 0.3.142 e Claude Code v2.1.142, as sessões usam as ferramentas Task estruturadas `TaskCreate`, `TaskUpdate`, `TaskGet` e `TaskList` em vez de `TodoWrite`. O SDK Python obtém essa mudança da CLI Claude Code que ele inicia, não da versão do pacote Python: a mudança se aplica uma vez que essa CLI — a cópia incluída dentro do pacote pip, ou uma que você aponta com `cli_path` — é v2.1.142 ou posterior. Consulte [Migrar para ferramentas Task](#migrate-to-task-tools) para saber como o código de monitoramento muda. Os exemplos nesta página definem `CLAUDE_CODE_ENABLE_TASKS=0` para continuar mostrando `TodoWrite` para sessões que ainda não foram migradas.

13</Note>13</Note>

14 14

15<h3 id="todo-lifecycle">15<h3 id="todo-lifecycle">

27 Quando as Tarefas São Usadas27 Quando as Tarefas São Usadas

28</h3>28</h3>

29 29

~~30O SDK cria automaticamente tarefas para:~~30O SDK cria tarefas para a maioria dos trabalhos com múltiplas etapas, como:

31 31

32* **Tarefas complexas com múltiplas etapas** que exigem 3 ou mais ações distintas32* **Tarefas complexas com múltiplas etapas** que exigem 3 ou mais ações distintas

33* **Listas de tarefas fornecidas pelo usuário** quando vários itens são mencionados33* **Listas de tarefas fornecidas pelo usuário** quando vários itens são mencionados

34* **Operações não triviais** que se beneficiam do rastreamento de progresso34* **Operações não triviais** que se beneficiam do rastreamento de progresso

35* **Solicitações explícitas** quando os usuários pedem organização de tarefas35* **Solicitações explícitas** quando os usuários pedem organização de tarefas

36 36

37Pode pular tarefas para solicitações muito curtas ou de uma única etapa.

37<h2 id="examples">39<h2 id="examples">

38 Exemplos40 Exemplos

39</h2>41</h2>

40 42

43Antes de executar estes exemplos, instale o Claude Agent SDK seguindo o [guia de início rápido](/pt/agent-sdk/quickstart).

45Cada exemplo é executado até que o agente termine e produza sua mensagem de resultado final. Se uma sessão atingir seu limite de turnos primeiro, essa mensagem de resultado terá o subtipo `error_max_turns`. Verifique `subtype` para detectar esse encerramento.

47Estes exemplos usam chamadas `query()` de um único disparo. Após produzir um resultado `error_max_turns`, `query()` lança um erro que inclui `Reached maximum number of turns`. Cada exemplo envolve seu loop em um bloco try para sair corretamente quando isso acontece.

49Consulte [Lidar com o resultado](/pt/agent-sdk/agent-loop#handle-the-result) para os subtipos de resultado.

41<h3 id="monitoring-todo-changes">51<h3 id="monitoring-todo-changes">

42 Monitorando Mudanças de Tarefas52 Monitorando Mudanças de Tarefas

43</h3>53</h3>

46 ```typescript TypeScript theme={null}56 ```typescript TypeScript theme={null}

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

48 58

59 try {

49 for await (const message of query({60 for await (const message of query({

50 prompt: "Optimize my React app performance and track progress with todos",61 prompt: "Optimize my React app performance and track progress with todos",

51 // Re-enable TodoWrite, which this example monitors. Without it, the SDK uses62 // Re-enable TodoWrite, which this example monitors. Without it, the SDK uses

68 }79 }

69 }80 }

70 }81 }

82 } catch (error) {

83 // A single-shot query() throws after yielding an error result,

84 // such as when the maxTurns limit is hit.

85 console.log(`Session ended with an error: ${error}`);

86 }

71 ```87 ```

72 88

73 ```python Python theme={null}89 ```python Python theme={null}

90 import asyncio

74 from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ToolUseBlock92 from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ToolUseBlock

75 93

95 async def main():

96 try:

76 async for message in query(97 async for message in query(

77 prompt="Optimize my React app performance and track progress with todos",98 prompt="Optimize my React app performance and track progress with todos",

78 # Re-enable TodoWrite, which this example monitors. Without it, the SDK uses99 # Re-enable TodoWrite, which this example monitors. Without it, the SDK uses

95 else "❌"116 else "❌"

96 )117 )

97 print(f"{i + 1}. {status} {todo['content']}")118 print(f"{i + 1}. {status} {todo['content']}")

119 except Exception as error:

120 # A single-shot query() raises after yielding an error result,

121 # such as when the max_turns limit is hit.

122 print(f"Session ended with an error: {error}")

123

124

125 asyncio.run(main())

98 ```126 ```

99</CodeGroup>127</CodeGroup>

100 128

128 }156 }

129 157

130 async trackQuery(prompt: string) {158 async trackQuery(prompt: string) {

159 try {

131 for await (const message of query({160 for await (const message of query({

132 prompt,161 prompt,

133 // Re-enable TodoWrite, which this tracker watches for.162 // Re-enable TodoWrite, which this tracker watches for.

142 }171 }

143 }172 }

144 }173 }

174 } catch (error) {

175 // A single-shot query() throws after yielding an error result,

176 // such as when the maxTurns limit is hit.

177 console.log(`Session ended with an error: ${error}`);

178 }

145 }179 }

146 }180 }

147 181

151 ```185 ```

152 186

153 ```python Python theme={null}187 ```python Python theme={null}

188 import asyncio

189

154 from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ToolUseBlock190 from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ToolUseBlock

155 from typing import List, Dict191 from typing import List, Dict

156 192

186 print(f"{i + 1}. {icon} {text}")222 print(f"{i + 1}. {icon} {text}")

187 223

188 async def track_query(self, prompt: str):224 async def track_query(self, prompt: str):

225 try:

189 async for message in query(226 async for message in query(

190 prompt=prompt,227 prompt=prompt,

191 # Re-enable TodoWrite, which this tracker watches for.228 # Re-enable TodoWrite, which this tracker watches for.

196 if isinstance(block, ToolUseBlock) and block.name == "TodoWrite":233 if isinstance(block, ToolUseBlock) and block.name == "TodoWrite":

197 self.todos = block.input["todos"]234 self.todos = block.input["todos"]

198 self.display_progress()235 self.display_progress()

236 except Exception as error:

237 # A single-shot query() raises after yielding an error result,

238 # such as when the max_turns limit is hit.

239 print(f"Session ended with an error: {error}")

199 240

200 241

201 # Usage242 # Usage

243 async def main():

202 tracker = TodoTracker()244 tracker = TodoTracker()

203 await tracker.track_query("Build a complete authentication system with todos")245 await tracker.track_query("Build a complete authentication system with todos")

246

247

248 asyncio.run(main())

204 ```249 ```

205</CodeGroup>250</CodeGroup>

206 251

217| Forma do item: `{ content, status, activeForm }` | Entrada de `TaskCreate`: `{ subject, description, activeForm?, metadata? }`. Entrada de `TaskUpdate`: `{ taskId, status?, subject?, description?, activeForm?, addBlocks?, addBlockedBy?, owner?, metadata? }`. `status` é `"pending"`, `"in_progress"` ou `"completed"`; defina `status: "deleted"` para deletar |262| Forma do item: `{ content, status, activeForm }` | Entrada de `TaskCreate`: `{ subject, description, activeForm?, metadata? }`. Entrada de `TaskUpdate`: `{ taskId, status?, subject?, description?, activeForm?, addBlocks?, addBlockedBy?, owner?, metadata? }`. `status` é `"pending"`, `"in_progress"` ou `"completed"`; defina `status: "deleted"` para deletar |

218| Renderizar `block.input.todos` diretamente | Acumular itens entre chamadas, ou ler um snapshot de um resultado de ferramenta `TaskList` |263| Renderizar `block.input.todos` diretamente | Acumular itens entre chamadas, ou ler um snapshot de um resultado de ferramenta `TaskList` |

219 264

220O ID de tarefa atribuído não está na entrada de `TaskCreate`. Ele volta no `tool_result` correspondente como `{ task: { id, subject } }`, então capture-o do bloco de resultado para codificar seu mapa. O exemplo a seguir mostra a mudança mínima para o loop [Monitorando Mudanças de Tarefas](#monitoring-todo-changes). Para renderizar uma lista completa, observe um resultado de ferramenta `TaskList` no fluxo ou acumule resultados de `TaskCreate` e entradas de `TaskUpdate` em um mapa.265O ID de tarefa atribuído não está na entrada de `TaskCreate`. Ele volta no `tool_result` correspondente como `{ task: { id, subject } }`, então capture-o do bloco de resultado para codificar seu mapa. O exemplo a seguir mostra a mudança mínima para o loop [Monitorando Mudanças de Tarefas](#monitoring-todo-changes). Ele lê apenas entradas de `tool_use` e ignora a captura de IDs de blocos `tool_result`. Para renderizar uma lista completa, observe um resultado de ferramenta `TaskList` no fluxo ou acumule resultados de `TaskCreate` e entradas de `TaskUpdate` em um mapa.

221 266

222O input `tool_use` transmitido é a forma bruta que o modelo emitiu. Claude Code repara alguns nomes de chave próximos mas incorretos antes da execução, mapeando `id` ou `task_id` para `taskId` e `active_form` para `activeForm`, mas esse reparo não é refletido no fluxo. Leia os campos de entrada de `TaskUpdate` defensivamente, como os exemplos abaixo fazem, em vez de assumir que o nome canônico está sempre presente.267O input `tool_use` transmitido é a forma bruta que o modelo emitiu. Claude Code repara alguns nomes de chave próximos mas incorretos antes da execução, mapeando `id` ou `task_id` para `taskId` e `active_form` para `activeForm`, mas esse reparo não é refletido no fluxo. Leia os campos de entrada de `TaskUpdate` defensivamente, como os exemplos abaixo fazem, em vez de assumir que o nome canônico está sempre presente.

223 268

225 ```typescript TypeScript theme={null}270 ```typescript TypeScript theme={null}

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

227 272

273 try {

228 for await (const message of query({274 for await (const message of query({

229 prompt: "Optimize my React app performance",275 prompt: "Optimize my React app performance and track progress with todos",

276 options: { maxTurns: 15 },

230 })) {277 })) {

231 if (message.type !== "assistant") continue;278 if (message.type !== "assistant") continue;

232 for (const block of message.message.content) {279 for (const block of message.message.content) {

246 }293 }

247 }294 }

248 }295 }

296 } catch (error) {

297 // A single-shot query() throws after yielding an error result.

298 console.log(`Session ended with an error: ${error}`);

299 }

249 ```300 ```

250 301

251 ```python Python theme={null}302 ```python Python theme={null}

252 from claude_agent_sdk import query, AssistantMessage, ToolUseBlock303 import asyncio

253 304

305 from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ToolUseBlock

306

307 async def main():

308 try:

254 async for message in query(309 async for message in query(

255 prompt="Optimize my React app performance",310 prompt="Optimize my React app performance and track progress with todos",

311 options=ClaudeAgentOptions(max_turns=15),

256 ):312 ):

257 if not isinstance(message, AssistantMessage):313 if not isinstance(message, AssistantMessage):

258 continue314 continue

269 )325 )

270 if task_id:326 if task_id:

271 print(f" {task_id} -> {block.input['status']}")327 print(f" {task_id} -> {block.input['status']}")

328 except Exception as error:

329 # A single-shot query() raises after yielding an error result.

330 print(f"Session ended with an error: {error}")

331

332

333 asyncio.run(main())

272 ```334 ```

273</CodeGroup>335</CodeGroup>

274 336

agent-sdk/typescript.md +18 −6

Details

551```551```

552 552

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

554* `CLAUDE_CODE_MAX_RETRIES`: máximo de tentativas de API. Padrão `10`, limitado a `15`. Cada tentativa obtém sua própria janela `API_TIMEOUT_MS`, então o tempo de parede no pior caso é aproximadamente `API_TIMEOUT_MS × (CLAUDE_CODE_MAX_RETRIES + 1)` mais backoff. Para execuções sem supervisão que precisam aguardar através de interrupções mais longas, defina `CLAUDE_CODE_RETRY_WATCHDOG=1` para tentar capacidade de erros indefinidamente.554* `CLAUDE_CODE_MAX_RETRIES`: máximo de tentativas de API. Padrão `10`, limitado a `15`. Cada tentativa obtém sua própria janela `API_TIMEOUT_MS`, então o tempo de parede no pior caso é aproximadamente `API_TIMEOUT_MS × (CLAUDE_CODE_MAX_RETRIES + 1)` mais backoff. Para execuções sem supervisão que precisam aguardar através de interrupções mais longas, defina `CLAUDE_CODE_RETRY_WATCHDOG=1`: ele tenta erros de capacidade indefinidamente, e {/* min-version: 2.1.199 */}a partir do Claude Code v2.1.199 aumenta o padrão para outros erros transitórios para `300` e remove o limite nesta variável.

555* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`: watchdog de travamento para subagentes lançados com `run_in_background`. Padrão `600000`. Redefine em cada evento de stream; em caso de travamento, aborta o subagente, marca a tarefa como falhada e expõe o erro ao pai com qualquer resultado parcial. Não se aplica a subagentes síncronos.555* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`: watchdog de travamento para subagentes lançados com `run_in_background`. Padrão `600000`. Redefine em cada evento de stream; em caso de travamento, aborta o subagente, marca a tarefa como falhada e expõe o erro ao pai com qualquer resultado parcial. Não se aplica a subagentes síncronos.

556* `CLAUDE_ENABLE_STREAM_WATCHDOG` com `CLAUDE_STREAM_IDLE_TIMEOUT_MS`: aborta a solicitação quando os cabeçalhos chegaram mas o corpo da resposta para de fazer stream. O watchdog está ativado por padrão para todos os provedores; defina `CLAUDE_ENABLE_STREAM_WATCHDOG=0` para desativá-lo. `CLAUDE_STREAM_IDLE_TIMEOUT_MS` padrão é `300000` e é fixado nesse mínimo. A solicitação abortada passa pelo caminho de tentativa normal.556* `CLAUDE_ENABLE_STREAM_WATCHDOG` com `CLAUDE_STREAM_IDLE_TIMEOUT_MS`: aborta a solicitação quando os cabeçalhos chegaram mas o corpo da resposta para de fazer stream. O watchdog está ativado por padrão para todos os provedores; defina `CLAUDE_ENABLE_STREAM_WATCHDOG=0` para desativá-lo. `CLAUDE_STREAM_IDLE_TIMEOUT_MS` padrão é `300000` e é fixado nesse mínimo. A solicitação abortada passa pelo caminho de tentativa normal.

557 557

901 decisionReason?: string;901 decisionReason?: string;

902 toolUseID: string;902 toolUseID: string;

903 agentID?: string;903 agentID?: string;

904 requestId: string;

904 }905 }

905) => Promise<PermissionResult>;906) => Promise<PermissionResult | null>;

906```907```

907 908

917| `requestId` | `string` | O `request_id` do envelope `control_request`. Uma `control_response` que sua aplicação envia fora do SDK, como um POST HTTP assinado, deve ecoar este valor para que o processo Claude Code possa corresponder a resposta à solicitação |

918

919O callback normalmente resolve a solicitação retornando um [`PermissionResult`](#permissionresult), que o SDK escreve de volta sobre seu transporte como a `control_response`. Retorne `null` apenas quando sua aplicação já enviou a `control_response` para esta solicitação sobre seu próprio canal, ecoando `requestId`; o SDK então pula escrever a resposta em seu transporte. Retornar `null` em qualquer outro caso deixa a chamada de ferramenta bloqueada indefinidamente, porque nenhuma `control_response` é jamais enviada e prompts de permissão não expiram.

920

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

916 922

917<h3 id="permissionresult">923<h3 id="permissionresult">

918 `PermissionResult`924 `PermissionResult`

2179};2185};

2180```2186```

2181 2187

2182Para uma tarefa de background em execução ou shell por ID.2188Para uma tarefa de background em execução ou shell por ID. {/* min-version: 2.1.198 */}A partir de v2.1.198, `task_id` também aceita um colega de equipe de agentes ou um agente de background nomeado por ID de agente ou nome.

2183 2189

2184<h3 id="notebookedit">2190<h3 id="notebookedit">

2185 NotebookEdit2191 NotebookEdit

3788| `ripgrep` | `{ command: string; args?: string[] }` | `undefined` | Configuração de binário ripgrep personalizado para ambientes sandbox |3794| `ripgrep` | `{ command: string; args?: string[] }` | `undefined` | Configuração de binário ripgrep personalizado para ambientes sandbox |

3789 3795

3790<Note>3796<Note>

3791 O sandbox depende do suporte de plataforma e, no Linux, ferramentas como `bubblewrap` e `socat`. Quando `enabled` é `true` e o sandbox não consegue iniciar, `query()` relata uma mensagem `result` com `subtype: "error_during_execution"` e o motivo em `errors`, depois para. Observe esse subtipo em vez de esperar que `query()` lance uma exceção antes de gerar mensagens.3797 O sandbox depende do suporte de plataforma e, no Linux, ferramentas como `bubblewrap` e `socat`. Quando `enabled` é `true` e o sandbox não consegue iniciar, `query()` relata uma mensagem `result` com `subtype: "error_during_execution"` e o motivo em `errors`. Para uma única chamada de mensagem `query()`, o SDK lança após gerar esse resultado de erro, então envolva o loop em um bloco try para continuar além dele. Veja [Lidar com o resultado](/pt/agent-sdk/agent-loop#handle-the-result) para o contrato de erro.

3792 3798

3793 Para executar sem sandbox, defina `failIfUnavailable: false`.3799 Para executar sem sandbox, defina `failIfUnavailable: false`.

3794</Note>3800</Note>

3800```typescript theme={null}3806```typescript theme={null}

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

3802 3808

3803for await (const message of query({3809try {

3810 for await (const message of query({

3804 prompt: "Build and test my project",3811 prompt: "Build and test my project",

3805 options: {3812 options: {

3806 sandbox: {3813 sandbox: {

3811 }3818 }

3812 }3819 }

3813 }3820 }

3814})) {3821 })) {

3815 if ("result" in message) console.log(message.result);3822 if ("result" in message) console.log(message.result);

3823 }

3824} catch (error) {

3825 // Uma query() de uma única vez lança após gerar um resultado de erro,

3826 // como quando o sandbox não consegue iniciar (failIfUnavailable padrão é true).

3827 console.log(`Session ended with an error: ${error}`);

3816}3828}

3817```3829```

3818 3830

agent-teams.md +12 −3

Details

89* **Enter**: abra a transcrição do companheiro de equipe selecionado e envie uma mensagem diretamente89* **Enter**: abra a transcrição do companheiro de equipe selecionado e envie uma mensagem diretamente

90* **Escape**: interrompa o turno atual do companheiro de equipe selecionado90* **Escape**: interrompa o turno atual do companheiro de equipe selecionado

91 91

92{/* min-version: 2.1.181 */}A partir da v2.1.181, a linha de um companheiro de equipe ocioso se oculta após 30 segundos e reaparece em seu próximo turno. O companheiro de equipe continua em execução e endereçável enquanto oculto.92{/* min-version: 2.1.199 */}A partir da v2.1.199, a linha de um companheiro de equipe ocioso permanece no painel enquanto qualquer companheiro de equipe ou subagente ainda estiver trabalhando, para que você possa selecioná-lo para revisar sua transcrição ou enviar-lhe mais trabalho. Quando todos os agentes no painel estão ociosos, as linhas ociosas se ocultam após 30 segundos e reaparecem no próximo turno do companheiro de equipe; o companheiro de equipe continua em execução e endereçável enquanto oculto. Na v2.1.181 até v2.1.198, uma linha ociosa se ocultava 30 segundos após seu próprio turno terminar, mesmo enquanto outros companheiros de equipe ainda estavam trabalhando; linhas ociosas não são ocultadas em versões anteriores à v2.1.181.

94Quando mais de três companheiros de equipe estão ociosos ao mesmo tempo, as linhas além das três primeiras se recolhem em uma única linha que conta os companheiros de equipe recolhidos, como `2 idle agents` quando cinco estão ociosos. Selecione-a e pressione Enter para expandir as linhas recolhidas, ou pressione Esc para recolhê-las novamente. Companheiros de equipe trabalhando, companheiros de equipe que falharam e o companheiro de equipe que você está visualizando sempre mantêm suas próprias linhas.

93 95

94Se você quiser cada companheiro de equipe em seu próprio painel dividido, veja [Escolha um modo de exibição](#choose-a-display-mode).96Se você quiser cada companheiro de equipe em seu próprio painel dividido, veja [Escolha um modo de exibição](#choose-a-display-mode).

95 97

174* **Modo in-process**: use as teclas de seta para cima e para baixo no painel de agentes para selecionar um companheiro de equipe, depois pressione Enter para visualizar sua sessão e digite para enviar uma mensagem. Pressione `x` em um companheiro de equipe selecionado para interrompê-lo. Pressione Ctrl+T para alternar a lista de tarefas.176* **Modo in-process**: use as teclas de seta para cima e para baixo no painel de agentes para selecionar um companheiro de equipe, depois pressione Enter para visualizar sua sessão e digite para enviar uma mensagem. Pressione `x` em um companheiro de equipe selecionado para interrompê-lo. Pressione Ctrl+T para alternar a lista de tarefas.

175* **Modo split-pane**: clique em um painel de companheiro de equipe para interagir com sua sessão diretamente. Cada companheiro de equipe tem uma visualização completa de seu próprio terminal.177* **Modo split-pane**: clique em um painel de companheiro de equipe para interagir com sua sessão diretamente. Cada companheiro de equipe tem uma visualização completa de seu próprio terminal.

176 178

179Enquanto você está visualizando um companheiro de equipe in-process, texto simples e [skills](/pt/skills) vão para esse companheiro de equipe, mas comandos integrados ainda são executados na sessão do líder.

180

181O modelo e modo rápido de um companheiro de equipe são fixos quando ele é gerado, portanto `/model` e `/fast` apenas alteram as configurações do líder. {/* min-version: 2.1.199 */}A partir da v2.1.199, digitar qualquer comando enquanto visualiza um companheiro de equipe mostra um aviso de que a alteração se aplica ao líder; versões anteriores a aplicavam ao líder sem indicação. `/effort` ainda se aplica aos turnos posteriores do companheiro de equipe visualizado, porque os companheiros de equipe seguem o [nível de esforço](/pt/model-config#adjust-effort-level) do líder.

182

177<h3 id="assign-and-claim-tasks">183<h3 id="assign-and-claim-tasks">

178 Atribuir e reivindicar tarefas184 Atribuir e reivindicar tarefas

179</h3>185</h3>

295**Como os companheiros de equipe compartilham informações:**301**Como os companheiros de equipe compartilham informações:**

296 302

297* **Entrega automática de mensagens**: quando os companheiros de equipe enviam mensagens, elas são entregues automaticamente aos destinatários. O líder não precisa fazer polling para atualizações.303* **Entrega automática de mensagens**: quando os companheiros de equipe enviam mensagens, elas são entregues automaticamente aos destinatários. O líder não precisa fazer polling para atualizações.

298* **Notificações de ociosidade**: quando um companheiro de equipe termina e para, ele notifica automaticamente o líder.304* **Notificações de ociosidade**: quando um companheiro de equipe termina e para, ele notifica automaticamente o líder. {/* min-version: 2.1.198 */}A partir da v2.1.198, um companheiro de equipe cuja vez termina em um erro de API notifica o líder que falhou e inclui o texto do erro, em vez de parecer terminar normalmente.

299* **Lista de tarefas compartilhada**: todos os agentes podem ver o status da tarefa e reivindicar trabalho disponível.305* **Lista de tarefas compartilhada**: todos os agentes podem ver o status da tarefa e reivindicar trabalho disponível.

300* **Mensagens de companheiros de equipe**: envie uma mensagem para um companheiro de equipe específico pelo nome. Para alcançar todos, envie uma mensagem por destinatário.306* **Mensagens de companheiros de equipe**: envie uma mensagem para um companheiro de equipe específico pelo nome. Para alcançar todos, envie uma mensagem por destinatário.

301 307

430Se os companheiros de equipe não aparecerem depois que você pedir ao Claude para criar uma equipe:436Se os companheiros de equipe não aparecerem depois que você pedir ao Claude para criar uma equipe:

431 437

432* No modo in-process, os companheiros de equipe aparecem no painel de agentes abaixo da entrada de prompt. Use as teclas de seta para cima e para baixo para selecionar um e pressione Enter para visualizá-lo.438* No modo in-process, os companheiros de equipe aparecem no painel de agentes abaixo da entrada de prompt. Use as teclas de seta para cima e para baixo para selecionar um e pressione Enter para visualizá-lo.

433* Uma linha de companheiro de equipe que desapareceu após ficar inativa foi ocultada, não interrompida. As linhas inativas se ocultam após 30 segundos e reaparecem na próxima vez do companheiro de equipe. Envie uma mensagem ao companheiro de equipe pelo nome para trazê-lo de volta.439* Uma linha de companheiro de equipe que desapareceu após ficar inativa foi ocultada, não interrompida. As linhas inativas se ocultam 30 segundos após o painel inteiro ficar inativo e reaparecem na próxima vez do companheiro de equipe. Quando mais de três companheiros de equipe estão inativos, suas linhas excedentes se recolhem em uma única linha `N idle agents` que Enter expande. Envie uma mensagem ao companheiro de equipe pelo nome para trazer uma linha oculta de volta.

434* Verifique se a tarefa que você deu ao Claude era complexa o suficiente para justificar uma equipe. Claude decide se deve gerar companheiros de equipe com base na tarefa.440* Verifique se a tarefa que você deu ao Claude era complexa o suficiente para justificar uma equipe. Claude decide se deve gerar companheiros de equipe com base na tarefa.

435* Se você explicitamente solicitou split panes, certifique-se de que tmux está instalado e disponível no seu PATH:441* Se você explicitamente solicitou split panes, certifique-se de que tmux está instalado e disponível no seu PATH:

436 ```bash theme={null}442 ```bash theme={null}

453* Dê a eles instruções adicionais diretamente459* Dê a eles instruções adicionais diretamente

454* Gere um companheiro de equipe de substituição para continuar o trabalho460* Gere um companheiro de equipe de substituição para continuar o trabalho

455 461

462{/* min-version: 2.1.198 */}A partir da v2.1.198, uma mensagem do líder ou de outro companheiro de equipe acorda um companheiro de equipe in-process que está aguardando para tentar novamente uma solicitação de API com falha, para que ele tente novamente imediatamente em vez de aguardar o atraso de repetição completo.

463

456<h3 id="lead-shuts-down-before-work-is-done">464<h3 id="lead-shuts-down-before-work-is-done">

457 Líder encerra antes do trabalho estar pronto465 Líder encerra antes do trabalho estar pronto

458</h3>466</h3>

481* **Encerramento pode ser lento**: os companheiros de equipe terminam sua solicitação atual ou chamada de ferramenta antes de encerrar, o que pode levar tempo.489* **Encerramento pode ser lento**: os companheiros de equipe terminam sua solicitação atual ou chamada de ferramenta antes de encerrar, o que pode levar tempo.

482* **Uma equipe por sessão**: uma sessão tem exatamente uma equipe, com escopo para essa sessão. Você não pode criar equipes nomeadas adicionais ou compartilhar uma equipe entre sessões.490* **Uma equipe por sessão**: uma sessão tem exatamente uma equipe, com escopo para essa sessão. Você não pode criar equipes nomeadas adicionais ou compartilhar uma equipe entre sessões.

483* **Sem equipes aninhadas**: os companheiros de equipe não podem gerar seus próprios companheiros de equipe. Apenas o líder pode gerenciar a equipe.491* **Sem equipes aninhadas**: os companheiros de equipe não podem gerar seus próprios companheiros de equipe. Apenas o líder pode gerenciar a equipe.

492* **Sem subagentes em segundo plano de companheiros de equipe in-process**: os próprios subagentes de um companheiro de equipe in-process são executados em primeiro plano. Pedir por um em segundo plano, seja com `run_in_background` ou uma definição de subagente que define `background: true`, retorna um erro, porque o trabalho em segundo plano de um companheiro de equipe não pode sobreviver ao processo do líder. Subagentes lançados da conversa principal seguem o [padrão de segundo plano](/pt/sub-agents#run-subagents-in-foreground-or-background).

484* **Líder é fixo**: a sessão principal é o líder por sua vida útil. Você não pode promover um companheiro de equipe a líder ou transferir liderança.493* **Líder é fixo**: a sessão principal é o líder por sua vida útil. Você não pode promover um companheiro de equipe a líder ou transferir liderança.

485* **Permissões definidas no tempo de geração**: todos os companheiros de equipe começam com o modo de permissão do líder. Você pode alterar modos de companheiros de equipe individuais após gerar, mas não pode definir modos por companheiro de equipe no tempo de geração.494* **Permissões definidas no tempo de geração**: todos os companheiros de equipe começam com o modo de permissão do líder. Você pode alterar modos de companheiros de equipe individuais após gerar, mas não pode definir modos por companheiro de equipe no tempo de geração.

486* **Split panes requerem tmux ou iTerm2**: o modo in-process padrão funciona em qualquer terminal. O modo split-pane não é suportado no terminal integrado do VS Code, Windows Terminal ou Ghostty.495* **Split panes requerem tmux ou iTerm2**: o modo in-process padrão funciona em qualquer terminal. O modo split-pane não é suportado no terminal integrado do VS Code, Windows Terminal ou Ghostty.

agent-view.md +60 −11

Details

27* [Início rápido](#quick-start): dê a Claude uma tarefa para trabalhar em background, verifique-a e intervenha quando necessário27* [Início rápido](#quick-start): dê a Claude uma tarefa para trabalhar em background, verifique-a e intervenha quando necessário

28* [Monitorar sessões com agent view](#monitor-sessions-with-agent-view), incluindo ícones de estado, espiada e resposta, anexação, organização e atalhos de teclado28* [Monitorar sessões com agent view](#monitor-sessions-with-agent-view), incluindo ícones de estado, espiada e resposta, anexação, organização e atalhos de teclado

29* [Despache novos agentes](#dispatch-new-agents) a partir de agent view, de dentro de uma sessão ou do seu shell29* [Despache novos agentes](#dispatch-new-agents) a partir de agent view, de dentro de uma sessão ou do seu shell

~~30* [Gerenciar sessões do shell](#manage-sessions-from-the-shell)~~30* [Gerenciar sessões do shell](#manage-sessions-from-the-shell) com `claude agents`, `claude attach` e comandos relacionados

31* [Como as sessões em background são hospedadas](#how-background-sessions-are-hosted) pelo processo supervisor31* [Como as sessões em background são hospedadas](#how-background-sessions-are-hosted) pelo processo supervisor

32 32

33<h2 id="quick-start">33<h2 id="quick-start">

64 </Step>64 </Step>

65 65

66 <Step title="Trazer uma sessão existente">66 <Step title="Trazer uma sessão existente">

67 Para mover uma sessão que você já tem aberta para a visualização do agente, execute `/bg` dentro dela, ou pressione `←` em um prompt vazio para colocá-la em background e abrir a visualização do agente em uma etapa. A sessão continua em execução e aparece como uma linha ao lado das que você despachou.67 Esta etapa precisa de uma sessão em execução. Se você seguiu as etapas anteriores, você não tem uma aberta neste terminal, portanto abra uma sessão regular `claude` em outro terminal e envie uma mensagem para ela primeiro. Para mover uma sessão que você já tem aberta para a visualização do agente, execute `/bg` dentro dela, ou pressione `←` em um prompt vazio para colocá-la em background e abrir a visualização do agente em uma etapa. A sessão continua em execução e aparece como uma linha ao lado das que você despachou.

68 </Step>68 </Step>

69</Steps>69</Steps>

70 70

76 76

77Execute `claude agents` para abrir agent view. Ele assume o terminal completo e lista cada sessão agrupada por estado, com sessões fixadas e as que precisam de você no topo. Cada linha mostra o nome da sessão, atividade atual e há quanto tempo foi alterada pela última vez.77Execute `claude agents` para abrir agent view. Ele assume o terminal completo e lista cada sessão agrupada por estado, com sessões fixadas e as que precisam de você no topo. Cada linha mostra o nome da sessão, atividade atual e há quanto tempo foi alterada pela última vez.

78 78

79O nome é tingido com a cor definida por [`/color`](/pt/commands) naquela sessão. {/* min-version: 2.1.199 */}A partir da v2.1.199, a cor é mantida quando você [coloca uma sessão em background](#from-inside-a-session) com `←` ou `/background`.

79Por padrão, a lista mostra cada sessão em background que você iniciou, em todos os seus projetos. Uma sessão funcionando em um repositório e outra em um worktree diferente aparecem aqui, independentemente de qual diretório você abriu agent view. Para limitar a lista a um projeto, passe `--cwd`:81Por padrão, a lista mostra cada sessão em background que você iniciou, em todos os seus projetos. Uma sessão funcionando em um repositório e outra em um worktree diferente aparecem aqui, independentemente de qual diretório você abriu agent view. Para limitar a lista a um projeto, passe `--cwd`:

80 82

81```bash theme={null}83```bash theme={null}

91 ✽ clawd walk cycle Write assets/sprites/clawd-walk.png 3m93 ✽ clawd walk cycle Write assets/sprites/clawd-walk.png 3m

92 94

93Ready for review95Ready for review

~~94 ∙ jump physics Opened PR with collision fix PR #2048 2h~~96 ∙ jump physics Opened PR with collision fix #2048 2h

95 97

96Needs input98Needs input

97 ✻ power-up design needs input: double jump or wall climb? 1m99 ✻ power-up design needs input: double jump or wall climb? 1m

129| `∙` | O processo saiu. Você ainda pode espreitar, responder ou anexar, e Claude reinicia de onde parou |131| `∙` | O processo saiu. Você ainda pode espreitar, responder ou anexar, e Claude reinicia de onde parou |

130| `✢` | Uma sessão [`/loop`](/pt/scheduled-tasks) dormindo entre iterações. A linha mostra sua contagem de execução e uma contagem regressiva |132| `✢` | Uma sessão [`/loop`](/pt/scheduled-tasks) dormindo entre iterações. A linha mostra sua contagem de execução e uma contagem regressiva |

131 133

132O rótulo `PR #N` que pode aparecer na borda direita de uma linha é o [pull request que a sessão abriu](#pull-request-status), não parte do ícone de estado. Quando uma sessão abriu mais de um pull request, o rótulo mostra uma contagem em vez disso, como `3 PRs`.134O rótulo `#N` que pode aparecer na borda direita de uma linha é o [pull request que a sessão abriu](#pull-request-status), não parte do ícone de estado.

133 135

134O título da aba do terminal mostra a contagem de aguardando-entrada enquanto agent view está aberto: `2 awaiting input · claude agents` quando sessões precisam de entrada, ou `claude agents` quando nenhuma precisa.136O título da aba do terminal mostra a contagem de aguardando-entrada enquanto agent view está aberto: `2 awaiting input · claude agents` quando sessões precisam de entrada, ou `claude agents` quando nenhuma precisa.

135 137

138A partir da v2.1.198, enquanto agent view está aberto, Claude Code também envia uma notificação através do seu [canal de notificação de terminal](/pt/terminal-config#get-a-terminal-bell-or-notification) configurado quando uma sessão em background local começa a precisar de sua entrada, termina ou falha. Sessões que executam em um cronograma, como sessões [`/loop`](/pt/scheduled-tasks), notificam apenas quando precisam de sua entrada. As notificações usam a mesma configuração [`preferredNotifChannel`](/pt/settings#available-settings) que o resto do Claude Code e disparam o hook [`Notification`](/pt/hooks#notification) com o tipo `agent_needs_input` ou `agent_completed`.

139

136Sessões em background não precisam de nenhum terminal aberto para continuar funcionando. Um [processo supervisor](#the-supervisor-process) separado as executa, então você pode fechar agent view, fechar seu shell ou iniciar uma nova sessão interativa e seu trabalho despachado continua.140Sessões em background não precisam de nenhum terminal aberto para continuar funcionando. Um [processo supervisor](#the-supervisor-process) separado as executa, então você pode fechar agent view, fechar seu shell ou iniciar uma nova sessão interativa e seu trabalho despachado continua.

137 141

138O estado da sessão persiste no disco através de atualizações automáticas e reinicializações do supervisor. As sessões também são preservadas quando sua máquina dorme. Seus processos retomam ao acordar e o supervisor se reconecta a eles em vez de tratar a lacuna de tempo como inatividade. Desligar ainda interrompe as sessões em execução; veja [Sessions show as failed after shutdown](#sessions-show-as-failed-after-shutdown) para saber como recuperá-las.142O estado da sessão persiste no disco através de atualizações automáticas e reinicializações do supervisor. As sessões também são preservadas quando sua máquina dorme. Seus processos retomam ao acordar e o supervisor se reconecta a eles em vez de tratar a lacuna de tempo como inatividade. Desligar ainda interrompe as sessões em execução; veja [Sessions show as failed after shutdown](#sessions-show-as-failed-after-shutdown) para saber como recuperá-las.

151 Status de pull request155 Status de pull request

152</h3>156</h3>

153 157

154Quando uma sessão abre um pull request, um rótulo `PR #1234` aparece na borda direita da linha, vinculado ao pull request em terminais que suportam hiperlinks. O rótulo persiste quando você envia um acompanhamento para a sessão, então o pull request permanece visível enquanto a linha reverte para progresso ao vivo.158Quando uma sessão abre um pull request, um rótulo `#1234` aparece na borda direita da linha, vinculado ao pull request em terminais que suportam hiperlinks. O rótulo persiste quando você envia um acompanhamento para a sessão, então o pull request permanece visível enquanto a linha reverte para progresso ao vivo. Sessões em background que isolaram suas alterações em um worktree abrem esses pull requests por conta própria; [How file edits are isolated](#how-file-edits-are-isolated) cobre quando isso acontece e o que uma sessão nunca faz sem perguntar.

155 159

156Quando uma sessão abriu mais de um pull request, o rótulo mostra uma contagem em vez disso, como `3 PRs`, colorido pelo pull request aberto que mais precisa de atenção. Abra o [painel de espiada](#peek-and-reply) para ver todos eles.160Quando uma sessão abriu mais de um pull request, o rótulo mostra uma contagem em vez disso, como `3 PRs`, colorido pelo pull request aberto que mais precisa de atenção. Abra o [painel de espiada](#peek-and-reply) para ver todos eles.

157 161

190 194

191Sessões anexadas sempre renderizam em [modo fullscreen](/pt/fullscreen), independentemente de sua configuração `tui`, porque uma sessão em background não tem scrollback de terminal para anexar. Role com `PgUp`, `PgDn` ou a roda do mouse, e pressione `Ctrl+O` para modo de transcript. O scroll nativo do seu terminal e o modo de cópia tmux mostram apenas o viewport atual, o mesmo que quando você executa qualquer aplicativo fullscreen.195Sessões anexadas sempre renderizam em [modo fullscreen](/pt/fullscreen), independentemente de sua configuração `tui`, porque uma sessão em background não tem scrollback de terminal para anexar. Role com `PgUp`, `PgDn` ou a roda do mouse, e pressione `Ctrl+O` para modo de transcript. O scroll nativo do seu terminal e o modo de cópia tmux mostram apenas o viewport atual, o mesmo que quando você executa qualquer aplicativo fullscreen.

192 196

193Pressione `←` em um prompt vazio para desanexar e retornar a agent view. Se um diálogo tem foco e não está respondendo a `←`, pressione `Ctrl+Z` para desanexar imediatamente.197Pressione `←` em um prompt vazio, ou execute `/exit`, para desanexar e retornar a agent view. A partir da v2.1.198, isso funciona da mesma forma se você abriu a sessão a partir de agent view ou com `claude attach <id>` a partir do seu shell.

198

199`Ctrl+Z` também desanexa, mas volta para onde você começou: agent view se você anexou de lá, ou seu shell se você executou `claude attach`. Use `Ctrl+Z` quando um diálogo tem foco e não está respondendo a `←`.

194 200

195`Ctrl+C` mantém seu comportamento de interrupção padrão enquanto anexado: ele cancela uma resposta em execução ou comando shell `!` em vez de desanexar. Pressionar `Ctrl+C` duas vezes em um prompt vazio desanexa, o mesmo que em qualquer sessão.201`Ctrl+C` mantém seu comportamento de interrupção padrão enquanto anexado: ele cancela uma resposta em execução ou comando shell `!` em vez de desanexar. Pressionar `Ctrl+C` duas vezes em um prompt vazio desanexa, o mesmo que em qualquer sessão.

196 202

291 297

292Um pequeno conjunto de comandos é executado em agent view em vez de ser despachado: `/exit` e `/quit` fecham agent view, `/logout` desconecta você, e `/model` define o [modelo de despacho](#set-the-model). Skills, seus próprios comandos e built-ins que expandem prompts como `/init` são enviados para uma nova sessão em background como seu primeiro prompt. Outros comandos built-in mostram uma dica `attach to a session to run it` em vez disso.298Um pequeno conjunto de comandos é executado em agent view em si em vez de ser despachado:

299

300* `/exit` e `/quit` fecham agent view

301* `/logout` desconecta você

302* `/model` define o [modelo de despacho](#set-the-model)

303* {/* min-version: 2.1.198 */}A partir da v2.1.198, `/login` abre o diálogo de entrada para que você possa entrar novamente sem anexar a uma sessão

304

305Skills, seus próprios comandos e built-ins que expandem prompts como `/init` são enviados para uma nova sessão em background como seu primeiro prompt. Outros comandos built-in mostram uma dica `attach to a session to run it` em vez disso.

293 306

294Empacotar uma tarefa recorrente como uma [skill](/pt/skills) permite que você inicie o mesmo fluxo de trabalho a partir de agent view repetidamente sem redigitar o prompt.307Empacotar uma tarefa recorrente como uma [skill](/pt/skills) permite que você inicie o mesmo fluxo de trabalho a partir de agent view repetidamente sem redigitar o prompt.

295 308

313 326

314Execute `/background` ou seu alias `/bg` para mover a conversa atual para uma sessão em background. Passe um prompt como `/bg run the test suite and fix any failures` para dar uma instrução adicional primeiro. Se Claude estiver respondendo quando você executar `/bg`, a resposta continua na sessão em background.327Execute `/background` ou seu alias `/bg` para mover a conversa atual para uma sessão em background. Passe um prompt como `/bg run the test suite and fix any failures` para dar uma instrução adicional primeiro. Se Claude estiver respondendo quando você executar `/bg`, a resposta continua na sessão em background.

315 328

329Sair de uma sessão interativa que ainda tem trabalho em background em execução, como subagents, comandos shell em background, workflows ou [monitors](/pt/tools-reference#monitor-tool), mostra um diálogo `Background work is running` em vez de sair imediatamente. {/* min-version: 2.1.198 */}A partir da v2.1.198, o diálogo oferece `Move to background and exit` junto com `Exit anyway` e `Stay`. Escolhê-lo move a sessão para o background da mesma forma que `/background` faz, depois retorna você ao seu shell, para que o trabalho que pode ser transferido continue em execução e a sessão apareça em agent view. A opção não é mostrada quando agent view está [desativado](#turn-off-agent-view).

330

316Colocar em background a partir de uma sessão interativa inicia um novo processo que retoma da conversa salva, e o trabalho em andamento se move para ele: comandos shell em background em execução, subagents em background, workflows dinâmicos e tarefas agendadas que você criou com [`/loop`](/pt/scheduled-tasks) são transferidos para a sessão em background e continuam em execução lá. Um subagent se move junto com tudo que iniciou, portanto é transferido apenas quando todo esse trabalho pode se mover também, incluindo no Windows. Para parar o trabalho em andamento em vez de transferi-lo, defina a variável de ambiente [`CLAUDE_DISABLE_ADOPT=1`](/pt/env-vars#variables); Claude Code então pede que você confirme antes de colocar em background.331Colocar em background a partir de uma sessão interativa inicia um novo processo que retoma da conversa salva, e o trabalho em andamento se move para ele: comandos shell em background em execução, subagents em background, workflows dinâmicos e tarefas agendadas que você criou com [`/loop`](/pt/scheduled-tasks) são transferidos para a sessão em background e continuam em execução lá. Um subagent se move junto com tudo que iniciou, portanto é transferido apenas quando todo esse trabalho pode se mover também, incluindo no Windows. Para parar o trabalho em andamento em vez de transferi-lo, defina a variável de ambiente [`CLAUDE_DISABLE_ADOPT=1`](/pt/env-vars#variables); Claude Code então pede que você confirme antes de colocar em background.

317 332

318Trabalho que não pode ser transferido, como um [monitor](/pt/tools-reference#monitor-tool) em execução, é interrompido. Um subagent em background que possui um monitor é interrompido junto com ele. Quando algum desse trabalho está em execução, Claude Code mostra um diálogo `Background this session?` para que você possa confirmar antes de ser interrompido.333Trabalho que não pode ser transferido, como um [monitor](/pt/tools-reference#monitor-tool) em execução, é interrompido. Um subagent em background que possui um monitor é interrompido junto com ele. Quando algum desse trabalho está em execução, Claude Code mostra um diálogo `Background this session?` para que você possa confirmar antes de ser interrompido.

342claude --bg "investigate the flaky SettingsChangeDetector test"357claude --bg "investigate the flaky SettingsChangeDetector test"

343```358```

344 359

360O prompt é o argumento posicional, não um valor `-p`. {/* min-version: 2.1.198 */}A partir da v2.1.198, combinar `--bg` com `-p` ou `--print` é rejeitado com um erro antes de qualquer sessão ser criada, porque `--print` nunca inicia a sessão interativa à qual `claude agents` se anexa.

361

345Para executar um subagent específico como o agente principal da sessão, combine `--bg` com `--agent`:362Para executar um subagent específico como o agente principal da sessão, combine `--bg` com `--agent`:

346 363

347```bash theme={null}364```bash theme={null}

414 431

415Um [subagent](/pt/sub-agents) que a sessão em background gera herda o diretório de trabalho da sessão, portanto suas edições de arquivo chegam ao worktree da sessão em vez de sua cópia de trabalho. Para dar a um subagent seu próprio worktree separado, defina [`isolation: worktree`](/pt/sub-agents#supported-frontmatter-fields) em seu frontmatter ou passe `isolation: "worktree"` ao gerá-lo.432Um [subagent](/pt/sub-agents) que a sessão em background gera herda o diretório de trabalho da sessão, portanto suas edições de arquivo chegam ao worktree da sessão em vez de sua cópia de trabalho. Para dar a um subagent seu próprio worktree separado, defina [`isolation: worktree`](/pt/sub-agents#supported-frontmatter-fields) em seu frontmatter ou passe `isolation: "worktree"` ao gerá-lo.

416 433

434A partir da v2.1.198, uma sessão em background que isolou suas alterações de código em um worktree também confirma, envia seu próprio branch e abre um pull request de rascunho sem parar para perguntar. O rótulo [`#N`](#pull-request-status) aparece em sua linha quando o pull request é aberto. Nunca envia para `main` ou `master`, nunca força-envia ou mescla, e pula o pull request quando você disse para não abrir um ou o repositório não tem um remoto.

435

436Uma sessão editando um checkout que não isolou a si mesma ainda pergunta antes de confirmar ou alternar branches. Isso se aplica quando o isolamento é definido como `"none"`, quando a movimentação do worktree falhou, ou quando a sessão foi iniciada dentro de um worktree que já existia.

437

417<h3 id="set-the-model">438<h3 id="set-the-model">

418 Set the model439 Set the model

419</h3>440</h3>

529 550

530Depois que uma sessão termina e fica desanexada por cerca de uma hora, o supervisor interrompe seu processo para liberar recursos. Uma sessão que você [fixou](#organize-the-list) com `Ctrl+T` é isenta e mantém seu processo em execução enquanto inativo. O transcript e o estado permanecem no disco de qualquer forma, e na próxima vez que você anexar, espreitar ou responder a uma sessão parada, o supervisor inicia um novo processo de onde parou. Quando cada sessão terminou e nenhum terminal está conectado, o supervisor em si sai e é iniciado novamente na próxima vez que você precisar dele.551Depois que uma sessão termina e fica desanexada por cerca de uma hora, o supervisor interrompe seu processo para liberar recursos. Uma sessão que você [fixou](#organize-the-list) com `Ctrl+T` é isenta e mantém seu processo em execução enquanto inativo. O transcript e o estado permanecem no disco de qualquer forma, e na próxima vez que você anexar, espreitar ou responder a uma sessão parada, o supervisor inicia um novo processo de onde parou. Quando cada sessão terminou e nenhum terminal está conectado, o supervisor em si sai e é iniciado novamente na próxima vez que você precisar dele.

531 552

532Comandos shell em background e workflows dinâmicos que a sessão iniciou continuam em execução quando seu processo é interrompido, reiniciado ou atualizado, incluindo no Windows. O próximo processo iniciado para essa sessão os retoma, um comando shell que terminou no meio é relatado como concluído com sua saída, e um workflow retoma de onde parou. Comandos shell iniciados por um subagent e [monitors](/pt/tools-reference#monitor-tool) em execução ainda param com o processo, e deletar a sessão interrompe tudo que ela entregou. Para parar comandos shell em background e workflows com o processo também, defina a variável de ambiente [`CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF`](/pt/env-vars#variables) como `1`.553O trabalho em background que a sessão iniciou no nível superior é entregue quando seu processo é interrompido, reiniciado ou atualizado, incluindo no Windows. O próximo processo iniciado para essa sessão retoma o trabalho:

554

555* Um comando de shell em background que terminou no meio é relatado como concluído com sua saída

556* Um workflow dinâmico retoma de onde parou

557* Um [subagent em background](/pt/sub-agents#run-subagents-in-foreground-or-background) retoma de seu próprio transcript

558

559{/* min-version: 2.1.198 */}A partir da v2.1.198, a entrega cobre todos os três. Antes da v2.1.198, cobria apenas comandos de shell e workflows, então um subagent em background parava com o processo e era relatado como falho no próximo despertar.

560

561O trabalho cujo estado vive apenas dentro do próprio processo para com ele em vez de ser entregue. Isso inclui comandos de shell que um subagent iniciou, que o subagent retomado pode iniciar novamente, e [monitors](/pt/tools-reference#monitor-tool) em execução, cujo fluxo de eventos não pode ser movido para outro processo.

562

563Deletar a sessão interrompe tudo que ela entregou. Para parar todo o trabalho em background da sessão com o processo em vez de entregá-lo, defina a variável de ambiente [`CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF`](/pt/env-vars#variables) como `1`.

533 564

534Se uma sessão reiniciada volta mostrando apenas seu prompt original porque Claude Code leu mal seu transcript como vazio, o transcript de conversa é renomeado com um sufixo `.orphaned-` em vez de ser deletado, portanto permanece em sua máquina.565Se uma sessão reiniciada volta mostrando apenas seu prompt original porque Claude Code leu mal seu transcript como vazio, o transcript de conversa é renomeado com um sufixo `.orphaned-` em vez de ser deletado, portanto permanece em sua máquina.

535 566

606 637

607Sleep sozinho não causa isso. Sessões são preservadas durante o sleep e o supervisor se reconecta a elas ao acordar.638Sleep sozinho não causa isso. Sessões são preservadas durante o sleep e o supervisor se reconecta a elas ao acordar.

608 639

640<h3 id="a-session-fails-before-starting-with-a-possibly-low-memory-note">

641 A session fails before starting with a `possibly low memory` note

642</h3>

643

644A partir da v2.1.199, quando o processo de uma sessão em background sai antes de terminar de iniciar e o host está com pouca memória, o status da linha nomeia a saída e adiciona `possibly low memory — free some up and retry`. Versões anteriores mostravam apenas o motivo da saída para essa falha.

645

646A nota é uma hipótese, não uma causa confirmada. Claude Code a adiciona apenas quando o processo saiu silenciosamente, sem escrever um erro e sem ser interrompido por um sinal, e o host relatou pouca memória naquele momento. Quando o processo escreveu um erro antes de sair, a linha mostra esse erro em vez disso.

647

648Libere memória na máquina, depois anexe, espreite ou responda à linha e o supervisor inicia um novo processo para a sessão. Quando a memória permanece baixa, o supervisor também [interrompe sessões ociosas](#the-supervisor-process) para liberar recursos por conta própria.

649

609<h3 id="agent-view-says-the-background-service-did-not-respond">650<h3 id="agent-view-says-the-background-service-did-not-respond">

610 Agent view says the background service did not respond651 Agent view says the background service did not respond

611</h3>652</h3>

636 677

637Veja a [referência de erro](/pt/errors#could-not-resolve-authentication-method) para a lista completa de causas e correções.678Veja a [referência de erro](/pt/errors#could-not-resolve-authentication-method) para a lista completa de causas e correções.

638 679

639<h3 id="background-sessions-cannot-read-desktop-documents-or-downloads-on-macos">680<h3 id="background-sessions-can’t-read-desktop-documents-or-downloads-on-macos">

640 Background sessions cannot read Desktop, Documents, or Downloads on macOS681 Background sessions can't read Desktop, Documents, or Downloads on macOS

641</h3>682</h3>

642 683

643No macOS, o host da sessão em background é executado como seu próprio processo e solicita acesso a pastas protegidas separadamente do seu terminal. Se uma sessão em background relatar `Operation not permitted` ao ler `~/Desktop`, `~/Documents`, `~/Downloads` ou outro local protegido, conceda acesso em Configurações do Sistema em Privacidade e Segurança > Arquivos e Pastas, ou ative Acesso Total ao Disco para a entrada.684No macOS, o host da sessão em background é executado como seu próprio processo e solicita acesso a pastas protegidas separadamente do seu terminal. Se uma sessão em background relatar `Operation not permitted` ao ler `~/Desktop`, `~/Documents`, `~/Downloads` ou outro local protegido, conceda acesso em Configurações do Sistema em Privacidade e Segurança > Arquivos e Pastas, ou ative Acesso Total ao Disco para a entrada.

644 685

645Com o instalador nativo, a entrada aparece como Claude Code e a concessão persiste entre atualizações. Com outros métodos de instalação, como Homebrew ou npm, a entrada mostra o caminho do binário e pode precisar ser concedida novamente após atualizar.686Com o instalador nativo, a entrada aparece como Claude Code e a concessão persiste entre atualizações. Com outros métodos de instalação, como Homebrew ou npm, a entrada mostra o caminho do binário e pode precisar ser concedida novamente após atualizar.

646 687

688<h3 id="background-sessions-can’t-reach-local-network-hosts-on-macos">

689 Background sessions can't reach local-network hosts on macOS

690</h3>

691

692No macOS 15 e posterior, o sistema bloqueia um processo de alcançar dispositivos na sua rede local até que você conceda permissão de Rede Local. Antes da v2.1.198, o host da sessão em background nunca solicitava essa permissão, então comandos direcionados a um endereço LAN falhavam com `connect: no route to host` mesmo que o mesmo comando funcionasse em um terminal em primeiro plano. {/* min-version: 2.1.198 */}A partir da v2.1.198, o primeiro comando em uma sessão em background que se conecta a um endereço de rede local dispara o prompt de permissão de Rede Local do macOS para Claude Code. Conceda uma vez e esses comandos alcançam hosts LAN da mesma forma que fazem em um terminal em primeiro plano.

693

647<h3 id="a-session-is-slow-to-respond-after-attaching">694<h3 id="a-session-is-slow-to-respond-after-attaching">

648 A session is slow to respond after attaching695 A session is slow to respond after attaching

649</h3>696</h3>

683Agent view evoluiu rapidamente durante a visualização de pesquisa. Se você estiver em uma versão mais antiga do Claude Code, alguns comportamentos nesta página podem diferir; em particular, `claude agents` rejeita flags que ainda não suporta com um erro de opção desconhecida. A tabela abaixo lista quando cada flag e comportamento foi adicionado.730Agent view evoluiu rapidamente durante a visualização de pesquisa. Se você estiver em uma versão mais antiga do Claude Code, alguns comportamentos nesta página podem diferir; em particular, `claude agents` rejeita flags que ainda não suporta com um erro de opção desconhecida. A tabela abaixo lista quando cada flag e comportamento foi adicionado.

684 731

686| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |733| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

734| v2.1.199 | {/* min-version: 2.1.199 */}Uma sessão em background cujo processo sai antes de terminar de iniciar em um host com pouca memória mostra `possibly low memory — free some up and retry` no status de sua linha em vez de apenas o motivo de saída simples. Colocar uma sessão em background com `←` ou `/background` carrega seu `/color` para a nova linha. |

735| v2.1.198 | {/* min-version: 2.1.198 */}Agent view envia uma notificação através de `preferredNotifChannel` quando uma sessão em background precisa de entrada, termina ou falha, e dispara o hook `Notification` com o tipo `agent_needs_input` ou `agent_completed`. `←` e `/exit` dentro de `claude attach <id>` retornam para agent view em vez de sair para o shell; `Ctrl+Z` retorna para o shell. Uma sessão em background que isolou seu trabalho em um worktree faz commit, envia seu próprio branch isolado, nunca `main` ou `master`, e abre um pull request em rascunho quando termina em vez de perguntar primeiro. `/login` é executado em agent view e abre o diálogo de entrada. O diálogo de saída `Background work is running` oferece `Move to background and exit`. A entrega de saída também cobre subagentes em background, que retomam de sua transcrição no próximo despertar em vez de serem relatados como falhados. `claude --bg` combinado com `-p` ou `--print` é rejeitado com um erro. |

687| v2.1.196 | {/* min-version: 2.1.196 */}Um único pressionamento de `←` coloca em background uma sessão em primeiro plano; versões anteriores exigiam dois pressionamentos, com uma dica de rodapé e uma confirmação. `--dangerously-skip-permissions` passado para `claude agents` mostra o aviso de bypass em vez de ser silenciosamente descartado. Sessões interativas que você nunca nomeou carregam um nome padrão como `my-app-3f` em listagens de sessão e `claude agents --json`. Comandos shell em background e workflows dinâmicos sobrevivem ao processo da sessão sendo interrompido, reiniciado ou atualizado, incluindo no Windows; defina `CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF=1` para desativar a entrega. Um transcript lido mal como vazio no reinício é renomeado com um sufixo `.orphaned-` em vez de ser deletado. |736| v2.1.196 | {/* min-version: 2.1.196 */}Um único pressionamento de `←` coloca em background uma sessão em primeiro plano; versões anteriores exigiam dois pressionamentos, com uma dica de rodapé e uma confirmação. `--dangerously-skip-permissions` passado para `claude agents` mostra o aviso de bypass em vez de ser silenciosamente descartado. Sessões interativas que você nunca nomeou carregam um nome padrão como `my-app-3f` em listagens de sessão e `claude agents --json`. Comandos shell em background e workflows dinâmicos sobrevivem ao processo da sessão sendo interrompido, reiniciado ou atualizado, incluindo no Windows; defina `CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF=1` para desativar a entrega. Um transcript lido mal como vazio no reinício é renomeado com um sufixo `.orphaned-` em vez de ser deletado. |

688| v2.1.195 | {/* min-version: 2.1.195 */}O trabalho em andamento é transferido quando você coloca em background uma sessão no Windows também; defina `CLAUDE_DISABLE_ADOPT=1` para interrompê-lo em vez disso. O grupo `Completed` preenche o espaço vertical restante e o cabeçalho se compacta em terminais curtos. Uma versão mais antiga do Claude Code não descarta mais campos `state.json` mais novos ou oculta essas sessões de `claude agents`. Anexar a uma sessão parada muda imediatamente em vez de mostrar uma tela em branco por até cinco segundos. Um supervisor que não consegue aceitar conexões sai e libera seu bloqueio por conta própria. |737| v2.1.195 | {/* min-version: 2.1.195 */}O trabalho em andamento é transferido quando você coloca em background uma sessão no Windows também; defina `CLAUDE_DISABLE_ADOPT=1` para interrompê-lo em vez disso. O grupo `Completed` preenche o espaço vertical restante e o cabeçalho se compacta em terminais curtos. Uma versão mais antiga do Claude Code não descarta mais campos `state.json` mais novos ou oculta essas sessões de `claude agents`. Anexar a uma sessão parada muda imediatamente em vez de mostrar uma tela em branco por até cinco segundos. Um supervisor que não consegue aceitar conexões sai e libera seu bloqueio por conta própria. |

689| v2.1.174 | {/* min-version: 2.1.174 */}Sessões em background não herdam mais variáveis de endpoint de gateway como `ANTHROPIC_BASE_URL` do shell de inicialização do supervisor; o supervisor fornece um snapshot de credencial fresco para workers pré-aquecidos, corrigindo erros espúrios de `Could not resolve authentication method`. |738| v2.1.174 | {/* min-version: 2.1.174 */}Sessões em background não herdam mais variáveis de endpoint de gateway como `ANTHROPIC_BASE_URL` do shell de inicialização do supervisor; o supervisor fornece um snapshot de credencial fresco para workers pré-aquecidos, corrigindo erros espúrios de `Could not resolve authentication method`. |

agents.md +1 −1

Details

53O comando para verificar o trabalho em execução depende de qual abordagem você usou:53O comando para verificar o trabalho em execução depende de qual abordagem você usou:

54 54

55* Para sessões em segundo plano, `claude agents` abre [visualização de agentes](/pt/agent-view): uma tela mostrando cada sessão, seu estado e quais precisam de sua entrada.55* Para sessões em segundo plano, `claude agents` abre [visualização de agentes](/pt/agent-view): uma tela mostrando cada sessão, seu estado e quais precisam de sua entrada.

56* Para subagentes na sessão atual, `/agents` abre um painel com uma aba **Running** listando subagentes ativos e uma aba **Library** onde você [cria e edita subagentes personalizados](/pt/sub-agents#use-the-%2Fagents-command). Apesar do nome similar, isso é separado de `claude agents`.56* Para subagentes na sessão atual, subagentes em segundo plano nomeados aparecem na digitação de menção @- com seu status. {/* min-version: 2.1.198 */}A partir da v2.1.198, `/agents` não abre mais um painel; imprime um aviso apontando para os locais dos arquivos de subagentes. Para [criar e editar subagentes personalizados](/pt/sub-agents#configure-subagents), peça ao Claude ou edite os arquivos diretamente. Apesar do nome similar, `/agents` é separado de `claude agents`.

57* Para qualquer coisa em execução em segundo plano da sessão atual, `/tasks` lista cada item e permite que você verifique, se anexe ou interrompa.57* Para qualquer coisa em execução em segundo plano da sessão atual, `/tasks` lista cada item e permite que você verifique, se anexe ou interrompa.

58* Para fluxos de trabalho dinâmicos, `/workflows` lista execuções em andamento e concluídas, a fase em que cada uma está e quantos agentes terminaram.58* Para fluxos de trabalho dinâmicos, `/workflows` lista execuções em andamento e concluídas, a fase em que cada uma está e quantos agentes terminaram.

59 59

amazon-bedrock.md +1 −1

Details

184 184

185Estas duas configurações têm diferentes condições de acionamento:185Estas duas configurações têm diferentes condições de acionamento:

186 186

187* **`awsAuthRefresh`**: executa apenas quando Claude Code detecta que suas credenciais AWS expiraram, localmente com base em seu timestamp ou quando Bedrock retorna um erro de credencial, depois tenta novamente a solicitação com credenciais atualizadas.187* **`awsAuthRefresh`**: executa apenas quando Claude Code detecta que suas credenciais AWS expiraram, localmente com base em seu timestamp ou quando a API retorna um erro de credencial, depois tenta novamente a solicitação com credenciais atualizadas.

188* **`awsCredentialExport`**: executa no início da sessão e em cada recarga de credencial, mesmo quando as credenciais em sua cadeia de provedor de credenciais padrão AWS ainda são válidas. Use isso quando sua conta Bedrock requer credenciais entre contas que diferem das que a cadeia de provedor padrão resolveria.188* **`awsCredentialExport`**: executa no início da sessão e em cada recarga de credencial, mesmo quando as credenciais em sua cadeia de provedor de credenciais padrão AWS ainda são válidas. Use isso quando sua conta Bedrock requer credenciais entre contas que diferem das que a cadeia de provedor padrão resolveria.

189 189

190<h5 id="example-configuration">190<h5 id="example-configuration">

auto-mode-config.md +18 −7

Details

54 54

55Para a maioria das organizações, `autoMode.environment` é o único campo que você precisa definir. Ele diz ao classificador quais repositórios, buckets e domínios são confiáveis: o classificador o usa para decidir o que significa "externo", portanto qualquer destino não listado é um alvo potencial de exfiltração.55Para a maioria das organizações, `autoMode.environment` é o único campo que você precisa definir. Ele diz ao classificador quais repositórios, buckets e domínios são confiáveis: o classificador o usa para decidir o que significa "externo", portanto qualquer destino não listado é um alvo potencial de exfiltração.

56 56

~~57A partir do Claude Code v2.1.195, `claude auto-mode defaults` imprime dois tipos de entrada de ambiente.~~57A partir do Claude Code v2.1.198, `claude auto-mode defaults` imprime três tipos de entrada de ambiente. Versões anteriores a v2.1.195 imprimem apenas os primeiros cinco slots de confiança.

58 58

59* **Slots de contexto**: descrevem sua organização, stack e postura de segurança para que o classificador leia as outras regras em seu contexto. Ao contrário dos outros dois tipos, os slots de contexto não têm regras próprias que os direcionem. Cada um padrão para `None configured` ou para a suposição conservadora nomeada ao lado:

60 * **Organização**

61 * **Uso principal do Claude Code**: padrão para desenvolvimento de software

62 * **Provedor(es) de nuvem**

63 * **Visibilidade do repositório**: um repositório é assumido como privado a menos que seu host remoto e nome indiquem o contrário

64 * **Compartilhamento interno / hospedagem de snippet**: serviços públicos de paste e gist são tratados como fora do limite de confiança até que você nomeie um

65 * **CLIs específicas da organização**

66 * **Gerenciamento de segredos**

67 * **Branches padrão / protegidos**: `main` e `master` são tratados como protegidos até que você nomeie outros

68 * **Alvos de implantação de CI/CD**

69 * **Postura de rede**

70 * **Namespaces / ambientes de implantação protegidos**: volta para a heurística de alvos remotos sensíveis até que você nomeie eles

71 * **Retenção de dados / desclassificação**

59* **Slots de confiança**: nomeiam o que o classificador trata como dentro de seu limite. Os slots são Repositório confiável, Controle de código-fonte, Domínios internos confiáveis, Buckets de nuvem confiáveis, Serviços internos principais e Registro de pacotes interno. As entradas de repositório e controle de código-fonte padrão para o repositório de trabalho e seus remotes configurados. Todos os outros slots de confiança padrão para `None configured`, portanto nada mais é confiável até que você o adicione.72* **Slots de confiança**: nomeiam o que o classificador trata como dentro de seu limite. Os slots são Repositório confiável, Controle de código-fonte, Domínios internos confiáveis, Buckets de nuvem confiáveis, Serviços internos principais e Registro de pacotes interno. As entradas de repositório e controle de código-fonte padrão para o repositório de trabalho e seus remotes configurados. Todos os outros slots de confiança padrão para `None configured`, portanto nada mais é confiável até que você o adicione.

60* **Slots de sensibilidade**: nomeiam o que as regras de proteção tratam como alto risco. Os slots são Locais de PII / dados regulados, Alvos remotos sensíveis e Escopos de IaC protegidos. Cada um padrão para uma heurística ampla, como tratar qualquer host ou namespace cujo nome carrega `prod` ou `production` como um alvo remoto sensível, portanto as regras de proteção estão ativas antes de você configurar qualquer coisa. Nomear alvos concretos em um slot de sensibilidade faz com que essas regras se apliquem aos alvos nomeados em vez da heurística.73* **Slots de sensibilidade**: nomeiam o que as regras de proteção tratam como alto risco. Os slots são Locais de dados sensíveis e públicos, Alvos remotos sensíveis e Escopos de IaC protegidos. Cada um padrão para uma heurística ampla, como tratar qualquer host ou namespace cujo nome carrega `prod` ou `production` como um alvo remoto sensível, portanto as regras de proteção estão ativas antes de você configurar qualquer coisa. Nomear alvos concretos em um slot de sensibilidade faz com que essas regras se apliquem aos alvos nomeados em vez da heurística.

~~62Versões anteriores a v2.1.195 imprimem apenas os primeiros cinco slots de confiança.~~

63 74

64Para adicionar suas próprias entradas junto com os padrões, inclua a string literal `"$defaults"` no array. As entradas padrão são inseridas nessa posição, portanto suas entradas personalizadas podem vir antes ou depois delas.75Para adicionar suas próprias entradas junto com os padrões, inclua a string literal `"$defaults"` no array. As entradas padrão são inseridas nessa posição, portanto suas entradas personalizadas podem vir antes ou depois delas.

65 76

87* **Domínios internos confiáveis**: nomes de host para APIs, painéis e serviços dentro de sua rede, como `*.internal.example.com`98* **Domínios internos confiáveis**: nomes de host para APIs, painéis e serviços dentro de sua rede, como `*.internal.example.com`

88* **Serviços internos principais**: CI, registros de artefatos, índices de pacotes internos, ferramentas de incidentes99* **Serviços internos principais**: CI, registros de artefatos, índices de pacotes internos, ferramentas de incidentes

89* **Registro de pacotes interno**: o registro npm, PyPI ou outro privado através do qual as instalações devem ser roteadas, portanto as instalações que o contornam para um registro público são bloqueadas100* **Registro de pacotes interno**: o registro npm, PyPI ou outro privado através do qual as instalações devem ser roteadas, portanto as instalações que o contornam para um registro público são bloqueadas

90* **Locais de PII / dados regulados**: os buckets, bancos de dados ou caminhos que contêm dados pessoais ou regulados, para que o classificador proteja esses locais em vez de adivinhar pelo conteúdo101* **Locais de dados sensíveis e públicos**: os buckets, bancos de dados ou caminhos que contêm dados pessoais, dados comerciais confidenciais, credenciais, dados regulados ou material similarmente sensível, e os públicos com os quais os dados em cada local podem ser compartilhados, para que o classificador proteja esses locais em vez de adivinhar pelo conteúdo. {/* min-version: 2.1.195 */}{/* max-version: 2.1.197 */}Claude Code v2.1.195 através de v2.1.197 nomeiam esta entrada Locais de PII / dados regulados e cobrem apenas locais que contêm dados pessoais ou regulados, sem a dimensão de público

91* **Alvos remotos sensíveis**: os namespaces, hosts ou contêineres que contam como produção, portanto shells remotos e port-forwards para eles precisam de sua aprovação explícita102* **Alvos remotos sensíveis**: os namespaces, hosts ou contêineres que contam como produção, portanto shells remotos e port-forwards para eles precisam de sua aprovação explícita

92* **Escopos de IaC protegidos**: os recursos de infraestrutura cuja aplicação ou destruição sempre devem exigir que você nomeie a mudança103* **Escopos de IaC protegidos**: os recursos de infraestrutura cuja aplicação ou destruição sempre devem exigir que você nomeie a mudança

93* **Contexto adicional**: restrições de indústria regulada, infraestrutura multi-tenant ou requisitos de conformidade que afetam o que o classificador deve tratar como arriscado104* **Contexto adicional**: restrições de indústria regulada, infraestrutura multi-tenant ou requisitos de conformidade que afetam o que o classificador deve tratar como arriscado

94 105

95As entradas Registro de pacotes interno, Locais de PII / dados regulados, Alvos remotos sensíveis e Escopos de IaC protegidos exigem Claude Code v2.1.195 ou posterior. Versões anteriores ainda as leem como contexto simples, mas não têm as regras integradas que as direcionam.106As entradas Registro de pacotes interno, Locais de dados sensíveis e públicos, Alvos remotos sensíveis e Escopos de IaC protegidos exigem Claude Code v2.1.195 ou posterior. Versões anteriores ainda as leem como contexto simples, mas não têm as regras integradas que as direcionam.

96 107

97Um modelo inicial útil: preencha os campos entre colchetes e remova as linhas que não se aplicam.108Um modelo inicial útil: preencha os campos entre colchetes e remova as linhas que não se aplicam.

98 109

chrome.md +15 −2

Details

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.3> Use this file to discover all available pages before exploring further.

4 4

~~5# Use Claude Code with Chrome (beta)~~5# Use Claude Code with Chrome

6 6

7> Conecte Claude Code ao seu navegador Chrome para testar aplicativos web, depurar com logs de console, automatizar preenchimento de formulários e extrair dados de páginas web.7> Conecte Claude Code ao seu navegador Chrome para testar aplicativos web, depurar com logs de console, automatizar preenchimento de formulários e extrair dados de páginas web.

8 8

11Claude abre novas abas para tarefas do navegador e compartilha o estado de login do seu navegador, para que possa acessar qualquer site em que você já esteja conectado. As ações do navegador são executadas em uma janela Chrome visível em tempo real. Quando Claude encontra uma página de login ou CAPTCHA, ele pausa e pede que você a manipule manualmente.11Claude abre novas abas para tarefas do navegador e compartilha o estado de login do seu navegador, para que possa acessar qualquer site em que você já esteja conectado. As ações do navegador são executadas em uma janela Chrome visível em tempo real. Quando Claude encontra uma página de login ou CAPTCHA, ele pausa e pede que você a manipule manualmente.

12 12

13<Note>13<Note>

14 A integração com Chrome está em beta e atualmente funciona com Google Chrome e Microsoft Edge. Ainda não é suportada em Brave, Arc ou outros navegadores baseados em Chromium. WSL (Windows Subsystem for Linux) também não é suportado.14 A integração com Chrome funciona com Google Chrome e Microsoft Edge. Ainda não é suportada em Brave, Arc ou outros navegadores baseados em Chromium. Também não é suportada no Windows Subsystem for Linux (WSL).

15</Note>15</Note>

16 16

17<h2 id="capabilities">17<h2 id="capabilities">

90 90

91As permissões no nível do site são herdadas da extensão Chrome. Gerencie permissões nas configurações da extensão Chrome para controlar quais sites Claude pode navegar, clicar e digitar.91As permissões no nível do site são herdadas da extensão Chrome. Gerencie permissões nas configurações da extensão Chrome para controlar quais sites Claude pode navegar, clicar e digitar.

92 92

93<h3 id="browser-tools-in-plan-mode">

94 Ferramentas do navegador no modo de plano

95</h3>

97No [modo de plano](/pt/permission-modes#analyze-before-you-edit-with-plan-mode), as chamadas de ferramentas do navegador que apenas leem a página ou o estado do navegador são executadas sem um prompt de permissão, e as chamadas que alteram o estado solicitam aprovação.

99* **Chamadas somente leitura**: `read_page`, `get_page_text`, `find`, leitura de mensagens do console ou solicitações de rede, e captura de tela

100* **Chamadas que alteram o estado**: cliques, digitação, navegação, gerenciamento de abas e janelas, e gravação de um GIF

101

102A partir da v2.1.199, uma chamada que de outra forma seria somente leitura que define um sinalizador de entrada que altera o estado, como `createIfEmpty` em `tabs_context_mcp`, `clear` nos leitores de console e rede, ou `save_to_disk` em uma captura de tela, também solicita aprovação. Uma chamada `browser_batch` é executada sem um prompt apenas quando cada ação dentro dela é somente leitura.

103

93<h2 id="example-workflows">104<h2 id="example-workflows">

94 Fluxos de trabalho de exemplo105 Fluxos de trabalho de exemplo

95</h2>106</h2>

208 219

209Na primeira vez que você ativa a integração com Chrome, Claude Code instala um arquivo de configuração do host de mensagens nativas. Chrome lê este arquivo na inicialização, portanto, se a extensão não for detectada na sua primeira tentativa, reinicie Chrome para pegar a nova configuração.220Na primeira vez que você ativa a integração com Chrome, Claude Code instala um arquivo de configuração do host de mensagens nativas. Chrome lê este arquivo na inicialização, portanto, se a extensão não for detectada na sua primeira tentativa, reinicie Chrome para pegar a nova configuração.

210 221

222A partir da v2.1.199, Claude Code abre uma aba do navegador solicitando que você conecte a extensão apenas nessa primeira instalação. Sessões posteriores que reescrevem o arquivo de configuração, por exemplo após alternar entre compilações de Claude Code ou diretórios de configuração, não a reabrem.

223

211Se a conexão ainda falhar, verifique se o arquivo de configuração do host existe em:224Se a conexão ainda falhar, verifique se o arquivo de configuração do host existe em:

212 225

213Para Chrome:226Para Chrome:

claude-apps-gateway-config.md +63 −8

Details

4 4

5# Configuração do gateway de aplicativos Claude5# Configuração do gateway de aplicativos Claude

6 6

7> Referência para cada opção de gateway.yaml: listener e TLS, OIDC, sessão, armazenamento Postgres, upstreams Bedrock/Agent Platform/Foundry, roteamento de modelos, políticas gerenciadas e telemetria.7> Referência para cada opção de gateway.yaml: listener e TLS, OIDC, sessão, armazenamento Postgres, upstreams Bedrock/Claude Platform on AWS/Agent Platform/Foundry, roteamento de modelos, políticas gerenciadas e telemetria.

8 8

9Uma implantação de gateway de aplicativos Claude é configurada por um arquivo YAML, convencionalmente `gateway.yaml`. O arquivo define tudo o que o gateway faz: onde ele escuta, como os desenvolvedores fazem login, para onde a inferência vai e quais políticas e telemetria se aplicam. Esta página é a referência para cada opção nesse arquivo. Para escrever o seu primeiro, comece pelo [quickstart](/pt/claude-apps-gateway#quickstart), que constrói uma configuração mínima funcional e a executa; uma vez que você tenha uma configuração com a qual esteja satisfeito, o [guia de implantação](/pt/claude-apps-gateway-deploy) cobre a containerização e hospedagem no Kubernetes, Cloud Run ou sua própria plataforma.9Uma implantação de gateway de aplicativos Claude é configurada por um arquivo YAML, convencionalmente `gateway.yaml`. O arquivo define tudo o que o gateway faz: onde ele escuta, como os desenvolvedores fazem login, para onde a inferência vai e quais políticas e telemetria se aplicam. Esta página é a referência para cada opção nesse arquivo.

11Para escrever o seu primeiro, comece pelo [quickstart](/pt/claude-apps-gateway#quickstart), que constrói uma configuração mínima funcional e a executa. Uma vez que você tenha uma configuração com a qual esteja satisfeito, o [guia de implantação](/pt/claude-apps-gateway-deploy) cobre a containerização e hospedagem no Kubernetes, Cloud Run ou sua própria plataforma.

10 12

11O gateway lê o arquivo uma vez, na inicialização, com `claude gateway --config /path/to/gateway.yaml`. Cada opção é validada contra um esquema na inicialização, portanto uma configuração malformada falha no início com um erro no nível do campo em vez de no primeiro uso.13O gateway lê o arquivo uma vez, na inicialização, com `claude gateway --config /path/to/gateway.yaml`. Cada opção é validada contra um esquema na inicialização, portanto uma configuração malformada falha no início com um erro no nível do campo em vez de no primeiro uso.

12 14

24* [`oidc`](#oidc): seu provedor de identidade (IdP), incluindo emissor, cliente, mapeamento de declarações e quem pode fazer login26* [`oidc`](#oidc): seu provedor de identidade (IdP), incluindo emissor, cliente, mapeamento de declarações e quem pode fazer login

25* [`session`](#session): os tokens de portador que o gateway emite, com segredo e tempo de vida27* [`session`](#session): os tokens de portador que o gateway emite, com segredo e tempo de vida

26* [`store`](#store): PostgreSQL, para concessões de dispositivo e contadores de limite de taxa28* [`store`](#store): PostgreSQL, para concessões de dispositivo e contadores de limite de taxa

~~27* [`upstreams`](#upstreams): para onde a inferência vai, seja Anthropic, Bedrock, Agent Platform ou Foundry~~29* [`upstreams`](#upstreams): para onde a inferência vai, seja Anthropic, Bedrock, Claude Platform na AWS, Agent Platform ou Foundry

28 30

29**Seções opcionais:**31**Seções opcionais:**

30 32

68 `oidc`70 `oidc`

69</h3>71</h3>

70 72

71OpenID Connect (OIDC) é o protocolo SSO que o gateway usa com seu provedor de identidade; consulte [Configuração do provedor de identidade](/pt/claude-apps-gateway-deploy#identity-provider-setup) para saber o que registrar no lado do IdP. O bloco `oidc` conecta o gateway ao seu provedor de identidade e decide quem pode fazer login. Ele nomeia o emissor e cliente OAuth, mapeia as declarações que carregam email e grupos e restringe o login por domínio de email ou grupo.73O bloco `oidc` conecta o gateway ao seu provedor de identidade e decide quem pode fazer login. Ele nomeia o emissor e cliente OAuth, mapeia as declarações que carregam email e grupos e restringe o login por domínio de email ou grupo.

75OpenID Connect (OIDC) é o protocolo SSO que o gateway usa com seu provedor de identidade; consulte [Configuração do provedor de identidade](/pt/claude-apps-gateway-deploy#identity-provider-setup) para saber o que registrar no lado do IdP.

72 76

74| ------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |78| ------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

121 `upstreams`125 `upstreams`

122</h3>126</h3>

123 127

124`upstreams` é uma lista ordenada. O gateway encaminha inferência para o primeiro upstream que resolve o modelo solicitado. Em `5xx`, `429` ou timeout, ele falha para o próximo; outro `4xx` não, porque esses erros são atribuíveis à solicitação em vez do upstream. Múltiplos upstreams do mesmo provedor devem definir um `name:` distinto.128`upstreams` é uma lista ordenada. O gateway encaminha inferência para o primeiro upstream que resolve o modelo solicitado. Em `5xx`, `429`, `401`, `403`, `404` ou timeout, ele falha para o próximo; outro `4xx` não, porque esses erros são atribuíveis à solicitação em vez do upstream. Um `401` ou `403` significa que a credencial do próprio gateway falhou contra esse upstream, e um `404` significa que esse upstream não serve o modelo solicitado, portanto um upstream posterior na lista ainda pode.

129

130Failover em `404` requer gateway v2.1.198 ou posterior. Versões anteriores retornavam o primeiro `404` ao cliente mesmo quando um upstream posterior na lista servia o modelo.

125 131

126Clientes Bedrock, Agent Platform e Foundry são construídos uma vez na inicialização, e seus SDKs atualizam credenciais internamente, portanto girar credenciais de nuvem não requer reinicialização. Chaves de API Anthropic estáticas e portadores são lidos na inicialização; consulte [Anthropic API](#anthropic-api).132Múltiplos upstreams do mesmo provedor devem definir um `name:` distinto.

133

134Clientes Bedrock, Claude Platform on AWS, Agent Platform e Foundry são construídos uma vez na inicialização, e seus SDKs atualizam credenciais internamente, portanto girar credenciais de nuvem não requer reinicialização. Chaves de API Anthropic estáticas e portadores são lidos na inicialização; consulte [Anthropic API](#anthropic-api).

127 135

128<h4 id="anthropic-api">136<h4 id="anthropic-api">

129 Anthropic API137 Anthropic API

193| Em qualquer outro lugar | Passe credenciais através das variáveis env `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` e `AWS_SESSION_TOKEN`, ou defina-as explicitamente em `auth:` com expansão `${VAR}` |201| Em qualquer outro lugar | Passe credenciais através das variáveis env `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` e `AWS_SESSION_TOKEN`, ou defina-as explicitamente em `auth:` com expansão `${VAR}` |

194| Região | `region:` é a região do endpoint da API. Perfis de inferência entre regiões roteiam através da geo (US, EU, APAC) independentemente de qual você escolher. Para regiões fora dos EUA ou ARNs de throughput provisionado, adicione um bloco [`models:`](#models) com os IDs corretos por upstream. |202| Região | `region:` é a região do endpoint da API. Perfis de inferência entre regiões roteiam através da geo (US, EU, APAC) independentemente de qual você escolher. Para regiões fora dos EUA ou ARNs de throughput provisionado, adicione um bloco [`models:`](#models) com os IDs corretos por upstream. |

195 203

204<h4 id="claude-platform-on-aws">

205 Claude Platform on AWS

206</h4>

207

208Claude Platform on AWS serve a primeira API Anthropic em infraestrutura AWS em `aws-external-anthropic.<region>.api.aws`. Usa IDs de modelo de primeira parte, honra cabeçalhos `anthropic-beta` conforme enviados e serve `count_tokens`, portanto nenhuma tradução específica do Bedrock se aplica. O provedor `anthropicAws` requer Claude Code v2.1.198 ou posterior; versões anteriores do gateway o rejeitam na inicialização.

209

210Para a implantação do lado do cliente da mesma plataforma, consulte [Claude Code on Claude Platform on AWS](/pt/claude-platform-on-aws). O upstream do lado do gateway:

211

212```yaml theme={null}

213upstreams:

214 - provider: anthropicAws

215 region: us-east-1

216 workspace_id: wrkspc_...

217 auth:

218 api_key: ${ANTHROPIC_AWS_API_KEY} # enviado como x-api-key

219 # OU SigV4 através da cadeia de credencial padrão AWS:

220 # auth: {}

221 # OU credenciais SigV4 explícitas:

222 # auth:

223 # aws_access_key_id: ${AWS_ACCESS_KEY_ID}

224 # aws_secret_access_key: ${AWS_SECRET_ACCESS_KEY}

225 # Substitua o endpoint derivado:

226 # base_url: https://aws-external-anthropic.us-east-1.api.aws

227```

228

229A plataforma é executada em uma conta AWS separada do Amazon Bedrock e assina solicitações SigV4 para seu próprio nome de serviço, `aws-external-anthropic`, portanto uma função IAM com escopo Bedrock não a autoriza. Uma chave de API em `auth.api_key` tem precedência quando credenciais SigV4 também estão definidas. Um bloco `auth` vazio usa a cadeia de credencial padrão do AWS SDK, a mesma cadeia que o upstream [Amazon Bedrock](#amazon-bedrock) usa.

230

231| Campo | Obrigatório | Descrição |

232| ------------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |

233| `region` | Sim | Região AWS, letras minúsculas, dígitos e hífens. O gateway deriva o endpoint a partir dela como `https://aws-external-anthropic.<region>.api.aws`. |

234| `workspace_id` | Sim | Enviado como um cabeçalho em cada solicitação; a plataforma o requer |

235| `auth.api_key` | Não | Chave de API para a plataforma, enviada como `x-api-key`. Não é um token de portador: os dois modos de autenticação são uma chave de API ou SigV4. |

236| `auth.aws_access_key_id` / `auth.aws_secret_access_key` | Não | Credenciais SigV4 explícitas. Definir um sem o outro falha na inicialização. `auth.aws_session_token` é aceito junto com eles. |

237| `base_url` | Não | Substitua o endpoint derivado |

238

239Como a plataforma resolve IDs de modelo de primeira parte, o catálogo integrado roteia para ela sem um bloco [`models:`](#models). Quando você cura uma lista `models:`, chave a entrada `anthropicAws:` com o ID de primeira parte.

240

196<h4 id="google-cloud-agent-platform">241<h4 id="google-cloud-agent-platform">

197 Google Cloud Agent Platform242 Google Cloud Agent Platform

198</h4>243</h4>

255 300

256O mesmo provedor pode aparecer mais de uma vez com um `name:` distinto. Isso cobre diferentes regiões, diferentes contas através de diferentes cadeias de credencial, throughput provisionado versus sob demanda e fallback entre provedores.301O mesmo provedor pode aparecer mais de uma vez com um `name:` distinto. Isso cobre diferentes regiões, diferentes contas através de diferentes cadeias de credencial, throughput provisionado versus sob demanda e fallback entre provedores.

257 302

258O gateway tenta upstreams em ordem. `5xx`, `429`, timeouts e endpoint ausente (`501`) falham; outro `4xx` não. `429` é capacidade por upstream, portanto esgotamento de throughput provisionado (PT) falha para sob demanda. Um upstream que não pode resolver o modelo solicitado é pulado sem uma viagem de rede.303O gateway tenta upstreams em ordem. `5xx`, `429`, `401`, `403`, `404`, timeouts e endpoint ausente (`501`) falham; outro `4xx` não.

304

305`429` é capacidade por upstream, portanto esgotamento de throughput provisionado (PT) falha para sob demanda. `404` é disponibilidade de modelo por upstream, portanto um upstream que não habilitou um modelo não bloqueia um upstream posterior que o serve. Um upstream que não pode resolver o modelo solicitado é pulado sem uma viagem de rede.

259 306

260Este exemplo roteia uma alocação de throughput provisionado Bedrock primeiro, transborda para sob demanda e uma segunda conta, e volta para a API Anthropic por último:307Este exemplo roteia uma alocação de throughput provisionado Bedrock primeiro, transborda para sob demanda e uma segunda conta, e volta para a API Anthropic por último:

261 308

513* `sandbox.network.allowManagedDomainsOnly` e `sandbox.filesystem.allowManagedReadPathsOnly`: quando bloqueadas, as listas de permissão correspondentes são unidas entre fontes560* `sandbox.network.allowManagedDomainsOnly` e `sandbox.filesystem.allowManagedReadPathsOnly`: quando bloqueadas, as listas de permissão correspondentes são unidas entre fontes

514* [`allowAllClaudeAiMcps`](/pt/settings#available-settings): substituição de permissão apenas para a lista de permissão do servidor MCP claude.ai561* [`allowAllClaudeAiMcps`](/pt/settings#available-settings): substituição de permissão apenas para a lista de permissão do servidor MCP claude.ai

515* `sandbox.bwrapPath` e `sandbox.socatPath`: caminhos do sistema de arquivos para os binários auxiliares [sandbox](/pt/sandboxing)562* `sandbox.bwrapPath` e `sandbox.socatPath`: caminhos do sistema de arquivos para os binários auxiliares [sandbox](/pt/sandboxing)

563* [`forceRemoteSettingsRefresh`](/pt/server-managed-settings): bloqueia a inicialização até que as configurações gerenciadas remotas sejam buscadas recentemente, portanto uma política MDM ou arquivo que a define é honrada mesmo quando um payload remoto em cache que carece da chave é a fonte de maior prioridade

516 564

517`allowManagedPermissionRulesOnly` e `disableBypassPermissionsMode` não são entre fontes, portanto apenas o valor da fonte vencedora se aplica.565`allowManagedPermissionRulesOnly` e `disableBypassPermissionsMode` não são entre fontes, portanto apenas o valor da fonte vencedora se aplica.

518 566

580| `limits` | `max_request_bytes` | 32 MiB | Corpo de solicitação de entrada máximo; solicitações de tamanho excessivo obtêm `413` antes do corpo ser armazenado em buffer. Aumente para solicitações de arquivo ou imagem grandes. |628| `limits` | `max_request_bytes` | 32 MiB | Corpo de solicitação de entrada máximo; solicitações de tamanho excessivo obtêm `413` antes do corpo ser armazenado em buffer. Aumente para solicitações de arquivo ou imagem grandes. |

583| `timeouts` | `upstream_ttfb_ms` | 120000 | Espera máxima pelos cabeçalhos de resposta do upstream (tempo até o primeiro byte). O corpo da resposta então flui sem limite de relógio de parede. Aplica-se ao caminho upstream Anthropic direto; Bedrock, Agent Platform e Foundry são limitados pelo próprio timeout do SDK do provedor. |631| `timeouts` | `upstream_ttfb_ms` | 120000 | Espera máxima pelos cabeçalhos de resposta do upstream (tempo até o primeiro byte). O corpo da resposta então flui sem limite de relógio de parede. Aplica-se ao caminho upstream Anthropic direto; cada outro provedor é limitado pelo próprio timeout do SDK do provedor. |

584| `rate_limits` | `device_authorization.max` / `.window_seconds` | 30 / 600 | Limite de taxa por IP no endpoint de autorização de dispositivo não autenticado. Aumente para uma grande organização atrás de um IP de saída compartilhado ou NAT. Esses limites se aplicam apenas ao fluxo de concessão de dispositivo de login, não a `/v1/messages` inferência. Consulte [Resistência de força bruta de código de usuário](/pt/claude-apps-gateway-deploy#user-code-brute-force-resistance). |632| `rate_limits` | `device_authorization.max` / `.window_seconds` | 30 / 600 | Limite de taxa por IP no endpoint de autorização de dispositivo não autenticado. Aumente para uma grande organização atrás de um IP de saída compartilhado ou NAT. Esses limites se aplicam apenas ao fluxo de concessão de dispositivo de login, não a `/v1/messages` inferência. Consulte [Resistência de força bruta de código de usuário](/pt/claude-apps-gateway-deploy#user-code-brute-force-resistance). |

586 634

662 # region: us-east-1710 # region: us-east-1

663 # auth: {}711 # auth: {}

664 712

713 # - provider: anthropicAws

714 # region: us-east-1

715 # workspace_id: wrkspc_...

716 # auth:

717 # api_key: ${ANTHROPIC_AWS_API_KEY}

718

665 # - provider: vertex719 # - provider: vertex

666 # region: us-east5720 # region: us-east5

667 # project_id: example-prod721 # project_id: example-prod

678 upstream_model:732 upstream_model:

679 anthropic: claude-opus-4-8733 anthropic: claude-opus-4-8

680 # bedrock: us.anthropic.claude-opus-4-8734 # bedrock: us.anthropic.claude-opus-4-8

735 # anthropicAws: claude-opus-4-8

681 # vertex: claude-opus-4-8736 # vertex: claude-opus-4-8

682 # foundry: <your-opus-deployment-name>737 # foundry: <your-opus-deployment-name>

683 - id: claude-sonnet-4-6738 - id: claude-sonnet-4-6

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

Details

97<Note>97<Note>

98 **Identidade de carga de trabalho**98 **Identidade de carga de trabalho**

99 99

100 Prefira a identidade de carga de trabalho da plataforma em relação a chaves estáticas: IRSA no EKS para Bedrock, Workload Identity no GKE para Agent Platform e identidade de carga de trabalho no AKS para Foundry. Defina `auth: {}` no bloco upstream, ou `use_azure_ad: true` para Foundry, e o gateway pega a identidade do pod através da cadeia de credencial padrão desse provedor. Para um emparelhamento entre nuvens, como um upstream Bedrock no GKE, defina credenciais explícitas no bloco `auth` do upstream. A [referência `upstreams`](/pt/claude-apps-gateway-config#upstreams) tem detalhes de configuração por plataforma.100 Prefira a identidade de carga de trabalho da plataforma em relação a chaves estáticas: IRSA no EKS para Bedrock e para Claude Platform na AWS, Workload Identity no GKE para Agent Platform e identidade de carga de trabalho no AKS para Foundry. Defina `auth: {}` no bloco upstream, ou `use_azure_ad: true` para Foundry, e o gateway pega a identidade do pod através da cadeia de credencial padrão desse provedor. Para um emparelhamento entre nuvens, como um upstream Bedrock no GKE, defina credenciais explícitas no bloco `auth` do upstream. A [referência `upstreams`](/pt/claude-apps-gateway-config#upstreams) tem detalhes de configuração por plataforma.

101</Note>101</Note>

102 102

103<h3 id="cloud-run">103<h3 id="cloud-run">

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

Details

723Teleport verifica esses requisitos antes de retomar uma sessão. Se algum requisito não for atendido, você verá um erro ou será solicitado a resolver o problema.723Teleport verifica esses requisitos antes de retomar uma sessão. Se algum requisito não for atendido, você verá um erro ou será solicitado a resolver o problema.

724 724

725| Requisito | Detalhes |725| Requisito | Detalhes |

726| ------------------- | --------------------------------------------------------------------------------------------------------------------------------- |726| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

727| Estado git limpo | Seu diretório de trabalho não deve ter alterações não confirmadas. Teleport solicita que você guarde as alterações se necessário. |727| Estado git limpo | Seu diretório de trabalho não deve ter alterações não confirmadas. Teleport solicita que você guarde as alterações se necessário. |

728| Repositório correto | Você deve executar `--teleport` a partir de um checkout do mesmo repositório, não de um fork. |728| Repositório correto | Você deve executar `--teleport` a partir de um checkout do mesmo repositório, não de um fork. A partir da v2.1.199, Claude Code aceita um checkout mesmo quando não consegue analisar o remoto em um nome de host, como um alias de host SSH como `git@work:owner/repo.git` ou uma forma abreviada reescrita por `insteadOf`. Ele mostra um prompt de confirmação primeiro, e apenas quando o proprietário do remoto e o nome do repositório correspondem ao repositório da sessão. |

729| Branch disponível | A branch da sessão em nuvem deve ter sido enviada para o remoto. Teleport busca e faz checkout automaticamente. |729| Branch disponível | A branch da sessão em nuvem deve ter sido enviada para o remoto. Teleport busca e faz checkout automaticamente. |

730| Mesma conta | Você deve estar autenticado na mesma conta claude.ai usada na sessão em nuvem. |730| Mesma conta | Você deve estar autenticado na mesma conta claude.ai usada na sessão em nuvem. |

731 731

claude-platform-on-aws.md +1 −1

Details

230 230

231Para CI e automação, dê ao executor uma função IAM com permissão para invocar o serviço Anthropic e defina `AWS_REGION`. A cadeia de credenciais pega a função automaticamente.231Para CI e automação, dê ao executor uma função IAM com permissão para invocar o serviço Anthropic e defina `AWS_REGION`. A cadeia de credenciais pega a função automaticamente.

232 232

233Se suas credenciais SSO expirarem durante a sessão, configure [`awsAuthRefresh`](/pt/amazon-bedrock#advanced-credential-configuration) para que Claude Code execute novamente seu comando de login e tente novamente em vez de falhar. Adicione o comando ao seu `settings.json`:233Se suas credenciais SSO expirarem durante a sessão, configure [`awsAuthRefresh`](/pt/amazon-bedrock#advanced-credential-configuration) para que Claude Code execute novamente seu comando de login e tente novamente em vez de falhar. A atualização automática no Claude Platform on AWS requer Claude Code v2.1.198 ou posterior; versões anteriores param com um prompt para executar `/login`, que não pode atualizar credenciais AWS. Adicione o comando ao seu `settings.json`:

234 234

235```json theme={null}235```json theme={null}

236{236{

cli-reference.md +4 −2

Details

47 47

48Se você digitar incorretamente um subcomando, Claude Code sugere a correspondência mais próxima e sai sem iniciar uma sessão. Por exemplo, `claude udpate` imprime `Did you mean claude update?`.48Se você digitar incorretamente um subcomando, Claude Code sugere a correspondência mais próxima e sai sem iniciar uma sessão. Por exemplo, `claude udpate` imprime `Did you mean claude update?`.

49 49

50{/* min-version: 2.1.199 */}A partir da v2.1.199, `claude --dangerously-skip-permissions daemon <subcommand>` executa o subcomando `daemon`. Versões anteriores tratavam `daemon <subcommand>` como o prompt para uma nova sessão interativa, então o subcomando nunca era executado quando a flag vinha primeiro, uma configuração comum quando `claude` é aliasado para incluir a flag. Apenas um `--dangerously-skip-permissions` ou `--allow-dangerously-skip-permissions` à frente roteia para `daemon` desta forma; qualquer outra flag à frente ainda inicia uma sessão interativa.

50<h2 id="cli-flags">52<h2 id="cli-flags">

51 Sinalizadores CLI53 Sinalizadores CLI

52</h2>54</h2>

66| `--ax-screen-reader` | {/* min-version: 2.1.181 */}Renderizar saída amigável ao leitor de tela: texto simples sem bordas decorativas ou animações. Força o renderizador clássico, portanto a configuração [`tui`](/pt/settings#available-settings) não tem efeito para a sessão. Tem precedência sobre [`CLAUDE_AX_SCREEN_READER`](/pt/env-vars) e a configuração [`axScreenReader`](/pt/settings#available-settings). Requer Claude Code v2.1.181 ou posterior | `claude --ax-screen-reader` |68| `--ax-screen-reader` | {/* min-version: 2.1.181 */}Renderizar saída amigável ao leitor de tela: texto simples sem bordas decorativas ou animações. Força o renderizador clássico, portanto a configuração [`tui`](/pt/settings#available-settings) não tem efeito para a sessão. Tem precedência sobre [`CLAUDE_AX_SCREEN_READER`](/pt/env-vars) e a configuração [`axScreenReader`](/pt/settings#available-settings). Requer Claude Code v2.1.181 ou posterior | `claude --ax-screen-reader` |

67| `--bare` | Modo mínimo: pular auto-descoberta de hooks, skills, plugins, servidores MCP, memória automática e CLAUDE.md para que chamadas com script iniciem mais rapidamente. Claude tem acesso a ferramentas Bash, leitura de arquivo e edição de arquivo. Define [`CLAUDE_CODE_SIMPLE`](/pt/env-vars). Veja [modo bare](/pt/headless#start-faster-with-bare-mode) | `claude --bare -p "query"` |69| `--bare` | Modo mínimo: pular auto-descoberta de hooks, skills, plugins, servidores MCP, memória automática e CLAUDE.md para que chamadas com script iniciem mais rapidamente. Claude tem acesso a ferramentas Bash, leitura de arquivo e edição de arquivo. Define [`CLAUDE_CODE_SIMPLE`](/pt/env-vars). Veja [modo bare](/pt/headless#start-faster-with-bare-mode) | `claude --bare -p "query"` |

69| `--bg`, `--background` | Iniciar a sessão como um [agente de fundo](/pt/agent-view) e retornar imediatamente. Imprime o ID da sessão e comandos de gerenciamento. Combine com `--exec` para executar um comando shell como um trabalho de fundo em vez de uma sessão Claude, ou com `--agent` para executar um subagent específico | `claude --bg "investigate the flaky test"` |71| `--bg`, `--background` | Iniciar a sessão como um [agente de fundo](/pt/agent-view) e retornar imediatamente. Imprime o ID da sessão e comandos de gerenciamento. Combine com `--exec` para executar um comando shell como um trabalho de fundo em vez de uma sessão Claude, ou com `--agent` para executar um subagent específico. {/* min-version: 2.1.198 */}Não pode ser combinado com `-p`/`--print`; veja a [referência de erro](/pt/errors#command-line-errors) | `claude --bg "investigate the flaky test"` |

70| `--channels` | (Visualização de pesquisa) Servidores MCP cujas notificações de [channel](/pt/channels) Claude deve ouvir nesta sessão. Lista separada por espaço de entradas `plugin:<name>@<marketplace>`. Requer autenticação Claude.ai | `claude --channels plugin:my-notifier@my-marketplace` |72| `--channels` | (Visualização de pesquisa) Servidores MCP cujas notificações de [channel](/pt/channels) Claude deve ouvir nesta sessão. Lista separada por espaço de entradas `plugin:<name>@<marketplace>`. Requer autenticação Claude.ai | `claude --channels plugin:my-notifier@my-marketplace` |

100| `--no-session-persistence` | Desativar persistência de sessão para que as sessões não sejam salvas em disco e não possam ser retomadas. Apenas modo print. A variável de ambiente [`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](/pt/env-vars) faz o mesmo em qualquer modo | `claude -p --no-session-persistence "query"` |102| `--no-session-persistence` | Desativar persistência de sessão para que as sessões não sejam salvas em disco e não possam ser retomadas. Apenas modo print. A variável de ambiente [`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](/pt/env-vars) faz o mesmo em qualquer modo | `claude -p --no-session-persistence "query"` |

102| `--permission-mode` | Começar em um [modo de permissão](/pt/permission-modes) especificado. Aceita `default`, `acceptEdits`, `plan`, `auto`, `dontAsk` ou `bypassPermissions`. Substitui `defaultMode` dos arquivos de configuração | `claude --permission-mode plan` |104| `--permission-mode` | Começar em um [modo de permissão](/pt/permission-modes) especificado. Aceita `default`, `acceptEdits`, `plan`, `auto`, `dontAsk` ou `bypassPermissions`. Substitui `defaultMode` dos arquivos de configuração | `claude --permission-mode plan` |

103| `--permission-prompt-tool` | Especificar uma ferramenta MCP para lidar com prompts de permissão em modo não interativo | `claude -p --permission-prompt-tool mcp_auth_tool "query"` |105| `--permission-prompt-tool` | Especificar uma ferramenta MCP para lidar com prompts de permissão em modo não interativo. {/* min-version: 2.1.199 */}A partir de v2.1.199, a ferramenta de prompt não pode aprovar uma ferramenta MCP marcada como [exigindo interação do usuário](/pt/mcp#require-approval-for-a-specific-tool): um resultado `allow` para uma é convertido em uma negação | `claude -p --permission-prompt-tool mcp_auth_tool "query"` |

104| `--plugin-dir` | Carregar um plugin de um diretório ou arquivo `.zip` apenas para esta sessão. Cada sinalizador leva um caminho. Repita o sinalizador para vários plugins: `--plugin-dir A --plugin-dir B.zip` | `claude --plugin-dir ./my-plugin` |106| `--plugin-dir` | Carregar um plugin de um diretório ou arquivo `.zip` apenas para esta sessão. Cada sinalizador leva um caminho. Repita o sinalizador para vários plugins: `--plugin-dir A --plugin-dir B.zip` | `claude --plugin-dir ./my-plugin` |

105| `--plugin-url` | Buscar um arquivo `.zip` de plugin de uma URL apenas para esta sessão. Repita o sinalizador para vários plugins, ou passe URLs separadas por espaço em um único valor entre aspas | `claude --plugin-url https://example.com/plugin.zip` |107| `--plugin-url` | Buscar um arquivo `.zip` de plugin de uma URL apenas para esta sessão. Repita o sinalizador para vários plugins, ou passe URLs separadas por espaço em um único valor entre aspas | `claude --plugin-url https://example.com/plugin.zip` |

106| `--print`, `-p` | Imprimir resposta sem modo interativo (veja [documentação do Agent SDK](/pt/agent-sdk/overview) para detalhes de uso programático) | `claude -p "query"` |108| `--print`, `-p` | Imprimir resposta sem modo interativo (veja [documentação do Agent SDK](/pt/agent-sdk/overview) para detalhes de uso programático) | `claude -p "query"` |

commands.md +11 −10

Details

10 10

11Digite `/` para ver todos os comandos disponíveis para você, ou digite `/` seguido de letras para filtrar.11Digite `/` para ver todos os comandos disponíveis para você, ou digite `/` seguido de letras para filtrar.

12 12

~~13Um comando é reconhecido apenas no início da sua mensagem. O texto que segue o nome do comando é passado para ele como argumentos.~~13Um comando é reconhecido apenas no início da sua mensagem. O texto que segue o nome do comando é passado para ele como argumentos. {/* min-version: 2.1.199 */}A partir da v2.1.199, [skills](/pt/skills#pass-arguments-to-skills) são a exceção: uma invocação de skill seguida por mais skills, como `/skill-a /skill-b do XYZ`, carrega cada skill nomeada no início e passa o texto final para cada uma como argumentos. Até seis skills podem ser encadeadas.

14 14

15<h2 id="commands-across-a-typical-workflow">15<h2 id="commands-across-a-typical-workflow">

16 Comandos em um fluxo de trabalho típico16 Comandos em um fluxo de trabalho típico

18 18

19A maioria dos comandos é útil em um ponto específico de uma sessão, desde a configuração de um projeto até o envio de uma alteração.19A maioria dos comandos é útil em um ponto específico de uma sessão, desde a configuração de um projeto até o envio de uma alteração.

20 20

21**Primeira sessão em um repositório.** Execute `/init` para gerar um `CLAUDE.md` inicial, depois `/memory` para refiná-lo. Use `/mcp` e `/agents` para configurar quaisquer servidores ou subagentes que o projeto necessite, e `/permissions` para definir as regras de aprovação que você deseja.21**Primeira sessão em um repositório.** Execute `/init` para gerar um `CLAUDE.md` inicial, depois `/memory` para refiná-lo. Use `/mcp` para configurar quaisquer servidores que o projeto necessite, peça a Claude para criar quaisquer [subagentes](/pt/sub-agents) que você queira, e execute `/permissions` para definir suas regras de aprovação.

22 22

23**Durante uma tarefa.** `/plan` alterna para o Plan Mode antes de uma grande alteração. `/model` e `/effort` ajustam quanto raciocínio você está gastando. Quando a conversa fica longa, `/context` mostra para onde a janela está indo e `/compact` a resume; use `/btw` para uma observação rápida que não deve inchar o histórico.23**Durante uma tarefa.** `/plan` alterna para o Plan Mode antes de uma grande alteração. `/model` e `/effort` ajustam qual modelo você está usando e quanto raciocínio ele aplica. Quando a conversa fica longa, `/context` mostra o que está preenchendo a janela e `/compact` a resume para liberar espaço. Use `/btw` para uma observação rápida que não deve ser adicionada ao histórico de conversa.

24 24

25**Executando trabalho em paralelo.** `/agents` abre o gerenciador para os [subagentes](/pt/sub-agents) aos quais Claude pode delegar tarefas secundárias, e `/tasks` lista o que está em execução no segundo plano da sessão atual. `/background` desanexa a sessão inteira para continuar em execução como um [agente de fundo](/pt/agent-view) e libera seu terminal. Para uma grande alteração que abrange a base de código, `/batch` a decompõe em unidades independentes e executa cada uma em seu próprio [worktree](/pt/worktrees). Consulte [Executar agentes em paralelo](/pt/agents) para saber como essas abordagens se relacionam.25**Executando trabalho em paralelo.** Claude delega tarefas secundárias para [subagentes](/pt/sub-agents), e `/tasks` lista o que está em execução no segundo plano da sessão atual. `/background` desanexa a sessão inteira para continuar em execução como um [agente de fundo](/pt/agent-view) e libera seu terminal. Para uma grande alteração que abrange a base de código, `/batch` a decompõe em unidades independentes e executa cada uma em seu próprio [worktree](/pt/worktrees). Consulte [Executar agentes em paralelo](/pt/agents) para saber como essas abordagens se relacionam.

26 26

27**Antes de você enviar.** `/diff` mostra o que mudou, `/code-review` verifica o diff quanto a bugs de correção e limpezas e pode aplicar as descobertas com `--fix`, `/review` executa a mesma revisão somente leitura em uma solicitação de pull do GitHub, e `/security-review` fornece uma passagem mais profunda somente leitura. `/code-review ultra` executa uma revisão multi-agente na nuvem.27**Antes de você enviar.** `/diff` mostra o que mudou, `/code-review` verifica o diff quanto a bugs de correção e limpezas e pode aplicar as descobertas com `--fix`, `/review` executa a mesma revisão somente leitura em uma solicitação de pull do GitHub, e `/security-review` fornece uma passagem mais profunda somente leitura. `/code-review ultra` executa uma revisão multi-agente na nuvem.

28 28

51| :--------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |51| :--------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

52| `/add-dir <path>` | Adicionar um diretório de trabalho para acesso a arquivos durante a sessão atual. A maioria da configuração `.claude/` [não é descoberta](/pt/permissions#additional-directories-grant-file-access-not-configuration) do diretório adicionado. Você pode retomar a sessão posteriormente do diretório adicionado com `--continue` ou `--resume` |52| `/add-dir <path>` | Adicionar um diretório de trabalho para acesso a arquivos durante a sessão atual. A maioria da configuração `.claude/` [não é descoberta](/pt/permissions#additional-directories-grant-file-access-not-configuration) do diretório adicionado. Você pode retomar a sessão posteriormente do diretório adicionado com `--continue` ou `--resume` |

53| `/advisor [model\|off]` | {/* min-version: 2.1.98 */}Ativar ou desativar a [ferramenta advisor](/pt/advisor), que consulta um segundo modelo para orientação em momentos-chave durante uma tarefa. Aceita `opus`, `sonnet`, `fable` ({/* min-version: 2.1.170 */}v2.1.170+), ou um ID de modelo completo. Sem um argumento, abre um seletor. Requer Claude Code v2.1.98 ou posterior |53| `/advisor [model\|off]` | {/* min-version: 2.1.98 */}Ativar ou desativar a [ferramenta advisor](/pt/advisor), que consulta um segundo modelo para orientação em momentos-chave durante uma tarefa. Aceita `opus`, `sonnet`, `fable` ({/* min-version: 2.1.170 */}v2.1.170+), ou um ID de modelo completo. Sem um argumento, abre um seletor. Requer Claude Code v2.1.98 ou posterior |

54| `/agents` | Gerenciar configurações de [agent](/pt/sub-agents) |54| `/agents` | {/* min-version: 2.1.198 */}A partir da v2.1.198, executar `/agents` imprime um lembrete para pedir ao Claude para criar ou gerenciar [subagentes](/pt/sub-agents), ou para editar `.claude/agents/` ou `~/.claude/agents/` diretamente. {/* max-version: 2.1.197 */}Na v2.1.197 e anteriores, abre uma interface interativa para criar e gerenciar configurações de subagente |

55| `/autofix-pr [prompt]` | Gerar uma sessão [Claude Code na web](/pt/claude-code-on-the-web#auto-fix-pull-requests) que monitora o PR do branch atual e envia correções quando o CI falha ou revisores deixam comentários. Detecta o PR aberto do seu branch verificado com `gh pr view`; para monitorar um PR diferente, primeiro verifique seu branch. Por padrão, a sessão remota é instruída a corrigir todas as falhas de CI e comentários de revisão; passe um prompt para dar instruções diferentes, por exemplo `/autofix-pr only fix lint and type errors`. Requer a CLI `gh` e acesso a [Claude Code na web](/pt/claude-code-on-the-web) |55| `/autofix-pr [prompt]` | Gerar uma sessão [Claude Code na web](/pt/claude-code-on-the-web#auto-fix-pull-requests) que monitora o PR do branch atual e envia correções quando o CI falha ou revisores deixam comentários. Detecta o PR aberto do seu branch verificado com `gh pr view`; para monitorar um PR diferente, primeiro verifique seu branch. Por padrão, a sessão remota é instruída a corrigir todas as falhas de CI e comentários de revisão; passe um prompt para dar instruções diferentes, por exemplo `/autofix-pr only fix lint and type errors`. Requer a CLI `gh` e acesso a [Claude Code na web](/pt/claude-code-on-the-web) |

56| `/background [prompt]` | Desanexar a sessão atual para executar como um [agente de fundo](/pt/agent-view) e liberar este terminal. Passe um prompt para enviar uma instrução adicional antes de desanexar. Monitore a sessão com `claude agents`. Alias: `/bg` |56| `/background [prompt]` | Desanexar a sessão atual para executar como um [agente de fundo](/pt/agent-view) e liberar este terminal. Passe um prompt para enviar uma instrução adicional antes de desanexar. Monitore a sessão com `claude agents`. Alias: `/bg` |

57| `/batch <instruction>` | **[Skill](/pt/skills#bundled-skills).** Orquestrar mudanças em larga escala em um codebase em paralelo. Pesquisa o codebase, decompõe o trabalho em 5 a 30 unidades independentes e apresenta um plano. Uma vez aprovado, gera um [subagent de fundo](/pt/sub-agents#run-subagents-in-foreground-or-background) por unidade em um [git worktree](/pt/worktrees) isolado. Cada subagent implementa sua unidade, executa testes e abre uma solicitação de pull. Requer um repositório git. Exemplo: `/batch migrate src/ from Solid to React` |57| `/batch <instruction>` | **[Skill](/pt/skills#bundled-skills).** Orquestrar mudanças em larga escala em um codebase em paralelo. Pesquisa o codebase, decompõe o trabalho em 5 a 30 unidades independentes e apresenta um plano. Uma vez aprovado, gera um [subagent de fundo](/pt/sub-agents#run-subagents-in-foreground-or-background) por unidade em um [git worktree](/pt/worktrees) isolado. Cada subagent implementa sua unidade, executa testes e abre uma solicitação de pull. Requer um repositório git. Exemplo: `/batch migrate src/ from Solid to React` |

68| `/context [all]` | Visualizar o uso atual de contexto como uma grade colorida. Mostra sugestões de otimização para ferramentas pesadas em contexto, inchaço de memória e avisos de capacidade. No [modo tela cheia](/pt/fullscreen), o detalhamento por item é recolhido para manter a grade visível. Passe `all` para expandi-lo |68| `/context [all]` | Visualizar o uso atual de contexto como uma grade colorida. Mostra sugestões de otimização para ferramentas pesadas em contexto, inchaço de memória e avisos de capacidade. No [modo tela cheia](/pt/fullscreen), o detalhamento por item é recolhido para manter a grade visível. Passe `all` para expandi-lo |

69| `/copy [N]` | Copiar a última resposta do assistente para a área de transferência. Passe um número `N` para copiar a N-ésima resposta mais recente: `/copy 2` copia a segunda mais recente. Quando há blocos de código, mostra um seletor interativo para selecionar blocos individuais ou a resposta completa. Pressione `w` no seletor para escrever a seleção em um arquivo em vez da área de transferência, o que é útil via SSH |69| `/copy [N]` | Copiar a última resposta do assistente para a área de transferência. Passe um número `N` para copiar a N-ésima resposta mais recente: `/copy 2` copia a segunda mais recente. Quando há blocos de código, mostra um seletor interativo para selecionar blocos individuais ou a resposta completa. Pressione `w` no seletor para escrever a seleção em um arquivo em vez da área de transferência, o que é útil via SSH |

71| `/dataviz [request]` | **[Skill](/pt/skills#bundled-skills).** Orientação de design para gráficos, diagramas e painéis. Claude escolhe a forma de gráfico para os dados, atribui cor por função, valida a paleta para segurança de daltonismo e contraste com um script agrupado, e aplica regras de marca, interação e acessibilidade. Usa uma paleta de espaço reservado neutra da marca que você substitui pela sua própria. {/* min-version: 2.1.198 */}Requer Claude Code v2.1.198 ou posterior |

71| `/debug [description]` | **[Skill](/pt/skills#bundled-skills).** Ativar registro de depuração para a sessão atual e solucionar problemas lendo o log de depuração da sessão. O registro de depuração está desativado por padrão, a menos que você tenha iniciado com `claude --debug`, então executar `/debug` no meio da sessão começa a capturar logs a partir desse ponto. Opcionalmente, descreva o problema para focar a análise |72| `/debug [description]` | **[Skill](/pt/skills#bundled-skills).** Ativar registro de depuração para a sessão atual e solucionar problemas lendo o log de depuração da sessão. O registro de depuração está desativado por padrão, a menos que você tenha iniciado com `claude --debug`, então executar `/debug` no meio da sessão começa a capturar logs a partir desse ponto. Opcionalmente, descreva o problema para focar a análise |

72| `/deep-research <question>` | **[Workflow](/pt/workflows#bundled-workflows).** Expandir buscas na web em uma pergunta, buscar e verificar fontes e sintetizar um relatório citado |73| `/deep-research <question>` | **[Workflow](/pt/workflows#bundled-workflows).** Expandir buscas na web em uma pergunta, buscar e verificar fontes e sintetizar um relatório citado |

74| `/design-sync [hint]` | **[Skill](/pt/skills#bundled-skills).** Converter o sistema de design React do seu repositório e carregá-lo em [Claude Design](https://claude.ai/design), para que os designs que ele produz usem seus componentes reais. Opcionalmente, nomeie o sistema de design, por exemplo `/design-sync Acme DS`. Uma primeira sincronização verifica cada componente e pode levar algumas horas em um repositório grande. Disponível na API Anthropic; no Amazon Bedrock, na plataforma de agentes do Google Cloud e no Microsoft Foundry, a ferramenta subjacente não consegue acessar claude.ai, então o comando não está disponível |75| `/design-sync [hint]` | **[Skill](/pt/skills#bundled-skills).** Converter o sistema de design React do seu repositório e carregá-lo em [Claude Design](https://claude.ai/design), para que os designs que ele produz usem seus componentes reais. Opcionalmente, nomeie o sistema de design, por exemplo `/design-sync Acme DS`. Uma primeira sincronização verifica cada componente e pode levar algumas horas em um repositório grande. Disponível na API Anthropic; no Amazon Bedrock, na plataforma de agentes do Google Cloud e no Microsoft Foundry, a ferramenta subjacente não consegue acessar claude.ai, então o comando não está disponível |

75| `/desktop` | Continuar a sessão atual no aplicativo Claude Code Desktop. Requer macOS ou Windows e uma assinatura Claude. Alias: `/app` |76| `/desktop` | Continuar a sessão atual no aplicativo Claude Code Desktop. Requer macOS ou Windows e uma assinatura Claude. Alias: `/app` |

76| `/diff` | Abrir um visualizador de diff interativo mostrando alterações não confirmadas e diffs por turno. Use as setas esquerda/direita para alternar entre o diff git atual e turnos individuais do Claude, e cima/baixo para navegar pelos arquivos |77| `/diff` | Abrir um visualizador de diff interativo mostrando alterações não confirmadas e diffs por turno. Use as setas esquerda/direita para alternar entre o diff git atual e turnos individuais do Claude, e cima/baixo para navegar pelos arquivos. {/* min-version: 2.1.198 */}A partir da v2.1.198, o visualizador aberto também se atualiza automaticamente quando o estado git do repositório muda fora da sessão, como uma mudança de branch ou commit em outro terminal |

77| `/doctor` | Diagnosticar e verificar sua instalação e configurações do Claude Code. Os resultados aparecem com ícones de status. Pressione `f` para que Claude corrija qualquer problema relatado |78| `/doctor` | Diagnosticar e verificar sua instalação e configurações do Claude Code. Os resultados aparecem com ícones de status. Pressione `f` para que Claude corrija qualquer problema relatado |

78| `/effort [level\|auto]` | Definir o [nível de esforço](/pt/model-config#adjust-effort-level) do modelo. Aceita `low`, `medium`, `high`, `xhigh`, `max` ou `ultracode`; os níveis disponíveis dependem do modelo, e `max` e `ultracode` são apenas para sessão. `ultracode` é uma configuração do Claude Code que combina raciocínio `xhigh` com orquestração automática de [workflow](/pt/workflows#let-claude-decide-with-ultracode). `auto` redefine para o padrão do modelo. Sem um argumento, abre um controle deslizante interativo; use as setas esquerda e direita para escolher um nível e `Enter` para aplicar. Entra em vigor imediatamente sem esperar a resposta atual terminar |79| `/effort [level\|auto]` | Definir o [nível de esforço](/pt/model-config#adjust-effort-level) do modelo. Aceita `low`, `medium`, `high`, `xhigh`, `max` ou `ultracode`; os níveis disponíveis dependem do modelo, e `max` e `ultracode` são apenas para sessão. `ultracode` é uma configuração do Claude Code que combina raciocínio `xhigh` com orquestração automática de [workflow](/pt/workflows#let-claude-decide-with-ultracode). `auto` redefine para o padrão do modelo. Sem um argumento, abre um controle deslizante interativo; use as setas esquerda e direita para escolher um nível e `Enter` para aplicar. Entra em vigor imediatamente sem esperar a resposta atual terminar |

79| `/exit` | Sair da CLI. Em uma [sessão de fundo](/pt/agent-view#attach-to-a-session) anexada, isso desanexa e a sessão continua em execução. Alias: `/quit` |80| `/exit` | Sair da CLI. Em uma [sessão de fundo](/pt/agent-view#attach-to-a-session) anexada, isso desanexa e a sessão continua em execução. Alias: `/quit` |

81| `/fast [on\|off]` | Alternar [modo rápido](/pt/fast-mode) ativado ou desativado |82| `/fast [on\|off]` | Alternar [modo rápido](/pt/fast-mode) ativado ou desativado |

83| `/fewer-permission-prompts` | **[Skill](/pt/skills#bundled-skills).** Verificar seus transcritos para chamadas de ferramentas Bash e MCP comuns somente leitura, depois adicionar uma lista de permissões priorizada ao projeto `.claude/settings.json` para reduzir prompts de permissão |84| `/fewer-permission-prompts` | **[Skill](/pt/skills#bundled-skills).** Verificar seus transcritos para chamadas de ferramentas Bash e MCP comuns somente leitura, depois adicionar uma lista de permissões priorizada ao projeto `.claude/settings.json` para reduzir prompts de permissão |

84| `/focus` | Alternar a visualização de foco, que mostra apenas seu último prompt, um resumo de chamada de ferramenta de uma linha com estatísticas de edição de diff e a resposta final. A seleção persiste entre sessões; defina [`viewMode`](/pt/settings#available-settings) nas configurações para substituir. Disponível apenas em [renderização em tela cheia](/pt/fullscreen) |85| `/focus` | Alternar a visualização de foco, que mostra apenas seu último prompt, um resumo de chamada de ferramenta de uma linha com estatísticas de edição de diff e a resposta final. {/* min-version: 2.1.198 */}A partir da v2.1.198, o resumo de chamada de ferramenta também conta os subagentes lançados no turno e recolhe notificações de tarefas de fundo concluídas em uma única contagem. A seleção persiste entre sessões; defina [`viewMode`](/pt/settings#available-settings) nas configurações para substituir. Disponível apenas em [renderização em tela cheia](/pt/fullscreen) |

85| `/fork <directive>` | {/* min-version: 2.1.161 */}Gerar um [subagent bifurcado](/pt/sub-agents#fork-the-current-conversation): um subagent de fundo que herda a conversa completa e trabalha na diretiva enquanto você continua. Seu resultado retorna à sua conversa quando termina. Para alternar para uma cópia da conversa você mesmo, use `/branch`. Antes da v2.1.161, `/fork` é um alias para `/branch` |86| `/fork <directive>` | {/* min-version: 2.1.161 */}Gerar um [subagent bifurcado](/pt/sub-agents#fork-the-current-conversation): um subagent de fundo que herda a conversa completa e trabalha na diretiva enquanto você continua. Seu resultado retorna à sua conversa quando termina. Para alternar para uma cópia da conversa você mesmo, use `/branch`. Antes da v2.1.161, `/fork` é um alias para `/branch` |

86| `/goal [condition\|clear]` | Definir uma [meta](/pt/goal): Claude continua trabalhando entre turnos até que a condição seja atendida. Sem um argumento, mostra a meta atual ou mais recentemente alcançada. `clear`, `stop`, `off`, `reset`, `none` ou `cancel` remove uma meta ativa antecipadamente |87| `/goal [condition\|clear]` | Definir uma [meta](/pt/goal): Claude continua trabalhando entre turnos até que a condição seja atendida. Sem um argumento, mostra a meta atual ou mais recentemente alcançada. `clear`, `stop`, `off`, `reset`, `none` ou `cancel` remove uma meta ativa antecipadamente |

87| `/heapdump` | Escrever um snapshot de heap JavaScript e um detalhamento de memória para `~/Desktop`, ou seu diretório inicial no Linux sem uma pasta Desktop, para diagnosticar alto uso de memória. Consulte [solução de problemas](/pt/troubleshooting#high-cpu-or-memory-usage) |88| `/heapdump` | Escrever um snapshot de heap JavaScript e um detalhamento de memória para `~/Desktop`, ou seu diretório inicial no Linux sem uma pasta Desktop, para diagnosticar alto uso de memória. Consulte [solução de problemas](/pt/troubleshooting#high-cpu-or-memory-usage) |

118| `/resume [session]` | Retomar uma conversa por ID ou nome, ou abrir o seletor de sessão. A partir da v2.1.144, [sessões de fundo](/pt/agent-view) aparecem no seletor marcadas com `bg`. Alias: `/continue` |119| `/resume [session]` | Retomar uma conversa por ID ou nome, ou abrir o seletor de sessão. A partir da v2.1.144, [sessões de fundo](/pt/agent-view) aparecem no seletor marcadas com `bg`. Alias: `/continue` |

119| `/review [PR]` | Revisar uma solicitação de pull do GitHub por número, usando o mesmo mecanismo de revisão que `/code-review`. Sem argumentos, lista PRs abertos para escolher. Para uma revisão baseada em nuvem, consulte [`/code-review ultra`](/pt/ultrareview) |120| `/review [PR]` | Revisar uma solicitação de pull do GitHub por número, usando o mesmo mecanismo de revisão que `/code-review`. Sem argumentos, lista PRs abertos para escolher. Para uma revisão baseada em nuvem, consulte [`/code-review ultra`](/pt/ultrareview) |

120| `/rewind` | Retroceder a conversa e/ou código para um ponto anterior, ou resumir a partir de uma mensagem selecionada. Consulte [checkpointing](/pt/checkpointing). Aliases: `/checkpoint`, `/undo` |121| `/rewind` | Retroceder a conversa e/ou código para um ponto anterior, ou resumir a partir de uma mensagem selecionada. Consulte [checkpointing](/pt/checkpointing). Aliases: `/checkpoint`, `/undo` |

121| `/run` | **[Skill](/pt/skills#bundled-skills).** Iniciar e conduzir o aplicativo do seu projeto para ver uma alteração funcionando no aplicativo em execução, não apenas em testes. Consulte [Executar e verificar seu aplicativo](/pt/skills#run-and-verify-your-app). {/* min-version: 2.1.145 */}Requer Claude Code v2.1.145 ou posterior |122| `/run` | **[Skill](/pt/skills#bundled-skills).** Iniciar e conduzir o aplicativo do seu projeto para ver uma alteração funcionando, não apenas em testes. Consulte [Executar e verificar seu aplicativo](/pt/skills#run-and-verify-your-app). {/* min-version: 2.1.145 */}Requer Claude Code v2.1.145 ou posterior |

122| `/run-skill-generator` | **[Skill](/pt/skills#bundled-skills).** Ensinar `/run` e `/verify` como construir, iniciar e conduzir o aplicativo do seu projeto a partir de um ambiente limpo escrevendo uma [skill](/pt/skills#run-and-verify-your-app) por projeto. {/* min-version: 2.1.145 */}Requer Claude Code v2.1.145 ou posterior |123| `/run-skill-generator` | **[Skill](/pt/skills#bundled-skills).** Ensinar `/run` e `/verify` como construir, iniciar e conduzir o aplicativo do seu projeto a partir de um ambiente limpo escrevendo uma [skill](/pt/skills#run-and-verify-your-app) por projeto. {/* min-version: 2.1.145 */}Requer Claude Code v2.1.145 ou posterior |

124| `/schedule [description]` | Criar, atualizar, listar ou executar [rotinas](/pt/routines), que são executadas na infraestrutura em nuvem gerenciada pela Anthropic. Claude orienta você através da configuração conversacionalmente. Alias: `/routines` |125| `/schedule [description]` | Criar, atualizar, listar ou executar [rotinas](/pt/routines), que são executadas na infraestrutura em nuvem gerenciada pela Anthropic. Claude orienta você através da configuração conversacionalmente. Alias: `/routines` |

127| `/setup-bedrock` | Configurar autenticação, região e fixações de modelo do [Amazon Bedrock](/pt/amazon-bedrock) através de um assistente interativo. Visível apenas quando `CLAUDE_CODE_USE_BEDROCK=1` está definido. Usuários do Bedrock pela primeira vez também podem acessar este assistente na tela de login |128| `/setup-bedrock` | Configurar autenticação, região e fixações de modelo do [Amazon Bedrock](/pt/amazon-bedrock) através de um assistente interativo. Visível apenas quando `CLAUDE_CODE_USE_BEDROCK=1` está definido. Usuários do Bedrock pela primeira vez também podem acessar este assistente na tela de login |

128| `/setup-vertex` | Configurar autenticação, projeto, região e fixações de modelo do [Google Vertex AI](/pt/google-vertex-ai) através de um assistente interativo. Visível apenas quando `CLAUDE_CODE_USE_VERTEX=1` está definido. Usuários do Vertex AI pela primeira vez também podem acessar este assistente na tela de login |129| `/setup-vertex` | Configurar autenticação, projeto, região e fixações de modelo do [Google Vertex AI](/pt/google-vertex-ai) através de um assistente interativo. Visível apenas quando `CLAUDE_CODE_USE_VERTEX=1` está definido. Usuários do Vertex AI pela primeira vez também podem acessar este assistente na tela de login |

129| `/simplify [target]` | {/* min-version: 2.1.154 */}**[Skill](/pt/skills#bundled-skills).** Revisar o código alterado para oportunidades de limpeza e aplicar as correções. Quatro [agentes](/pt/sub-agents) de revisão são executados em paralelo, cobrindo reutilização de helpers existentes, simplificação, eficiência e se a alteração está no nível certo de abstração. A partir da v2.1.154, a revisão não procura por bugs de correção. Use `/code-review` para encontrar bugs. Em versões anteriores, `/simplify` é equivalente a `/code-review --fix`. Passe um caminho ou referência de PR para revisar um alvo específico |130| `/simplify [target]` | {/* min-version: 2.1.154 */}**[Skill](/pt/skills#bundled-skills).** Revisar o código alterado para oportunidades de limpeza e aplicar as correções. Quatro [agentes](/pt/sub-agents) de revisão são executados em paralelo, cobrindo reutilização de helpers existentes, simplificação, eficiência e se a alteração está no nível certo de abstração. A partir da v2.1.154, a revisão não procura por bugs de correção. Use `/code-review` para encontrar bugs. Em versões anteriores, `/simplify` é equivalente a `/code-review --fix`. Passe um caminho ou referência de PR para revisar um alvo específico |

130| `/skills` | Listar [skills](/pt/skills) disponíveis. Pressione `t` para classificar por contagem de tokens. Pressione `Space` para [ocultar uma skill do Claude ou do menu `/`](/pt/skills#override-skill-visibility-from-settings), depois `Enter` para salvar |131| `/skills` | Listar [skills](/pt/skills) disponíveis. {/* min-version: 2.1.121 */}A partir da v2.1.121, digite para filtrar a lista por nome. Pressione `t` para classificar por contagem de tokens. Pressione `Space` para [ocultar uma skill do Claude ou do menu `/`](/pt/skills#override-skill-visibility-from-settings), depois `Enter` para salvar |

132| `/status` | Abrir a interface de Configurações (aba Status) mostrando versão, modelo, conta e conectividade. Funciona enquanto Claude está respondendo, sem esperar a resposta atual terminar |133| `/status` | Abrir a interface de Configurações na aba Status, mostrando versão, modelo, conta e conectividade. Funciona enquanto Claude está respondendo |

133| `/statusline` | Configurar a [linha de status](/pt/statusline) do Claude Code. Descreva o que você quer, ou execute sem argumentos para auto-configurar a partir do seu prompt de shell |134| `/statusline` | Configurar a [linha de status](/pt/statusline) do Claude Code. Descreva o que você quer, ou execute sem argumentos para auto-configurar a partir do seu prompt de shell |

135| `/stop` | Parar a [sessão de fundo](/pt/agent-view) atual. Disponível apenas enquanto anexado a uma sessão de fundo; a transcrição e qualquer worktree são mantidos. Para desanexar sem parar, use `/exit` ou pressione `←` |136| `/stop` | Parar a [sessão de fundo](/pt/agent-view) atual. Disponível apenas enquanto anexado a uma sessão de fundo; a transcrição e qualquer worktree são mantidos. Para desanexar sem parar, use `/exit` ou pressione `←` |

context-window.md +1 −1

Details

1587 O que sobrevive à compactação1587 O que sobrevive à compactação

1588</h2>1588</h2>

1589 1589

1590Quando uma sessão longa é compactada, Claude Code resume o histórico de conversa para caber na janela de contexto. O que acontece com suas instruções depende de como foram carregadas:1590Quando uma sessão longa é compactada, Claude Code resume o histórico de conversa para caber na janela de contexto. {/* min-version: 2.1.198 */}A partir da v2.1.198, a solicitação de resumo herda a configuração de [extended thinking](/pt/model-config#extended-thinking) da sua sessão, portanto ela raciocina com o thinking habilitado quando sua sessão o tem habilitado e permanece desativado caso contrário. O thinking afeta apenas como o resumo é produzido; suas configurações de sessão permanecem inalteradas depois. O que acontece com suas instruções depende de como foram carregadas:

1591 1591

1592| Mecanismo | Após compactação |1592| Mecanismo | Após compactação |

1593| :----------------------------------------------- | :---------------------------------------------------------------------------------------------------------------- |1593| :----------------------------------------------- | :---------------------------------------------------------------------------------------------------------------- |

costs.md +3 −3

Details

107* **Limpe entre tarefas**: Use `/clear` para começar do zero ao mudar para trabalho não relacionado. Contexto obsoleto desperdiça tokens em cada mensagem subsequente. Use `/rename` antes de limpar para que você possa encontrar facilmente a sessão depois, então `/resume` para retornar a ela.107* **Limpe entre tarefas**: Use `/clear` para começar do zero ao mudar para trabalho não relacionado. Contexto obsoleto desperdiça tokens em cada mensagem subsequente. Use `/rename` antes de limpar para que você possa encontrar facilmente a sessão depois, então `/resume` para retornar a ela.

108* **Adicione instruções de compactação personalizadas**: `/compact Focus on code samples and API usage` diz a Claude o que preservar durante a sumarização.108* **Adicione instruções de compactação personalizadas**: `/compact Focus on code samples and API usage` diz a Claude o que preservar durante a sumarização.

109 109

110Você também pode personalizar o comportamento de compactação em seu CLAUDE.md:110Você também pode personalizar o comportamento de compactação em seu arquivo CLAUDE.md na raiz do seu projeto:

111 111

112```markdown theme={null}112```markdown theme={null}

113# Compact instructions113# Compact instructions

170 </Tab>170 </Tab>

171 171

172 <Tab title="filter-test-output.sh">172 <Tab title="filter-test-output.sh">

173 O hook chama este script, que verifica se o comando é um executor de teste e o modifica para mostrar apenas falhas:173 O hook chama este script. Crie a pasta com `mkdir -p ~/.claude/hooks`, salve o script abaixo como `~/.claude/hooks/filter-test-output.sh` e torne-o executável com `chmod +x ~/.claude/hooks/filter-test-output.sh`. Ele verifica se o comando é um executor de teste e o modifica para mostrar apenas falhas:

174 174

175 ```bash theme={null}175 ```bash theme={null}

176 #!/bin/bash176 #!/bin/bash

198 Ajuste o pensamento estendido198 Ajuste o pensamento estendido

199</h3>199</h3>

200 200

201O pensamento estendido é habilitado por padrão porque melhora significativamente o desempenho em tarefas complexas de planejamento e raciocínio. Tokens de pensamento são faturados como tokens de saída, e o orçamento padrão pode ser dezenas de milhares de tokens por solicitação dependendo do modelo. Para tarefas mais simples onde raciocínio profundo não é necessário, você pode reduzir custos baixando o [nível de esforço](/pt/model-config#adjust-effort-level) com `/effort` ou em `/model`, desabilitando pensamento em `/config`, ou, em modelos com um [orçamento de pensamento fixo](/pt/model-config#adaptive-reasoning-and-fixed-thinking-budgets), baixando o orçamento com `MAX_THINKING_TOKENS=8000`. Modelos de raciocínio adaptativo ignoram orçamentos diferentes de zero, portanto use níveis de esforço lá em vez disso. Desabilitar pensamento não está disponível no Fable 5, que sempre usa pensamento estendido.201O pensamento estendido é habilitado por padrão porque melhora significativamente o desempenho em tarefas complexas de planejamento e raciocínio. Tokens de pensamento são faturados como tokens de saída, e o orçamento padrão pode ser dezenas de milhares de tokens por solicitação dependendo do modelo. Para tarefas mais simples onde raciocínio profundo não é necessário, você pode reduzir custos baixando o [nível de esforço](/pt/model-config#adjust-effort-level) com `/effort` ou em `/model`, desabilitando pensamento em `/config`, ou, em modelos com um [orçamento de pensamento fixo](/pt/model-config#adaptive-reasoning-and-fixed-thinking-budgets), baixando o orçamento definindo a [variável de ambiente](/pt/env-vars) `MAX_THINKING_TOKENS`, por exemplo `MAX_THINKING_TOKENS=8000`. Modelos de raciocínio adaptativo ignoram orçamentos diferentes de zero, portanto use níveis de esforço lá em vez disso. Desabilitar pensamento não está disponível no Fable 5, que sempre usa pensamento estendido.

202 202

203<h3 id="delegate-verbose-operations-to-subagents">203<h3 id="delegate-verbose-operations-to-subagents">

204 Delegue operações verbosas para subagentes204 Delegue operações verbosas para subagentes

debug-your-config.md +1 −2

Details

14 Veja o que foi carregado no contexto14 Veja o que foi carregado no contexto

15</h2>15</h2>

16 16

17O comando `/context` mostra tudo que ocupa a janela de contexto para a sessão atual, dividido por categoria: prompt do sistema, arquivos de memória, skills, ferramentas MCP e mensagens de conversa. Execute-o primeiro para confirmar se seu `CLAUDE.md`, regras ou descrições de skill estão presentes.17O comando `/context` mostra tudo que ocupa a janela de contexto para a sessão atual, dividido por categoria: prompt do sistema, arquivos de memória, skills, subagentes personalizados com a fonte de cada um carregado, ferramentas MCP e mensagens de conversa. Execute-o primeiro para confirmar se seu `CLAUDE.md`, regras ou descrições de skill estão presentes.

18 18

19Para detalhes sobre uma categoria específica, acompanhe com o comando dedicado:19Para detalhes sobre uma categoria específica, acompanhe com o comando dedicado:

20 20

22| :--------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |22| :--------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

25| `/agents` | Subagentes configurados e suas configurações |

27| `/mcp` | Servidores MCP conectados e seu status |26| `/mcp` | Servidores MCP conectados e seu status |

desktop.md +1 −1

Details

829* **Linux (beta)**: Computer Use ainda não está disponível no aplicativo desktop Linux. Veja [Claude Desktop no Linux](/pt/desktop-linux).829* **Linux (beta)**: Computer Use ainda não está disponível no aplicativo desktop Linux. Veja [Claude Desktop no Linux](/pt/desktop-linux).

830* **Sugestões de código inline**: Desktop não fornece sugestões no estilo autocompletar. Funciona através de prompts conversacionais e alterações de código explícitas.830* **Sugestões de código inline**: Desktop não fornece sugestões no estilo autocompletar. Funciona através de prompts conversacionais e alterações de código explícitas.

831* **Equipes de agentes**: sessões paralelas de Claude Code que se comunicam entre si estão disponíveis no [CLI](/pt/agent-teams), não em Desktop. Para trabalho multi-agente dentro de uma sessão, use [dynamic workflows](/pt/workflows), que são executados em Desktop.831* **Equipes de agentes**: sessões paralelas de Claude Code que se comunicam entre si estão disponíveis no [CLI](/pt/agent-teams), não em Desktop. Para trabalho multi-agente dentro de uma sessão, use [dynamic workflows](/pt/workflows), que são executados em Desktop.

832* **Comandos terminal-dialog**: comandos integrados que abrem um painel interativo no terminal, como `/permissions`, `/config`, `/agents` e `/doctor`, não estão disponíveis na aba Code e respondem com `isn't available in this environment`. Edite [arquivos de configuração](/pt/settings) diretamente para gerenciar regras de permissão e configuração, ou execute o comando a partir do CLI autônomo.832* **Comandos terminal-dialog**: comandos integrados que abrem um painel interativo no terminal, como `/permissions`, `/config` e `/doctor`, não estão disponíveis na aba Code e respondem com `isn't available in this environment`. Edite [arquivos de configuração](/pt/settings) diretamente para gerenciar regras de permissão e configuração, ou execute o comando a partir do CLI autônomo.

833 833

834<h2 id="troubleshooting">834<h2 id="troubleshooting">

835 Solução de problemas835 Solução de problemas

env-vars.md +8 −4

Details

145| `BASH_MAX_TIMEOUT_MS` | Tempo limite máximo que o modelo pode definir para comandos bash de longa duração (padrão: 600000, ou 10 minutos) |145| `BASH_MAX_TIMEOUT_MS` | Tempo limite máximo que o modelo pode definir para comandos bash de longa duração (padrão: 600000, ou 10 minutos) |

146| `CCR_FORCE_BUNDLE` | Defina como `1` para forçar [`claude --remote`](/pt/claude-code-on-the-web#send-local-repositories-without-github) a agrupar e fazer upload do seu repositório local mesmo quando o acesso ao GitHub está disponível |146| `CCR_FORCE_BUNDLE` | Defina como `1` para forçar [`claude --remote`](/pt/claude-code-on-the-web#send-local-repositories-without-github) a agrupar e fazer upload do seu repositório local mesmo quando o acesso ao GitHub está disponível |

147| `CLAUDECODE` | Defina como `1` em subprocessos que Claude Code gera (ferramentas Bash e PowerShell, sessões tmux, [hook](/pt/hooks) comandos, [linha de status](/pt/statusline) comandos, subprocessos [servidor MCP](/pt/mcp) stdio). Extensões IDE também definem isso em seus terminais integrados. Use para detectar quando um script está sendo executado dentro de um subprocesso gerado por Claude Code. Para verificar se o processo atual foi gerado diretamente por uma chamada de ferramenta ou hook, em vez de dentro de um servidor MCP stdio que Claude Code iniciou, use `CLAUDE_CODE_CHILD_SESSION` em vez disso |147| `CLAUDECODE` | Defina como `1` em subprocessos que Claude Code gera (ferramentas Bash e PowerShell, sessões tmux, [hook](/pt/hooks) comandos, [linha de status](/pt/statusline) comandos, subprocessos [servidor MCP](/pt/mcp) stdio). Extensões IDE também definem isso em seus terminais integrados. Use para detectar quando um script está sendo executado dentro de um subprocesso gerado por Claude Code. Para verificar se o processo atual foi gerado diretamente por uma chamada de ferramenta ou hook, em vez de dentro de um servidor MCP stdio que Claude Code iniciou, use `CLAUDE_CODE_CHILD_SESSION` em vez disso |

148| `CLAUDE_AFK_COUNTDOWN_MS` | {/* min-version: 2.1.198 */}Quantos milissegundos antes da auto-continuação a contagem regressiva na tela aparece em um diálogo `AskUserQuestion` não respondido. Padrão `20000` (20 segundos). Veja `CLAUDE_AFK_TIMEOUT_MS`. Requer Claude Code v2.1.198 ou posterior |

149| `CLAUDE_AFK_TIMEOUT_MS` | {/* min-version: 2.1.198 */}Quantos milissegundos de tempo ocioso antes de um diálogo [`AskUserQuestion`](/pt/tools-reference) não respondido auto-continuar sem você. Padrão `60000` (60 segundos). Para manter perguntas abertas enquanto você está ausente, defina um valor grande como `86400000` (24 horas). Definir `0` não desativa o tempo limite; fecha o diálogo imediatamente. Requer Claude Code v2.1.198 ou posterior |

148| `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS` | Defina como `1` para desabilitar todos os tipos de [subagente](/pt/sub-agents) integrados, como Explore e Plan. Aplica-se apenas em modo não interativo (a flag `-p`). Útil para usuários do SDK que desejam uma tela em branco |150| `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS` | Defina como `1` para desabilitar todos os tipos de [subagente](/pt/sub-agents) integrados, como Explore e Plan. Aplica-se apenas em modo não interativo (a flag `-p`). Útil para usuários do SDK que desejam uma tela em branco |

149| `CLAUDE_AGENT_SDK_MCP_NO_PREFIX` | Defina como `1` para pular o prefixo `mcp__<server>__` em nomes de ferramentas de servidores MCP criados pelo SDK. As ferramentas usam seus nomes originais. Apenas uso do SDK |151| `CLAUDE_AGENT_SDK_MCP_NO_PREFIX` | Defina como `1` para pular o prefixo `mcp__<server>__` em nomes de ferramentas de servidores MCP criados pelo SDK. As ferramentas usam seus nomes originais. Apenas uso do SDK |

150| `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS` | Tempo limite de travamento em milissegundos para subagentes em segundo plano. Padrão `600000` (10 minutos). O temporizador é reiniciado em cada evento de progresso de streaming; se nenhum progresso chegar dentro da janela, o subagente é abortado e a tarefa é marcada como falha, exibindo qualquer resultado parcial para o pai |152| `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS` | Tempo limite de travamento em milissegundos para subagentes em segundo plano. Padrão `600000` (10 minutos). O temporizador é reiniciado em cada evento de progresso de streaming; se nenhum progresso chegar dentro da janela, o subagente é abortado e a tarefa é marcada como falha, exibindo qualquer resultado parcial para o pai |

162| `CLAUDE_CODE_ATTRIBUTION_HEADER` | Defina como `0` para omitir o bloco de atribuição (versão do cliente e impressão digital do prompt) do início do prompt do sistema. Desabilitá-lo melhora as taxas de acerto do cache de prompt ao rotear através de um [gateway LLM](/pt/llm-gateway). O cache da API Anthropic não é afetado |164| `CLAUDE_CODE_ATTRIBUTION_HEADER` | Defina como `0` para omitir o bloco de atribuição (versão do cliente e impressão digital do prompt) do início do prompt do sistema. Desabilitá-lo melhora as taxas de acerto do cache de prompt ao rotear através de um [gateway LLM](/pt/llm-gateway). O cache da API Anthropic não é afetado |

163| `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | Defina a capacidade de contexto em tokens usada para cálculos de auto-compactação. Padrão é a janela de contexto do modelo: 200K para modelos padrão ou 1M para modelos de [contexto estendido](/pt/model-config#extended-context), exceto em Sonnet 5, que tem seu próprio [limite padrão](/pt/model-config#sonnet-5-context-window). Use um valor mais baixo como `500000` em um modelo de 1M para tratar a janela como 500K para fins de compactação. O valor é limitado à janela de contexto real do modelo. `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` é aplicado como uma porcentagem deste valor. Definir esta variável desacopla o limite de compactação do `used_percentage` da linha de status, que sempre usa a janela de contexto completa do modelo |165| `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | Defina a capacidade de contexto em tokens usada para cálculos de auto-compactação. Padrão é a janela de contexto do modelo: 200K para modelos padrão ou 1M para modelos de [contexto estendido](/pt/model-config#extended-context), exceto em Sonnet 5, que tem seu próprio [limite padrão](/pt/model-config#sonnet-5-context-window). Use um valor mais baixo como `500000` em um modelo de 1M para tratar a janela como 500K para fins de compactação. O valor é limitado à janela de contexto real do modelo. `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` é aplicado como uma porcentagem deste valor. Definir esta variável desacopla o limite de compactação do `used_percentage` da linha de status, que sempre usa a janela de contexto completa do modelo |

164| `CLAUDE_CODE_AUTO_CONNECT_IDE` | Substitua a [conexão IDE](/pt/vs-code) automática. Por padrão, Claude Code se conecta automaticamente quando iniciado dentro do terminal integrado de uma IDE suportada. Defina como `false` para evitar isso. Defina como `true` para forçar uma tentativa de conexão quando a detecção automática falha, como quando tmux obscurece o terminal pai. Tem precedência sobre a configuração global [`autoConnectIde`](/pt/settings#global-config-settings) |166| `CLAUDE_CODE_AUTO_CONNECT_IDE` | Substitua a [conexão IDE](/pt/vs-code) automática. Por padrão, Claude Code se conecta automaticamente quando iniciado dentro do terminal integrado de uma IDE suportada. Defina como `false` para evitar isso. Defina como `true` para forçar uma tentativa de conexão quando a detecção automática falha, como quando tmux obscurece o terminal pai. Tem precedência sobre a configuração global [`autoConnectIde`](/pt/settings#global-config-settings) |

167| `CLAUDE_CODE_BRIDGE_SESSION_ID` | {/* min-version: 2.1.199 */}Definido automaticamente em subprocessos de ferramenta Bash e [comando hook](/pt/hooks) enquanto a sessão tem uma conexão [Remote Control](/pt/remote-control) ativa, e removido quando a conexão termina. O valor é o ID da sessão em forma `session_`, o mesmo identificador que aparece na URL `claude.ai/code` da sessão, para que um script possa vincular de volta à sessão que o executou. Requer Claude Code v2.1.199 ou posterior. Em [sessões em nuvem](/pt/claude-code-on-the-web), leia `CLAUDE_CODE_REMOTE_SESSION_ID` em vez disso |

165| `CLAUDE_CODE_CERT_STORE` | Lista separada por vírgula de fontes de certificado CA para conexões TLS. `bundled` é o conjunto de CA Mozilla fornecido com Claude Code. `system` é o armazenamento de confiança do sistema operacional, somente leitura em tempos de execução com `tls.getCACertificates`: o binário nativo, ou Node 22.15 ou posterior para instalações npm. Veja [Armazenamento de certificado CA](/pt/network-config#ca-certificate-store). Padrão é `bundled,system` |168| `CLAUDE_CODE_CERT_STORE` | Lista separada por vírgula de fontes de certificado CA para conexões TLS. `bundled` é o conjunto de CA Mozilla fornecido com Claude Code. `system` é o armazenamento de confiança do sistema operacional, somente leitura em tempos de execução com `tls.getCACertificates`: o binário nativo, ou Node 22.15 ou posterior para instalações npm. Veja [Armazenamento de certificado CA](/pt/network-config#ca-certificate-store). Padrão é `bundled,system` |

166| `CLAUDE_CODE_CHILD_SESSION` | {/* min-version: 2.1.172 */}Defina como `1` em subprocessos que Claude Code gera via ferramentas Bash, PowerShell e Monitor, [hook](/pt/hooks) comandos e [linha de status](/pt/statusline) comandos. Não definido para subprocessos [servidor MCP](/pt/mcp) stdio, que são de longa duração e sobrevivem à sessão que os gerou. Diferentemente de `CLAUDECODE`, isso é definido apenas pelo Claude Code quando ele inicia um subprocesso e não por extensões IDE, então distingue de forma confiável uma sessão aninhada de um `claude` de nível superior iniciado em um terminal integrado IDE. Uma `claude` TUI interativa aninhada iniciada desta forma é automaticamente excluída de `--resume`, `--continue`, histórico de seta para cima e a lista `claude agents`. Sessões `claude -p` não interativas ainda persistem. Defina `CLAUDE_CODE_FORCE_SESSION_PERSISTENCE=1` para substituir esta exclusão. Requer Claude Code v2.1.172 ou posterior |169| `CLAUDE_CODE_CHILD_SESSION` | {/* min-version: 2.1.172 */}Defina como `1` em subprocessos que Claude Code gera via ferramentas Bash, PowerShell e Monitor, [hook](/pt/hooks) comandos e [linha de status](/pt/statusline) comandos. Não definido para subprocessos [servidor MCP](/pt/mcp) stdio, que são de longa duração e sobrevivem à sessão que os gerou. Diferentemente de `CLAUDECODE`, isso é definido apenas pelo Claude Code quando ele inicia um subprocesso e não por extensões IDE, então distingue de forma confiável uma sessão aninhada de um `claude` de nível superior iniciado em um terminal integrado IDE. Uma `claude` TUI interativa aninhada iniciada desta forma é automaticamente excluída de `--resume`, `--continue`, histórico de seta para cima e a lista `claude agents`. Sessões `claude -p` não interativas ainda persistem. Defina `CLAUDE_CODE_FORCE_SESSION_PERSISTENCE=1` para substituir esta exclusão. Requer Claude Code v2.1.172 ou posterior |

172| `CLAUDE_CODE_DEBUG_LOG_LEVEL` | Nível de log mínimo escrito no arquivo de log de depuração. Valores: `verbose`, `debug` (padrão), `info`, `warn`, `error`. Defina como `verbose` para incluir diagnósticos de alto volume como saída completa de comando de linha de status, ou aumente para `error` para reduzir ruído |175| `CLAUDE_CODE_DEBUG_LOG_LEVEL` | Nível de log mínimo escrito no arquivo de log de depuração. Valores: `verbose`, `debug` (padrão), `info`, `warn`, `error`. Defina como `verbose` para incluir diagnósticos de alto volume como saída completa de comando de linha de status, ou aumente para `error` para reduzir ruído |

173| `CLAUDE_CODE_DISABLE_1M_CONTEXT` | Defina como `1` para desabilitar suporte a [janela de contexto de 1M](/pt/model-config#extended-context). Quando definido, variantes de modelo de 1M não estão disponíveis no seletor de modelo, e sessões [Sonnet 5](/pt/model-config#sonnet-5-context-window) são tratadas como tendo uma janela de 200K. Útil para ambientes corporativos com requisitos de conformidade |176| `CLAUDE_CODE_DISABLE_1M_CONTEXT` | Defina como `1` para desabilitar suporte a [janela de contexto de 1M](/pt/model-config#extended-context). Quando definido, variantes de modelo de 1M não estão disponíveis no seletor de modelo, e sessões [Sonnet 5](/pt/model-config#sonnet-5-context-window) são tratadas como tendo uma janela de 200K. Útil para ambientes corporativos com requisitos de conformidade |

174| `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` | Defina como `1` para desabilitar [raciocínio adaptativo](/pt/model-config#adjust-effort-level) em Opus 4.6 e Sonnet 4.6 e voltar ao orçamento de pensamento fixo controlado por `MAX_THINKING_TOKENS`. {/* min-version: 2.1.111 */}A partir de v2.1.111, não tem efeito em Fable 5, Sonnet 5 ou Opus 4.7 e posterior, que sempre usam raciocínio adaptativo |177| `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` | Defina como `1` para desabilitar [raciocínio adaptativo](/pt/model-config#adjust-effort-level) em Opus 4.6 e Sonnet 4.6 e voltar ao orçamento de pensamento fixo controlado por `MAX_THINKING_TOKENS`. {/* min-version: 2.1.111 */}A partir de v2.1.111, não tem efeito em Fable 5, Sonnet 5 ou Opus 4.7 e posterior, que sempre usam raciocínio adaptativo |

175| `CLAUDE_CODE_DISABLE_ADVISOR_TOOL` | {/* min-version: 2.1.98 */}Defina como `1` para desabilitar a [ferramenta advisor](/pt/advisor). O comando `/advisor` e a flag `--advisor` ficam indisponíveis e qualquer `advisorModel` configurado é ignorado. Requer Claude Code v2.1.98 ou posterior |178| `CLAUDE_CODE_DISABLE_ADVISOR_TOOL` | {/* min-version: 2.1.98 */}Defina como `1` para desabilitar a [ferramenta advisor](/pt/advisor). O comando `/advisor` fica indisponível, qualquer `advisorModel` configurado é ignorado e a flag `--advisor` é aceita mas não tem efeito, para que scripts existentes que a passam continuem funcionando sem erros. Requer Claude Code v2.1.98 ou posterior |

176| `CLAUDE_CODE_DISABLE_AGENT_VIEW` | Defina como `1` para desativar [agentes em segundo plano e visualização de agentes](/pt/agent-view): `claude agents`, `--bg`, `/background` e o supervisor sob demanda. Equivalente à configuração [`disableAgentView`](/pt/settings#available-settings) |179| `CLAUDE_CODE_DISABLE_AGENT_VIEW` | Defina como `1` para desativar [agentes em segundo plano e visualização de agentes](/pt/agent-view): `claude agents`, `--bg`, `/background` e o supervisor sob demanda. Equivalente à configuração [`disableAgentView`](/pt/settings#available-settings) |

177| `CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN` | Defina como `1` para desabilitar [renderização em tela cheia](/pt/fullscreen) e usar o renderizador de tela principal clássico. A conversa permanece no scrollback nativo do seu terminal para que `Cmd+f` e modo de cópia tmux funcionem como de costume. Tem precedência sobre `CLAUDE_CODE_NO_FLICKER` e a configuração [`tui`](/pt/settings#available-settings). Você também pode alternar com `/tui default`. Não se aplica a sessões em segundo plano abertas de [visualização de agentes](/pt/agent-view), que sempre usam renderização em tela cheia |180| `CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN` | Defina como `1` para desabilitar [renderização em tela cheia](/pt/fullscreen) e usar o renderizador de tela principal clássico. A conversa permanece no scrollback nativo do seu terminal para que `Cmd+f` e modo de cópia tmux funcionem como de costume. Tem precedência sobre `CLAUDE_CODE_NO_FLICKER` e a configuração [`tui`](/pt/settings#available-settings). Você também pode alternar com `/tui default`. Não se aplica a sessões em segundo plano abertas de [visualização de agentes](/pt/agent-view), que sempre usam renderização em tela cheia |

178| `CLAUDE_CODE_DISABLE_ARTIFACT` | Defina como `1` para desabilitar a ferramenta [Artifact](/pt/artifacts), que publica saída de sessão como uma página web privada em claude.ai. Equivalente à configuração [`disableArtifact`](/pt/settings#available-settings) |181| `CLAUDE_CODE_DISABLE_ARTIFACT` | Defina como `1` para desabilitar a ferramenta [Artifact](/pt/artifacts), que publica saída de sessão como uma página web privada em claude.ai. Equivalente à configuração [`disableArtifact`](/pt/settings#available-settings) |

179| `CLAUDE_CODE_DISABLE_ATTACHMENTS` | Defina como `1` para desabilitar o processamento de anexos. Menções de arquivo com sintaxe `@` são enviadas como texto simples em vez de serem expandidas para conteúdo de arquivo |182| `CLAUDE_CODE_DISABLE_ATTACHMENTS` | Defina como `1` para desabilitar o processamento de anexos. Menções de arquivo com sintaxe `@` são enviadas como texto simples em vez de serem expandidas para conteúdo de arquivo |

180| `CLAUDE_CODE_DISABLE_AUTO_MEMORY` | Defina como `1` para desabilitar [memória automática](/pt/memory#auto-memory). Defina como `0` para forçar a memória automática mesmo quando `--bare` mode ou [`autoMemoryEnabled: false`](/pt/settings#available-settings) desabilitaria de outra forma. Quando desabilitada, Claude não cria ou carrega arquivos de memória automática |183| `CLAUDE_CODE_DISABLE_AUTO_MEMORY` | Defina como `1` para desabilitar [memória automática](/pt/memory#auto-memory). Defina como `0` para forçar a memória automática mesmo quando `--bare` mode ou [`autoMemoryEnabled: false`](/pt/settings#available-settings) desabilitaria de outra forma. Quando desabilitada, Claude não cria ou carrega arquivos de memória automática |

181| `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` | Defina como `1` para desabilitar toda a funcionalidade de tarefas em segundo plano, incluindo o parâmetro `run_in_background` em ferramentas Bash e subagent, auto-backgrounding e o atalho Ctrl+B |184| `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` | Defina como `1` para desabilitar toda a funcionalidade de tarefas em segundo plano, incluindo o parâmetro `run_in_background` em ferramentas Bash e subagent, auto-backgrounding e o atalho Ctrl+B |

182| `CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF` | {/* min-version: 2.1.196 */}Defina como `1` para parar os comandos de shell em segundo plano em execução de uma [sessão em segundo plano](/pt/agent-view) e fluxos de trabalho dinâmicos quando o [supervisor](/pt/agent-view#the-supervisor-process) para, reinicia ou atualiza o processo dessa sessão, em vez de entregá-los ao próximo processo da sessão. Afeta apenas esse handoff: colocar uma sessão em segundo plano com `←` ou [`/background`](/pt/agent-view#from-inside-a-session) ainda carrega o trabalho em andamento, e `CLAUDE_DISABLE_ADOPT` desativa ambos. Requer Claude Code v2.1.196 ou posterior |185| `CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF` | {/* min-version: 2.1.196 */}Defina como `1` para parar os comandos de shell em segundo plano em execução de uma [sessão em segundo plano](/pt/agent-view), fluxos de trabalho dinâmicos e, {/* min-version: 2.1.198 */}a partir de v2.1.198, subagentes em segundo plano quando o [supervisor](/pt/agent-view#the-supervisor-process) para, reinicia ou atualiza o processo dessa sessão, em vez de entregá-los ao próximo processo da sessão. Afeta apenas esse handoff: colocar uma sessão em segundo plano com `←` ou [`/background`](/pt/agent-view#from-inside-a-session) ainda carrega o trabalho em andamento, e `CLAUDE_DISABLE_ADOPT` desativa ambos. Requer Claude Code v2.1.196 ou posterior |

183| `CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP` | {/* min-version: 2.1.193 */}Defina como `1` para parar Claude Code de encerrar [comandos de shell em segundo plano](/pt/interactive-mode#background-bash-commands) quando o sistema operacional relata pressão de memória. Por padrão, em macOS e Linux, Claude Code encerra um shell em segundo plano iniciado na sessão principal em um sinal de pressão de memória uma vez que a sessão ficou ociosa por 30 minutos e nenhuma volta ou subagente está em execução. Windows não tem sinal de pressão de memória, então essa variável não tem efeito lá. Requer Claude Code v2.1.193 ou posterior |186| `CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP` | {/* min-version: 2.1.193 */}Defina como `1` para parar Claude Code de encerrar [comandos de shell em segundo plano](/pt/interactive-mode#background-bash-commands) quando o sistema operacional relata pressão de memória. Por padrão, em macOS e Linux, Claude Code encerra um shell em segundo plano iniciado na sessão principal em um sinal de pressão de memória uma vez que a sessão ficou ociosa por 30 minutos e nenhuma volta ou subagente está em execução. Windows não tem sinal de pressão de memória, então essa variável não tem efeito lá. Requer Claude Code v2.1.193 ou posterior |

184| `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS` | Defina como `1` para desabilitar as [skills](/pt/skills) e workflows que vêm com Claude Code: skills agrupadas e workflows integrados são removidos inteiramente, enquanto comandos slash integrados como `/init` permanecem digitáveis mas são ocultados do modelo. Skills de plugins, `.claude/skills/` e `.claude/commands/` não são afetadas. Equivalente à configuração [`disableBundledSkills`](/pt/settings#available-settings); `0` não a substitui |187| `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS` | Defina como `1` para desabilitar as [skills](/pt/skills) e workflows que vêm com Claude Code: skills agrupadas e workflows integrados são removidos inteiramente, enquanto comandos slash integrados como `/init` permanecem digitáveis mas são ocultados do modelo. Skills de plugins, `.claude/skills/` e `.claude/commands/` não são afetadas. Equivalente à configuração [`disableBundledSkills`](/pt/settings#available-settings); `0` não a substitui |

185| `CLAUDE_CODE_DISABLE_CLAUDE_MDS` | Defina como `1` para evitar carregar qualquer arquivo de memória CLAUDE.md no contexto, incluindo arquivos de usuário, projeto e memória automática |188| `CLAUDE_CODE_DISABLE_CLAUDE_MDS` | Defina como `1` para evitar carregar qualquer arquivo de memória CLAUDE.md no contexto, incluindo arquivos de usuário, projeto e memória automática |

186| `CLAUDE_CODE_DISABLE_CRON` | Defina como `1` para desabilitar [tarefas agendadas](/pt/scheduled-tasks). A skill `/loop` e ferramentas cron ficam indisponíveis e qualquer tarefa já agendada para de disparar, incluindo tarefas que já estão em execução no meio da sessão |189| `CLAUDE_CODE_DISABLE_CRON` | Defina como `1` para desabilitar [tarefas agendadas](/pt/scheduled-tasks). A skill `/loop` e ferramentas cron ficam indisponíveis e qualquer tarefa já agendada para de disparar, incluindo tarefas que já estão em execução no meio da sessão |

187| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | Defina como `1` para remover cabeçalhos de solicitação `anthropic-beta` específicos do Anthropic e campos de esquema de ferramenta beta (como `defer_loading` e `eager_input_streaming`) de solicitações de API. Use isso quando um gateway proxy rejeita solicitações com erros como "Unexpected value(s) for the `anthropic-beta` header" ou "Extra inputs are not permitted". Campos padrão (`name`, `description`, `input_schema`, `cache_control`) são preservados |190| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | Defina como `1` para remover cabeçalhos de solicitação `anthropic-beta` específicos do Anthropic e campos de esquema de ferramenta beta (como `defer_loading` e `eager_input_streaming`) de solicitações de API. Use isso quando um gateway proxy rejeita solicitações com erros como "Unexpected value(s) for the `anthropic-beta` header" ou "Extra inputs are not permitted". Campos padrão (`name`, `description`, `input_schema`, `cache_control`) são preservados |

191| `CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS` | {/* min-version: 2.1.198 */}Defina como `1` para desabilitar os [subagentes Explore e Plan](/pt/sub-agents#built-in-subagents) integrados. Claude explora com suas ferramentas de busca ou o subagente de propósito geral em vez disso, e [modo plan](/pt/permission-modes#analyze-before-you-edit-with-plan-mode) lê arquivos diretamente em vez de iniciar agentes Explore e Plan. Subagentes personalizados nomeados `Explore` ou `Plan` não são afetados. Para remover todos os tipos de subagentes integrados no Agent SDK ou modo não interativo, use `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS` em vez disso. Requer Claude Code v2.1.198 ou posterior |

189| `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` | Defina como `1` para desabilitar as pesquisas de qualidade de sessão "Como Claude está se saindo?". Pesquisas também são desabilitadas quando `DISABLE_TELEMETRY`, `DO_NOT_TRACK` ou `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` está definido, a menos que `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` opte por participar novamente. Para definir uma taxa de amostra em vez de desabilitar completamente, use a configuração [`feedbackSurveyRate`](/pt/settings#available-settings). Veja [Pesquisas de qualidade de sessão](/pt/data-usage#session-quality-surveys) |193| `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` | Defina como `1` para desabilitar as pesquisas de qualidade de sessão "Como Claude está se saindo?". Pesquisas também são desabilitadas quando `DISABLE_TELEMETRY`, `DO_NOT_TRACK` ou `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` está definido, a menos que `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` opte por participar novamente. Para definir uma taxa de amostra em vez de desabilitar completamente, use a configuração [`feedbackSurveyRate`](/pt/settings#available-settings). Veja [Pesquisas de qualidade de sessão](/pt/data-usage#session-quality-surveys) |

190| `CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING` | Defina como `1` para desabilitar [checkpointing](/pt/checkpointing) de arquivo. O comando `/rewind` não será capaz de restaurar alterações de código |194| `CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING` | Defina como `1` para desabilitar [checkpointing](/pt/checkpointing) de arquivo. O comando `/rewind` não será capaz de restaurar alterações de código |

230| `CLAUDE_CODE_IDE_SKIP_VALID_CHECK` | Defina como `1` para pular validação de entradas de arquivo de bloqueio IDE durante a conexão. Use quando a auto-conexão falha em encontrar sua IDE apesar dela estar em execução |234| `CLAUDE_CODE_IDE_SKIP_VALID_CHECK` | Defina como `1` para pular validação de entradas de arquivo de bloqueio IDE durante a conexão. Use quando a auto-conexão falha em encontrar sua IDE apesar dela estar em execução |

231| `CLAUDE_CODE_MAX_CONTEXT_TOKENS` | Substitua o tamanho da janela de contexto que Claude Code assume para o modelo ativo. {/* min-version: 2.1.193 */}A partir de v2.1.193, aplicado diretamente para nomes de modelo que Claude Code não reconhece como um modelo Claude; para modelos Claude reconhecidos, só tem efeito quando `DISABLE_COMPACT` também está definido. Use isso ao rotear para um modelo através de `ANTHROPIC_BASE_URL` cuja janela de contexto não corresponde ao tamanho integrado para seu nome |235| `CLAUDE_CODE_MAX_CONTEXT_TOKENS` | Substitua o tamanho da janela de contexto que Claude Code assume para o modelo ativo. {/* min-version: 2.1.193 */}A partir de v2.1.193, aplicado diretamente para nomes de modelo que Claude Code não reconhece como um modelo Claude; para modelos Claude reconhecidos, só tem efeito quando `DISABLE_COMPACT` também está definido. Use isso ao rotear para um modelo através de `ANTHROPIC_BASE_URL` cuja janela de contexto não corresponde ao tamanho integrado para seu nome |

232| `CLAUDE_CODE_MAX_OUTPUT_TOKENS` | Defina o número máximo de tokens de saída para a maioria das solicitações. Padrões e limites variam por modelo; veja [max output tokens](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison). Aumentar este valor reduz a janela de contexto efetiva disponível antes que [auto-compactação](/pt/costs#reduce-token-usage) seja acionada |236| `CLAUDE_CODE_MAX_OUTPUT_TOKENS` | Defina o número máximo de tokens de saída para a maioria das solicitações. Padrões e limites variam por modelo; veja [max output tokens](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison). Aumentar este valor reduz a janela de contexto efetiva disponível antes que [auto-compactação](/pt/costs#reduce-token-usage) seja acionada |

233| `CLAUDE_CODE_MAX_RETRIES` | Substitua o número de vezes para tentar novamente solicitações de API falhadas (padrão: 10). {/* min-version: 2.1.186 */}Limitado a 15 a partir de v2.1.186. Para sessões não supervisionadas que precisam aguardar através de interrupções mais longas, defina `CLAUDE_CODE_RETRY_WATCHDOG` em vez disso |237| `CLAUDE_CODE_MAX_RETRIES` | Substitua o número de vezes para tentar novamente solicitações de API falhadas (padrão: 10). {/* min-version: 2.1.186 */}Limitado a 15 a partir de v2.1.186; {/* min-version: 2.1.199 */}a partir de v2.1.199, `CLAUDE_CODE_RETRY_WATCHDOG` aumenta o padrão e remove o limite. Para sessões não supervisionadas que precisam aguardar através de interrupções mais longas, defina `CLAUDE_CODE_RETRY_WATCHDOG` em vez disso |

234| `CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY` | Número máximo de ferramentas somente leitura e subagentes que podem executar em paralelo (padrão: 10). Valores mais altos aumentam o paralelismo mas consomem mais recursos |238| `CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY` | Número máximo de ferramentas somente leitura e subagentes que podem executar em paralelo (padrão: 10). Valores mais altos aumentam o paralelismo mas consomem mais recursos |

235| `CLAUDE_CODE_MAX_TURNS` | Limite o número de voltas agentes quando nenhum limite explícito é passado. Equivalente a passar [`--max-turns`](/pt/cli-reference#cli-flags), que tem precedência quando ambos estão definidos. Um valor que não é um inteiro positivo é rejeitado na inicialização com um erro em vez de ser tratado como sem limite |239| `CLAUDE_CODE_MAX_TURNS` | Limite o número de voltas agentes quando nenhum limite explícito é passado. Equivalente a passar [`--max-turns`](/pt/cli-reference#cli-flags), que tem precedência quando ambos estão definidos. Um valor que não é um inteiro positivo é rejeitado na inicialização com um erro em vez de ser tratado como sem limite |

236| `CLAUDE_CODE_MCP_ALLOWLIST_ENV` | Defina como `1` para gerar servidores MCP stdio com apenas um ambiente de linha de base segura mais o `env` configurado do servidor, em vez de herdar seu ambiente de shell |240| `CLAUDE_CODE_MCP_ALLOWLIST_ENV` | Defina como `1` para gerar servidores MCP stdio com apenas um ambiente de linha de base segura mais o `env` configurado do servidor, em vez de herdar seu ambiente de shell |

262| `CLAUDE_CODE_REMOTE_SESSION_ID` | Definido automaticamente em [sessões em nuvem](/pt/claude-code-on-the-web) para o ID da sessão atual. Leia isso para construir um link de volta para a transcrição da sessão. Veja [Vincular saída de volta à sessão](/pt/claude-code-on-the-web#link-output-back-to-the-session) |266| `CLAUDE_CODE_REMOTE_SESSION_ID` | Definido automaticamente em [sessões em nuvem](/pt/claude-code-on-the-web) para o ID da sessão atual. Leia isso para construir um link de volta para a transcrição da sessão. Veja [Vincular saída de volta à sessão](/pt/claude-code-on-the-web#link-output-back-to-the-session) |

263| `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` | Defina como `1` para retomar automaticamente se a sessão anterior terminou no meio de uma volta. Usado em modo SDK para que o modelo continue sem exigir que o SDK reenvie o prompt |267| `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` | Defina como `1` para retomar automaticamente se a sessão anterior terminou no meio de uma volta. Usado em modo SDK para que o modelo continue sem exigir que o SDK reenvie o prompt |

264| `CLAUDE_CODE_RESUME_PROMPT` | Substitua a mensagem de continuação injetada ao retomar uma sessão que terminou no meio de uma volta. Padrão é `Continue from where you left off.`. Scripts de spawn para agentes de longa duração podem definir isso para uma mensagem de inicialização mais diretiva. Uma string vazia usa o padrão |268| `CLAUDE_CODE_RESUME_PROMPT` | Substitua a mensagem de continuação injetada ao retomar uma sessão que terminou no meio de uma volta. Padrão é `Continue from where you left off.`. Scripts de spawn para agentes de longa duração podem definir isso para uma mensagem de inicialização mais diretiva. Uma string vazia usa o padrão |

265| `CLAUDE_CODE_RETRY_WATCHDOG` | {/* min-version: 2.1.186 */}Defina como `1` para sessões não supervisionadas, como harnesses de avaliação, trabalhos 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 watchdog recua até 5 minutos entre tentativas, ou até o limite ser redefinido quando a resposta carrega um tempo de redefinição de limite de taxa, então uma sessão que atinge um limite de uso aguarda a janela restante. Requer Claude Code v2.1.186 ou posterior |269| `CLAUDE_CODE_RETRY_WATCHDOG` | {/* min-version: 2.1.186 */}Defina como `1` para sessões não supervisionadas, como harnesses de avaliação, trabalhos 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 watchdog recua até 5 minutos entre tentativas, ou até o limite ser redefinido quando a resposta carrega um tempo de redefinição de limite de taxa, então uma sessão que atinge um limite de uso aguarda a janela restante. {/* min-version: 2.1.199 */}A partir de v2.1.199, também aumenta a contagem de retry padrão para outros erros transitórios, como erros de servidor, timeouts e conexões descartadas, 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 |

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

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

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

errors.md +164 −20

Details

27| `Request timed out` | [Erros de servidor](#request-timed-out), ou [Rede](#unable-to-connect-to-api) se a mensagem mencionar sua conexão com a internet |27| `Request timed out` | [Erros de servidor](#request-timed-out), ou [Rede](#unable-to-connect-to-api) se a mensagem mencionar sua conexão com a internet |

28| `Server error mid-response. The response above may be incomplete.` | [Erros de servidor](#the-response-above-may-be-incomplete) |

29| `Connection closed mid-response` / `Response stalled mid-stream` | [Erros de servidor](#the-response-above-may-be-incomplete) |

28| `<model> is temporarily unavailable, so auto mode cannot determine the safety of...` | [Erros de servidor](#auto-mode-cannot-determine-the-safety-of-an-action) |30| `<model> is temporarily unavailable, so auto mode cannot determine the safety of...` | [Erros de servidor](#auto-mode-cannot-determine-the-safety-of-an-action) |

29| `Auto mode could not evaluate this action and is blocking it for safety` | [Erros de servidor](#auto-mode-cannot-determine-the-safety-of-an-action) |31| `Auto mode could not evaluate this action and is blocking it for safety` | [Erros de servidor](#auto-mode-cannot-determine-the-safety-of-an-action) |

30| `Auto mode classifier transcript exceeded context window` | [Erros de servidor](#auto-mode-cannot-determine-the-safety-of-an-action) |32| `Auto mode classifier transcript exceeded context window` | [Erros de servidor](#auto-mode-cannot-determine-the-safety-of-an-action) |

33| `Agent terminated early due to an API error` | [Erros de servidor](#agent-terminated-early-due-to-an-api-error) |

43| `Remote Control is only available when using Claude via api.anthropic.com` | [Autenticação](#remote-control-requires-the-anthropic-api) |46| `Remote Control is only available when using Claude via api.anthropic.com` | [Autenticação](#remote-control-requires-the-anthropic-api) |

49| `AWS credentials expired or invalid` | [Autenticação](#aws-credentials-expired-or-invalid) |

50| `AWS authentication failed` | [Autenticação](#aws-authentication-failed) |

47| `Waiting for API response · will retry in` | [Tentativas automáticas](#automatic-retries), ou [Rede](#unable-to-connect-to-api) se persistir |52| `Waiting for API response · will retry in` | [Tentativas automáticas](#automatic-retries), ou [Rede](#unable-to-connect-to-api) se persistir |

54| `SSL certificate error (...)` during login or startup | [Rede](#ssl-certificate-errors) |

63| `Claude Code is unable to respond to this request, which appears to violate our Usage Policy` | [Erros de solicitação](#usage-policy-refusal) |69| `Claude Code is unable to respond to this request, which appears to violate our Usage Policy` | [Erros de solicitação](#usage-policy-refusal) |

71| Respostas parecem de qualidade inferior ao usual | [Qualidade de resposta](#responses-seem-lower-quality-than-usual) |

65 72

66<h2 id="automatic-retries">73<h2 id="automatic-retries">

67 Tentativas automáticas74 Tentativas automáticas

68</h2>75</h2>

69 76

70O Claude Code tenta novamente falhas transitórias antes de mostrar um erro. Erros de servidor, respostas sobrecarregadas, tempos limite de solicitação, throttles 429 temporários e conexões perdidas são todos repetidos até 10 vezes com backoff exponencial. Enquanto tenta novamente, o spinner mostra uma contagem regressiva `Retrying in Ns · attempt x/y`.77O Claude Code tenta novamente falhas transitórias antes de mostrar um erro. Erros de servidor, respostas sobrecarregadas, tempos limite de solicitação, throttles 429 temporários e conexões perdidas são todos repetidos até 10 vezes com backoff exponencial. {/* min-version: 2.1.198 */}A partir da v2.1.198, isso cobre conexões que caem no meio de uma resposta antes de qualquer saída visível ter sido transmitida: Claude Code re-emite a solicitação com o mesmo backoff e o turno continua em vez de parar com um erro de conexão. {/* min-version: 2.1.199 */}A partir da v2.1.199, throttles 429 temporários que não carregam os cabeçalhos de cota do seu plano também são repetidos quando você está conectado com uma assinatura claude.ai; versões anteriores os repetiam apenas para autenticações de chave de API e Enterprise.

71 78

72{/* min-version: 2.1.185 */}Se nenhum dado chegar no fluxo de resposta por 20 segundos enquanto uma solicitação ainda está pendente, o spinner mostra `Waiting for API response · will retry in … · check your network` antes de qualquer tentativa ter começado. A solicitação ainda não falhou: a contagem regressiva é executada até o ponto em que o Claude Code interrompe a conexão travada e tenta novamente, portanto o banner desaparece por conta própria assim que os dados retomam ou a tentativa é bem-sucedida. A partir da v2.1.185, o limite é de 20 segundos; versões anteriores mostram o banner após 10 segundos com uma redação diferente. Se reaparecer em cada tentativa, trate-o como um [problema de rede](#unable-to-connect-to-api).79Duas classes de falha não são repetidas, porque uma tentativa não pode ter sucesso:

73 80

~~74Quando você vê um dos erros nesta página, essas tentativas já foram esgotadas. Você pode ajustar o comportamento com estas variáveis de ambiente:~~81* {/* min-version: 2.1.199 */}A partir da v2.1.199, uma falha de validação de certificado TLS, como um proxy que inspeciona TLS, um pacote `NODE_EXTRA_CA_CERTS` ausente ou um certificado expirado, falha na primeira tentativa para que a correção apareça imediatamente em vez de após o orçamento de tentativa completo. Consulte [Erros de certificado SSL](#ssl-certificate-errors). Condições TLS transitórias, como um tempo limite de handshake, ainda são repetidas.

82* {/* min-version: 2.1.199 */}A partir da v2.1.199, um erro de servidor que chega depois que Claude já transmitiu saída visível mantém a resposta parcial e anexa um [aviso de resposta incompleta](#the-response-above-may-be-incomplete) em vez de tentar novamente, já que re-executar a solicitação poderia executar as mesmas chamadas de ferramentas duas vezes. Versões anteriores descartavam a saída parcial e relatavam o turno como um erro.

84Enquanto tenta novamente, o spinner mostra uma contagem regressiva `Retrying in Ns · attempt x/y` após um rótulo de erro. O rótulo nomeia a razão específica da primeira tentativa para falhas em que você pode agir imediatamente: a rede está inativa, um handshake TLS falhou ou você atingiu um limite de taxa. Para outros erros, ele lê `API error` no início. {/* min-version: 2.1.198 */}A partir da v2.1.198, ele muda para a razão específica da terceira tentativa, ou na tentativa final quando `CLAUDE_CODE_MAX_RETRIES` permite menos de três; versões anteriores mudam apenas na tentativa final.

86{/* min-version: 2.1.198 */}A partir da v2.1.198, a dica de spinner usual é suprimida durante tentativas. Uma vez que a razão do erro é revelada, se a falha for uma sobrecarga 529, a linha abaixo da contagem regressiva também nomeia onde verificar o status do serviço: `status.claude.com` na API Anthropic, ou o host do provedor ou gateway nomeado na mensagem em outras configurações.

88{/* min-version: 2.1.185 */}Se nenhum dado chegar no fluxo de resposta por 20 segundos enquanto uma solicitação ainda está pendente, o spinner mostra `Waiting for API response · will retry in … · check your network` antes de qualquer tentativa ter começado. A solicitação ainda não falhou: a contagem regressiva é executada até o ponto em que Claude Code interrompe a conexão travada e tenta novamente, portanto o banner desaparece por conta própria assim que os dados retomam ou a tentativa é bem-sucedida. A partir da v2.1.185, o limite é de 20 segundos; versões anteriores mostram o banner após 10 segundos com uma redação diferente. Se reaparecer em cada tentativa, trate-o como um [problema de rede](#unable-to-connect-to-api).

90Quando você vê um dos erros nesta página, essas tentativas já foram esgotadas, a menos que pertença a uma classe que não é repetida, como uma falha de validação de certificado. Você pode ajustar o comportamento com estas variáveis de ambiente:

75 91

77| :------------------------------------------- | :----------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |93| :------------------------------------------- | :----------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

78| [`CLAUDE_CODE_MAX_RETRIES`](/pt/env-vars) | 10 | Número de tentativas de repetição. {/* min-version: 2.1.186 */}Limitado a 15 a partir da v2.1.186. Reduza-o para expor falhas mais rapidamente em scripts. |94| [`CLAUDE_CODE_MAX_RETRIES`](/pt/env-vars) | 10 | Número de tentativas de repetição. {/* min-version: 2.1.186 */}Limitado a 15 a partir da v2.1.186; {/* min-version: 2.1.199 */}a partir da v2.1.199 `CLAUDE_CODE_RETRY_WATCHDOG` aumenta o padrão e remove o limite. Reduza-o para expor falhas mais rapidamente em scripts. |

79| [`CLAUDE_CODE_RETRY_WATCHDOG`](/pt/env-vars) | não definido | Defina como `1` em sessões autônomas, como trabalhos de CI, para repetir erros de capacidade `429` e `529` indefinidamente em vez de falhar após `CLAUDE_CODE_MAX_RETRIES` tentativas. |95| [`CLAUDE_CODE_RETRY_WATCHDOG`](/pt/env-vars) | não definido | Defina como `1` em sessões autônomas, como trabalhos de CI, para repetir erros de capacidade `429` e `529` indefinidamente em vez de falhar após `CLAUDE_CODE_MAX_RETRIES` tentativas. {/* min-version: 2.1.199 */}A partir da v2.1.199, também aumenta a contagem de tentativas padrão para outros erros transitórios, como erros de servidor, tempos limite e conexões perdidas, 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. |

80| [`API_TIMEOUT_MS`](/pt/env-vars) | 600000 | Tempo limite por solicitação em milissegundos. Aumente-o para redes lentas ou proxies. |96| [`API_TIMEOUT_MS`](/pt/env-vars) | 600000 | Tempo limite por solicitação em milissegundos. Aumente-o para redes lentas ou proxies. |

81 97

82<h2 id="server-errors">98<h2 id="server-errors">

115API Error: Repeated 529 Overloaded errors. The API is at capacity — this is usually temporary. Try again in a moment. If it persists, check https://status.claude.com.131API Error: Repeated 529 Overloaded errors. The API is at capacity — this is usually temporary. Try again in a moment. If it persists, check https://status.claude.com.

116```132```

117 133

118A frase final varia por provedor da mesma forma que o erro 500 acima. Um 529 não é seu limite de uso e não conta contra sua cota.134A frase final varia por provedor da mesma forma que o erro 500 acima.

135

136Um 529 não é seu limite de uso e não conta contra sua cota.

119 137

120**O que fazer:**138**O que fazer:**

121 139

133Request timed out151Request timed out

134```152```

135 153

136Isso pode acontecer durante períodos de alta carga ou quando uma resposta muito grande está sendo gerada. O tempo limite padrão de solicitação é de 10 minutos.154Isso pode acontecer durante períodos de alta carga ou quando o modelo está gerando uma resposta muito grande. O tempo limite padrão de solicitação é de 10 minutos.

137 155

138**O que fazer:**156**O que fazer:**

139 157

142* Se uma rede lenta ou proxy for a causa, aumente `API_TIMEOUT_MS` conforme descrito em [Tentativas automáticas](#automatic-retries)160* Se uma rede lenta ou proxy for a causa, aumente `API_TIMEOUT_MS` conforme descrito em [Tentativas automáticas](#automatic-retries)

143* Se os tempos limite forem frequentes e sua rede estiver saudável, consulte [Erros de rede e conexão](#network-and-connection-errors) abaixo161* Se os tempos limite forem frequentes e sua rede estiver saudável, consulte [Erros de rede e conexão](#network-and-connection-errors) abaixo

144 162

163<h3 id="the-response-above-may-be-incomplete">

164 The response above may be incomplete

165</h3>

166

167Uma resposta de streaming falhou depois que Claude já havia produzido saída visível. Re-enviar a solicitação poderia executar as mesmas chamadas de ferramentas duas vezes, portanto Claude Code mantém o que já foi transmitido e anexa este aviso em vez de descartar o turno. Qual variante você vê nomeia a causa:

168

169```text theme={null}

170API Error: Server error mid-response. The response above may be incomplete.

171API Error: Connection closed mid-response. The response above may be incomplete.

172API Error: Response stalled mid-stream. The response above may be incomplete.

173```

174

175* {/* min-version: 2.1.199 */}}`Server error mid-response`: um erro de servidor sobrecarregado ou 5xx no meio do fluxo. Esta variante requer Claude Code v2.1.199 ou posterior; antes disso, esse caso descartava a saída parcial e relatava o turno inteiro como um erro.

176* `Connection closed mid-response`: a conexão caiu.

177* `Response stalled mid-stream`: o fluxo parou de enviar dados.

178

179**O que fazer:**

180

181* Leia a resposta que foi transmitida. Nada foi perdido, mas as frases finais ou chamadas de ferramentas podem estar faltando.

182* Responda com `continue` para que Claude continue de onde parou

183* Se o mesmo erro aparecer antes de qualquer saída visível, Claude Code tenta novamente a solicitação em vez de finalizá-la. Consulte [Tentativas automáticas](#automatic-retries).

184

145<h3 id="auto-mode-cannot-determine-the-safety-of-an-action">185<h3 id="auto-mode-cannot-determine-the-safety-of-an-action">

146 Auto mode cannot determine the safety of an action186 Auto mode cannot determine the safety of an action

147</h3>187</h3>

173* Tente novamente a ação; isso geralmente funciona na próxima tentativa213* Tente novamente a ação; isso geralmente funciona na próxima tentativa

174* Execute `claude --debug` e repita a ação para ver a resposta do classificador subjacente no log de depuração214* Execute `claude --debug` e repita a ação para ver a resposta do classificador subjacente no log de depuração

175 215

216Quando uma verificação de segurança de API separada bloqueou a solicitação do classificador por causa do conteúdo anterior da conversa:

217

218```text theme={null}

219Auto mode could not evaluate this action and is blocking it for safety — a safety check separate from auto mode blocked this request because of earlier conversation content — it isn't about the action itself — run with --debug for details

220```

221

222**O que fazer:**

223

224* Esta não é uma decisão sobre sua ação. O conteúdo já em sua conversa acionou um filtro de segurança na API quando o modo automático enviou a conversa para o classificador

225* Tentar novamente não ajudará; o mesmo conteúdo de conversa acionará o filtro novamente

226* Mude para um [modo de permissão](/pt/permission-modes) diferente para que você possa aprovar a ação quando solicitado, ou inicie uma conversa nova sem o conteúdo que acionou

227

176Quando a conversa cresceu além da janela de contexto do classificador:228Quando a conversa cresceu além da janela de contexto do classificador:

177 229

178```text theme={null}230```text theme={null}

186* Aprove ou negue a ação no prompt que aparece238* Aprove ou negue a ação no prompt que aparece

187* Execute `/compact` para reduzir o tamanho da conversa para que as ações subsequentes se encaixem novamente na janela do classificador239* Execute `/compact` para reduzir o tamanho da conversa para que as ações subsequentes se encaixem novamente na janela do classificador

188 240

241<h3 id="agent-terminated-early-due-to-an-api-error">

242 Agent terminated early due to an API error

243</h3>

244

245{/* min-version: 2.1.199 */}A solicitação de API de um [subagente](/pt/sub-agents) falhou terminalmente, por exemplo, porque um limite de uso foi atingido ou as tentativas de um erro de servidor se esgotaram, portanto o subagente parou antes de terminar sua tarefa. Esta mensagem requer Claude Code v2.1.199 ou posterior; antes disso, o texto de erro da API era retornado para Claude como se fosse o resultado do subagente.

246

247```text theme={null}

248Agent terminated early due to an API error: <error detail>

249```

250

251**O que fazer:**

252

253* Corresponda o detalhe do erro após os dois pontos à sua própria seção nesta página, como [Limites de uso](#usage-limits) ou [Erros de servidor](#server-errors), e siga os passos dessa seção

254* Uma vez que o erro subjacente seja resolvido, peça ao Claude para tentar novamente a tarefa ou [retomar o subagente](/pt/sub-agents#resume-subagents)

255

256Quando um limite de taxa, sobrecarga ou erro de servidor interrompe um subagente em primeiro plano que já produziu saída, Claude recebe essa saída parcial marcada como incompleta em vez deste erro. Consulte [Erros de API em subagentes](/pt/sub-agents#api-errors-in-subagents).

257

189<h2 id="usage-limits">258<h2 id="usage-limits">

190 Limites de uso259 Limites de uso

191</h2>260</h2>

193Esses erros significam que uma cota vinculada à sua conta ou plano foi atingida. Eles são distintos dos [erros de servidor](#server-errors), que afetam todos.262Esses erros significam que uma cota vinculada à sua conta ou plano foi atingida. Eles são distintos dos [erros de servidor](#server-errors), que afetam todos.

194 263

195<h3 id="you’ve-hit-your-session-limit">264<h3 id="you’ve-hit-your-session-limit">

196 Você atingiu seu limite de sessão265 You've hit your session limit

197</h3>266</h3>

198 267

199Os planos de assinatura incluem uma permissão de uso contínua. Quando acaba, você vê uma dessas mensagens:268Os planos de assinatura incluem uma permissão de uso contínua. Quando acaba, você vê uma dessas mensagens:

210 279

211* Aguarde o tempo de reset mostrado no erro280* Aguarde o tempo de reset mostrado no erro

212* Execute `/usage` para ver seus limites de plano e quando eles são redefinidos281* Execute `/usage` para ver seus limites de plano e quando eles são redefinidos

213* Execute `/usage-credits` para comprar uso adicional em Pro e Max, ou para solicitá-lo ao seu administrador em Team e Enterprise. Consulte [usage credits for paid plans](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) para saber como isso é cobrado.282* Execute `/usage-credits` para comprar uso adicional em Pro e Max, ou para solicitá-lo ao seu administrador em Team e Enterprise. Consulte [extra usage for paid Claude plans](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) para saber como isso é cobrado.

214* Para atualizar seu plano para limites de base mais altos, consulte [claude.com/pricing](https://claude.com/pricing)283* Para atualizar seu plano para limites de base mais altos, consulte [claude.com/pricing](https://claude.com/pricing)

215 284

216Para monitorar sua permissão restante antes de atingir o limite, adicione os campos `rate_limits` a uma [linha de status personalizada](/pt/statusline#rate-limit-usage), ou no aplicativo Desktop clique no [anel de uso](/pt/desktop#check-usage) ao lado do seletor de modelo.285Para monitorar sua permissão restante antes de atingir o limite, adicione os campos `rate_limits` a uma [linha de status personalizada](/pt/statusline#rate-limit-usage), ou no aplicativo Desktop clique no [anel de uso](/pt/desktop#check-usage) ao lado do seletor de modelo.

217 286

218<h3 id="usage-credits-required-for-1m-context">287<h3 id="usage-credits-required-for-1m-context">

219 Créditos de uso necessários para contexto de 1M288 Usage credits required for 1M context

220</h3>289</h3>

221 290

222O modelo selecionado usa a janela de contexto estendida de 1M tokens, e seu plano inclui apenas através de créditos de uso.291O modelo selecionado usa a janela de contexto estendida de 1M tokens, e seu plano inclui apenas através de créditos de uso.

237* Para remover variantes de 1M do seletor de modelo completamente, defina [`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`](/pt/env-vars)306* Para remover variantes de 1M do seletor de modelo completamente, defina [`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`](/pt/env-vars)

238 307

239<h3 id="server-is-temporarily-limiting-requests">308<h3 id="server-is-temporarily-limiting-requests">

240 O servidor está limitando temporariamente as solicitações309 Server is temporarily limiting requests

241</h3>310</h3>

242 311

243A API aplicou um throttle de curta duração que não está relacionado à sua cota de plano.312A API aplicou um throttle de curta duração que não está relacionado à sua cota de plano.

246API Error: Server is temporarily limiting requests (not your usage limit)315API Error: Server is temporarily limiting requests (not your usage limit)

247```316```

248 317

249Isso é [repetido automaticamente](#automatic-retries) antes de ser mostrado.318Claude Code diferencia esses dos seus limites de plano pela ausência dos cabeçalhos de cota unificados que uma resposta de limite real carrega. {/* min-version: 2.1.199 */}A partir da v2.1.199, isso é [repetido automaticamente](#automatic-retries) com backoff antes de ser mostrado, independentemente de como você se autentica. Em versões anteriores, uma sessão conectada com uma assinatura claude.ai falhou o turno na primeira ocorrência; apenas autenticações de chave de API e Enterprise o repetiram.

250 319

251**O que fazer:**320**O que fazer:**

252 321

254* Verifique [status.claude.com](https://status.claude.com) se persistir323* Verifique [status.claude.com](https://status.claude.com) se persistir

255 324

256<h3 id="request-rejected-429">325<h3 id="request-rejected-429">

257 Solicitação rejeitada (429)326 Request rejected (429)

258</h3>327</h3>

259 328

260Você atingiu o limite de taxa configurado para sua chave de API, projeto Amazon Bedrock ou projeto Google Vertex AI.329Você atingiu o limite de taxa configurado para sua chave de API, projeto Amazon Bedrock ou projeto Google Vertex AI.

273* Reduza a concorrência: reduza [`CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY`](/pt/env-vars), evite executar muitos subagentes paralelos ou mude para um modelo menor com `/model` para execuções de script de alto volume342* Reduza a concorrência: reduza [`CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY`](/pt/env-vars), evite executar muitos subagentes paralelos ou mude para um modelo menor com `/model` para execuções de script de alto volume

274 343

275<h3 id="credit-balance-is-too-low">344<h3 id="credit-balance-is-too-low">

276 Saldo de crédito muito baixo345 Credit balance is too low

277</h3>346</h3>

278 347

279Sua organização Console ficou sem créditos pré-pagos.348Sua organização Console ficou sem créditos pré-pagos.

402Your organization has disabled Claude subscription access for Claude Code · Use an Anthropic API key instead, or ask your admin to enable access471Your organization has disabled Claude subscription access for Claude Code · Use an Anthropic API key instead, or ask your admin to enable access

403```472```

404 473

405Esta é uma configuração de organização do lado do servidor, portanto não pode ser substituída por configurações locais, variáveis de ambiente ou sinalizadores CLI. O Agent SDK e o modo não interativo `-p` apresentam isso como o código de erro `oauth_org_not_allowed`.474Esta é uma configuração de organização do lado do servidor, portanto não pode ser substituída por configurações locais, variáveis de ambiente ou sinalizadores CLI.

475

476O Agent SDK e o modo não interativo `-p` apresentam isso como o código de erro `oauth_org_not_allowed`.

406 477

407**O que fazer:**478**O que fazer:**

408 479

477 548

478* Execute `/login` para criar um novo token com os escopos atuais. Você não precisa fazer logout primeiro.549* Execute `/login` para criar um novo token com os escopos atuais. Você não precisa fazer logout primeiro.

479 550

551<h3 id="aws-credentials-expired-or-invalid">

552 AWS credentials expired or invalid

553</h3>

554

555{/* min-version: 2.1.198 */}Esta mensagem requer Claude Code v2.1.198 ou posterior e aparece apenas quando [`awsAuthRefresh`](/pt/amazon-bedrock#advanced-credential-configuration) está definido no seu arquivo de configurações. Seu token de sessão AWS expirou ou foi rejeitado, e a atualização automática que Claude Code já executou não produziu uma credencial que a API aceita. Aparece em um 401 de [Claude Platform on AWS](/pt/claude-platform-on-aws) ou do [endpoint Mantle](/pt/amazon-bedrock#use-the-mantle-endpoint), que é como esses provedores relatam um token de segurança expirado.

556

557A dica de ação no meio nomeia o comando `awsAuthRefresh` do seu arquivo de configurações, portanto varia. A parte estável é o `AWS credentials expired or invalid` inicial:

558

559```text theme={null}

560AWS credentials expired or invalid · run /login and select "Claude Platform on AWS · refresh credentials", or run `aws sso login --profile myprofile` in another terminal · API Error: 401 ...

561```

562

563Sem `awsAuthRefresh` configurado, o mesmo 401 mostra a mensagem genérica `Please run /login` em vez disso, que não pode atualizar credenciais AWS.

564

565**O que fazer:**

566

567* Execute o comando `awsAuthRefresh` nomeado na mensagem, como `aws sso login --profile myprofile`, em outro terminal e complete o login do navegador, depois tente novamente

568* Em uma sessão interativa, execute `/login`, escolha **3rd-party platform**, depois selecione **Claude Platform on AWS · refresh credentials** em **Using 3rd-party platforms** para executar o mesmo comando sem reiniciar Claude Code. Consulte [Configure AWS credentials](/pt/claude-platform-on-aws#1-configure-aws-credentials)

569* Se o erro se repetir após o comando de atualização ter sucesso, confirme que a identidade é válida fora do Claude Code com `aws sts get-caller-identity` no mesmo shell e perfil

570

571<h3 id="aws-authentication-failed">

572 AWS authentication failed

573</h3>

574

575{/* min-version: 2.1.198 */}Esta mensagem requer Claude Code v2.1.198 ou posterior e aparece apenas quando [`awsAuthRefresh`](/pt/amazon-bedrock#advanced-credential-configuration) está definido no seu arquivo de configurações. Seu provedor AWS retornou um 403, ou [Amazon Bedrock](/pt/amazon-bedrock) retornou um 401.

576

577Claude Code não pode dizer qual causa você atingiu. Amazon Bedrock relata um token de segurança expirado como um 403, mas um 403 também é como ele relata uma negação de autorização, como um `AccessDeniedException` de uma permissão IAM ausente ou um modelo que não está habilitado para sua conta.

578

579Um 401 do Amazon Bedrock também chega aqui em vez de em [AWS credentials expired or invalid](#aws-credentials-expired-or-invalid), porque Bedrock não relata um token expirado como um 401. Um 401 desse endpoint geralmente vem de algo mais no caminho da solicitação, como um proxy corporativo.

580

581Uma atualização de credencial corrige um token expirado e não pode corrigir as outras causas, portanto a mensagem oferece ambas:

582

583```text theme={null}

584AWS authentication failed · run /login and select "Claude Platform on AWS · refresh credentials", or run `aws sso login --profile myprofile` in another terminal · if credentials are current, check AWS permissions and model access · API Error: 403 ...

585```

586

587A dica de ação no meio nomeia o comando `awsAuthRefresh` do seu arquivo de configurações, portanto varia. A parte estável é o `AWS authentication failed` inicial.

588

589**O que fazer:**

590

591* Execute o comando `awsAuthRefresh` nomeado na mensagem, ou `aws sso login`, no caso de uma credencial expirada ser a causa

592* Se suas credenciais estão atuais, confirme que as permissões IAM em [IAM configuration](/pt/amazon-bedrock#iam-configuration) estão anexadas à identidade que você está usando e que o modelo selecionado está habilitado para sua conta e região

593* Execute `aws sts get-caller-identity` para confirmar qual identidade suas solicitações usam; um `AWS_PROFILE` obsoleto ou perfil padrão é uma causa comum de incompatibilidade de permissão

594

480<h2 id="network-and-connection-errors">595<h2 id="network-and-connection-errors">

481 Erros de rede e conexão596 Erros de rede e conexão

482</h2>597</h2>

525Unable to connect to API: Self-signed certificate detected640Unable to connect to API: Self-signed certificate detected

526```641```

527 642

643{/* min-version: 2.1.199 */}A partir da v2.1.199, uma falha de validação de certificado não é repetida, portanto este erro aparece na primeira tentativa em vez de após o [orçamento de tentativa](#automatic-retries) completo. Versões anteriores gastavam alguns minutos tentando antes de mostrá-lo. Condições TLS transitórias, como um tempo limite de handshake, ainda são repetidas.

644

645Durante `/login` e a verificação de conectividade de inicialização, a mesma falha é relatada com o código OpenSSL e a correção inline:

646

647```text theme={null}

648SSL certificate error (UNABLE_TO_GET_ISSUER_CERT_LOCALLY). If you are behind a corporate proxy or TLS-intercepting firewall, set NODE_EXTRA_CA_CERTS to your CA bundle path, or ask IT to allowlist *.anthropic.com. Run /doctor for details.

649```

650

528**O que fazer:**651**O que fazer:**

529 652

530* Exporte o pacote CA da sua organização e aponte o Claude Code para ele com `NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.pem`653* Exporte o pacote CA da sua organização e aponte o Claude Code para ele com `NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.pem`

811* Se você não conseguir identificar qual turno causou, execute `/clear` para iniciar uma conversa nova no mesmo projeto. Sua conversa anterior é preservada em disco e permanece disponível em `/resume`.934* Se você não conseguir identificar qual turno causou, execute `/clear` para iniciar uma conversa nova no mesmo projeto. Sua conversa anterior é preservada em disco e permanece disponível em `/resume`.

812* Em [modo não interativo](/pt/headless) (`-p`), onde rewind não está disponível, tente novamente com um prompt reformulado em uma nova sessão sem `--continue`. As verificações de política variam por modelo, portanto, mudar para um modelo diferente com `--model` também pode resolver a recusa em alguns casos.935* Em [modo não interativo](/pt/headless) (`-p`), onde rewind não está disponível, tente novamente com um prompt reformulado em uma nova sessão sem `--continue`. As verificações de política variam por modelo, portanto, mudar para um modelo diferente com `--model` também pode resolver a recusa em alguns casos.

813 936

937<h2 id="command-line-errors">

938 Erros de linha de comando

939</h2>

940

941Esses erros vêm da validação própria do Claude Code da linha de comando `claude`. Claude Code os imprime imediatamente, antes de criar uma sessão ou enviar qualquer solicitação de API.

942

943<h3 id="conflict-between-bg-and-print">

944 Conflict between --bg and --print

945</h3>

946

947Esta mensagem requer Claude Code v2.1.198 ou posterior. Você combinou `--bg` com `-p` ou `--print` na mesma invocação `claude`. `--bg` inicia uma [sessão em background](/pt/agent-view#from-your-shell) que você depois anexa com `claude agents`, enquanto `--print` executa [não interativamente](/pt/headless) e nunca inicia a sessão interativa que `claude agents` anexa. Antes da v2.1.198, essa combinação criava silenciosamente um trabalho em background que nunca poderia ser anexado.

948

949```text theme={null}

950--bg and --print conflict: --print never starts the interactive session that `claude agents` attaches to, so the job would be unattachable. The prompt is the positional — drop --print: `claude --bg '<task>'`.

951```

952

953**O que fazer:**

954

955* Solte `-p` ou `--print`. `--bg` toma o prompt como seu argumento posicional, portanto `claude --bg "<task>"` é o comando completo. Consulte [Dispatch new agents from your shell](/pt/agent-view#from-your-shell).

956* Para executar o prompt não interativamente e imprimir o resultado em vez de criar uma sessão em background, solte `--bg` e execute `claude -p "<task>"`

957

814<h2 id="responses-seem-lower-quality-than-usual">958<h2 id="responses-seem-lower-quality-than-usual">

815 As respostas parecem ter qualidade inferior ao usual959 Respostas parecem de qualidade inferior ao usual

816</h2>960</h2>

817 961

818Se as respostas do Claude parecem menos capazes do que você espera, mas nenhum erro é exibido, a causa geralmente é o estado da conversa em vez do modelo em si. O Claude Code não muda silenciosamente versões de modelo. Ele pode mudar para um modelo fallback em três casos específicos:962Se as respostas do Claude parecem menos capazes do que você espera, mas nenhum erro é exibido, a causa geralmente é o estado da conversa em vez do modelo em si. O Claude Code não muda silenciosamente versões de modelo. Ele pode mudar para um modelo fallback em três casos específicos:

838 Relatar um erro982 Relatar um erro

839</h2>983</h2>

840 984

841Esta página cobre erros da API Claude. Para erros de outros componentes do Claude Code, consulte o guia relevante:985Para erros de componentes que esta página não cobre, consulte o guia relevante:

842 986

843* Servidor MCP falhou ao conectar ou autenticar: [MCP](/pt/mcp)987* Servidor MCP falhou ao conectar ou autenticar: [MCP](/pt/mcp)

844* Script hook falhou ou bloqueou uma ferramenta: [Debug hooks](/pt/hooks#debug-hooks)988* Script hook falhou ou bloqueou uma ferramenta: [Debug hooks](/pt/hooks#debug-hooks)

845* Permissão negada ou erros de sistema de arquivos durante instalação: [Troubleshooting installation and login](/pt/troubleshoot-install)989* Permissão negada ou erros de sistema de arquivos durante instalação: [Troubleshoot installation and login](/pt/troubleshoot-install)

846 990

847Se um erro não estiver listado aqui ou a correção sugerida não ajudar:991Se um erro não estiver listado aqui ou a correção sugerida não ajudar:

848 992

fullscreen.md +5 −3

Details

58* **Clique em uma sugestão no comando `/` ou na lista de arquivo `@`** para aceitá-la. Passar o mouse destaca a linha sob seu cursor.58* **Clique em uma sugestão no comando `/` ou na lista de arquivo `@`** para aceitá-la. Passar o mouse destaca a linha sob seu cursor.

59* **Clique em uma opção em um menu de seleção** para escolhê-la. Isso cobre prompts de permissão, `/model`, `/config` e outros diálogos que mostram uma lista de opções. Passar o mouse mostra um ponteiro na linha sob seu cursor. Requer Claude Code v2.1.187 ou posterior.59* **Clique em uma opção em um menu de seleção** para escolhê-la. Isso cobre prompts de permissão, `/model`, `/config` e outros diálogos que mostram uma lista de opções. Passar o mouse mostra um ponteiro na linha sob seu cursor. Requer Claude Code v2.1.187 ou posterior.

60* **Clique em um resultado de ferramenta recolhido** para expandi-lo e ver a saída completa. Clique novamente para recolher. A chamada de ferramenta e seu resultado se expandem juntos. Apenas mensagens que têm mais a mostrar são clicáveis.60* **Clique em um resultado de ferramenta recolhido** para expandi-lo e ver a saída completa. Clique novamente para recolher. A chamada de ferramenta e seu resultado se expandem juntos. Apenas mensagens que têm mais a mostrar são clicáveis.

61* **Mantenha `Cmd` no macOS, ou `Ctrl` no Linux e Windows, e clique em uma URL ou caminho de arquivo** para abri-lo. Caminhos de arquivo na saída da ferramenta, como os impressos após um Edit ou Write, abrem no seu aplicativo padrão. URLs simples `http://` e `https://` abrem no seu navegador. A partir da v2.1.181, um clique simples sem manter `Cmd` ou `Ctrl` não abre mais links, correspondendo ao comportamento do terminal nativo. No terminal integrado do VS Code e terminais semelhantes baseados em xterm.js, Claude Code defere para o próprio manipulador de links do terminal, que usa o mesmo gesto.61* **Mantenha `Cmd` no macOS, ou `Ctrl` no Linux e Windows, e clique em uma URL ou caminho de arquivo** para abri-lo. Caminhos de arquivo na saída da ferramenta, como os impressos após um Edit ou Write, abrem no seu aplicativo padrão. URLs simples `http://` e `https://` abrem no seu navegador. A partir da v2.1.181, um clique simples sem manter `Cmd` ou `Ctrl` não abre mais links, correspondendo ao comportamento do terminal nativo. Alguns terminais macOS encaminham `Cmd`+clique para o aplicativo em execução em vez de abrir o link eles mesmos, e o protocolo de mouse do terminal não tem como codificar a tecla `Cmd`, então Claude Code a recebe como um clique simples. No Ghostty, e a partir da v2.1.198 no Warp no macOS, Claude Code detecta isso e permite que um clique simples em um link o abra, e manter `Cmd` ainda funciona. No terminal integrado do VS Code e terminais semelhantes baseados em xterm.js, Claude Code defere para o próprio manipulador de links do terminal, que usa o mesmo gesto.

62* **Clique e arraste** para selecionar texto em qualquer lugar da conversa. Clique duplo seleciona uma palavra, correspondendo aos limites de palavra do iTerm2 para que um caminho de arquivo seja selecionado como uma unidade. Clique triplo seleciona a linha.62* **Clique e arraste** para selecionar texto em qualquer lugar da conversa. Clique duplo seleciona uma palavra, correspondendo aos limites de palavra do iTerm2 para que um caminho de arquivo seja selecionado como uma unidade. A partir da v2.1.198, clicar duas vezes em uma URL seleciona a URL inteira, incluindo o esquema. Clique triplo seleciona a linha.

63* **Role com a roda do mouse** para se mover pela conversa.63* **Role com a roda do mouse** para se mover pela conversa.

64 64

65O texto selecionado é copiado para sua área de transferência automaticamente ao soltar o mouse. Para desativar isso, alterne Copiar ao selecionar em `/config`. Com isso desativado, pressione `Ctrl+Shift+c` para copiar manualmente. Em terminais que suportam o protocolo de teclado kitty, como kitty, WezTerm, Ghostty e iTerm2, `Cmd+c` também funciona. Se você tiver uma seleção ativa, `Ctrl+c` copia em vez de cancelar.65O texto selecionado é copiado para sua área de transferência automaticamente ao soltar o mouse. Para desativar isso, alterne Copiar ao selecionar em `/config`.

67Com Copiar ao selecionar desativado, pressione `Ctrl+Shift+c` para copiar manualmente. Em terminais que suportam o protocolo de teclado kitty, como kitty, WezTerm, Ghostty e iTerm2, `Cmd+c` também funciona. Se você tiver uma seleção ativa, `Ctrl+c` copia em vez de cancelar.

66 68

67Com uma seleção ativa, mantenha `Shift` pressionado e pressione as teclas de seta para estendê-la a partir do teclado. `Shift+↑` e `Shift+↓` rolam a janela de visualização quando a seleção atinge a borda superior ou inferior. `Shift+Home` e `Shift+End` estendem para o início ou fim da linha atual.69Com uma seleção ativa, mantenha `Shift` pressionado e pressione as teclas de seta para estendê-la a partir do teclado. `Shift+↑` e `Shift+↓` rolam a janela de visualização quando a seleção atinge a borda superior ou inferior. `Shift+Home` e `Shift+End` estendem para o início ou fim da linha atual.

68 70

gateways.md +1 −1

Details

44 Claude apps gateway44 Claude apps gateway

45</h3>45</h3>

46 46

47Claude apps gateway é o gateway auto-hospedado da Anthropic, incluído no binário `claude`. Ele roteia para Amazon Bedrock, Google Cloud, Microsoft Foundry ou a API Anthropic como upstream. Os desenvolvedores fazem login com seu provedor de identidade corporativa através de `/login`, o gateway impõe acesso a modelo e [configurações gerenciadas](/pt/permissions#managed-settings) por grupo IdP, e emite métricas de uso [OpenTelemetry Protocol (OTLP)](/pt/monitoring-usage) para sua própria pilha de observabilidade.47Claude apps gateway é o gateway auto-hospedado da Anthropic, incluído no binário `claude`. Ele roteia para Amazon Bedrock, Claude Platform on AWS, Google Cloud, Microsoft Foundry ou a API Anthropic como upstream. Os desenvolvedores fazem login com seu provedor de identidade corporativa através de `/login`, o gateway impõe acesso a modelo e [configurações gerenciadas](/pt/permissions#managed-settings) por grupo IdP, e emite métricas de uso [OpenTelemetry Protocol (OTLP)](/pt/monitoring-usage) para sua própria pilha de observabilidade.

48 48

49Como é construído e testado junto com cada lançamento de Claude Code, ele encaminha os cabeçalhos e campos de solicitação que Claude Code envia. Um gateway mantido separadamente precisa ter suas [regras de encaminhamento atualizadas](/pt/llm-gateway-protocol#forward-as-open-lists) conforme esses cabeçalhos e campos mudam a cada lançamento; Claude apps gateway é lançado com a CLI, portanto não há lista para manter atualizada. Veja [Disponibilidade e limitações](/pt/claude-apps-gateway#availability-and-limitations) para o pequeno conjunto de recursos que se comportam de forma diferente em uma sessão de gateway.49Como é construído e testado junto com cada lançamento de Claude Code, ele encaminha os cabeçalhos e campos de solicitação que Claude Code envia. Um gateway mantido separadamente precisa ter suas [regras de encaminhamento atualizadas](/pt/llm-gateway-protocol#forward-as-open-lists) conforme esses cabeçalhos e campos mudam a cada lançamento; Claude apps gateway é lançado com a CLI, portanto não há lista para manter atualizada. Veja [Disponibilidade e limitações](/pt/claude-apps-gateway#availability-and-limitations) para o pequeno conjunto de recursos que se comportam de forma diferente em uma sessão de gateway.

50 50

hooks.md +79 −43

Details

16 Ciclo de vida do hook16 Ciclo de vida do hook

17</h2>17</h2>

18 18

19Hooks disparam em pontos específicos durante uma sessão do Claude Code. Quando um evento dispara e um matcher corresponde, o Claude Code passa contexto JSON sobre o evento para seu manipulador de hook. Para hooks de comando, a entrada chega em stdin. Para hooks HTTP, chega como corpo da solicitação POST. Seu manipulador pode então inspecionar a entrada, tomar ação e opcionalmente retornar uma decisão. Os eventos caem em três cadências: uma vez por sessão (`SessionStart`, `SessionEnd`), uma vez por turno (`UserPromptSubmit`, `Stop`, `StopFailure`) e em cada chamada de ferramenta dentro do loop agentic (`PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PostToolBatch`, `SubagentStart`, `SubagentStop`, `TaskCreated`, `TaskCompleted`):19Hooks disparam em pontos específicos durante uma sessão do Claude Code. Quando um evento dispara e um matcher corresponde, o Claude Code passa contexto JSON sobre o evento para seu manipulador de hook. Para hooks de comando, a entrada chega em stdin. Para hooks HTTP, chega como corpo da solicitação POST. Seu manipulador pode então inspecionar a entrada, tomar ação e opcionalmente retornar uma decisão.

21Os eventos caem em três cadências:

23* uma vez por sessão: `SessionStart` e `SessionEnd`

24* uma vez por turno: `UserPromptSubmit`, `Stop` e `StopFailure`

25* em cada chamada de ferramenta dentro do loop agentic: `PreToolUse` e `PostToolUse`

20 26

21<div style={{maxWidth: "500px", margin: "0 auto"}}>27<div style={{maxWidth: "500px", margin: "0 auto"}}>

22 <Frame>28 <Frame>

217| `Notification` | tipo de notificação | `permission_prompt`, `idle_prompt`, `auth_success`, `elicitation_dialog`, `elicitation_complete`, `elicitation_response` |223| `Notification` | tipo de notificação | `permission_prompt`, `idle_prompt`, `auth_success`, `elicitation_dialog`, `elicitation_complete`, `elicitation_response`, `agent_needs_input`, `agent_completed` |

317 323

318Todos os hooks correspondentes executam em paralelo, e manipuladores idênticos são automaticamente desduplicados. Hooks de comando são desduplicados por string de comando e `args`, e hooks HTTP são desduplicados por URL.324Todos os hooks correspondentes executam em paralelo, e manipuladores idênticos são automaticamente desduplicados. Hooks de comando são desduplicados por string de comando e `args`, e hooks HTTP são desduplicados por URL.

319 325

320Manipuladores executam no diretório atual com o ambiente do Claude Code. A variável de ambiente `$CLAUDE_CODE_REMOTE` é definida como `"true"` em ambientes web remotos e não é definida na CLI local.326Manipuladores executam no diretório atual com o ambiente do Claude Code. A variável de ambiente `$CLAUDE_CODE_REMOTE` é definida como `"true"` em ambientes web remotos e não é definida na CLI local. {/* min-version: 2.1.199 */}A partir de v2.1.199, [`$CLAUDE_CODE_BRIDGE_SESSION_ID`](/pt/env-vars) é definido para o ID de sessão [Remote Control](/pt/remote-control) enquanto a sessão local tem uma conexão Remote Control ativa.

321 327

322<h4 id="common-fields">328<h4 id="common-fields">

323 Campos comuns329 Campos comuns

704Código de saída 2 é a forma de um hook sinalizar "pare, não faça isso". O efeito depende do evento, porque alguns eventos representam ações que podem ser bloqueadas (como uma chamada de ferramenta que ainda não aconteceu) e outros representam coisas que já aconteceram ou não podem ser prevenidas.710Código de saída 2 é a forma de um hook sinalizar "pare, não faça isso". O efeito depende do evento, porque alguns eventos representam ações que podem ser bloqueadas (como uma chamada de ferramenta que ainda não aconteceu) e outros representam coisas que já aconteceram ou não podem ser prevenidas.

705 711

707| :-------------------- | :------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------- |713| :-------------------- | :------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------- |

708| `PreToolUse` | Sim | Bloqueia a chamada da ferramenta |714| `PreToolUse` | Sim | Bloqueia a chamada da ferramenta |

709| `PermissionRequest` | Sim | Nega a permissão |715| `PermissionRequest` | Sim | Nega a permissão |

710| `UserPromptSubmit` | Sim | Bloqueia o processamento de prompt e apaga o prompt |716| `UserPromptSubmit` | Sim | Bloqueia o processamento de prompt e apaga o prompt |

711| `UserPromptExpansion` | Sim | Bloqueia a expansão |717| `UserPromptExpansion` | Sim | Bloqueia a expansão |

712| `Stop` | Sim | Previne Claude de parar, continua a conversa |718| `Stop` | Sim | Previne Claude de parar, continua a conversa |

713| `SubagentStop` | Sim | Previne o subagente de parar |719| `SubagentStop` | Sim | Previne o subagente de parar |

714| `TeammateIdle` | Sim | Previne o colega de ficar ocioso (colega continua trabalhando) |720| `TeammateIdle` | Sim | Previne o colega de ficar ocioso, para que continue trabalhando |

715| `TaskCreated` | Sim | Reverte a criação de tarefa |721| `TaskCreated` | Sim | Reverte a criação de tarefa |

716| `TaskCompleted` | Sim | Previne a tarefa de ser marcada como concluída |722| `TaskCompleted` | Sim | Previne a tarefa de ser marcada como concluída |

717| `ConfigChange` | Sim | Bloqueia a mudança de configuração de entrar em efeito (exceto `policy_settings`) |723| `ConfigChange` | Sim | Bloqueia a mudança de configuração de entrar em efeito (exceto `policy_settings`) |

718| `StopFailure` | Não | Saída e código de saída são ignorados |724| `StopFailure` | Não | Saída e código de saída são ignorados |

719| `PostToolUse` | Não | Mostra stderr ao Claude (ferramenta já executou) |725| `PostToolUse` | Não | Mostra stderr ao Claude; a ferramenta já executou |

720| `PostToolUseFailure` | Não | Mostra stderr ao Claude (ferramenta já falhou) |726| `PostToolUseFailure` | Não | Mostra stderr ao Claude; a ferramenta já falhou |

721| `PostToolBatch` | Sim | Para o loop agentic antes da próxima chamada de modelo |727| `PostToolBatch` | Sim | Para o loop agentic antes da próxima chamada de modelo |

722| `PermissionDenied` | Não | Código de saída e stderr são ignorados (negação já ocorreu). Use JSON `hookSpecificOutput.retry: true` para dizer ao modelo que pode tentar novamente |728| `PermissionDenied` | Não | Código de saída e stderr são ignorados porque a negação já ocorreu. Use JSON `hookSpecificOutput.retry: true` para dizer ao modelo que pode tentar novamente |

723| `Notification` | Não | Mostra stderr apenas ao usuário |729| `Notification` | Não | Mostra stderr apenas ao usuário |

724| `SubagentStart` | Não | Mostra stderr apenas ao usuário |730| `SubagentStart` | Não | Mostra stderr apenas ao usuário |

725| `SessionStart` | Não | Mostra stderr apenas ao usuário |731| `SessionStart` | Não | Mostra stderr apenas ao usuário |

736| `InstructionsLoaded` | Não | Código de saída é ignorado |742| `InstructionsLoaded` | Não | Código de saída é ignorado |

737| `MessageDisplay` | Não | O texto original é exibido |743| `MessageDisplay` | Não | O texto original é exibido |

738 744

745Para `SessionStart`, `Setup` e `SubagentStart`, o stderr de código de saída 2 é renderizado na transcrição como um aviso `<hook name> hook error`, da mesma forma que um [erro não-bloqueador](#exit-code-output) faz. Claude não vê isso, e a sessão ou subagente prossegue. Para `SubagentStart`, o aviso aparece na própria transcrição do subagente, não na conversa pai.

746

747A partir do Claude Code v2.1.199, `SessionStart`, `Setup` e `SubagentStart` mostram stderr de código de saída 2 na transcrição. Versões anteriores o escreviam apenas no log de debug.

748

739<h3 id="http-response-handling">749<h3 id="http-response-handling">

740 Tratamento de resposta HTTP750 Tratamento de resposta HTTP

741</h3>751</h3>

963 Entrada de SessionStart973 Entrada de SessionStart

964</h4>974</h4>

965 975

966Além dos [campos de entrada comuns](#common-input-fields), hooks SessionStart recebem `source` e opcionalmente `model`, `agent_type` e `session_title`. O campo `source` indica como a sessão começou: `"startup"` para novas sessões, `"resume"` para sessões retomadas, `"clear"` após `/clear` ou `"compact"` após compactação. O campo `model` contém o identificador do modelo ativo. Pode ser omitido, por exemplo após `/clear` ou quando uma sessão é restaurada através de recuperação de conversa, então verifique o campo antes de lê-lo. Se você iniciar Claude Code com `claude --agent <name>`, um campo `agent_type` contém o nome do agente. O campo `session_title` carrega o título da sessão atual se um já estiver definido, por exemplo via `--name` ou `/rename`. Um hook que emite `sessionTitle` pode verificar `session_title` primeiro para evitar sobrescrever um título que o usuário definiu explicitamente.976Além dos [campos de entrada comuns](#common-input-fields), hooks SessionStart recebem `source` e opcionalmente `model`, `agent_type` e `session_title`:

977

978| Campo | Descrição |

979| :-------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

980| `source` | Como a sessão começou: `"startup"` para novas sessões, `"resume"` para sessões retomadas, `"clear"` após `/clear` ou `"compact"` após compactação |

981| `model` | O identificador do modelo ativo. Pode ser omitido, por exemplo após `/clear` ou quando uma sessão é restaurada através de recuperação de conversa, então verifique o campo antes de lê-lo |

982| `agent_type` | O nome do agente, presente quando você inicia Claude Code com `claude --agent <name>` |

983| `session_title` | O título da sessão atual se um já estiver definido, por exemplo via `--name` ou `/rename`. Um hook que emite `sessionTitle` pode verificar `session_title` primeiro para evitar sobrescrever um título que o usuário definiu explicitamente |

967 984

968```json theme={null}985```json theme={null}

969{986{

983Qualquer texto que seu script de hook imprima em stdout é adicionado como contexto para Claude. Além dos [campos de saída JSON](#json-output) disponíveis para todos os hooks, você pode retornar esses campos específicos do evento:1000Qualquer texto que seu script de hook imprima em stdout é adicionado como contexto para Claude. Além dos [campos de saída JSON](#json-output) disponíveis para todos os hooks, você pode retornar esses campos específicos do evento:

984 1001

985| Campo | Descrição |1002| Campo | Descrição |

986| :------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |1003| :------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

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

988| `initialUserMessage` | String usada como a primeira mensagem de usuário da sessão. Aplica-se em [modo não-interativo](/pt/headless) (`-p`), onde se torna o primeiro turno mesmo se nenhum prompt for fornecido. Se um prompt for fornecido, ele segue como o próximo turno. Diferentemente de `additionalContext`, que se anexa a um turno existente, isso cria o turno |1005| `initialUserMessage` | String usada como a primeira mensagem de usuário da sessão. Aplica-se em [modo não-interativo](/pt/headless) com a flag `-p`, onde se torna o primeiro turno mesmo se nenhum prompt for fornecido. Se um prompt for fornecido, ele segue como o próximo turno. Diferentemente de `additionalContext`, que se anexa a um turno existente, isso cria o turno |

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

991| `reloadSkills` | Boolean. Quando `true`, Claude Code re-escaneia os diretórios [skill](/pt/skills) e comando após os hooks SessionStart completarem, então skills que o hook instalou estão disponíveis na mesma sessão, começando com o primeiro prompt |1008| `reloadSkills` | Boolean. Quando `true`, Claude Code re-escaneia os diretórios [skill](/pt/skills) e comando após os hooks SessionStart completarem, então skills que o hook instalou estão disponíveis na mesma sessão, começando com o primeiro prompt |

1062 Setup1079 Setup

1063</h3>1080</h3>

1064 1081

1065Dispara apenas quando você lança Claude Code com `--init-only`, ou com `--init` ou `--maintenance` em modo de impressão (`-p`). Não dispara na inicialização normal. Use-o para instalação de dependência única ou limpeza agendada que você aciona explicitamente de CI ou scripts, separado da inicialização de sessão normal. Para inicialização por sessão, use [SessionStart](#sessionstart) em vez disso.1082Dispara apenas quando você lança Claude Code com `--init-only`, ou com `--init` ou `--maintenance` em [modo não-interativo](/pt/headless) com a flag `-p`. Não dispara na inicialização normal. Use-o para instalação de dependência única ou limpeza agendada que você aciona explicitamente de CI ou scripts, separado da inicialização de sessão normal. Para inicialização por sessão, use [SessionStart](#sessionstart) em vez disso.

1066 1083

1067O valor do matcher corresponde à flag CLI que acionou o hook:1084O valor do matcher corresponde à flag CLI que acionou o hook:

1068 1085

1073 1090

1074`--init-only` executa hooks Setup e hooks SessionStart com o matcher `startup`, depois sai sem iniciar uma conversa. `--init` e `--maintenance` disparam hooks Setup apenas quando combinados com `-p` (modo de impressão); em uma sessão interativa essas duas flags atualmente não disparam hooks Setup.1091`--init-only` executa hooks Setup e hooks SessionStart com o matcher `startup`, depois sai sem iniciar uma conversa. `--init` e `--maintenance` disparam hooks Setup apenas quando combinados com `-p`; em uma sessão interativa essas duas flags atualmente não disparam hooks Setup.

1075 1092

1076Porque Setup não dispara em cada lançamento, um plugin que precisa de uma dependência instalada não pode confiar apenas em Setup. O padrão prático é verificar a dependência no primeiro uso e instalar se ausente, por exemplo um hook ou skill que testa `${CLAUDE_PLUGIN_DATA}/node_modules` e executa `npm install` se ausente. Consulte o [diretório de dados persistentes](/pt/plugins-reference#persistent-data-directory) para onde armazenar dependências instaladas.1093Porque Setup não dispara em cada lançamento, um plugin que precisa de uma dependência instalada não pode confiar apenas em Setup. O padrão prático é verificar a dependência no primeiro uso e instalar se ausente, por exemplo um hook ou skill que testa `${CLAUDE_PLUGIN_DATA}/node_modules` e executa `npm install` se ausente. Consulte o [diretório de dados persistentes](/pt/plugins-reference#persistent-data-directory) para onde armazenar dependências instaladas.

1077 1094

1095 Controle de decisão de Setup1112 Controle de decisão de Setup

1096</h4>1113</h4>

1097 1114

1098Hooks Setup não podem bloquear. Na saída de código 2, stderr é mostrado ao usuário; em qualquer outro código de saída não-zero, stderr aparece apenas quando você lança com `--verbose`. Em ambos os casos a execução continua. Para passar informação para o contexto de Claude, retorne `additionalContext` em saída JSON; stdout simples é escrito apenas no log de debug. Além dos [campos de saída JSON](#json-output) disponíveis para todos os hooks, você pode retornar esses campos específicos do evento:1115Hooks Setup não podem bloquear. Qualquer código de saída não-zero, incluindo 2, superficializa stderr ao usuário como um aviso de `<hook name> hook error`, e a execução continua. Em [modo não-interativo](/pt/headless), a saída do hook aparece apenas quando você lança com `--verbose`.

1116

1117Para passar informação para o contexto de Claude, retorne `additionalContext` em saída JSON; stdout simples é escrito apenas no log de debug. Além dos [campos de saída JSON](#json-output) disponíveis para todos os hooks, você pode retornar esses campos específicos do evento:

1099 1118

1100| Campo | Descrição |1119| Campo | Descrição |

1101| :------------------ | :-------------------------------------------------------------------------------------- |1120| :------------------ | :-------------------------------------------------------------------------------------- |

1191* **Stdout de texto simples**: qualquer texto não-JSON escrito em stdout é adicionado como contexto1210* **Stdout de texto simples**: qualquer texto não-JSON escrito em stdout é adicionado como contexto

1192* **JSON com `additionalContext`**: use o formato JSON abaixo para mais controle. O campo `additionalContext` é adicionado como contexto1211* **JSON com `additionalContext`**: use o formato JSON abaixo para mais controle. O campo `additionalContext` é adicionado como contexto

1193 1212

1194Stdout simples é mostrado como saída de hook na transcrição. O campo `additionalContext` é adicionado mais discretamente.1213Stdout simples é mostrado como saída de hook na transcrição. O valor `additionalContext` é injetado como um lembrete do sistema que Claude lê sem uma entrada de transcrição visível.

1195 1214

1196Para bloquear um prompt, retorne um objeto JSON com `decision` definido para `"block"`:1215Para bloquear um prompt, retorne um objeto JSON com `decision` definido para `"block"`:

1197 1216

1215}1234}

1216```1235```

1217 1236

1218<Note>

1219 O formato JSON não é obrigatório para casos simples. Para adicionar contexto, você pode imprimir texto simples em stdout com saída 0. Use JSON quando precisar bloquear prompts ou quiser controle mais estruturado.

1220</Note>

~~1221~~

1222<h3 id="userpromptexpansion">1237<h3 id="userpromptexpansion">

1223 UserPromptExpansion1238 UserPromptExpansion

1224</h3>1239</h3>

1545Em `PostToolUse`, `tool_response` para uma chamada Agent concluída carrega o texto final do subagente junto com telemetria de uso. Leia esses campos para registrar custo por subagente de um hook:1560Em `PostToolUse`, `tool_response` para uma chamada Agent concluída carrega o texto final do subagente junto com telemetria de uso. Leia esses campos para registrar custo por subagente de um hook:

1546 1561

1548| :------------------ | :----- | :---------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------- |1563| :------------------ | :----- | :---------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

1549| `status` | string | `"completed"` | `"completed"` para chamadas síncronas, `"async_launched"` para `run_in_background: true` |1564| `status` | string | `"completed"` | `"completed"` para subagentes em primeiro plano, `"async_launched"` para subagentes em background. {/* min-version: 2.1.198 */}A partir de v2.1.198, subagentes executam em background por padrão, então um `run_in_background` omitido também produz `"async_launched"` |

1551| `content` | array | `[{"type": "text", "text": "Found 12 endpoints..."}]` | Os blocos de texto final do subagente |1566| `content` | array | `[{"type": "text", "text": "Found 12 endpoints..."}]` | Os blocos de texto final do subagente |

1552| `resolvedModel` | string | `"claude-sonnet-4-5"` | Modelo que o subagente executou, que pode diferir do modelo solicitado. {/* min-version: 2.1.174 */}Requer Claude Code v2.1.174 ou posterior |1567| `resolvedModel` | string | `"claude-sonnet-4-5"` | Modelo que o subagente executou, que pode diferir do modelo solicitado. {/* min-version: 2.1.174 */}Requer Claude Code v2.1.174 ou posterior |

1556| `usage` | object | `{"input_tokens": 8320, ...}` | Divisão de tokens por tipo: `input_tokens`, `output_tokens`, `cache_creation_input_tokens`, `cache_read_input_tokens` |1571| `usage` | object | `{"input_tokens": 8320, ...}` | Divisão de tokens por tipo: `input_tokens`, `output_tokens`, `cache_creation_input_tokens`, `cache_read_input_tokens` |

1557 1572

1558Para chamadas `run_in_background: true`, a ferramenta retorna imediatamente após lançar o subagente, então `tool_response` não carrega campos de uso. Tem `status: "async_launched"`, `agentId`, `description`, `prompt`, `outputFile` e `resolvedModel` em vez disso.1573Para subagentes em background, a ferramenta retorna imediatamente após lançar, então `tool_response` não carrega campos de uso. Tem `status: "async_launched"`, `agentId`, `description`, `prompt`, `outputFile` e `resolvedModel`.

1559 1574

1560O campo `resolvedModel` nomeia o modelo que o subagente realmente executa, que pode diferir do valor `model` em `tool_input`, como quando `availableModels` ou outra sobrescrita se aplica. Requer Claude Code v2.1.174 ou posterior.1575O campo `resolvedModel` nomeia o modelo que o subagente realmente executa, que pode diferir do valor `model` em `tool_input`, como quando `availableModels` ou outra sobrescrita se aplica. Requer Claude Code v2.1.174 ou posterior.

1561 1576

1593Hooks `PreToolUse` podem controlar se uma chamada de ferramenta prossegue. Diferentemente de outros hooks que usam um campo `decision` de nível superior, PreToolUse retorna sua decisão dentro de um objeto `hookSpecificOutput`. Isso oferece controle mais rico: quatro resultados (permitir, negar, pedir ou adiar) além da capacidade de modificar entrada de ferramenta antes da execução.1608Hooks `PreToolUse` podem controlar se uma chamada de ferramenta prossegue. Diferentemente de outros hooks que usam um campo `decision` de nível superior, PreToolUse retorna sua decisão dentro de um objeto `hookSpecificOutput`. Isso oferece controle mais rico: quatro resultados (permitir, negar, pedir ou adiar) além da capacidade de modificar entrada de ferramenta antes da execução.

1594 1609

1595| Campo | Descrição |1610| Campo | Descrição |

1596| :------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |1611| :------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

1597| `permissionDecision` | `"allow"` ignora o prompt de permissão. `"deny"` previne a chamada da ferramenta. `"ask"` solicita ao usuário confirmar. `"defer"` sai graciosamente para que a ferramenta possa ser retomada mais tarde. [Regras de negação e pergunta](/pt/permissions#manage-permissions) ainda se aplicam independentemente do que o hook retorna |1612| `permissionDecision` | `"allow"` ignora o prompt de permissão, exceto para [ferramentas que requerem interação do usuário](#pretooluse-decision-control). `"deny"` previne a chamada da ferramenta. `"ask"` solicita ao usuário confirmar. `"defer"` sai graciosamente para que a ferramenta possa ser retomada mais tarde. [Regras de negação e pergunta](/pt/permissions#manage-permissions) ainda são avaliadas independentemente do que o hook retorna |

1598| `permissionDecisionReason` | Para `"allow"` e `"ask"`, mostrado ao usuário mas não ao Claude. Para `"deny"`, mostrado ao Claude. Para `"defer"`, ignorado |1613| `permissionDecisionReason` | Para `"allow"` e `"ask"`, mostrado ao usuário mas não ao Claude. Para `"deny"`, mostrado ao Claude. Para `"defer"`, ignorado |

1599| `updatedInput` | Modifica os parâmetros de entrada da ferramenta antes da execução. Substitui o objeto de entrada inteiro, então inclua campos inalterados junto com os modificados. Combine com `"allow"` para aprovação automática ou `"ask"` para mostrar a entrada modificada ao usuário. Para `"defer"`, ignorado |1614| `updatedInput` | Modifica os parâmetros de entrada da ferramenta antes da execução. Substitui o objeto de entrada inteiro, então inclua campos inalterados junto com os modificados. Combine com `"allow"` para aprovação automática ou `"ask"` para mostrar a entrada modificada ao usuário. Para `"defer"`, ignorado |

1600| `additionalContext` | String adicionada ao contexto de Claude junto com o resultado da ferramenta. Para `"defer"`, ignorado. Consulte [Adicionar contexto para Claude](#add-context-for-claude) |1615| `additionalContext` | String adicionada ao contexto de Claude junto com o resultado da ferramenta. Para `"defer"`, ignorado. Consulte [Adicionar contexto para Claude](#add-context-for-claude) |

1619 1634

1620`AskUserQuestion` e `ExitPlanMode` requerem interação do usuário e normalmente bloqueiam em [modo não-interativo](/pt/headless) com a flag `-p`. Retornar `permissionDecision: "allow"` junto com `updatedInput` satisfaz esse requisito: o hook lê a entrada da ferramenta de stdin, coleta a resposta através de sua própria UI e a retorna em `updatedInput` para que a ferramenta execute sem solicitar. Retornar `"allow"` sozinho não é suficiente para essas ferramentas. Para `AskUserQuestion`, ecoar de volta o array `questions` original e adicionar um objeto [`answers`](#askuserquestion) mapeando o texto de cada pergunta para a resposta escolhida.1635`AskUserQuestion` e `ExitPlanMode` requerem interação do usuário e normalmente bloqueiam em [modo não-interativo](/pt/headless) com a flag `-p`. Retornar `permissionDecision: "allow"` junto com `updatedInput` satisfaz esse requisito: o hook lê a entrada da ferramenta de stdin, coleta a resposta através de sua própria UI e a retorna em `updatedInput` para que a ferramenta execute sem solicitar. Retornar `"allow"` sozinho não é suficiente para essas ferramentas. Para `AskUserQuestion`, ecoar de volta o array `questions` original e adicionar um objeto [`answers`](#askuserquestion) mapeando o texto de cada pergunta para a resposta escolhida.

1621 1636

1637A partir de v2.1.199, uma ferramenta MCP cujo servidor a marca com [`_meta["anthropic/requiresUserInteraction"]`](/pt/mcp#require-approval-for-a-specific-tool) é mais rigorosa: um hook não pode pular seu prompt de aprovação com `"allow"`, com ou sem `updatedInput`, porque Claude Code não pode confirmar que o hook coletou a interação que a ferramenta precisa.

1638

1622<Note>1639<Note>

1623 PreToolUse anteriormente usava campos `decision` e `reason` de nível superior, mas esses estão deprecados para este evento. Use `hookSpecificOutput.permissionDecision` e `hookSpecificOutput.permissionDecisionReason` em vez disso. Os valores deprecados `"approve"` e `"block"` mapeiam para `"allow"` e `"deny"` respectivamente. Outros eventos como PostToolUse e Stop continuam usando `decision` e `reason` de nível superior como seu formato atual.1640 PreToolUse anteriormente usava campos `decision` e `reason` de nível superior, mas esses estão deprecados para este evento. Use `hookSpecificOutput.permissionDecision` e `hookSpecificOutput.permissionDecisionReason` em vez disso. Os valores deprecados `"approve"` e `"block"` mapeiam para `"allow"` e `"deny"` respectivamente. Outros eventos como PostToolUse e Stop continuam usando `decision` e `reason` de nível superior como seu formato atual.

1624</Note>1641</Note>

2016 Notification2033 Notification

2017</h3>2034</h3>

2018 2035

2019Executa quando Claude Code envia notificações. Corresponde no tipo de notificação: `permission_prompt`, `idle_prompt`, `auth_success`, `elicitation_dialog`, `elicitation_complete`, `elicitation_response`. Omita o matcher para executar hooks para todos os tipos de notificação.2036Executa quando Claude Code envia notificações. Corresponde no tipo de notificação. Omita o matcher para executar hooks para todos os tipos de notificação.

2037

2038| Matcher | Quando dispara |

2039| :--------------------- | :------------------------------------------------------------------------------------------------------------------------------------- |

2040| `permission_prompt` | Claude precisa que você aprove um uso de ferramenta |

2041| `idle_prompt` | Claude está feito e esperando seu próximo prompt |

2042| `auth_success` | Autenticação é concluída |

2043| `elicitation_dialog` | Um servidor MCP abre um formulário de elicitação |

2044| `elicitation_complete` | Um formulário de elicitação MCP é submetido ou descartado |

2045| `elicitation_response` | Uma resposta de elicitação MCP é enviada de volta ao servidor |

2046| `agent_needs_input` | Uma sessão em background começa esperando sua entrada. Dispara apenas enquanto [agent view](/pt/agent-view) está aberto em um terminal |

2047| `agent_completed` | Uma sessão em background termina ou falha. Dispara apenas enquanto [agent view](/pt/agent-view) está aberto em um terminal |

2048

2049Os tipos `agent_needs_input` e `agent_completed` requerem Claude Code v2.1.198 ou posterior.

2020 2050

2021Use matchers separados para executar diferentes manipuladores dependendo do tipo de notificação. Esta configuração aciona um script de alerta específico de permissão quando Claude precisa de aprovação de permissão e uma notificação diferente quando Claude está ocioso:2051Use matchers separados para executar diferentes manipuladores dependendo do tipo de notificação. Esta configuração aciona um script de alerta específico de permissão quando Claude precisa de aprovação de permissão e uma notificação diferente quando Claude está ocioso:

2022 2052

2079 Entrada de SubagentStart2109 Entrada de SubagentStart

2080</h4>2110</h4>

2081 2111

2082Além dos [campos de entrada comuns](#common-input-fields), hooks SubagentStart recebem `agent_id` com o identificador único para o subagente e `agent_type` com o nome do agente (agentes integrados como `"general-purpose"`, `"Explore"`, `"Plan"` ou nomes de agentes personalizados).2112Além dos [campos de entrada comuns](#common-input-fields), hooks SubagentStart recebem `agent_id` com o identificador único para o subagente e `agent_type` com o nome do agente que o matcher filtra.

2083 2113

2084```json theme={null}2114```json theme={null}

2085{2115{

2561Além dos [campos de saída JSON](#json-output) disponíveis para todos os hooks, hooks CwdChanged podem retornar `watchPaths` para definir dinamicamente quais caminhos de arquivo [FileChanged](#filechanged) monitora:2591Além dos [campos de saída JSON](#json-output) disponíveis para todos os hooks, hooks CwdChanged podem retornar `watchPaths` para definir dinamicamente quais caminhos de arquivo [FileChanged](#filechanged) monitora:

2562 2592

2563| Campo | Descrição |2593| Campo | Descrição |

2564| :----------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |2594| :----------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

2565| `watchPaths` | Array de caminhos absolutos. Substitui a lista de monitoramento dinâmica atual (caminhos de sua configuração `matcher` são sempre monitorados). Retornar um array vazio limpa a lista dinâmica, que é típico ao entrar em um novo diretório |2595| `watchPaths` | Array de caminhos absolutos. Substitui a lista de monitoramento dinâmica atual. Caminhos de sua configuração `matcher` são sempre monitorados. Retornar um array vazio limpa a lista dinâmica, que é típico ao entrar em um novo diretório |

2566 2596

2567Hooks CwdChanged não têm controle de decisão. Eles não podem bloquear a mudança de diretório.2597Hooks CwdChanged não têm controle de decisão. Eles não podem bloquear a mudança de diretório.

2568 2598

2586Além dos [campos de entrada comuns](#common-input-fields), hooks FileChanged recebem `file_path` e `event`.2616Além dos [campos de entrada comuns](#common-input-fields), hooks FileChanged recebem `file_path` e `event`.

2587 2617

2588| Campo | Descrição |2618| Campo | Descrição |

2589| :---------- | :---------------------------------------------------------------------------------------------------------- |2619| :---------- | :---------------------------------------------------------------------------------------------------------------------------- |

2591| `event` | O que aconteceu: `"change"` (arquivo modificado), `"add"` (arquivo criado) ou `"unlink"` (arquivo deletado) |2621| `event` | O que aconteceu: `"change"` para um arquivo modificado, `"add"` para um arquivo criado ou `"unlink"` para um arquivo deletado |

2592 2622

2593```json theme={null}2623```json theme={null}

2594{2624{

2608Além dos [campos de saída JSON](#json-output) disponíveis para todos os hooks, hooks FileChanged podem retornar `watchPaths` para atualizar dinamicamente quais caminhos de arquivo são monitorados:2638Além dos [campos de saída JSON](#json-output) disponíveis para todos os hooks, hooks FileChanged podem retornar `watchPaths` para atualizar dinamicamente quais caminhos de arquivo são monitorados:

2609 2639

2610| Campo | Descrição |2640| Campo | Descrição |

2611| :----------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |2641| :----------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

2612| `watchPaths` | Array de caminhos absolutos. Substitui a lista de monitoramento dinâmica atual (caminhos de sua configuração `matcher` são sempre monitorados). Use isso quando seu script de hook descobre arquivos adicionais para monitorar baseado no arquivo alterado |2642| `watchPaths` | Array de caminhos absolutos. Substitui a lista de monitoramento dinâmica atual. Caminhos de sua configuração `matcher` são sempre monitorados. Use isso quando seu script de hook descobre arquivos adicionais para monitorar baseado no arquivo alterado |

2613 2643

2614Hooks FileChanged não têm controle de decisão. Eles não podem bloquear a mudança de arquivo de ocorrer.2644Hooks FileChanged não têm controle de decisão. Eles não podem bloquear a mudança de arquivo de ocorrer.

2615 2645

2617 WorktreeCreate2647 WorktreeCreate

2618</h3>2648</h3>

2619 2649

2620Quando você executa `claude --worktree` ou um [subagente usa `isolation: "worktree"`](/pt/sub-agents#choose-the-subagent-scope), Claude Code cria uma cópia de trabalho isolada usando `git worktree`. Se você configurar um hook WorktreeCreate, ele substitui o comportamento git padrão, permitindo que você use um sistema de controle de versão diferente como SVN, Perforce ou Mercurial.2650Executa quando um worktree está sendo criado, seja de `claude --worktree` ou de um [subagente usando `isolation: "worktree"`](/pt/sub-agents#choose-the-subagent-scope). Por padrão Claude Code cria a cópia de trabalho isolada com `git worktree`. Configurar um hook WorktreeCreate substitui esse comportamento git padrão, permitindo que você use um sistema de controle de versão diferente como SVN, Perforce ou Mercurial.

2621 2651

2622Porque o hook substitui o comportamento padrão inteiramente, [`.worktreeinclude`](/pt/worktrees#copy-gitignored-files-into-worktrees) não é processado. Se você precisar copiar arquivos de configuração local como `.env` para o novo worktree, faça isso dentro de seu script de hook.2652Porque o hook substitui o comportamento padrão inteiramente, [`.worktreeinclude`](/pt/worktrees#copy-gitignored-files-into-worktrees) não é processado. Se você precisar copiar arquivos de configuração local como `.env` para o novo worktree, faça isso dentro de seu script de hook.

2623 2653

2648 Entrada de WorktreeCreate2678 Entrada de WorktreeCreate

2649</h4>2679</h4>

2650 2680

2651Além dos [campos de entrada comuns](#common-input-fields), hooks WorktreeCreate recebem o campo `name`. Este é um identificador slug para o novo worktree, especificado pelo usuário ou auto-gerado (por exemplo, `bold-oak-a3f2`).2681Além dos [campos de entrada comuns](#common-input-fields), hooks WorktreeCreate recebem o campo `name`. Este é um identificador slug para o novo worktree, especificado pelo usuário ou auto-gerado, por exemplo `bold-oak-a3f2`.

2652 2682

2653```json theme={null}2683```json theme={null}

2654{2684{

2675 WorktreeRemove2705 WorktreeRemove

2676</h3>2706</h3>

2677 2707

2678A contraparte de limpeza para [WorktreeCreate](#worktreecreate). Este hook dispara quando um worktree está sendo removido, seja quando você sai de uma sessão `--worktree` e escolhe removê-lo, ou quando um subagente com `isolation: "worktree"` termina. Para worktrees baseados em git, Claude lida com limpeza automaticamente com `git worktree remove`. Se você configurou um hook WorktreeCreate para um sistema de controle de versão não-git, emparelhe-o com um hook WorktreeRemove para lidar com limpeza. Sem um, o diretório worktree é deixado no disco.2708Executa quando um worktree está sendo removido, seja quando você sai de uma sessão `--worktree` e escolhe removê-lo, ou quando um subagente com `isolation: "worktree"` termina. Esta é a contraparte de limpeza para [WorktreeCreate](#worktreecreate).

2709

2710Para worktrees baseados em git, Claude Code lida com limpeza automaticamente com `git worktree remove`. Se você configurou um hook WorktreeCreate para um sistema de controle de versão não-git, emparelhe-o com um hook WorktreeRemove para lidar com limpeza. Sem um, o diretório worktree é deixado no disco.

2679 2711

2680Claude Code passa o caminho que WorktreeCreate retornou como `worktree_path` na entrada do hook. Este exemplo lê esse caminho e remove o diretório:2712Claude Code passa o caminho que WorktreeCreate retornou como `worktree_path` na entrada do hook. Este exemplo lê esse caminho e remove o diretório:

2681 2713

3064 3096

3065Se você precisar de controle mais fino em qualquer evento, use um [hook de comando](#command-hook-fields) com os campos por evento descritos em [Controle de decisão](#decision-control).3097Se você precisar de controle mais fino em qualquer evento, use um [hook de comando](#command-hook-fields) com os campos por evento descritos em [Controle de decisão](#decision-control).

3066 3098

3067<h3 id="example-multi-criteria-stop-hook">3099<h3 id="check-multiple-conditions-before-stopping">

3068 Exemplo: Hook Stop com múltiplos critérios3100 Verificar múltiplas condições antes de parar

3069</h3>3101</h3>

3070 3102

3071Este hook `Stop` usa um prompt detalhado para verificar três condições antes de permitir que Claude pare. Se `"ok"` for `false`, Claude continua trabalhando com a razão fornecida como sua próxima instrução. Hooks `SubagentStop` usam o mesmo formato para avaliar se um [subagente](/pt/sub-agents) deve parar:3103Este hook `Stop` usa um prompt detalhado para verificar três condições antes de permitir que Claude pare. Hooks `SubagentStop` usam o mesmo formato para avaliar se um [subagente](/pt/sub-agents) deve parar. Se `"ok"` for `false`, Claude continua trabalhando com a razão fornecida como sua próxima instrução:

3072 3104

3073```json theme={null}3105```json theme={null}

3074{3106{

3192 3224

3193Notificações de conclusão de hook assíncrono são suprimidas por padrão. Para vê-las, ative modo verbose com `Ctrl+O` ou inicie Claude Code com `--verbose`.3225Notificações de conclusão de hook assíncrono são suprimidas por padrão. Para vê-las, ative modo verbose com `Ctrl+O` ou inicie Claude Code com `--verbose`.

3194 3226

3195<h3 id="example-run-tests-after-file-changes">3227<h3 id="run-tests-after-file-changes">

3196 Exemplo: executar testes após mudanças de arquivo3228 Executar testes após mudanças de arquivo

3197</h3>3229</h3>

3198 3230

3199Este hook inicia uma suite de testes em background sempre que Claude escreve um arquivo, então relata os resultados de volta ao Claude quando os testes terminam. Salve este script em `.claude/hooks/run-tests-async.sh` em seu projeto e torne-o executável com `chmod +x`:3231Este hook inicia uma suite de testes em background sempre que Claude escreve um arquivo, então relata os resultados de volta ao Claude quando os testes terminam. Salve este script em `.claude/hooks/run-tests-async.sh` em seu projeto e torne-o executável com `chmod +x`:

3287 Ferramenta Windows PowerShell3319 Ferramenta Windows PowerShell

3288</h2>3320</h2>

3289 3321

3290No Windows, você pode executar hooks individuais em PowerShell definindo `"shell": "powershell"` em um hook de comando. Hooks geram PowerShell diretamente, então isso funciona independentemente de `CLAUDE_CODE_USE_POWERSHELL_TOOL` estar definido. Claude Code auto-detecta `pwsh.exe` (PowerShell 7+) com fallback para `powershell.exe` (5.1).3322No Windows, você pode executar hooks individuais em PowerShell definindo `"shell": "powershell"` em um hook de comando. Hooks geram PowerShell diretamente, então isso funciona independentemente de `CLAUDE_CODE_USE_POWERSHELL_TOOL` estar definido. Claude Code auto-detecta `pwsh.exe`, o executável do PowerShell 7 e posterior, e volta para `powershell.exe` para Windows PowerShell 5.1.

3291 3323

3292```json theme={null}3324```json theme={null}

3293{3325{

3308}3340}

3309```3341```

3310 3342

3311Para referenciar o diretório raiz do projeto a partir de um comando em forma de shell do PowerShell, leia-o como uma variável de ambiente com `$env:CLAUDE_PROJECT_DIR`. PowerShell trata a forma nua `${CLAUDE_PROJECT_DIR}` como uma variável local, não como uma busca de ambiente, e Claude Code substitui esse espaço reservado em forma de shell apenas para [hooks de plugin](#reference-scripts-by-path). Para um hook definido em `settings.json`, use a forma `$env:` ou mude para [forma exec](#exec-form-and-shell-form), onde `${CLAUDE_PROJECT_DIR}` é substituído em cada elemento `args` independentemente de onde o hook está definido.3343Para referenciar o diretório raiz do projeto a partir de um comando em forma de shell do PowerShell, escreva `${CLAUDE_PROJECT_DIR}` ou `$env:CLAUDE_PROJECT_DIR`. A partir da v2.1.198, Claude Code reescreve os espaços reservados `${CLAUDE_PROJECT_DIR}`, `${CLAUDE_PLUGIN_ROOT}` e `${CLAUDE_PLUGIN_DATA}` em um comando em forma de shell do PowerShell para a forma `${env:NAME}` do PowerShell, independentemente de o hook estar definido em `settings.json`, um plugin ou uma skill. PowerShell então resolve o valor do ambiente exportado após análise, então o espaço reservado funciona dentro de strings entre aspas duplas, mas não dentro de strings entre aspas simples, onde PowerShell nunca expande variáveis.

3344

3345Antes da v2.1.198, essa reescrita se aplicava apenas a hooks de plugin. Em versões anteriores, um hook `settings.json` precisa da forma `$env:` ou [forma exec](#exec-form-and-shell-form), onde `${CLAUDE_PROJECT_DIR}` é substituído em cada elemento `args` independentemente de onde o hook está definido.

3346

3347Não escreva a forma nua `$CLAUDE_PROJECT_DIR` em um hook do PowerShell. PowerShell a analisa como uma variável local indefinida e a resolve para `$null`, o que deixa o caminho do script sem seu prefixo de diretório raiz do projeto. Claude Code não reescreve essa forma; em vez disso, registra um aviso no [log de depuração](#debug-hooks).

3312 3348

3313O exemplo abaixo mostra um hook `settings.json` que executa um script de projeto com a forma `$env:`:3349O exemplo abaixo mostra um hook `settings.json` que executa um script de projeto com a forma `$env:`, que funciona em todas as versões:

3314 3350

3315```json theme={null}3351```json theme={null}

3316{3352{

hooks-guide.md +35 −31

Details

87 87

88Hooks permitem executar código em pontos-chave do ciclo de vida do Claude Code: formatar arquivos após edições, bloquear comandos antes de executarem, enviar notificações quando Claude precisa de entrada, injetar contexto no início da sessão e muito mais. Para a lista completa de eventos de hook, consulte a [referência de Hooks](/pt/hooks#hook-lifecycle).88Hooks permitem executar código em pontos-chave do ciclo de vida do Claude Code: formatar arquivos após edições, bloquear comandos antes de executarem, enviar notificações quando Claude precisa de entrada, injetar contexto no início da sessão e muito mais. Para a lista completa de eventos de hook, consulte a [referência de Hooks](/pt/hooks#hook-lifecycle).

89 89

~~90Cada exemplo inclui um bloco de configuração pronto para usar que você adiciona a um [arquivo de configuração](#configure-hook-location). Os padrões mais comuns:~~90Cada exemplo inclui um bloco de configuração pronto para usar que você adiciona a um [arquivo de configuração](#configure-hook-location).

~~92* [Receba notificações quando Claude precisa de entrada](#get-notified-when-claude-needs-input)~~

~~93* [Formatar código automaticamente após edições](#auto-format-code-after-edits)~~

~~94* [Bloquear edições em arquivos protegidos](#block-edits-to-protected-files)~~

~~95* [Re-injetar contexto após compactação](#re-inject-context-after-compaction)~~

~~96* [Auditar mudanças de configuração](#audit-configuration-changes)~~

~~97* [Recarregar ambiente quando diretório ou arquivos mudam](#reload-environment-when-directory-or-files-change)~~

~~98* [Aprovar automaticamente prompts de permissão específicos](#auto-approve-specific-permission-prompts)~~

99 91

100Para um exemplo de produção de hooks que executam uma revisão de modelo separada e alimentam as descobertas de volta à sessão, consulte [como o plugin `security-guidance` se integra com Claude Code](/pt/security-guidance#how-the-plugin-integrates-with-claude-code).92Para um exemplo de produção de hooks que executam uma revisão de modelo separada e alimentam as descobertas de volta à sessão, consulte [como o plugin `security-guidance` se integra com Claude Code](/pt/security-guidance#how-the-plugin-integrates-with-claude-code).

101 93

182O `matcher` vazio dispara em todos os tipos de notificação. Para disparar apenas em eventos específicos, defina-o como um destes valores:174O `matcher` vazio dispara em todos os tipos de notificação. Para disparar apenas em eventos específicos, defina-o como um destes valores:

183 175

184| Matcher | Dispara quando |176| Matcher | Dispara quando |

185| :--------------------- | :------------------------------------------------------------ |177| :--------------------- | :---------------------------------------------------------------------------------------------------------------------------------------- |

184| `agent_needs_input` | Uma sessão em segundo plano começa a aguardar sua entrada. Dispara apenas enquanto a [visualização de agente](/pt/agent-view) está aberta |

185| `agent_completed` | Uma sessão em segundo plano termina ou falha. Dispara apenas enquanto a [visualização de agente](/pt/agent-view) está aberta |

186

187Os matchers `agent_needs_input` e `agent_completed` exigem Claude Code v2.1.198 ou posterior.

192 188

193Digite `/hooks` e selecione `Notification` para confirmar que o hook está registrado. Para o esquema de evento completo, consulte a [referência de Notification](/pt/hooks#notification).189Digite `/hooks` e selecione `Notification` para confirmar que o hook está registrado. Para o esquema de evento completo, consulte a [referência de Notification](/pt/hooks#notification).

194 190

198 194

199Execute automaticamente [Prettier](https://prettier.io/) em cada arquivo que Claude edita, para que a formatação permaneça consistente sem intervenção manual.195Execute automaticamente [Prettier](https://prettier.io/) em cada arquivo que Claude edita, para que a formatação permaneça consistente sem intervenção manual.

200 196

201Este hook usa o evento `PostToolUse` com um matcher `Edit|Write`, para que execute apenas após ferramentas de edição de arquivo. {/* min-version: 2.1.191 */}No Claude Code v2.1.191 ou posterior, você também pode escrever o matcher como `Edit,Write`, já que `|` e `,` são separadores de lista intercambiáveis para matchers de nome de ferramenta nessas versões. O comando extrai o caminho do arquivo editado com [`jq`](https://jqlang.github.io/jq/) e o passa para Prettier. Adicione isto a `.claude/settings.json` na raiz do seu projeto:197Este hook usa o evento `PostToolUse` com um matcher `Edit|Write`, para que execute apenas após ferramentas de edição de arquivo. O comando extrai o caminho do arquivo editado com [`jq`](https://jqlang.github.io/jq/) e o passa para Prettier. Adicione isto a `.claude/settings.json` na raiz do seu projeto:

202 198

203```json theme={null}199```json theme={null}

204{200{

218}214}

219```215```

220 216

217No Claude Code v2.1.191 ou posterior, você também pode escrever o matcher como `Edit,Write`, já que `|` e `,` são separadores de lista intercambiáveis para matchers de nome de ferramenta nessas versões.

218

221<Note>219<Note>

222 Os exemplos Bash nesta página usam `jq` para análise JSON. Instale-o com `brew install jq` (macOS), `apt-get install jq` (Debian/Ubuntu), ou consulte [downloads do `jq`](https://jqlang.github.io/jq/download/).220 Os exemplos Bash nesta página usam `jq` para análise JSON. Instale-o com `brew install jq` no macOS, `apt-get install jq` no Debian e Ubuntu, ou consulte [downloads do `jq`](https://jqlang.github.io/jq/download/).

223</Note>221</Note>

224 222

225<h3 id="block-edits-to-protected-files">223<h3 id="block-edits-to-protected-files">

254 ```252 ```

255 </Step>253 </Step>

256 254

257 <Step title="Torne o script executável (macOS/Linux)">255 <Step title="Torne o script executável no macOS e Linux">

258 Scripts de hook devem ser executáveis para que Claude Code os execute:256 Scripts de hook devem ser executáveis para que Claude Code os execute:

259 257

260 ```bash theme={null}258 ```bash theme={null}

378 376

379Execute `direnv allow` uma vez em cada diretório que tenha um `.envrc` para que direnv tenha permissão para carregá-lo. Se você usar devbox ou nix em vez de direnv, o mesmo padrão funciona com `devbox shellenv` ou `devbox global shellenv` no lugar de `direnv export bash`.377Execute `direnv allow` uma vez em cada diretório que tenha um `.envrc` para que direnv tenha permissão para carregá-lo. Se você usar devbox ou nix em vez de direnv, o mesmo padrão funciona com `devbox shellenv` ou `devbox global shellenv` no lugar de `direnv export bash`.

380 378

381Para reagir a arquivos específicos em vez de cada mudança de diretório, use `FileChanged` com um `matcher` listando os nomes de arquivo para observar, separados por `|`. Para construir a lista de observação, este valor é dividido em nomes de arquivo literais em vez de ser avaliado como uma regex. Consulte [FileChanged](/pt/hooks#filechanged) para como o mesmo valor também filtra quais grupos de hook executam quando um arquivo muda. Este exemplo observa `.envrc` e `.env` no diretório de trabalho:379Para reagir a arquivos específicos em vez de cada mudança de diretório, use `FileChanged` com um `matcher` listando os nomes de arquivo para observar, separados por `|`. Ao construir a lista de observação, Claude Code divide este valor em nomes de arquivo literais em vez de avaliá-lo como uma regex. Consulte [FileChanged](/pt/hooks#filechanged) para como o mesmo valor também filtra quais grupos de hook executam quando um arquivo muda. Este exemplo observa `.envrc` e `.env` no diretório de trabalho:

382 380

383```json theme={null}381```json theme={null}

384{382{

558}556}

559```557```

560 558

561Seu script pode analisar esse JSON e agir em qualquer um desses campos. Hooks `UserPromptSubmit` obtêm o texto `prompt` em vez disso, hooks `SessionStart` obtêm a `source` (startup, resume, clear, compact), e assim por diante. Consulte [Campos de entrada comuns](/pt/hooks#common-input-fields) na referência para campos compartilhados, e a seção de cada evento para esquemas específicos do evento.559Seu script pode analisar esse JSON e agir em qualquer um desses campos. Hooks `UserPromptSubmit` obtêm o texto `prompt` em vez disso, hooks `SessionStart` obtêm a `source` de `startup`, `resume`, `clear` ou `compact`, e assim por diante. Consulte [Campos de entrada comuns](/pt/hooks#common-input-fields) na referência para campos compartilhados, e a seção de cada evento para esquemas específicos do evento.

562 560

563<h4 id="hook-output">561<h4 id="hook-output">

564 Saída do hook562 Saída do hook

565</h4>563</h4>

566 564

567Seu script diz ao Claude Code o que fazer a seguir escrevendo para stdout ou stderr e saindo com um código específico. Por exemplo, um hook `PreToolUse` que quer bloquear um comando:565Seu script diz ao Claude Code o que fazer a seguir escrevendo para stdout ou stderr e saindo com um código específico. O seguinte hook `PreToolUse` bloqueia um comando:

568 566

569```bash theme={null}567```bash theme={null}

570#!/bin/bash568#!/bin/bash

619 617

620Outros eventos usam padrões de decisão diferentes. Por exemplo, hooks `PostToolUse` e `Stop` usam um campo `decision: "block"` de nível superior, enquanto `PermissionRequest` usa `hookSpecificOutput.decision.behavior`. Consulte a [tabela de resumo](/pt/hooks#decision-control) na referência para uma análise completa por evento.618Outros eventos usam padrões de decisão diferentes. Por exemplo, hooks `PostToolUse` e `Stop` usam um campo `decision: "block"` de nível superior, enquanto `PermissionRequest` usa `hookSpecificOutput.decision.behavior`. Consulte a [tabela de resumo](/pt/hooks#decision-control) na referência para uma análise completa por evento.

621 619

622Para hooks `UserPromptSubmit`, use `additionalContext` em vez disso para injetar texto no contexto do Claude. Hooks baseados em prompt (`type: "prompt"`) lidam com saída de forma diferente: consulte [Prompt-based hooks](#prompt-based-hooks).620Para hooks `UserPromptSubmit`, use `additionalContext` em vez disso para injetar texto no contexto do Claude.

621

622Hooks com `type: "prompt"` lidam com saída de forma diferente: consulte [Prompt-based hooks](#prompt-based-hooks).

623 623

624<h3 id="filter-hooks-with-matchers">624<h3 id="filter-hooks-with-matchers">

625 Filtrar hooks com matchers625 Filtrar hooks com matchers

626</h3>626</h3>

627 627

628Sem um matcher, um hook dispara em cada ocorrência de seu evento. Matchers permitem restringir isso. Por exemplo, se você quer executar um formatador apenas após edições de arquivo (não após cada chamada de ferramenta), adicione um matcher ao seu hook `PostToolUse`:628Sem um matcher, um hook dispara em cada ocorrência de seu evento. Matchers permitem restringir isso. Por exemplo, se você quer executar um formatador apenas após edições de arquivo, não após cada chamada de ferramenta, adicione um matcher ao seu hook `PostToolUse`:

629 629

630```json theme={null}630```json theme={null}

631{631{

659| `Notification` | tipo de notificação | `permission_prompt`, `idle_prompt`, `auth_success`, `elicitation_dialog`, `elicitation_complete`, `elicitation_response` |659| `Notification` | tipo de notificação | `permission_prompt`, `idle_prompt`, `auth_success`, `elicitation_dialog`, `elicitation_complete`, `elicitation_response`, `agent_needs_input`, `agent_completed` |

670| `UserPromptSubmit`, `PostToolBatch`, `Stop`, `TeammateIdle`, `TaskCreated`, `TaskCompleted`, `WorktreeCreate`, `WorktreeRemove`, `CwdChanged`, `MessageDisplay` | sem suporte a matcher | sempre dispara em cada ocorrência |670| `UserPromptSubmit`, `PostToolBatch`, `Stop`, `TeammateIdle`, `TaskCreated`, `TaskCompleted`, `WorktreeCreate`, `WorktreeRemove`, `CwdChanged`, `MessageDisplay` | sem suporte a matcher | sempre dispara em cada ocorrência |

671 671

672Alguns exemplos adicionais mostrando matchers em diferentes tipos de evento:672As abas abaixo mostram alguns matchers adicionais em diferentes tipos de evento.

673 673

674<Tabs>674<Tabs>

675 <Tab title="Registrar cada comando Bash">675 <Tab title="Registrar cada comando Bash">

753 753

754O campo `if` usa [sintaxe de regra de permissão](/pt/permissions) para filtrar hooks por nome de ferramenta e argumentos juntos, para que o processo do hook apenas seja gerado quando a chamada de ferramenta corresponder. Isto vai além de `matcher`, que filtra no nível do grupo apenas por nome de ferramenta.754O campo `if` usa [sintaxe de regra de permissão](/pt/permissions) para filtrar hooks por nome de ferramenta e argumentos juntos, para que o processo do hook apenas seja gerado quando a chamada de ferramenta corresponder. Isto vai além de `matcher`, que filtra no nível do grupo apenas por nome de ferramenta.

755 755

756Por exemplo, para executar um hook apenas quando Claude usa comandos `git` em vez de todos os comandos Bash:756Por exemplo, esta configuração executa um hook apenas quando Claude usa comandos `git` em vez de todos os comandos Bash:

757 757

758```json theme={null}758```json theme={null}

759{759{

807 807

808Execute [`/hooks`](/pt/hooks#the-%2Fhooks-menu) no Claude Code para navegar por todos os hooks configurados agrupados por evento. Para desabilitar hooks, defina `"disableAllHooks": true` no seu arquivo de configuração. Hooks configurados em configurações gerenciadas ainda executam a menos que `disableAllHooks` também esteja definido lá.808Execute [`/hooks`](/pt/hooks#the-%2Fhooks-menu) no Claude Code para navegar por todos os hooks configurados agrupados por evento.

809

810Para desabilitar hooks, defina `"disableAllHooks": true` no seu arquivo de configuração. Hooks configurados em configurações gerenciadas ainda executam a menos que `disableAllHooks` também esteja definido lá.

809 811

810Se você editar arquivos de configuração diretamente enquanto Claude Code está em execução, o observador de arquivo normalmente pega mudanças de hook automaticamente.812Se você editar arquivos de configuração diretamente enquanto Claude Code está em execução, o observador de arquivo normalmente pega mudanças de hook automaticamente.

811 813

925 Limitações927 Limitações

926</h3>928</h3>

927 929

930Tenha em mente estas restrições ao projetar hooks:

931

928* Hooks de comando se comunicam apenas através de stdout, stderr e códigos de saída. Eles não podem disparar comandos `/` ou chamadas de ferramenta. Texto retornado via `additionalContext` é injetado como um lembrete do sistema que Claude lê como texto simples. HTTP hooks se comunicam através do corpo da resposta em vez disso.932* Hooks de comando se comunicam apenas através de stdout, stderr e códigos de saída. Eles não podem disparar comandos `/` ou chamadas de ferramenta. Texto retornado via `additionalContext` é injetado como um lembrete do sistema que Claude lê como texto simples. HTTP hooks se comunicam através do corpo da resposta em vez disso.

929* Os timeouts do hook variam por tipo. Substitua por hook com o campo `timeout` em segundos.933* Os timeouts do hook variam por tipo. Substitua por hook com o campo `timeout` em segundos.

930 * `command`, `http`, `mcp_tool`: 10 minutos. `UserPromptSubmit` reduz estes para 30 segundos, e `MessageDisplay` reduz estes para 10 segundos.934 * `command`, `http`, `mcp_tool`: 10 minutos. `UserPromptSubmit` reduz estes para 30 segundos, e `MessageDisplay` reduz estes para 10 segundos.

931 * `prompt`: 30 segundos.935 * `prompt`: 30 segundos.

932 * `agent`: 60 segundos.936 * `agent`: 60 segundos.

933* Hooks `PostToolUse` não podem desfazer ações já que a ferramenta já foi executada.937* Hooks `PostToolUse` não podem desfazer ações já que a ferramenta já foi executada.

934* Hooks `PermissionRequest` não disparam em [modo não-interativo](/pt/headless) (`-p`). Use hooks `PreToolUse` para decisões de permissão automatizadas.938* Hooks `PermissionRequest` não disparam em [modo não-interativo](/pt/headless) com a flag `-p`. Use hooks `PreToolUse` para decisões de permissão automatizadas.

935* Hooks `Stop` disparam sempre que Claude termina de responder, não apenas na conclusão de tarefas. Eles não disparam em interrupções do usuário. Erros de API disparam [StopFailure](/pt/hooks#stopfailure) em vez disso.939* Hooks `Stop` disparam sempre que Claude termina de responder, não apenas na conclusão de tarefas. Eles não disparam em interrupções do usuário. Erros de API disparam [StopFailure](/pt/hooks#stopfailure) em vez disso.

936* Quando múltiplos hooks PreToolUse retornam [`updatedInput`](/pt/hooks#pretooluse) para reescrever argumentos de uma ferramenta, o último a terminar vence. Como hooks executam em paralelo, a ordem é não-determinística. Evite ter mais de um hook modificando a entrada da mesma ferramenta.940* Quando múltiplos hooks `PreToolUse` retornam [`updatedInput`](/pt/hooks#pretooluse) para reescrever argumentos de uma ferramenta, o último a terminar vence. Como hooks executam em paralelo, a ordem é não-determinística. Evite ter mais de um hook modificando a entrada da mesma ferramenta.

937 941

938<h3 id="hooks-and-permission-modes">942<h3 id="hooks-and-permission-modes">

939 Hooks e modos de permissão943 Hooks e modos de permissão

940</h3>944</h3>

941 945

942Hooks PreToolUse disparam antes de qualquer verificação de modo de permissão. Um hook que retorna `permissionDecision: "deny"` bloqueia a ferramenta mesmo em modo `bypassPermissions` ou com `--dangerously-skip-permissions`. Isto permite que você aplique política que usuários não podem contornar mudando seu modo de permissão.946Hooks `PreToolUse` disparam antes de qualquer verificação de modo de permissão. Um hook que retorna `permissionDecision: "deny"` bloqueia a ferramenta mesmo em modo `bypassPermissions` ou com `--dangerously-skip-permissions`. Isto permite que você aplique política que usuários não podem contornar mudando seu modo de permissão.

943 947

944O inverso não é verdadeiro: um hook retornando `"allow"` não contorna regras de negação de configurações. Hooks podem apertar restrições mas não afrouxá-las além do que regras de permissão permitem.948O inverso não é verdadeiro: um hook retornando `"allow"` não contorna regras de negação de configurações. Hooks podem apertar restrições mas não afrouxá-las além do que regras de permissão permitem.

945 949

950O hook está configurado mas nunca executa.954O hook está configurado mas nunca executa.

951 955

952* Execute `/hooks` e confirme que o hook aparece sob o evento correto956* Execute `/hooks` e confirme que o hook aparece sob o evento correto

953* Verifique que o padrão do matcher corresponde ao nome da ferramenta exatamente (matchers são sensíveis a maiúsculas)957* Verifique que o padrão do matcher corresponde ao nome da ferramenta exatamente. Matchers são sensíveis a maiúsculas

954* Verifique que você está acionando o tipo de evento correto (por exemplo, `PreToolUse` dispara antes da execução da ferramenta, `PostToolUse` dispara depois)958* Verifique que você está acionando o tipo de evento correto: `PreToolUse` dispara antes da execução da ferramenta, `PostToolUse` dispara depois

955* Se usar hooks `PermissionRequest` em modo não-interativo (`-p`), mude para `PreToolUse` em vez disso959* Se usar hooks `PermissionRequest` em modo não-interativo com a flag `-p`, mude para `PreToolUse` em vez disso

956 960

957<h3 id="hook-error-in-output">961<h3 id="hook-error-in-output">

958 Erro de hook na saída962 Erro de hook na saída

976Você editou um arquivo de configuração mas os hooks não aparecem no menu.980Você editou um arquivo de configuração mas os hooks não aparecem no menu.

977 981

978* Edições de arquivo são normalmente capturadas automaticamente. Se não tiverem aparecido após alguns segundos, o observador de arquivo pode ter perdido a mudança: reinicie sua sessão para forçar um recarregamento.982* Edições de arquivo são normalmente capturadas automaticamente. Se não tiverem aparecido após alguns segundos, o observador de arquivo pode ter perdido a mudança: reinicie sua sessão para forçar um recarregamento.

979* Verifique que seu JSON é válido (vírgulas finais e comentários não são permitidos)983* Verifique que seu JSON é válido: vírgulas finais e comentários não são permitidos

980* Confirme que o arquivo de configuração está no local correto: `.claude/settings.json` para hooks de projeto, `~/.claude/settings.json` para hooks globais984* Confirme que o arquivo de configuração está no local correto: `.claude/settings.json` para hooks de projeto, `~/.claude/settings.json` para hooks globais

981 985

982<h3 id="stop-hook-hits-the-block-cap">986<h3 id="stop-hook-hits-the-block-cap">

985 989

986Claude continua trabalhando em vez de parar, depois termina a rodada com um aviso de que o Stop hook bloqueou muitas vezes consecutivas sem progresso.990Claude continua trabalhando em vez de parar, depois termina a rodada com um aviso de que o Stop hook bloqueou muitas vezes consecutivas sem progresso.

987 991

988Claude Code substitui um Stop hook depois que ele bloqueia 8 vezes seguidas sem progresso. Seu script de hook precisa verificar se já acionou uma continuação. Analise o campo `stop_hook_active` da entrada JSON e saia cedo se for `true`:992Claude Code substitui um Stop hook depois que ele bloqueia oito vezes seguidas sem progresso. Seu script de hook precisa verificar se já acionou uma continuação. Analise o campo `stop_hook_active` da entrada JSON e saia cedo se for `true`:

989 993

990```bash theme={null}994```bash theme={null}

991#!/bin/bash995#!/bin/bash

1004 1008

1005Claude Code mostra um erro de análise JSON mesmo que seu script de hook produza JSON válido.1009Claude Code mostra um erro de análise JSON mesmo que seu script de hook produza JSON válido.

1006 1010

1007Quando Claude Code executa um hook de comando em forma de shell (um sem `args`), ele gera `sh -c` no macOS e Linux ou Git Bash no Windows por padrão. Este shell é não-interativo, mas Git Bash e algumas configurações (como `BASH_ENV` apontando para `~/.bashrc`) ainda fornecem seu perfil. Se esse perfil contiver instruções `echo` incondicionais, a saída é adicionada ao seu JSON do hook:1011Quando Claude Code executa um hook de comando em forma de shell, um sem `args`, ele gera `sh -c` no macOS e Linux ou Git Bash no Windows por padrão. Este shell é não-interativo, mas Git Bash e algumas configurações, como `BASH_ENV` apontando para `~/.bashrc`, ainda fornecem seu perfil. Se esse perfil contiver instruções `echo` incondicionais, a saída é adicionada ao seu JSON do hook:

1008 1012

1009```text theme={null}1013```text theme={null}

1010Shell ready on arm641014Shell ready on arm64

how-claude-code-works.md +0 −1

Details

210Comandos integrados também o guiam através da configuração:210Comandos integrados também o guiam através da configuração:

211 211

212* `/init` o guia através da criação de um CLAUDE.md para seu projeto212* `/init` o guia através da criação de um CLAUDE.md para seu projeto

213* `/agents` ajuda você a configurar subagents personalizados

214* `/doctor` diagnostica problemas comuns com sua instalação213* `/doctor` diagnostica problemas comuns com sua instalação

215 214

216<h3 id="it’s-a-conversation">215<h3 id="it’s-a-conversation">

llm-gateway-protocol.md +9 −1

Details

106 Bloco de atribuição do prompt do sistema106 Bloco de atribuição do prompt do sistema

107</h2>107</h2>

108 108

109Claude Code prepara um bloco de atribuição curto para o prompt do sistema contendo a versão do cliente e uma impressão digital derivada da conversa. O endpoint `api.anthropic.com` remove o bloco antes do processamento, então não afeta o cache de prompt de primeira parte; qualquer outro upstream o recebe como parte do prompt. Anthropic e os endpoints Claude dos provedores de nuvem o leem para atribuição, então para omiti-lo defina [`CLAUDE_CODE_ATTRIBUTION_HEADER=0`](/pt/env-vars) em vez de removê-lo no gateway.109Claude Code prepara um bloco de atribuição curto para o prompt do sistema contendo a versão do cliente e uma impressão digital derivada da conversa. O endpoint `api.anthropic.com` remove o bloco antes do processamento quando ele chega inalterado como o primeiro bloco do sistema, portanto não afeta o cache de prompt de primeira parte. Qualquer outro upstream o recebe como parte do prompt.

110

111A remoção é posicional, portanto funciona apenas quando o gateway encaminha o array `system` inalterado. Para manter o bloco fora do prompt sem perder outro conteúdo do sistema:

112

113* Encaminhe o array `system` exatamente como recebido, mantendo o bloco primeiro: adicionar outro bloco do sistema, reordenar o array ou convertê-lo em uma única string derrota a remoção, e o bloco então chega ao modelo e à chave do cache de prompt.

114* Mantenha o bloco em sua própria entrada de array: o endpoint trata um bloco mesclado que começa com o cabeçalho de atribuição como atribuição em sua totalidade e descarta tudo mesclado nele, incluindo o resto do prompt do sistema.

115* Se seu gateway deve reformular o conteúdo do sistema, defina [`CLAUDE_CODE_ATTRIBUTION_HEADER=0`](/pt/env-vars) para que Claude Code omita o bloco. Anthropic e os endpoints Claude dos provedores de nuvem leem o bloco para atribuição, portanto omita-o no cliente em vez de removê-lo ou movê-lo no gateway.

116

117Solicitações que chegam ao endpoint inalteradas não são afetadas.

110 118

111{/* min-version: 2.1.181 */}A partir de Claude Code v2.1.181, o bloco é estável pela vida útil de uma conversa quando solicitações são roteadas através de uma URL base personalizada, então um cache de prompt do lado do gateway com chave no corpo completo da solicitação funciona sem desabilitá-lo. Antes de v2.1.181, o bloco incluía um token por solicitação; nessas versões, defina `CLAUDE_CODE_ATTRIBUTION_HEADER=0` se seu gateway implementar tal cache.119{/* min-version: 2.1.181 */}A partir de Claude Code v2.1.181, o bloco é estável pela vida útil de uma conversa quando solicitações são roteadas através de uma URL base personalizada, então um cache de prompt do lado do gateway com chave no corpo completo da solicitação funciona sem desabilitá-lo. Antes de v2.1.181, o bloco incluía um token por solicitação; nessas versões, defina `CLAUDE_CODE_ATTRIBUTION_HEADER=0` se seu gateway implementar tal cache.

112 120

mcp.md +46 −1

Details

898 898

899A partir da v2.1.161, conectores aos quais você nunca fez login estão recolhidos atrás de uma linha `Show unused connectors` no final da seção claude.ai, para que uma lista provisionada pela organização não preencha o painel. Selecione a linha para expandi-los. Um conector ao qual você fez login antes permanece visível mesmo quando atualmente precisa de re-autenticação.899A partir da v2.1.161, conectores aos quais você nunca fez login estão recolhidos atrás de uma linha `Show unused connectors` no final da seção claude.ai, para que uma lista provisionada pela organização não preencha o painel. Selecione a linha para expandi-los. Um conector ao qual você fez login antes permanece visível mesmo quando atualmente precisa de re-autenticação.

900 900

901Os conectores do claude.ai são buscados apenas quando seu [método de autenticação](/pt/authentication#authentication-precedence) ativo é sua assinatura do claude.ai. Eles não são carregados quando `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, `apiKeyHelper`, ou um provedor de terceiros como Bedrock ou Vertex está ativo, mesmo que você tenha executado `/login` anteriormente. Se `/mcp` não listar um conector que você adicionou, execute `/status` para confirmar qual método de autenticação está ativo, desdefina essa variável de ambiente ou remova a configuração `apiKeyHelper`, depois execute `/login` para selecionar sua conta do claude.ai.901Os conectores do claude.ai são buscados apenas quando seu [método de autenticação](/pt/authentication#authentication-precedence) ativo é sua assinatura do claude.ai. Eles não são carregados quando `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, `apiKeyHelper`, ou um provedor de terceiros como Bedrock ou Vertex está ativo, mesmo que você tenha executado `/login` anteriormente.

902

903Se `/mcp` não listar um conector que você adicionou, execute `/status` para confirmar qual método de autenticação está ativo, desdefina essa variável de ambiente ou remova a configuração `apiKeyHelper`, depois execute `/login` para selecionar sua conta do claude.ai.

902 904

903Um servidor que você adicionou no Claude Code tem [precedência](#scope-hierarchy-and-precedence) sobre um conector do claude.ai que aponta para a mesma URL. Quando isso acontece, `/mcp` lista o conector como oculto e mostra como remover a duplicata se você preferir usar o conector.905Um servidor que você adicionou no Claude Code tem [precedência](#scope-hierarchy-and-precedence) sobre um conector do claude.ai que aponta para a mesma URL. Quando isso acontece, `/mcp` lista o conector como oculto e mostra como remover a duplicata se você preferir usar o conector.

904 906

1039 Se você encontrar frequentemente avisos de saída com servidores MCP específicos que você não controla, considere aumentar o limite `MAX_MCP_OUTPUT_TOKENS`. Você também pode pedir ao autor do servidor para adicionar a anotação `anthropic/maxResultSizeChars` ou para paginar suas respostas. A anotação não tem efeito em ferramentas que retornam conteúdo de imagem; para essas, aumentar `MAX_MCP_OUTPUT_TOKENS` é a única opção.1041 Se você encontrar frequentemente avisos de saída com servidores MCP específicos que você não controla, considere aumentar o limite `MAX_MCP_OUTPUT_TOKENS`. Você também pode pedir ao autor do servidor para adicionar a anotação `anthropic/maxResultSizeChars` ou para paginar suas respostas. A anotação não tem efeito em ferramentas que retornam conteúdo de imagem; para essas, aumentar `MAX_MCP_OUTPUT_TOKENS` é a única opção.

1040</Warning>1042</Warning>

1041 1043

1044<h2 id="tool-input-schemas-with-a-root-level-combinator">

1045 Esquemas de entrada de ferramenta com um combinador de nível raiz

1046</h2>

1047

1048Alguns servidores MCP declaram o esquema de entrada de uma ferramenta como uma união JSON Schema, com `anyOf`, `oneOf`, ou `allOf` no nível superior do esquema. A API Claude não aceita essas palavras-chave na raiz do esquema. Ela aceita combinadores aninhados dentro de `properties`, que Claude Code envia sem modificação.

1049

1050A partir do Claude Code v2.1.195, ferramentas com um combinador de nível raiz permanecem disponíveis. Antes de enviar a ferramenta para a API, Claude Code achata o esquema em um único objeto e prepara uma frase à descrição da ferramenta que diz ao Claude quais grupos de parâmetros pertencem juntos:

1051

1052* `allOf`: propriedades de cada ramo são mescladas, e a lista `required` de cada ramo ainda se aplica

1053* `anyOf` e `oneOf`: propriedades de cada ramo são mescladas, e a lista `required` de cada ramo é descrita na descrição da ferramenta em vez de ser aplicada pelo esquema

1054

1055Seu servidor recebe quaisquer argumentos que Claude escolheu, então continue validando a combinação no lado do servidor.

1056

1057Quando Claude Code não consegue produzir um esquema que a API aceita, ou em uma implantação que não recebe a configuração remota que ativa a reescrita, como uma máquina offline, ele ignora essa ferramenta, registra o motivo no log do servidor e deixa as outras ferramentas do servidor disponíveis. Versões anteriores a v2.1.195 ignoram cada ferramenta cujo esquema de entrada tem um `anyOf`, `oneOf`, ou `allOf` de nível raiz.

1058

1059<h2 id="require-approval-for-a-specific-tool">

1060 Exigir aprovação para uma ferramenta específica

1061</h2>

1062

1063Se você está construindo um servidor MCP, você pode marcar uma ferramenta como exigindo aprovação explícita a cada chamada definindo `_meta["anthropic/requiresUserInteraction"]` como `true` na entrada da ferramenta em resposta `tools/list`. O valor deve ser o booleano JSON `true`; qualquer outro valor é ignorado.

1064

1065Claude Code mostra o prompt de permissão dessa ferramenta a cada chamada, mesmo em modos de permissão `acceptEdits`, `auto` e `bypassPermissions` [permission modes](/pt/permissions#permission-modes), e não oferece uma opção "não pergunte novamente" para ela. [Regras de permissão](/pt/permissions#permission-rule-syntax) que correspondem à ferramenta também não pulam o prompt. No modo `dontAsk`, que nunca solicita, Claude Code nega a chamada em vez disso.

1066

1067O prompt tem que alcançar uma pessoa. No modo não interativo com [`--permission-prompt-tool`](/pt/cli-reference#cli-flags), um resultado `allow` da ferramenta de prompt para uma ferramenta sinalizada é convertido em uma negação com a mensagem `MCP tool requires user interaction; not supported via --permission-prompt-tool`. O callback [`canUseTool`](/pt/agent-sdk/permissions) do Agent SDK recebe essas chamadas e pode aprová-las, porque o host do SDK deve mostrá-las a um usuário.

1068

1069Use isso para ferramentas cujo prompt de permissão é em si o ponto, como uma etapa de consentimento ou concessão de acesso onde aprovação automática significaria que nenhum humano nunca concordou. Outras ferramentas do mesmo servidor mantêm seu comportamento de permissão normal.

1070

1071A seguinte entrada `tools/list` marca uma ferramenta como sempre exigindo aprovação.

1072

1073```json theme={null}

1074{

1075 "name": "grant_access",

1076 "description": "Requests access to a protected resource",

1077 "_meta": {

1078 "anthropic/requiresUserInteraction": true

1079 }

1080}

1081```

1082

1083A anotação `anthropic/requiresUserInteraction` requer Claude Code v2.1.199 ou posterior. Versões anteriores a ignoram e aplicam o fluxo de permissão padrão.

1084

1085Quando uma sessão está conectada ao [Remote Control](/pt/remote-control) ou a um host SDK, Claude Code marca a solicitação de permissão como exigindo interação do usuário, para que o cliente mostre o prompt de permissão da ferramenta para você responder em vez de uma ação de aprovação com um toque.

1086

1042<h2 id="respond-to-mcp-elicitation-requests">1087<h2 id="respond-to-mcp-elicitation-requests">

1043 Responder a solicitações de elicitação MCP1088 Responder a solicitações de elicitação MCP

1044</h2>1089</h2>

memory.md +1 −1

Details

235- Inclua comentários de documentação OpenAPI235- Inclua comentários de documentação OpenAPI

236```236```

237 237

238Regras sem um campo `paths` são carregadas incondicionalmente e se aplicam a todos os arquivos. Regras com escopo de caminho são acionadas quando Claude lê arquivos correspondentes ao padrão, não em cada uso de ferramenta.238Regras sem um campo `paths` são carregadas incondicionalmente e se aplicam a todos os arquivos. Regras com escopo de caminho são acionadas quando Claude lê arquivos correspondentes ao padrão, não em cada uso de ferramenta. {/* min-version: 2.1.198 */}A partir da v2.1.198, a correspondência também funciona quando Claude alcança um arquivo através de um caminho vinculado simbolicamente para o diretório do projeto, por exemplo em um checkout vinculado simbolicamente.

239 239

240Use padrões glob no campo `paths` para corresponder arquivos por extensão, diretório ou qualquer combinação:240Use padrões glob no campo `paths` para corresponder arquivos por extensão, diretório ou qualquer combinação:

241 241

model-config.md +61 −8

Details

31 31

32| Alias de modelo | Comportamento |32| Alias de modelo | Comportamento |

33| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |33| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

34| **`default`** | Valor especial que limpa qualquer substituição de modelo e reverte para o modelo recomendado para seu tipo de conta. Não é em si um alias de modelo |34| **`default`** | Valor especial que limpa qualquer substituição de modelo e reverte para o modelo recomendado para seu tipo de conta, ou para o [modelo padrão da organização](#organization-default-model) quando um administrador definiu um. Não é em si um alias de modelo |

84* `Enter`: alternar modelo e salvar como seu padrão84* `Enter`: alternar modelo e salvar como seu padrão

85* `s`: alternar modelo apenas para esta sessão85* `s`: alternar modelo apenas para esta sessão

86 86

~~87Digitar `/model <name>` diretamente se comporta como `Enter`. As configurações de projeto e gerenciadas ainda têm precedência e são reaplicadas no próximo lançamento.~~87Digitar `/model <name>` diretamente se comporta como `Enter`. As configurações de projeto e gerenciadas ainda têm precedência e são reaplicadas no próximo lançamento. {/* min-version: 2.1.196 */}Um [modelo padrão da organização](#organization-default-model) que seu administrador configurou para substituir a seleção do usuário também é reaplicado no próximo lançamento.

88 88

89Na v2.1.144 até v2.1.152, `/model` se aplicava apenas à sessão atual e `d` no seletor salvava um padrão.89Na v2.1.144 até v2.1.152, `/model` se aplicava apenas à sessão atual e `d` no seletor salvava um padrão.

90 90

130* **Modelo de sessão principal**: `/model`, o sinalizador `--model`, a variável de ambiente `ANTHROPIC_MODEL`, a configuração `model` e o modelo restaurado ao [retomar uma sessão](#setting-your-model)130* **Modelo de sessão principal**: `/model`, o sinalizador `--model`, a variável de ambiente `ANTHROPIC_MODEL`, a configuração `model` e o modelo restaurado ao [retomar uma sessão](#setting-your-model)

131* **Resolução de alias**: {/* min-version: 2.1.176 */}as variáveis de ambiente `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, `ANTHROPIC_DEFAULT_HAIKU_MODEL` e `ANTHROPIC_DEFAULT_FABLE_MODEL` não podem redirecionar um alias permitido para um modelo fora da lista131* **Resolução de alias**: {/* min-version: 2.1.176 */}as variáveis de ambiente `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, `ANTHROPIC_DEFAULT_HAIKU_MODEL` e `ANTHROPIC_DEFAULT_FABLE_MODEL` não podem redirecionar um alias permitido para um modelo fora da lista

132* **Modo rápido**: {/* min-version: 2.1.176 */}`/fast` recusa alternar quando isso implicaria mudar implicitamente para um modelo Opus fora da lista, com a mensagem "não está nos modelos permitidos da sua organização"132* **Modo rápido**: {/* min-version: 2.1.176 */}`/fast` recusa alternar quando isso implicaria mudar implicitamente para um modelo Opus fora da lista, com a mensagem "não está nos modelos permitidos da sua organização"

133* **Modelos de subagente**: o campo `model` em [subagente](/pt/sub-agents#choose-a-model) frontmatter, o parâmetro `model` da ferramenta Agent, o seletor de modelo em `/agents` e `CLAUDE_CODE_SUBAGENT_MODEL`133* **Modelos de subagente**: o campo `model` em [subagente](/pt/sub-agents#choose-a-model) frontmatter, o parâmetro `model` da ferramenta Agent, `CLAUDE_CODE_SUBAGENT_MODEL` e, na v2.1.197 e anterior, o seletor de modelo no assistente `/agents` {/* max-version: 2.1.197 */}

134* **Modelo de skill e comando**: o frontmatter `model` em [skills e comandos](/pt/skills)134* **Modelo de skill e comando**: o frontmatter `model` em [skills e comandos](/pt/skills)

135* **Modelo de advisor**: a configuração [`advisorModel`](/pt/advisor) configurada e o sinalizador `--advisor`135* **Modelo de advisor**: a configuração [`advisorModel`](/pt/advisor) configurada e o sinalizador `--advisor`

136* **Modelo de agente de fundo**: o modelo selecionado no [seletor de dispatch](/pt/agent-view)136* **Modelo de agente de fundo**: o modelo selecionado no [seletor de dispatch](/pt/agent-view)

137 137

138Alternar para um modelo bloqueado com `/model` é rejeitado com um erro, enquanto um sinalizador `--model` bloqueado, valor `ANTHROPIC_MODEL` ou configuração `model` é substituído na inicialização com um aviso nomeando tanto o modelo solicitado quanto o substituído, e a sessão é iniciada no modelo padrão. Uma substituição de subagente, skill ou comando bloqueada volta para o modelo herdado ou padrão em vez de falhar na solicitação; uma configuração `advisorModel` bloqueada desativa o advisor para a sessão, enquanto um sinalizador `--advisor` bloqueado sai com um erro no lançamento. Os modelos excluídos são ocultados do seletor `/model`.138Alternar para um modelo bloqueado com `/model` é rejeitado com um erro, enquanto um sinalizador `--model` bloqueado, valor `ANTHROPIC_MODEL` ou configuração `model` é substituído na inicialização com um aviso nomeando tanto o modelo solicitado quanto o substituído, e a sessão é iniciada no modelo padrão. Uma substituição de subagente, skill ou comando bloqueada volta para o modelo herdado ou padrão em vez de falhar na solicitação; uma configuração `advisorModel` bloqueada desativa o advisor para a sessão, enquanto um sinalizador `--advisor` bloqueado sai com um erro no lançamento. Os modelos excluídos são ocultados do seletor `/model`. {/* min-version: 2.1.199 */}A partir da v2.1.199, um ID de modelo completo na lista que não tem uma linha de seletor integrada, como uma versão mais antiga que a lista fixa, aparece no seletor `/model` como sua própria linha rotulada. Em versões anteriores, tal ID é selecionável apenas digitando `/model <id>`.

139 139

140As mudanças automáticas de modelo são verificadas da mesma forma: elementos de uma [cadeia de modelo de fallback](#fallback-model-chains) fora da lista de permissões são descartados, uma atualização de modo de plano como [`opusplan`](#opusplan-model-setting) para um modelo excluído é ignorada para que o planejamento continue no modelo da sessão, e um [fallback automático de modelo](#automatic-model-fallback) cujo alvo é excluído não é executado, portanto a solicitação sinalizada termina com uma recusa. Habilitar [modo rápido](/pt/fast-mode) é recusado quando o modelo em que a sessão seria executada depois está fora da lista de permissões.140As mudanças automáticas de modelo são verificadas da mesma forma: elementos de uma [cadeia de modelo de fallback](#fallback-model-chains) fora da lista de permissões são descartados, uma atualização de modo de plano como [`opusplan`](#opusplan-model-setting) para um modelo excluído é ignorada para que o planejamento continue no modelo da sessão, e um [fallback automático de modelo](#automatic-model-fallback) cujo alvo é excluído não é executado, portanto a solicitação sinalizada termina com uma recusa. Habilitar [modo rápido](/pt/fast-mode) é recusado quando o modelo em que a sessão seria executada depois está fora da lista de permissões.

141 141

184}184}

185```185```

186 186

187Quando o modelo padrão para o tipo de conta do usuário não está na lista de permissões, a opção Padrão se resolve para a primeira entrada `availableModels` que nomeia um modelo permitido e disponível, e a linha Padrão do seletor `/model` mostra esse modelo. Isso se aplica em todos os lugares onde o padrão é alcançado: inicialização da sessão, seleção de Padrão em `/model`, a palavra-chave `"default"` em [cadeias de modelo de fallback](#fallback-model-chains) e o fallback usado quando uma seleção excluída é descartada.187A opção Padrão resolve para o padrão do tipo de conta, ou para o [modelo padrão da organização](#organization-default-model) quando um administrador definiu um. Quando esse modelo não está na lista de permissões, a opção Padrão se resolve para a primeira entrada `availableModels` que nomeia um modelo permitido e disponível, e a linha Padrão do seletor `/model` mostra esse modelo. Isso se aplica em todos os lugares onde o padrão é alcançado: inicialização da sessão, seleção de Padrão em `/model`, a palavra-chave `"default"` em [cadeias de modelo de fallback](#fallback-model-chains) e o fallback usado quando uma seleção excluída é descartada.

188 188

189`enforceAvailableModels` não tem efeito quando `availableModels` não está definido ou está vazio: com `availableModels: []`, o modelo Padrão para o tipo de conta permanece utilizável, portanto a configuração não pode bloquear os usuários de cada modelo. Quando `availableModels` é não vazio, mas nenhuma entrada se resolve para um modelo permitido e disponível, a imposição se degrada e Padrão cai para o padrão do tipo de conta, com um aviso visível apenas em `--debug`. Mantenha pelo menos uma entrada garantidamente disponível na lista para evitar isso.189`enforceAvailableModels` não tem efeito quando `availableModels` não está definido ou está vazio: com `availableModels: []`, o modelo Padrão para o tipo de conta permanece utilizável, portanto a configuração não pode bloquear os usuários de cada modelo. Quando `availableModels` é não vazio, mas nenhuma entrada se resolve para um modelo permitido e disponível, a imposição se degrada e Padrão cai para o padrão do tipo de conta, com um aviso visível apenas em `--debug`. Mantenha pelo menos uma entrada garantidamente disponível na lista para evitar isso.

190 190

244 244

245Um modelo restrito é ocultado do seletor `/model`. Selecioná-lo pelo nome com `--model`, a variável de ambiente `ANTHROPIC_MODEL` ou a configuração `model` mostra o aviso `Model "<name>" is restricted by your organization's settings. Using <model> instead.` e a sessão é iniciada em um modelo permitido. Digitar `/model <name>` para um modelo restrito é rejeitado com `Model '<name>' is restricted by your organization's settings. Run /model to choose a different model.` e a sessão mantém seu modelo atual.245Um modelo restrito é ocultado do seletor `/model`. Selecioná-lo pelo nome com `--model`, a variável de ambiente `ANTHROPIC_MODEL` ou a configuração `model` mostra o aviso `Model "<name>" is restricted by your organization's settings. Using <model> instead.` e a sessão é iniciada em um modelo permitido. Digitar `/model <name>` para um modelo restrito é rejeitado com `Model '<name>' is restricted by your organization's settings. Run /model to choose a different model.` e a sessão mantém seu modelo atual.

246 246

247Os dois mecanismos se compõem: um modelo é selecionável apenas quando é permitido por `availableModels` e não é restrito pela organização. As restrições da organização são entregues a sessões na API Anthropic e implantações de [gateway LLM](/pt/llm-gateway). Sessões em Bedrock, Vertex AI, Foundry e Claude Platform on AWS não as recebem, portanto use `availableModels` nesses provedores.247As restrições se aplicam em toda a organização ou por função:

248

249* Desabilitar um modelo no nível da organização o remove para cada membro.

250* O acesso no nível de função concede diferentes modelos a diferentes funções personalizadas, e um membro que possui várias funções pode usar qualquer modelo que uma de suas funções conceda.

251* Os modelos Haiku estão sempre disponíveis e não podem ser desabilitados, portanto cada membro mantém pelo menos um modelo utilizável.

252* Uma mudança de acesso entra em vigor em novas solicitações dentro de cerca de um minuto; o seletor `/model` reflete isso na próxima vez que uma sessão é iniciada.

253

254Ambas as restrições se aplicam juntas: um modelo é selecionável apenas quando é permitido por `availableModels` e não é restrito pela organização. As restrições da organização são entregues a sessões na API Anthropic e implantações de [gateway LLM](/pt/llm-gateway). Sessões em Bedrock, Vertex AI, Foundry e Claude Platform on AWS não as recebem, portanto use `availableModels` nesses provedores.

255

256<h2 id="organization-default-model">

257 Modelo padrão da organização

258</h2>

259

260{/* plan-availability: feature=org-default-model plans=enterprise */}

261

262Os administradores da organização em planos Claude Enterprise podem definir um modelo padrão para membros do Claude Code a partir do console de administração claude.ai, para toda a organização ou por função personalizada. Quando um é definido, a opção Padrão resolve para esse modelo em vez do [padrão do tipo de conta](#default-model-setting). Requer Claude Code v2.1.196 ou posterior.

263

264A linha Padrão no seletor `/model` mostra o nome do modelo padrão da organização com o rótulo Padrão da organização. O rótulo lê Padrão da organização se o administrador definiu o padrão para toda a organização ou para sua função. Um padrão de função cobre membros dessa função personalizada e tem precedência sobre o padrão em toda a organização; quando várias de suas funções definem diferentes padrões, o modelo mais capaz se aplica.

265

266O modelo padrão da organização é um ponto de partida, não uma restrição, e qualquer outra seleção de modelo tem precedência sobre ele:

267

268* o sinalizador `--model` e a variável de ambiente `ANTHROPIC_MODEL`

269* um valor `model` em [configurações gerenciadas](/pt/settings#settings-files) ou fornecido através de `--settings`

270* um valor `model` em suas configurações de usuário, projeto ou local, incluindo um modelo que você salva com `/model`

271

272Os administradores também podem configurar o modelo padrão da organização para substituir a seleção do usuário. Com a substituição ativada, ele tem precedência sobre o valor `model` em configurações de usuário, projeto e local, portanto um modelo que você salva com `/model` se aplica para a sessão atual e o modelo padrão da organização retorna no próximo lançamento. Quando sua seleção difere, `/model` mostra `Your organization's default (<model>) applies on restart`. O sinalizador `--model`, `ANTHROPIC_MODEL`, configurações gerenciadas e `--settings` ainda têm precedência mesmo com a substituição ativada. A substituição está disponível para um conjunto limitado de organizações; pergunte ao seu time de contas Anthropic sobre disponibilidade.

273

274Para limitar quais modelos os membros podem selecionar, use [restrições de modelo da organização](#organization-model-restrictions) ou [`availableModels`](#restrict-model-selection) em vez disso.

275

276Claude Code lê o modelo padrão da organização uma vez na inicialização, portanto um padrão que o administrador altera no meio da sessão entra em vigor no próximo lançamento.

277

278Quando o modelo padrão da organização não substitui a seleção do usuário, o primeiro lançamento interativo após o administrador alterá-lo limpa a chave `model` de suas configurações de usuário uma vez, para que o novo padrão se aplique. Ele não altera nada mais no arquivo, e um modelo que você salva com `/model` após esse lançamento é mantido.

279

280O modelo padrão da organização passa pelas mesmas verificações de restrição que qualquer outro modelo Padrão antes de ser adotado:

281

282* [`availableModels`](#restrict-model-selection) por si só nunca restringe a opção Padrão, portanto um padrão da organização fora da lista de permissões ainda se aplica. Quando [`enforceAvailableModels`](#enforce-the-allowlist-for-the-default-model) também está definido, um padrão da organização fora da lista de permissões é remapeado para a primeira entrada da lista de permissões, como qualquer outro Padrão

283* um padrão da organização que [restrições de modelo da organização](#organization-model-restrictions) negam para sua conta é substituído pelo modelo mais recente permitido em sua família, ou uma família de menor custo quando cada versão dela é restrita

284* um padrão da organização que não está disponível para sua conta, como Fable 5 sob [retenção zero de dados](/pt/zero-data-retention), é ignorado, e a opção Padrão resolve para o padrão do tipo de conta

285

286A partir da v2.1.199, quando o modelo padrão da organização é uma família de modelo diferente do padrão usual do tipo de conta, o seletor `/model` mantém uma linha separada para essa família usual, para que você ainda possa alternar para ela para uma sessão. Na v2.1.196 até v2.1.198, essa linha está faltando no seletor.

287

288O modelo padrão da organização é entregue a sessões autenticadas com a API Anthropic. Sessões em implantações de [gateway LLM](/pt/llm-gateway), Amazon Bedrock, Agent Platform do Google Cloud, Microsoft Foundry e Claude Platform on AWS não o recebem. Para definir um padrão nesses deployments, use a chave `model` em [configurações gerenciadas](/pt/settings#settings-files) em vez disso.

289

290<h2 id="organization-effort-limits">

291 Limites de esforço da organização

292</h2>

293

294{/* plan-availability: feature=org-effort-limits plans=enterprise */}

295

296Os administradores da organização em planos Claude Enterprise podem definir um [nível de esforço](#adjust-effort-level) máximo por modelo para cada função personalizada, junto com [restrições de modelo da organização](#organization-model-restrictions) no nível de função. Os níveis acima do limite não são oferecidos no seletor `/effort`, e nomear um nível mais alto com `--effort` ou `/effort` é executado no limite em vez disso. Em sessões interativas e execuções `--print` em texto simples, um aviso nomeia os níveis solicitado e aplicado; com saída `json` ou `stream-json` ou em agentes de fundo, o limite se aplica silenciosamente. Os limites são por modelo, portanto alternar modelos pode alterar quais níveis estão disponíveis. Quando várias de suas funções concedem o mesmo modelo, o limite menos restritivo se aplica. Requer Claude Code v2.1.195 ou posterior.

297

298Os limites de esforço são entregues junto com [restrições de modelo da organização](#organization-model-restrictions) e seguem a mesma disponibilidade de provedor: sessões em Amazon Bedrock, Agent Platform do Google Cloud, Microsoft Foundry e Claude Platform on AWS não os recebem.

248 299

249<h2 id="special-model-behavior">300<h2 id="special-model-behavior">

250 Comportamento especial do modelo301 Comportamento especial do modelo

263 314

264Enterprise pagamento conforme o uso significa uma organização Enterprise cobrada por uso em vez de por assento de assinatura.315Enterprise pagamento conforme o uso significa uma organização Enterprise cobrada por uso em vez de por assento de assinatura.

265 316

266Quando as configurações gerenciadas [aplicam a lista de permissões para o modelo Padrão](#enforce-the-allowlist-for-the-default-model) e o padrão do tipo de conta não está em `availableModels`, `default` resolve para o Padrão aplicado em vez do padrão do tipo de conta acima.317Quando um administrador definiu um [modelo padrão da organização](#organization-default-model), `default` resolve para esse modelo em vez do padrão do tipo de conta acima. Requer Claude Code v2.1.196 ou posterior.

318

319Quando as configurações gerenciadas [aplicam a lista de permissões para o modelo Padrão](#enforce-the-allowlist-for-the-default-model) e o padrão do tipo de conta não está em `availableModels`, `default` resolve para o Padrão aplicado em vez do padrão do tipo de conta acima. Quando ambos se aplicam, o modelo padrão da organização substitui o padrão do tipo de conta primeiro e a imposição então se aplica a ele: um padrão da organização na lista de permissões é mantido, enquanto um fora da lista resolve para o Padrão aplicado.

267 320

268Fable 5 não é o modelo padrão em nenhum tipo de conta. As sessões usam Fable 5 apenas depois que você o escolhe, com `/model fable`, uma configuração `model` ou o alias `best` onde Fable 5 está disponível. Escolhê-lo com `/model` o salva como o modelo selecionado em suas configurações de usuário, portanto as sessões posteriores começam em Fable 5 até que você altere os modelos.321Fable 5 não é o modelo padrão em nenhum tipo de conta. As sessões usam Fable 5 apenas depois que você o escolhe, com `/model fable`, uma configuração `model` ou o alias `best` onde Fable 5 está disponível. Escolhê-lo com `/model` o salva como o modelo selecionado em suas configurações de usuário, portanto as sessões posteriores começam em Fable 5 até que você altere os modelos.

269 322

381 434

382Se você definir um nível que o modelo ativo não suporta, Claude Code volta para o nível mais alto suportado no ou abaixo do que você definiu. Por exemplo, `xhigh` é executado como `high` em Opus 4.6.435Se você definir um nível que o modelo ativo não suporta, Claude Code volta para o nível mais alto suportado no ou abaixo do que você definiu. Por exemplo, `xhigh` é executado como `high` em Opus 4.6. Sua organização também pode limitar quais níveis estão disponíveis para um modelo; veja [Limites de esforço da organização](#organization-effort-limits).

383 436

384O esforço padrão é `high` em Fable 5, Sonnet 5, Opus 4.8, Opus 4.6 e Sonnet 4.6, e `xhigh` em Opus 4.7.437O esforço padrão é `high` em Fable 5, Sonnet 5, Opus 4.8, Opus 4.6 e Sonnet 4.6, e `xhigh` em Opus 4.7.

385 438

monitoring-usage.md +1 −1

Details

1186 1186

1187Claude 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.1187Claude 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.

1188 1188

1189O atributo `attempt` no evento registra quantas tentativas foram feitas no total. `CLAUDE_CODE_MAX_RETRIES` tem como padrão 10 e é limitado a 15. Quando 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. Um valor menor indica um erro não retentável, como uma resposta `400`.1189O atributo `attempt` no evento registra o número total de tentativas. `CLAUDE_CODE_MAX_RETRIES` tem como padrão 10 e é limitado a 15; {/* min-version: 2.1.199 */}a partir da v2.1.199, `CLAUDE_CODE_RETRY_WATCHDOG` aumenta o padrão e remove o limite. Quando 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`.

1190 1190

1191Para 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.1191Para 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.

1192 1192

permission-modes.md +22 −7

Details

237* Force push ou push direto para `main`237* Force push ou push direto para `main`

238* {/* min-version: 2.1.182 */}`git reset --hard`, `git checkout -- .`, `git restore .`, `git clean -fd`, `git stash drop`, ou `git stash clear`, que o classificador presume que descartariam alterações não confirmadas238* {/* min-version: 2.1.182 */}`git reset --hard`, `git checkout -- .`, `git restore .`, `git clean -fd`, `git stash drop`, ou `git stash clear`, que o classificador presume que descartariam alterações não confirmadas

239* `git commit --amend` quando o commit no HEAD não foi criado nesta sessão239* `git commit --amend` quando o commit no HEAD não foi criado nesta sessão

240* {/* min-version: 2.1.198 */}A partir da v2.1.198, `git commit --amend` quando o commit no HEAD já foi enviado. Uma reword apenas de mensagem não é bloqueada: `--amend -m` sem nada recém-preparado, em um commit que Claude criou durante esta sessão

240* `terraform destroy`, `pulumi destroy`, `cdk destroy`, ou `terragrunt destroy`, e aplicar um plano que destrói recursos241* `terraform destroy`, `pulumi destroy`, `cdk destroy`, ou `terragrunt destroy`, e aplicar um plano que destrói recursos

241 242

242Claude Code v2.1.195 e posterior bloqueiam mais categorias por padrão. Várias dependem de entradas de [ambiente](/pt/auto-mode-config#define-trusted-infrastructure), como destinos remotos sensíveis e escopos de IaC protegidos, que você pode restringir a nomes concretos.243Claude Code v2.1.195 e posterior bloqueiam mais categorias por padrão. Várias dependem de entradas de [ambiente](/pt/auto-mode-config#define-trusted-infrastructure), como destinos remotos sensíveis e escopos de IaC protegidos, que você pode restringir a nomes concretos.

251* Shells interativos ou port-forwards em um destino remoto sensível252* Shells interativos ou port-forwards em um destino remoto sensível

252* Abertura de um túnel ou shell reverso que torna um serviço local acessível da internet pública253* Abertura de um túnel ou shell reverso que torna um serviço local acessível da internet pública

253* Impressão de uma credencial ou token ao vivo na transcrição ou em um arquivo254* Impressão de uma credencial ou token ao vivo na transcrição ou em um arquivo

254* Acesso a um local de PII ou dados regulados, ou cópia de dados para fora de um255* Acesso a um local listado como local de dados sensíveis em seu [ambiente](/pt/auto-mode-config#define-trusted-infrastructure), ou cópia de dados para fora de um. {/* min-version: 2.1.198 */}A partir da v2.1.198, isso também bloqueia o envio de dados de um para um público que a entrada exclui

255* Roteamento de uma instalação de pacote em torno de seu registro de pacotes interno para um registro público256* Roteamento de uma instalação de pacote em torno de seu registro de pacotes interno para um registro público. {/* min-version: 2.1.198 */}A partir da v2.1.198, isso também se aplica quando você disse a Claude que um registro interno ou espelho existe na conversa, não apenas quando um está listado em seu ambiente

256* Execução de um comando com um sinalizador que desativa uma proteção de segurança, como `--insecure`257* Execução de um comando com um sinalizador que desativa uma proteção de segurança, como `--insecure`

258* Lançamento de um loop de agente autônomo que é executado sem aprovação humana ou sandbox, como um iniciado com `--dangerously-skip-permissions` ou `--no-sandbox`. {/* min-version: 2.1.198 */}A partir da v2.1.198, isso também cobre a execução de um agente de terceiros ou harness de avaliação com isolamento e aprovação por ação desabilitados, como um runner iniciado com `--yes-always`

257* Ações do [Claude no Chrome](/pt/chrome) que poderiam enviar conteúdo da página, cookies ou credenciais fora de origem259* Ações do [Claude no Chrome](/pt/chrome) que poderiam enviar conteúdo da página, cookies ou credenciais fora de origem

258 260

261Claude Code v2.1.198 e posterior também bloqueiam estes por padrão:

262

263* Exclusão de arquivos em `/tmp`, `$TMPDIR`, ou outro diretório compartilhado de rascunho ou cache por wildcard, glob ou filtro de idade em vez de por um caminho nomeado específico

264* Inclusão de detalhes sensíveis em conteúdo enviado, carregado, publicado ou escrito para outras pessoas ou sistemas compartilhados, quando sua própria mensagem não autorizou esses detalhes para esse destinatário

265* Envio de pressionamentos de tecla para o próprio painel tmux do Claude Code para conduzir sua própria interface, que o classificador trata como Claude alterando suas próprias permissões ou supervisão

266

259**Permitido por padrão**:267**Permitido por padrão**:

260 268

261* Operações de arquivo local em seu diretório de trabalho269* Operações de arquivo local em seu diretório de trabalho

272* Envio de dados para os domínios confiáveis, buckets e serviços que você lista em [`environment`](/pt/auto-mode-config#define-trusted-infrastructure). Isso cobre apenas fluxo de dados, não operações destrutivas ou de credenciais na mesma infraestrutura280* Envio de dados para os domínios confiáveis, buckets e serviços que você lista em [`environment`](/pt/auto-mode-config#define-trusted-infrastructure). Isso cobre apenas fluxo de dados, não operações destrutivas ou de credenciais na mesma infraestrutura

273* [Claude no Chrome](/pt/chrome) navegação para um domínio interno confiável, localhost ou uma URL que você nomeou281* [Claude no Chrome](/pt/chrome) navegação para um domínio interno confiável, localhost ou uma URL que você nomeou

274 282

275Solicitações de acesso à rede do sandbox são roteadas através do classificador em vez de serem permitidas por padrão. Execute `claude auto-mode defaults` para ver as listas de regras completas. Se ações rotineiras forem bloqueadas, um administrador pode adicionar repositórios confiáveis, buckets e serviços via configuração `autoMode.environment`: veja [Configure auto mode](/pt/auto-mode-config).283Solicitações de acesso à rede do sandbox são roteadas através do classificador em vez de serem permitidas por padrão. {/* min-version: 2.1.198 */}A partir da v2.1.198, o classificador reutiliza seu veredicto para um host e porta de rede em vez de re-executar em cada conexão:

284

285* Um permitir é reutilizado até que novo conteúdo entre na conversa, ponto em que esse host é verificado novamente

286* Na CLI interativa, um negar é descartado quando o turno termina

287* Em [modo não-interativo](/pt/headless) e sessões do Agent SDK não há limite de turno, então um negar é reutilizado para o resto da execução

288* Alterar seu modo de permissão ou regras descarta todos os veredictos em cache

289

290Execute `claude auto-mode defaults` para ver as listas de regras completas. Se ações rotineiras forem bloqueadas, um administrador pode adicionar repositórios confiáveis, buckets e serviços via configuração `autoMode.environment`: veja [Configure auto mode](/pt/auto-mode-config).

276 291

277<h3 id="boundaries-you-state-in-conversation">292<h3 id="boundaries-you-state-in-conversation">

278 Limites que você declara na conversa293 Limites que você declara na conversa

300 315

301 1. Ações correspondentes às suas [regras de permitir ou negar](/pt/permissions#manage-permissions) resolvem imediatamente, exceto escritas em [caminhos protegidos](#protected-paths), que são roteadas para o classificador mesmo quando uma regra de permitir corresponde316 1. Ações correspondentes às suas [regras de permitir ou negar](/pt/permissions#manage-permissions) resolvem imediatamente, exceto escritas em [caminhos protegidos](#protected-paths), que são roteadas para o classificador mesmo quando uma regra de permitir corresponde

302 2. Ações somente leitura e edições de arquivo em seu diretório de trabalho são auto-aprovadas, exceto escritas em [caminhos protegidos](#protected-paths)317 2. Ações somente leitura e edições de arquivo em seu diretório de trabalho são auto-aprovadas, exceto escritas em [caminhos protegidos](#protected-paths)

303 3. Tudo mais vai para o classificador318 3. Tudo mais vai para o classificador. {/* min-version: 2.1.199 */}A partir da v2.1.199, uma ferramenta MCP marcada com [`_meta["anthropic/requiresUserInteraction"]`](/pt/mcp#require-approval-for-a-specific-tool) pula o classificador e o solicita diretamente, então uma etapa de consentimento nunca é auto-aprovada em nome do autor da ferramenta

304 4. Se o classificador bloqueia, Claude recebe o motivo e tenta uma alternativa319 4. Se o classificador bloqueia, Claude recebe o motivo e tenta uma alternativa

305 320

306 Ao entrar em auto mode, regras de permitir amplas que concedem execução de código arbitrário são descartadas:321 Ao entrar em auto mode, regras de permitir amplas que concedem execução de código arbitrário são descartadas:

326 </Accordion>341 </Accordion>

327 342

328 <Accordion title="Custo e latência">343 <Accordion title="Custo e latência">

329 O classificador é executado em um modelo configurado pelo servidor que é independente de sua seleção `/model`, então alternar modelos não muda a disponibilidade do classificador. Chamadas do classificador contam para seu uso de tokens. Cada verificação envia uma porção da transcrição mais a ação pendente, adicionando uma viagem de ida e volta antes da execução. Leituras e edições de diretório de trabalho fora de caminhos protegidos pulam o classificador, então a sobrecarga vem principalmente de comandos shell e operações de rede.344 O classificador é executado em um modelo configurado pelo servidor que é independente de sua seleção `/model`, então alternar modelos não muda a disponibilidade do classificador. Chamadas do classificador contam para seu uso de tokens. Cada verificação envia uma porção da transcrição mais a ação pendente, adicionando uma viagem de ida e volta antes da execução. Leituras e edições de diretório de trabalho fora de caminhos protegidos pulam o classificador, então a sobrecarga vem principalmente de comandos shell e operações de rede. {/* min-version: 2.1.198 */}A partir da v2.1.198, um veredicto de rede do sandbox para um host e porta é reutilizado em vez de re-classificado em cada conexão, então conexões repetidas para o mesmo host não adicionam cada uma uma verificação. [O que o classificador bloqueia por padrão](#what-the-classifier-blocks-by-default) descreve quanto tempo um permitir e um negar duram.

330 </Accordion>345 </Accordion>

331</AccordionGroup>346</AccordionGroup>

332 347

334 Allow only pre-approved tools with dontAsk mode349 Allow only pre-approved tools with dontAsk mode

335</h2>350</h2>

336 351

337O modo `dontAsk` auto-nega toda chamada de ferramenta que de outra forma solicitaria. Apenas ações correspondentes às suas regras `permissions.allow` e [comandos Bash somente leitura](/pt/permissions#read-only-commands) podem ser executadas; regras [`ask` explícitas](/pt/permissions#manage-permissions) são negadas em vez de solicitar. Isso torna o modo totalmente não-interativo para pipelines CI ou ambientes restritos onde você pré-define exatamente o que Claude pode fazer. Sessões em nuvem no [Claude Code na web](/pt/claude-code-on-the-web) ignoram `defaultMode: "dontAsk"`; consulte [bypassPermissions](#skip-all-checks-with-bypasspermissions-mode) para detalhes.352O modo `dontAsk` auto-nega toda chamada de ferramenta que de outra forma solicitaria. A barra de status mostra `⏵⏵ don't ask on` enquanto este modo está ativo. Apenas ações correspondentes às suas regras `permissions.allow` e [comandos Bash somente leitura](/pt/permissions#read-only-commands) podem ser executadas; regras [`ask` explícitas](/pt/permissions#manage-permissions) são negadas em vez de solicitar. {/* min-version: 2.1.199 */}A partir da v2.1.199, uma ferramenta MCP marcada com [`_meta["anthropic/requiresUserInteraction"]`](/pt/mcp#require-approval-for-a-specific-tool) também é negada neste modo mesmo quando uma regra de permissão corresponde a ela, porque seu cartão de aprovação precisa de uma resposta que este modo nunca coleta. Isso torna o modo totalmente não-interativo para pipelines CI ou ambientes restritos onde você pré-define exatamente o que Claude pode fazer. Sessões em nuvem no [Claude Code na web](/pt/claude-code-on-the-web) ignoram `defaultMode: "dontAsk"`; consulte [bypassPermissions](#skip-all-checks-with-bypasspermissions-mode) para detalhes.

338 353

339Defina-o na inicialização com a flag:354Defina-o na inicialização com a flag:

340 355

346 Pule todas as verificações com o modo bypassPermissions361 Pule todas as verificações com o modo bypassPermissions

347</h2>362</h2>

348 363

349O modo `bypassPermissions` desabilita prompts de permissão e verificações de segurança para que chamadas de ferramenta sejam executadas imediatamente. A partir da v2.1.126, isso inclui escritas em [caminhos protegidos](#protected-paths), que versões anteriores ainda solicitavam. Regras [ask explícitas](/pt/permissions#manage-permissions) ainda forçam um prompt neste modo, e remoções direcionadas à raiz do sistema de arquivos ou diretório home, como `rm -rf /` e `rm -rf ~`, ainda solicitam como um disjuntor contra erro do modelo. Use este modo apenas em ambientes isolados como contêineres, VMs ou dev containers sem acesso à internet, onde Claude Code não pode danificar seu sistema host.364O modo `bypassPermissions` desabilita prompts de permissão e verificações de segurança para que chamadas de ferramenta sejam executadas imediatamente. A partir da v2.1.126, isso inclui escritas em [caminhos protegidos](#protected-paths), que versões anteriores ainda solicitavam. Regras [ask explícitas](/pt/permissions#manage-permissions) ainda forçam um prompt neste modo, e remoções direcionadas à raiz do sistema de arquivos ou diretório home, como `rm -rf /` e `rm -rf ~`, ainda solicitam como um disjuntor contra erro do modelo. {/* min-version: 2.1.199 */}A partir da v2.1.199, ferramentas MCP marcadas com [`_meta["anthropic/requiresUserInteraction"]`](/pt/mcp#require-approval-for-a-specific-tool) também ainda solicitam. Use este modo apenas em ambientes isolados como contêineres, VMs ou dev containers sem acesso à internet, onde Claude Code não pode danificar seu sistema host.

350 365

351Você não pode entrar em `bypassPermissions` a partir de uma sessão que foi iniciada sem uma das flags de habilitação; reinicie com uma para habilitá-lo:366Você não pode entrar em `bypassPermissions` a partir de uma sessão que foi iniciada sem uma das flags de habilitação; reinicie com uma para habilitá-lo:

352 367

permissions.md +14 −3

Details

272As regras Read e Edit seguem a especificação [gitignore](https://git-scm.com/docs/gitignore) com quatro tipos de padrão distintos:272As regras Read e Edit seguem a especificação [gitignore](https://git-scm.com/docs/gitignore) com quatro tipos de padrão distintos:

273 273

275| ------------------ | ----------------------------------------------- | -------------------------------- | ------------------------------- |275| ------------------ | ----------------------------------------------- | -------------------------------- | ----------------------------------------------------------- |

276| `//path` | Caminho absoluto da raiz do sistema de arquivos | `Read(//Users/alice/secrets/**)` | `/Users/alice/secrets/**` |276| `//path` | Caminho absoluto da raiz do sistema de arquivos | `Read(//Users/alice/secrets/**)` | `/Users/alice/secrets/**` |

277| `~/path` | Caminho do diretório home | `Read(~/Documents/*.pdf)` | `/Users/alice/Documents/*.pdf` |277| `~/path` | Caminho do diretório home | `Read(~/Documents/*.pdf)` | `/Users/alice/Documents/*.pdf` |

278| `/path` | Caminho relativo à raiz do projeto | `Edit(/src/**/*.ts)` | `<raiz do projeto>/src/**/*.ts` |278| `/path` | Caminho relativo à fonte de configurações | `Edit(/src/**/*.ts)` | `<raiz do projeto>/src/**/*.ts` em configurações de projeto |

279| `path` ou `./path` | Caminho relativo ao diretório atual | `Read(*.env)` | `<cwd>/*.env` |279| `path` ou `./path` | Caminho relativo ao diretório atual | `Read(*.env)` | `<cwd>/*.env` |

280 280

281<Warning>281<Warning>

282 Um padrão como `/Users/alice/file` não é um caminho absoluto. É relativo à raiz do projeto. Use `//Users/alice/file` para caminhos absolutos.282 Um padrão como `/Users/alice/file` não é um caminho absoluto. A barra inicial única ancora na fonte de configurações, não na raiz do sistema de arquivos. Use `//Users/alice/file` para caminhos absolutos.

283</Warning>283</Warning>

284 284

285Um padrão `/path` ancora no diretório associado ao arquivo de configurações que o define, portanto a mesma regra corresponde a locais diferentes dependendo de onde você a coloca:

286

287| Regra definida em | `/path` se resolve para |

288| :-------------------------------------------------------------- | :---------------------------- |

289| Configurações de projeto ou local, como `.claude/settings.json` | `<raiz do projeto>/path` |

290| Configurações de usuário em `~/.claude/settings.json` | `~/.claude/path` |

291| Um arquivo passado com `--settings <file>` | `<diretório do arquivo>/path` |

292| Flags CLI, `/permissions` ou regras de sessão | `<cwd original>/path` |

293

294Uma regra deny como `Read(/secrets/**)` em configurações de usuário bloqueia `~/.claude/secrets/**`, não um diretório `secrets` em seu projeto. Para escrever uma regra em configurações de usuário que se aplique dentro de cada projeto, use um caminho absoluto `//` ou um caminho relativo à home `~/` em vez disso.

295

285No Windows, os caminhos são normalizados para forma POSIX antes da correspondência. `C:\Users\alice` se torna `/c/Users/alice`, portanto use `//c/**/.env` para corresponder arquivos `.env` em qualquer lugar nessa unidade. Para corresponder em todas as unidades, use `//**/.env`.296No Windows, os caminhos são normalizados para forma POSIX antes da correspondência. `C:\Users\alice` se torna `/c/Users/alice`, portanto use `//c/**/.env` para corresponder arquivos `.env` em qualquer lugar nessa unidade. Para corresponder em todas as unidades, use `//**/.env`.

286 297

287Exemplos:298Exemplos:

plugins.md +2 −2

Details

352Conforme você faz mudanças no seu plugin, execute `/reload-plugins` para pegar as atualizações sem reiniciar. Isso recarrega plugins, skills, agents, hooks, plugin MCP servers e plugin LSP servers. Teste seus componentes de plugin:352Conforme você faz mudanças no seu plugin, execute `/reload-plugins` para pegar as atualizações sem reiniciar. Isso recarrega plugins, skills, agents, hooks, plugin MCP servers e plugin LSP servers. Teste seus componentes de plugin:

353 353

354* Tente seus skills com `/plugin-name:skill-name`354* Tente seus skills com `/plugin-name:skill-name`

355* Verifique que agents aparecem em `/agents`355* Verifique que agents aparecem em `/context` sob Custom Agents, ou @-mencione um pelo seu nome com escopo

356* Verifique que hooks funcionam como esperado356* Verifique que hooks funcionam como esperado

357 357

358<Tip>358<Tip>

502 claude --plugin-dir ./my-plugin502 claude --plugin-dir ./my-plugin

503 ```503 ```

504 504

505 Teste cada componente: execute seus comandos, verifique que agents aparecem em `/agents` e verifique que hooks disparam corretamente.505 Teste cada componente: execute seus comandos, verifique que agents aparecem em `/context`, e verifique que hooks disparam corretamente.

506 </Step>506 </Step>

507</Steps>507</Steps>

508 508

plugins-reference.md +1 −1

Details

79 79

80**Pontos de integração**:80**Pontos de integração**:

81 81

~~82* Agents aparecem na interface `/agents`~~82* Agents aparecem na typeahead [@-mention](/pt/sub-agents#invoke-subagents-explicitly) sob seu nome com escopo, como `my-plugin:code-reviewer`, uma vez que o plugin está habilitado

83* Claude pode invocar agents automaticamente com base no contexto da tarefa83* Claude pode invocar agents automaticamente com base no contexto da tarefa

84* Agents podem ser invocados manualmente por usuários84* Agents podem ser invocados manualmente por usuários

85* Agents de plugin funcionam ao lado de agents Claude integrados85* Agents de plugin funcionam ao lado de agents Claude integrados

sandboxing.md +43 −5

Details

199 Protect credentials199 Protect credentials

200</h3>200</h3>

201 201

202A configuração `sandbox.credentials` declara arquivos de credenciais e variáveis de ambiente que comandos em sandbox não devem acessar. Os caminhos de arquivo listados são negados para leituras dentro do sandbox, o mesmo bloqueio que `filesystem.denyRead` aplica, e as variáveis de ambiente listadas são removidas antes de cada comando em sandbox ser executado. O bloco `credentials` dedicado mantém as regras de credenciais agrupadas com a remoção de variável de ambiente e separadas das regras gerais do sistema de arquivos. Requer Claude Code v2.1.187 ou posterior.202A configuração `sandbox.credentials` declara arquivos de credenciais e variáveis de ambiente a proteger de comandos em sandbox. Cada entrada nomeia um caminho de arquivo ou uma variável de ambiente e um `mode`. O bloco `credentials` dedicado mantém as regras de credenciais agrupadas e separadas das regras gerais do sistema de arquivos. Requer Claude Code v2.1.187 ou posterior.

203

204Para entradas com `"mode": "deny"`, caminhos de arquivo são negados para leituras dentro do sandbox, a mesma restrição que `filesystem.denyRead` aplica, e variáveis de ambiente são removidas antes de cada comando em sandbox ser executado.

203 205

204O exemplo abaixo bloqueia leituras do arquivo de credenciais AWS e do diretório SSH e remove `GITHUB_TOKEN` e `NPM_TOKEN` do ambiente de comandos em sandbox:206O exemplo abaixo bloqueia leituras do arquivo de credenciais AWS e do diretório SSH e remove `GITHUB_TOKEN` e `NPM_TOKEN` do ambiente de comandos em sandbox:

205 207

221}223}

222```224```

223 225

224Cada entrada carrega `"mode": "deny"`, que é o único valor suportado. O campo `mode` explícito mantém o esquema compatível com versões futuras com novos modos. Os caminhos de arquivo seguem as mesmas [regras de prefixo](/pt/settings#sandbox-path-prefixes) que as configurações `sandbox.filesystem.*`, e as entradas de cada [settings scope](/pt/settings#settings-precedence) são mescladas. Como o único modo é `deny`, qualquer escopo pode adicionar restrições, mas nenhum pode removê-las.226Entradas de arquivo suportam apenas `"mode": "deny"`. Entradas de variáveis de ambiente também aceitam `"mode": "mask"`, descrito abaixo.

227

228Os caminhos de arquivo seguem as mesmas [regras de prefixo](/pt/settings#sandbox-path-prefixes) que as configurações `sandbox.filesystem.*`, e as entradas `deny` de cada [settings scope](/pt/settings#settings-precedence) são mescladas. Uma entrada `deny` apenas restringe o acesso, portanto qualquer escopo pode adicionar uma, mas nenhum escopo pode remover uma que outro escopo adicionou.

225 229

226Não há uma lista de negação de credenciais integrada, portanto apenas os arquivos e variáveis que você listar são restritos. A configuração afeta apenas comandos Bash em sandbox. Para remover credenciais da Anthropic e de provedores de nuvem de todos os subprocessos independentemente do sandboxing, defina [`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`](/pt/env-vars).230Não há uma lista de negação de credenciais integrada, portanto apenas os arquivos e variáveis que você listar são restritos. A configuração afeta apenas comandos Bash em sandbox. Para remover credenciais da Anthropic e de provedores de nuvem de todos os subprocessos independentemente do sandboxing, defina [`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`](/pt/env-vars).

227 231

232<h4 id="mask-environment-variables">

233 Mask environment variables

234</h4>

235

236`"mode": "mask"` protege uma credencial mantendo as ferramentas que se autenticam com ela funcionando. `deny` remove a variável inteiramente, o que também quebra ferramentas que precisam dela, como `gh` ou `npm`. Requer Claude Code v2.1.199 ou posterior.

237

238Com `mask`, o comando em sandbox vê um valor sentinela por sessão em vez do real. Quando uma solicitação sai do sandbox para um dos `injectHosts` da credencial, o [sandbox proxy](#network-isolation) substitui o sentinela pelo valor real. O comando e tudo que ele registra nunca mantêm a credencial real, mas suas solicitações ainda se autenticam.

239

240O proxy substitui a credencial dentro do conteúdo da solicitação, portanto tem que vê-lo. Defina [`network.tlsTerminate`](/pt/settings#sandbox-settings) para que o proxy termine HTTPS em si. Sem isso, o mascaramento falha fechado: o comando ainda vê apenas o sentinela, mas o sentinela chega ao servidor inalterado e a autenticação falha. Claude Code relata essa configuração incorreta na inicialização e em `/doctor`.

241

242O exemplo abaixo mascara dois tokens. `GH_TOKEN` é substituído apenas em solicitações para `api.github.com`, enquanto `NPM_TOKEN` não tem `injectHosts` e é substituído em solicitações para cada host em `network.allowedDomains`. Cada entrada `injectHosts` deve ser coberta por `network.allowedDomains`.

243

244```json theme={null}

245{

246 "sandbox": {

247 "enabled": true,

248 "network": {

249 "tlsTerminate": {},

250 "allowedDomains": ["*.github.com", "registry.npmjs.org"]

251 },

252 "credentials": {

253 "envVars": [

254 { "name": "GH_TOKEN", "mode": "mask", "injectHosts": ["api.github.com"] },

255 { "name": "NPM_TOKEN", "mode": "mask" }

256 ]

257 }

258 }

259}

260```

261

262Diferentemente de `deny`, o mascaramento autoriza o proxy a enviar sua credencial real para os hosts listados, portanto é honrado apenas a partir de configurações que você ou seu administrador controlam: configurações de usuário, configurações gerenciadas e o sinalizador CLI `--settings`. Entradas `mask`, `network.tlsTerminate` e [`credentials.allowPlaintextInject`](/pt/settings#sandbox-settings) no `.claude/settings.json` ou `.claude/settings.local.json` de um repositório são ignoradas.

263

264Quando a mesma variável é listada com `deny` em qualquer escopo, `deny` tem precedência.

265

228<h2 id="how-sandboxing-works">266<h2 id="how-sandboxing-works">

229 Como o sandboxing funciona267 Como o sandboxing funciona

230</h2>268</h2>

255* **Cobertura abrangente**: as restrições se aplicam a todos os scripts, programas e subprocessos gerados por comandos293* **Cobertura abrangente**: as restrições se aplicam a todos os scripts, programas e subprocessos gerados por comandos

256 294

257<Note>295<Note>

258 O proxy integrado impõe a allowlist com base no nome de host solicitado e não termina ou inspeciona tráfego TLS. Consulte [Limitações de segurança](#security-limitations) para as implicações deste design, e [Configuração de proxy personalizado](#custom-proxy-configuration) se seu modelo de ameaça exigir inspeção TLS.296 O proxy integrado impõe a allowlist com base no nome de host solicitado e, por padrão, não termina ou inspeciona tráfego TLS. {/* min-version: 2.1.199 */}A configuração experimental [`network.tlsTerminate`](/pt/settings#sandbox-settings), disponível no Claude Code v2.1.199 e posterior, faz com que o proxy integrado termine TLS em si mesmo, o que as entradas de credenciais [`mask`](#protect-credentials) exigem. Consulte [Limitações de segurança](#security-limitations) para as implicações do padrão, e [Configuração de proxy personalizado](#custom-proxy-configuration) se seu modelo de ameaça exigir inspeção TLS.

259</Note>297</Note>

260 298

261<h3 id="os-level-enforcement">299<h3 id="os-level-enforcement">

412 Limitações de segurança450 Limitações de segurança

413</h3>451</h3>

414 452

415* **Filtragem de rede**: o sistema de filtragem de rede funciona restringindo os domínios aos quais os processos podem se conectar. O proxy integrado não termina ou realiza inspeção TLS no tráfego de saída, portanto o conteúdo de conexões criptografadas não é examinado. Você é responsável por garantir que apenas domínios confiáveis sejam permitidos em sua política.453* **Filtragem de rede**: o sandbox restringe quais domínios os processos podem se conectar. Por padrão, o proxy integrado não termina ou inspeciona TLS no tráfego de saída, portanto o conteúdo de conexões criptografadas não é examinado. A configuração experimental [`network.tlsTerminate`](/pt/settings#sandbox-settings) termina TLS no proxy para [substituição de credenciais `mask`](#protect-credentials), mas não adiciona filtragem de conteúdo. Você é responsável por garantir que apenas domínios confiáveis sejam permitidos em sua política.

416 454

417<Warning>455<Warning>

418 Permitir domínios amplos como `github.com` pode criar caminhos para exfiltração de dados. Como o proxy toma sua decisão de permissão do nome de host fornecido pelo cliente sem inspecionar TLS, código executado dentro do sandbox pode potencialmente usar [domain fronting](https://en.wikipedia.org/wiki/Domain_fronting) ou técnicas similares para alcançar hosts fora da allowlist. Se seu modelo de ameaça exigir garantias mais fortes, configure um [custom proxy](#custom-proxy-configuration) que termine TLS e inspecione tráfego, e instale seu certificado CA dentro do sandbox. Isolamento de rede mais forte e consciente de TLS é uma área ativa de desenvolvimento.456 Permitir domínios amplos como `github.com` pode criar caminhos para exfiltração de dados. Como o proxy toma sua decisão de permissão do nome de host fornecido pelo cliente sem inspecionar TLS, código executado dentro do sandbox pode potencialmente usar [domain fronting](https://en.wikipedia.org/wiki/Domain_fronting) ou técnicas similares para alcançar hosts fora da allowlist. Se seu modelo de ameaça exigir garantias mais fortes, configure um [custom proxy](#custom-proxy-configuration) que termine TLS e inspecione tráfego, e instale seu certificado CA dentro do sandbox. Isolamento de rede mais forte e consciente de TLS é uma área ativa de desenvolvimento.

440 478

441* **Ferramentas de arquivo integradas**: Read, Edit e Write usam o sistema de permissão diretamente em vez de serem executadas através do sandbox. Consulte [permissions](/pt/permissions).479* **Ferramentas de arquivo integradas**: Read, Edit e Write usam o sistema de permissão diretamente em vez de serem executadas através do sandbox. Consulte [permissions](/pt/permissions).

442* **Computer use**: quando Claude abre aplicativos e controla sua tela, ele é executado em seu desktop real em vez de em um ambiente isolado. Prompts de permissão por aplicativo controlam cada aplicativo. Consulte [computer use in the CLI](/pt/computer-use) ou [computer use in Desktop](/pt/desktop#let-claude-use-your-computer).480* **Computer use**: quando Claude abre aplicativos e controla sua tela, ele é executado em seu desktop real em vez de em um ambiente isolado. Prompts de permissão por aplicativo controlam cada aplicativo. Consulte [computer use in the CLI](/pt/computer-use) ou [computer use in Desktop](/pt/desktop#let-claude-use-your-computer).

443* **Variáveis de ambiente**: comandos Bash em sandbox herdam o ambiente do processo pai por padrão, incluindo quaisquer credenciais definidas lá. Use [`sandbox.credentials`](#protect-credentials) para remover variáveis específicas para comandos em sandbox, ou defina [`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`](/pt/env-vars) para remover credenciais do Anthropic e do provedor de nuvem de todos os subprocessos.481* **Variáveis de ambiente**: comandos Bash em sandbox herdam o ambiente do processo pai por padrão, incluindo quaisquer credenciais definidas lá. Use [`sandbox.credentials`](#protect-credentials) para remover ou mascarar variáveis específicas para comandos em sandbox, ou defina [`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`](/pt/env-vars) para remover credenciais do Anthropic e do provedor de nuvem de todos os subprocessos.

444* **Subagents**: [subagents](/pt/sub-agents) são executados no mesmo processo que a sessão pai e usam a mesma configuração de sandbox. Comandos Bash dentro de um subagent são colocados em sandbox quando sandboxing está habilitado na sessão pai.482* **Subagents**: [subagents](/pt/sub-agents) são executados no mesmo processo que a sessão pai e usam a mesma configuração de sandbox. Comandos Bash dentro de um subagent são colocados em sandbox quando sandboxing está habilitado na sessão pai.

445 483

446<Warning>484<Warning>

server-managed-settings.md +27 −9

Details

153 153

154As configurações gerenciadas pelo servidor e as [configurações gerenciadas pelo endpoint](/pt/settings#settings-files) ocupam o nível mais alto na [hierarquia de configurações](/pt/settings#settings-precedence) do Claude Code. Nenhum outro nível de configurações pode substituí-las, incluindo argumentos de linha de comando.154As configurações gerenciadas pelo servidor e as [configurações gerenciadas pelo endpoint](/pt/settings#settings-files) ocupam o nível mais alto na [hierarquia de configurações](/pt/settings#settings-precedence) do Claude Code. Nenhum outro nível de configurações pode substituí-las, incluindo argumentos de linha de comando.

155 155

156Dentro do nível gerenciado, um [`policyHelper`](/pt/settings#compute-managed-settings-with-a-policy-helper) configurado preempta todas as outras fontes gerenciadas, incluindo configurações gerenciadas pelo servidor: sua saída se torna a única configuração gerenciada para a execução. Caso contrário, a primeira fonte que entrega uma configuração não vazia vence. As configurações gerenciadas pelo servidor são verificadas primeiro, depois as configurações gerenciadas pelo endpoint. As fontes não se mesclam: se as configurações gerenciadas pelo servidor entregarem qualquer chave, as configurações gerenciadas pelo endpoint são ignoradas completamente. Uma exceção se aplica: um pequeno conjunto de [chaves de bloqueio entre fontes](/pt/settings#settings-precedence), como os bloqueios da lista de permissão de sandbox, é honrado quando qualquer fonte gerenciada controlada por administrador os define; o nível de registro HKCU gravável pelo usuário é excluído. Se as configurações gerenciadas pelo servidor não entregarem nada, as configurações gerenciadas pelo endpoint se aplicam.156Dentro do nível gerenciado, um [`policyHelper`](/pt/settings#compute-managed-settings-with-a-policy-helper) configurado preempta todas as outras fontes gerenciadas, incluindo configurações gerenciadas pelo servidor: sua saída se torna a única configuração gerenciada para a execução.

157

158Caso contrário, o Claude Code usa a primeira fonte que entrega uma configuração não vazia. As configurações gerenciadas pelo servidor são verificadas primeiro, depois as configurações gerenciadas pelo endpoint. As fontes não se mesclam: se as configurações gerenciadas pelo servidor entregarem qualquer chave, as configurações gerenciadas pelo endpoint são ignoradas. Se as configurações gerenciadas pelo servidor não entregarem nada, as configurações gerenciadas pelo endpoint se aplicam.

159

160Uma exceção se aplica: um pequeno conjunto de [chaves de bloqueio entre fontes](/pt/settings#settings-precedence), como os bloqueios da lista de permissão de sandbox, é honrado quando qualquer fonte gerenciada controlada por administrador os define; o nível de registro HKCU gravável pelo usuário é excluído.

157 161

158Se você limpar sua configuração gerenciada pelo servidor no console de administração com a intenção de voltar a uma plist gerenciada pelo endpoint ou política de registro, esteja ciente de que [configurações em cache](#fetch-and-caching-behavior) persistem em máquinas cliente até a próxima busca bem-sucedida. Execute `/status` para ver qual fonte gerenciada está ativa.162Se você limpar sua configuração gerenciada pelo servidor no console de administração com a intenção de voltar a uma plist gerenciada pelo endpoint ou política de registro, esteja ciente de que [configurações em cache](#fetch-and-caching-behavior) persistem em máquinas cliente até a próxima busca bem-sucedida. Execute `/status` para ver qual fonte gerenciada está ativa.

159 163

171 175

172**Lançamentos subsequentes com configurações em cache:**176**Lançamentos subsequentes com configurações em cache:**

173 177

174* As configurações em cache se aplicam imediatamente na inicialização178* As configurações em cache se aplicam imediatamente na inicialização, exceto pelas variáveis de ambiente de transporte, roteamento e autenticação descritas abaixo

175* O Claude Code busca configurações atualizadas em segundo plano179* O Claude Code busca configurações atualizadas em segundo plano

176* As configurações em cache persistem através de falhas de rede180* As configurações em cache persistem através de falhas de rede. As variáveis retidas permanecem retidas até que uma busca seja bem-sucedida

181

182A partir da v2.1.198, o Claude Code retém três categorias de variáveis no bloco `env` em cache até que o servidor confirme o payload para a sessão. Isso evita que um valor de proxy em cache, autoridade de certificação, endpoint ou credencial redirecione, intercepte ou reautentique a busca de configurações que confirma o payload. O endurecimento se aplica apenas ao cache de configurações buscado do servidor: [configurações gerenciadas pelo endpoint](/pt/settings#settings-files) implantadas através de MDM ou `managed-settings.json` não são afetadas. As categorias retidas são:

183

184* Configuração de proxy e TLS, como `HTTPS_PROXY`, `NODE_EXTRA_CA_CERTS` e as variáveis de certificado de cliente mTLS `CLAUDE_CODE_CLIENT_CERT` e `CLAUDE_CODE_CLIENT_KEY`

185* Roteamento de API e seleção de provedor, incluindo `ANTHROPIC_BASE_URL`, as variáveis de seleção de provedor como `CLAUDE_CODE_USE_BEDROCK` e `CLAUDE_CODE_USE_VERTEX`, e as URLs de endpoint do provedor como `ANTHROPIC_BEDROCK_BASE_URL`

186* Credenciais de autenticação, como `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN` e `CLAUDE_CODE_OAUTH_TOKEN`

187

188Todas as outras chaves no bloco `env` em cache, como telemetria e configuração OpenTelemetry, se aplicam na inicialização como antes. Uma vez que a busca seja bem-sucedida, as variáveis retidas se aplicam pelo resto da sessão.

189

190Se sua organização precisa de um proxy para alcançar `api.anthropic.com`, defina-o no ambiente do shell ou em [configurações do usuário](/pt/settings#settings-files) em vez de apenas no bloco `env` gerenciado. O primeiro lançamento não tem cache, portanto essas fontes já eram necessárias para a busca inicial.

177 191

178O Claude Code aplica atualizações de configurações automaticamente sem reinicialização, exceto para configurações avançadas como configuração OpenTelemetry, que exigem uma reinicialização completa para entrar em vigor.192O Claude Code aplica atualizações de configurações automaticamente sem reinicialização, exceto para configurações avançadas como configuração OpenTelemetry, que exigem uma reinicialização completa para entrar em vigor.

179 193

207}221}

208```222```

209 223

210Você também pode definir essa chave em um [perfil MDM gerenciado pelo endpoint](/pt/settings#settings-files) ou arquivo `managed-settings.json` do sistema para impor comportamento de falha fechada no primeiro lançamento, antes de qualquer payload do servidor ter sido entregue. A partir da v2.1.191, esse sinalizador é uma exceção à [regra de precedência](#settings-precedence) acima: ele é honrado quando definido em qualquer fonte gerenciada mesmo se um payload gerenciado pelo servidor em cache também estiver presente, portanto um valor entregue por MDM não é ignorado quando configurações gerenciadas pelo servidor existem. A busca de configurações também envia um cabeçalho `Cache-Control: no-cache` para que proxies HTTP intermediários não sirvam uma resposta obsoleta.224Você também pode definir essa chave em um [perfil MDM gerenciado pelo endpoint](/pt/settings#settings-files) ou arquivo `managed-settings.json` do sistema para impor comportamento de falha fechada no primeiro lançamento, antes de qualquer payload do servidor ter sido entregue. A partir da v2.1.191, esse sinalizador é uma exceção à [regra de precedência](#settings-precedence) acima: ele é honrado quando definido em qualquer fonte gerenciada mesmo se um payload gerenciado pelo servidor em cache também estiver presente, portanto um valor entregue por MDM não é ignorado quando configurações gerenciadas pelo servidor existem.

225

226A busca de configurações também envia um cabeçalho `Cache-Control: no-cache` para que proxies HTTP intermediários não sirvam uma resposta obsoleta.

211 227

212Antes de ativar essa configuração, certifique-se de que suas políticas de rede permitem conectividade a `api.anthropic.com`. Se esse endpoint estiver inacessível, a CLI sai na inicialização e os usuários não podem iniciar o Claude Code.228Antes de ativar essa configuração, certifique-se de que suas políticas de rede permitem conectividade a `api.anthropic.com`. Se esse endpoint estiver inacessível, a CLI sai na inicialização e os usuários não podem iniciar o Claude Code.

213 229

217 Caixas de diálogo de aprovação de segurança233 Caixas de diálogo de aprovação de segurança

218</h3>234</h3>

219 235

220Certas configurações que podem representar riscos de segurança exigem aprovação explícita do usuário antes de serem aplicadas:236Certas configurações que podem representar riscos de segurança exigem aprovação explícita do usuário antes de o Claude Code aplicá-las:

221 237

222* **Configurações de comando shell**: configurações que executam comandos shell238* **Configurações de comando shell**: configurações que executam comandos shell

223* **Variáveis de ambiente personalizadas**: variáveis não na lista de permissão segura conhecida239* **Variáveis de ambiente personalizadas**: variáveis não na lista de permissão segura conhecida

234 Disponibilidade de plataforma250 Disponibilidade de plataforma

235</h2>251</h2>

236 252

237As configurações gerenciadas pelo servidor exigem uma conexão direta a `api.anthropic.com`, e a entrega requer que a sessão se autentique com um login OAuth da organização ou uma chave de API configurada diretamente: as chaves retornadas por um script [`apiKeyHelper`](/pt/settings#available-settings) não acionam a busca de configurações. As configurações gerenciadas pelo servidor não estão disponíveis ao usar provedores de modelo de terceiros:253As configurações gerenciadas pelo servidor exigem uma conexão direta a `api.anthropic.com`, e a entrega requer que a sessão se autentique com um login OAuth da organização ou uma chave de API configurada diretamente. As chaves retornadas por um script [`apiKeyHelper`](/pt/settings#available-settings) não acionam a busca de configurações.

254

255As configurações gerenciadas pelo servidor não estão disponíveis ao usar provedores de modelo de terceiros:

238 256

239* Amazon Bedrock257* Amazon Bedrock

240* Google Vertex AI258* Google Vertex AI

259As configurações gerenciadas pelo servidor fornecem aplicação de política centralizada, mas funcionam como um controle do lado do cliente, não como um limite de segurança. Em dispositivos não gerenciados, um usuário não precisa de acesso de administrador ou sudo para contorná-las.277As configurações gerenciadas pelo servidor fornecem aplicação de política centralizada, mas funcionam como um controle do lado do cliente, não como um limite de segurança. Em dispositivos não gerenciados, um usuário não precisa de acesso de administrador ou sudo para contorná-las.

260 278

262| :----------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |280| :----------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

263| Usuário edita o arquivo de configurações em cache | O arquivo adulterado se aplica na inicialização, mas as configurações corretas são restauradas na próxima busca do servidor |281| Usuário edita o arquivo de configurações em cache | O arquivo adulterado se aplica na inicialização, mas as configurações corretas são restauradas na próxima busca do servidor. {/* min-version: 2.1.198 */}A partir da v2.1.198, as variáveis de ambiente de transporte, roteamento de API e autenticação no bloco `env` são [retidas até que o servidor confirme o payload](#fetch-and-caching-behavior) |

264| Usuário deleta o arquivo de configurações em cache | Comportamento de primeiro lançamento ocorre: configurações são buscadas de forma assíncrona com uma breve janela não aplicada |282| Usuário deleta o arquivo de configurações em cache | Comportamento de primeiro lançamento ocorre: configurações são buscadas de forma assíncrona com uma breve janela não aplicada |

265| Usuário executa um binário Claude Code modificado | Um usuário que pode executar um cliente modificado pode contornar qualquer controle do lado do cliente |283| Usuário executa um binário Claude Code modificado | Um usuário que pode executar um cliente modificado pode contornar qualquer controle do lado do cliente |

266| Usuário executa uma versão anterior do Claude Code | Versões que antecedem as configurações gerenciadas pelo servidor não as buscam ou aplicam |284| Usuário executa uma versão anterior do Claude Code | Versões que antecedem as configurações gerenciadas pelo servidor não as buscam ou aplicam |

267| API está indisponível | As configurações em cache se aplicam se disponíveis, caso contrário, as configurações gerenciadas não são aplicadas até a próxima busca bem-sucedida. Com `forceRemoteSettingsRefresh: true`, a CLI sai em vez de continuar, exceto para [subcomandos `claude auth`](#enforce-fail-closed-startup) |285| API está indisponível | As configurações em cache se aplicam se disponíveis, caso contrário, as configurações gerenciadas não são aplicadas até a próxima busca bem-sucedida. {/* min-version: 2.1.198 */}A partir da v2.1.198, as variáveis de ambiente de transporte, roteamento de API e autenticação no bloco `env` em cache são [retidas em caso de falha de busca](#fetch-and-caching-behavior); o resto do cache ainda se aplica. Com `forceRemoteSettingsRefresh: true`, a CLI sai em vez de continuar, exceto para [subcomandos `claude auth`](#enforce-fail-closed-startup) |

268| Usuário se autentica com uma organização diferente | As configurações não são entregues para contas fora da organização gerenciada |286| Usuário se autentica com uma organização diferente | As configurações não são entregues para contas fora da organização gerenciada |

269| Usuário configura um [provedor de modelo de terceiros](#platform-availability) | As configurações gerenciadas pelo servidor são ignoradas. Isso inclui definir `CLAUDE_CODE_USE_BEDROCK`, `CLAUDE_CODE_USE_MANTLE`, `CLAUDE_CODE_USE_VERTEX`, `CLAUDE_CODE_USE_FOUNDRY`, `CLAUDE_CODE_USE_ANTHROPIC_AWS`, ou um `ANTHROPIC_BASE_URL` não padrão |287| Usuário configura um [provedor de modelo de terceiros](#platform-availability) | As configurações gerenciadas pelo servidor são ignoradas. Isso inclui definir `CLAUDE_CODE_USE_BEDROCK`, `CLAUDE_CODE_USE_MANTLE`, `CLAUDE_CODE_USE_VERTEX`, `CLAUDE_CODE_USE_FOUNDRY`, `CLAUDE_CODE_USE_ANTHROPIC_AWS`, ou um `ANTHROPIC_BASE_URL` não padrão |

270| Tráfego de rede é interceptado ou redirecionado | Validação TLS desabilitada ou tráfego interceptado pode alterar as configurações que o cliente recebe |288| Tráfego de rede é interceptado ou redirecionado | Validação TLS desabilitada ou tráfego interceptado pode alterar as configurações que o cliente recebe |

sessions.md +2 −0

Details

97/branch try-streaming-approach97/branch try-streaming-approach

98```98```

99 99

100Se você omitir o nome, Claude Code nomeia o novo branch após o primeiro prompt na conversa. A partir da v2.1.198, isso também se aplica após [compaction](/pt/how-claude-code-works#when-context-fills-up); versões anteriores voltavam para o nome literal `Branched conversation` em vez de procurar além do resumo de compaction para o primeiro prompt original.

101

100Na linha de comando, combine `--continue` ou `--resume` com `--fork-session`:102Na linha de comando, combine `--continue` ou `--resume` com `--fork-session`:

101 103

102```bash theme={null}104```bash theme={null}

settings.md +17 −4

Details

398Configure comportamento avançado de sandboxing. Sandboxing isola comandos bash do seu sistema de arquivos e rede. Veja [Sandboxing](/pt/sandboxing) para detalhes.398Configure comportamento avançado de sandboxing. Sandboxing isola comandos bash do seu sistema de arquivos e rede. Veja [Sandboxing](/pt/sandboxing) para detalhes.

399 399

401| :------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------- |401| :------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------- |

403| `failIfUnavailable` | Sair com um erro na inicialização se `sandbox.enabled` é true mas o sandbox não pode iniciar (dependências faltantes ou plataforma não suportada). Quando false (padrão), um aviso é mostrado e comandos executam sem sandbox. Destinado para implantações de configurações gerenciadas que exigem sandboxing como um portão duro | `true` |403| `failIfUnavailable` | Sair com um erro na inicialização se `sandbox.enabled` é true mas o sandbox não pode iniciar (dependências faltantes ou plataforma não suportada). Quando false (padrão), um aviso é mostrado e comandos executam sem sandbox. Destinado para implantações de configurações gerenciadas que exigem sandboxing como um portão duro | `true` |

409| `filesystem.denyRead` | Caminhos onde comandos sandboxed não podem ler. Arrays são mesclados em todos os escopos de configuração. Também mesclado com caminhos de regras de permissão `Read(...)` deny. | `["~/.aws/credentials"]` |409| `filesystem.denyRead` | Caminhos onde comandos sandboxed não podem ler. Arrays são mesclados em todos os escopos de configuração. Também mesclado com caminhos de regras de permissão `Read(...)` deny. | `["~/.aws/credentials"]` |

410| `filesystem.allowRead` | Caminhos para re-permitir leitura dentro de regiões `denyRead`. Tem precedência sobre `denyRead`. Arrays são mesclados em todos os escopos de configuração. Use isto para criar padrões de acesso de leitura apenas para workspace. | `["."]` |410| `filesystem.allowRead` | Caminhos para re-permitir leitura dentro de regiões `denyRead`. Tem precedência sobre `denyRead`. Arrays são mesclados em todos os escopos de configuração. Use isto para criar padrões de acesso de leitura apenas para workspace. | `["."]` |

411| `filesystem.allowManagedReadPathsOnly` | (Apenas configurações gerenciadas) Apenas caminhos `allowRead` de configurações gerenciadas são respeitados. `denyRead` ainda se mescla de todas as fontes. Padrão: false | `true` |411| `filesystem.allowManagedReadPathsOnly` | (Apenas configurações gerenciadas) Apenas caminhos `allowRead` de configurações gerenciadas são respeitados. `denyRead` ainda se mescla de todas as fontes. Padrão: false | `true` |

412| `credentials.files` | Arquivos ou diretórios de credenciais que comandos sandboxed não podem ler. Aplica o mesmo bloqueio de leitura que `filesystem.denyRead`; a chave separada mantém caminhos de credenciais agrupados com `credentials.envVars` e separados de regras gerais de sistema de arquivos. Cada entrada é `{ "path": "...", "mode": "deny" }`. Caminhos usam os mesmos [prefixos](#sandbox-path-prefixes) que configurações `filesystem.*`. Arrays são mesclados em todos os escopos de configuração. Apenas `deny` é suportado. Requer Claude Code v2.1.187 ou posterior. | `[{ "path": "~/.aws/credentials", "mode": "deny" }]` |412| `credentials.files` | {/* min-version: 2.1.187 */}Arquivos ou diretórios de credenciais que comandos sandboxed não podem ler. Aplica o mesmo bloqueio de leitura que `filesystem.denyRead`; a chave separada mantém caminhos de credenciais agrupados com `credentials.envVars` e separados de regras gerais de sistema de arquivos. Cada entrada é `{ "path": "...", "mode": "deny" }`, e `deny` é o único modo suportado para arquivos. Caminhos usam os mesmos [prefixos](#sandbox-path-prefixes) que configurações `filesystem.*`. Arrays são mesclados em todos os escopos de configuração. Requer Claude Code v2.1.187 ou posterior. | `[{ "path": "~/.aws/credentials", "mode": "deny" }]` |

413| `credentials.envVars` | Variáveis de ambiente para desconfigurar antes de executar comandos sandboxed. Cada entrada é `{ "name": "...", "mode": "deny" }`. Arrays são mesclados em todos os escopos de configuração. Apenas `deny` é suportado. Requer Claude Code v2.1.187 ou posterior. | `[{ "name": "GITHUB_TOKEN", "mode": "deny" }]` |413| `credentials.envVars` | {/* min-version: 2.1.187 */}Variáveis de ambiente para [proteger de comandos sandboxed](/pt/sandboxing#protect-credentials). Cada entrada tem um `name` e um `mode`; o nome deve começar com uma letra ou underscore e conter apenas letras, dígitos e underscores. `deny` remove a variável do ambiente de comandos sandboxed. Requer Claude Code v2.1.187 ou posterior. {/* min-version: 2.1.199 */}`mask` substitui a variável com um valor sentinela por sessão dentro do sandbox enquanto o proxy do sandbox substitui o valor real em solicitações de saída para `injectHosts` dessa entrada; requer `network.tlsTerminate` e Claude Code v2.1.199 ou posterior. Entradas `mask` são apenas honradas de configurações de usuário, gerenciadas, ou CLI `--settings`, não de `.claude/settings.json` ou `.claude/settings.local.json`. Arrays são mesclados em todos os escopos de configuração, e `deny` tem precedência quando a mesma variável aparece com ambos os modos. | `[{ "name": "GITHUB_TOKEN", "mode": "deny" }]` |

414| `credentials.envVars[].injectHosts` | Hosts onde o proxy do sandbox substitui o valor real de uma entrada `mask`. Cada host também deve ser coberto por `network.allowedDomains`, exatamente ou por um curinga. Quando indefinido, o proxy substitui o valor em solicitações para cada host em `network.allowedDomains`. Aceito mas ignorado quando `mode` é `deny`. Requer Claude Code v2.1.199 ou posterior. {/* min-version: 2.1.199 */} | `["api.github.com"]` |

415| `credentials.allowPlaintextInject` | Permitir substituição `mask` em solicitações HTTP simples bem como HTTPS com TLS terminado. Em HTTP simples a identidade upstream não é verificada e a credencial viaja em cleartext, então deixe isto desligado fora de redes de teste confiáveis. Apenas honrado de configurações de usuário, gerenciadas, ou CLI `--settings`, não de `.claude/settings.json` ou `.claude/settings.local.json`. Padrão: false. Requer Claude Code v2.1.199 ou posterior. {/* min-version: 2.1.199 */} | `true` |

414| `network.allowUnixSockets` | (Apenas macOS) Caminhos de socket Unix acessíveis no sandbox. Ignorado no Linux e WSL2, onde o filtro seccomp não pode inspecionar caminhos de socket; use `allowAllUnixSockets` em vez disso. | `["~/.ssh/agent-socket"]` |416| `network.allowUnixSockets` | (Apenas macOS) Caminhos de socket Unix acessíveis no sandbox. Ignorado no Linux e WSL2, onde o filtro seccomp não pode inspecionar caminhos de socket; use `allowAllUnixSockets` em vez disso. | `["~/.ssh/agent-socket"]` |

415| `network.allowAllUnixSockets` | Permitir todas as conexões de socket Unix no sandbox. No Linux e WSL2 esta é a única maneira de permitir sockets Unix, já que pula o filtro seccomp que de outra forma bloqueia chamadas `socket(AF_UNIX, ...)`. Padrão: false | `true` |417| `network.allowAllUnixSockets` | Permitir todas as conexões de socket Unix no sandbox. No Linux e WSL2 esta é a única maneira de permitir sockets Unix, já que pula o filtro seccomp que de outra forma bloqueia chamadas `socket(AF_UNIX, ...)`. Padrão: false | `true` |

420| `network.allowManagedDomainsOnly` | (Apenas configurações gerenciadas) Apenas `allowedDomains` e regras allow `WebFetch(domain:...)` de configurações gerenciadas são respeitadas. Domínios de configurações de usuário, projeto e local são ignorados. Domínios não permitidos são bloqueados automaticamente sem solicitar o usuário. Domínios negados ainda são respeitados de todas as fontes. Padrão: false | `true` |422| `network.allowManagedDomainsOnly` | (Apenas configurações gerenciadas) Apenas `allowedDomains` e regras allow `WebFetch(domain:...)` de configurações gerenciadas são respeitadas. Domínios de configurações de usuário, projeto e local são ignorados. Domínios não permitidos são bloqueados automaticamente sem solicitar o usuário. Domínios negados ainda são respeitados de todas as fontes. Padrão: false | `true` |

421| `network.httpProxyPort` | Porta de proxy HTTP usada se você deseja trazer seu próprio proxy. Se não especificado, Claude executará seu próprio proxy. | `8080` |423| `network.httpProxyPort` | Porta de proxy HTTP usada se você deseja trazer seu próprio proxy. Se não especificado, Claude executará seu próprio proxy. | `8080` |

422| `network.socksProxyPort` | Porta de proxy SOCKS5 usada se você deseja trazer seu próprio proxy. Se não especificado, Claude executará seu próprio proxy. | `8081` |424| `network.socksProxyPort` | Porta de proxy SOCKS5 usada se você deseja trazer seu próprio proxy. Se não especificado, Claude executará seu próprio proxy. | `8081` |

425| `network.tlsTerminate` | Experimental. Terminar TLS dentro do proxy do sandbox para que possa ler o conteúdo de solicitações HTTPS. Necessário para [substituição de credenciais](/pt/sandboxing#protect-credentials) `mask`. Defina `{}` para gerar uma autoridade de certificado efêmera para a sessão, ou defina `caCertPath` e `caKeyPath` para usar a sua própria. Apenas honrado de configurações de usuário, gerenciadas, ou CLI `--settings`, não de `.claude/settings.json` ou `.claude/settings.local.json`. Requer Claude Code v2.1.199 ou posterior. {/* min-version: 2.1.199 */} | `{}` |

424| `enableWeakerNetworkIsolation` | (Apenas macOS) Permitir acesso ao serviço de confiança TLS do sistema (`com.apple.trustd.agent`) no sandbox. Necessário para ferramentas baseadas em Go como `gh`, `gcloud`, e `terraform` verificarem certificados TLS ao usar `httpProxyPort` com um proxy MITM e CA personalizada. **Reduz segurança** abrindo um possível caminho de exfiltração de dados. Padrão: false | `true` |427| `enableWeakerNetworkIsolation` | (Apenas macOS) Permitir acesso ao serviço de confiança TLS do sistema (`com.apple.trustd.agent`) no sandbox. Necessário para ferramentas baseadas em Go como `gh`, `gcloud`, e `terraform` verificarem certificados TLS ao usar `httpProxyPort` com um proxy MITM e CA personalizada. **Reduz segurança** abrindo um possível caminho de exfiltração de dados. Padrão: false | `true` |

425| `allowAppleEvents` | (Apenas macOS) Permitir que comandos sandboxed enviem Apple Events. Necessário para `open`, `osascript`, e ferramentas que abrem URLs em um navegador, que de outra forma falham com erro `-600`. **Remove isolamento de execução de código.** Comandos sandboxed podem lançar outras aplicações sem sandbox sem prompt do usuário; eles também podem enviar comandos AppleScript para aplicações em execução como Terminal, sujeito ao prompt de consentimento de automação por aplicativo do macOS (TCC). Apenas honrado de configurações de usuário, gerenciadas, ou CLI, não de configurações de projeto. Padrão: false | `true` |428| `allowAppleEvents` | (Apenas macOS) Permitir que comandos sandboxed enviem Apple Events. Necessário para `open`, `osascript`, e ferramentas que abrem URLs em um navegador, que de outra forma falham com erro `-600`. **Remove isolamento de execução de código.** Comandos sandboxed podem lançar outras aplicações sem sandbox sem prompt do usuário; eles também podem enviar comandos AppleScript para aplicações em execução como Terminal, sujeito ao prompt de consentimento de automação por aplicativo do macOS (TCC). Apenas honrado de configurações de usuário, gerenciadas, ou CLI, não de configurações de projeto. Padrão: false | `true` |

6601. **Configurações gerenciadas** ([gerenciadas pelo servidor](/pt/server-managed-settings), [políticas de nível MDM/SO](#configuration-scopes), ou [configurações gerenciadas](/pt/settings#settings-files))6631. **Configurações gerenciadas** ([gerenciadas pelo servidor](/pt/server-managed-settings), [políticas de nível MDM/SO](#configuration-scopes), ou [configurações gerenciadas](/pt/settings#settings-files))

661 * Políticas implantadas por TI através de entrega de servidor, perfis de configuração MDM, políticas de registro, ou arquivos de configurações gerenciadas664 * Políticas implantadas por TI através de entrega de servidor, perfis de configuração MDM, políticas de registro, ou arquivos de configurações gerenciadas

662 * Não podem ser substituídas por qualquer outro nível, incluindo argumentos de linha de comando665 * Não podem ser substituídas por qualquer outro nível, incluindo argumentos de linha de comando

663 * Dentro do nível gerenciado, a precedência é: saída [`policyHelper`](#compute-managed-settings-with-a-policy-helper), que quando configurada é a única fonte gerenciada usada > remota (configurações gerenciadas pelo servidor do [claude.ai](/pt/server-managed-settings) ou [gateway de aplicativos Claude](/pt/claude-apps-gateway)-entregues) > políticas de nível MDM/SO > baseadas em arquivo (`managed-settings.d/*.json` + `managed-settings.json`) > registro HKCU (apenas Windows). Apenas uma fonte gerenciada é usada; fontes não se mesclam entre camadas, com uma exceção: as chaves de bloqueio de sandbox `sandbox.network.allowManagedDomainsOnly` e `sandbox.filesystem.allowManagedReadPathsOnly`, com suas listas de permissões associadas, `allowAllClaudeAiMcps`, e os caminhos binários de sandbox `sandbox.bwrapPath` e `sandbox.socatPath` são honrados quando qualquer fonte gerenciada controlada por administrador os define; a camada HKCU gravável pelo usuário é excluída. Dentro da camada baseada em arquivo, arquivos drop-in e o arquivo base são mesclados juntos.666 * Dentro do nível gerenciado, apenas uma fonte é usada e as outras são ignoradas em vez de mescladas. Precedência, mais alta primeiro:

667 * Saída [`policyHelper`](#compute-managed-settings-with-a-policy-helper): quando configurada, esta é a única fonte gerenciada usada

668 * Remota (configurações gerenciadas pelo servidor do [claude.ai](/pt/server-managed-settings) ou [gateway de aplicativos Claude](/pt/claude-apps-gateway)-entregues)

669 * Políticas de nível MDM/SO

670 * Baseada em arquivo (`managed-settings.d/*.json` e `managed-settings.json`, mescladas juntas)

671 * Registro HKCU (apenas Windows)

672 * Algumas chaves são exceções, honradas quando qualquer fonte gerenciada controlada por administrador as define em vez de apenas a fonte vencedora. A fonte de registro HKCU gravável pelo usuário é excluída. As chaves de exceção são:

673 * as chaves de bloqueio de sandbox `sandbox.network.allowManagedDomainsOnly` e `sandbox.filesystem.allowManagedReadPathsOnly`, com suas listas de permissões associadas

674 * `allowAllClaudeAiMcps`

675 * os caminhos binários de sandbox `sandbox.bwrapPath` e `sandbox.socatPath`

676 * [`forceRemoteSettingsRefresh`](/pt/server-managed-settings)

664 * Hosts de incorporação como Claude Desktop podem fornecer política via opção SDK `managedSettings`. Por padrão isto é ignorado quando qualquer fonte gerenciada controlada por administrador está presente: configurações gerenciadas pelo servidor, uma política MDM ou SO, ou um arquivo de configurações gerenciadas. O fallback de registro HKCU gravável pelo usuário não conta como uma fonte gerenciada controlada por administrador. Administradores podem optar por definir [`parentSettingsBehavior`](#available-settings) como `"merge"`. Os valores do incorporador são filtrados para que possam apertar a política gerenciada mas não afrouxá-la.677 * Hosts de incorporação como Claude Desktop podem fornecer política via opção SDK `managedSettings`. Por padrão isto é ignorado quando qualquer fonte gerenciada controlada por administrador está presente: configurações gerenciadas pelo servidor, uma política MDM ou SO, ou um arquivo de configurações gerenciadas. O fallback de registro HKCU gravável pelo usuário não conta como uma fonte gerenciada controlada por administrador. Administradores podem optar por definir [`parentSettingsBehavior`](#available-settings) como `"merge"`. Os valores do incorporador são filtrados para que possam apertar a política gerenciada mas não afrouxá-la.

665 678

6662. **Argumentos de linha de comando**6792. **Argumentos de linha de comando**

setup.md +1 −1

Details

453 Instalar com npm453 Instalar com npm

454</h3>454</h3>

455 455

456Você também pode instalar Claude Code como um pacote npm global. O pacote requer [Node.js 18 ou posterior](https://nodejs.org/en/download).456Você também pode instalar Claude Code como um pacote npm global. A partir da v2.1.198, o pacote npm requer [Node.js 22 ou posterior](https://nodejs.org/en/download). Em uma versão mais antiga do Node.js, npm imprime um aviso `EBADENGINE` durante a instalação em vez de falhar; a instalação é concluída e `claude` ainda funciona, já que o pacote baixa um binário nativo que não usa seu Node.js em tempo de execução.

457 457

458```bash theme={null}458```bash theme={null}

459npm install -g @anthropic-ai/claude-code459npm install -g @anthropic-ai/claude-code

skills.md +6 −0

Details

443 443

444Se você invocar uma skill com argumentos mas a skill não incluir `$ARGUMENTS`, Claude Code anexa `ARGUMENTS: <your input>` ao final do conteúdo da skill para que Claude ainda veja o que você digitou.444Se você invocar uma skill com argumentos mas a skill não incluir `$ARGUMENTS`, Claude Code anexa `ARGUMENTS: <your input>` ao final do conteúdo da skill para que Claude ainda veja o que você digitou.

445 445

446Você também pode empilhar várias skills no início de uma mensagem. A partir da v2.1.199, digitar `/code-review /fix-issue 123` carrega ambas as skills e passa o texto final `123` como `$ARGUMENTS` para cada uma delas. Em versões anteriores, apenas a primeira skill carregava e recebia `/fix-issue 123` como texto de argumento literal.

447

448Claude Code expande a primeira skill mais até cinco mais empilhadas depois dela. A expansão para quando o primeiro token não é uma skill invocável pelo usuário inline, então uma skill que é executada como um [subagent bifurcado](#run-skills-in-a-subagent) ou uma cujos argumentos podem começar com um comando slash, como `/loop`, também termina ali; esse token e tudo depois dele se tornam o texto de argumento para cada skill expandida.

449

446Para acessar argumentos individuais por posição, use `$ARGUMENTS[N]` ou a forma mais curta `$N`:450Para acessar argumentos individuais por posição, use `$ARGUMENTS[N]` ou a forma mais curta `$N`:

447 451

448```yaml theme={null}452```yaml theme={null}

624| `"user-invocable-only"` | Oculto | Sim |628| `"user-invocable-only"` | Oculto | Sim |

625| `"off"` | Oculto | Oculto |629| `"off"` | Oculto | Oculto |

626 630

631A partir da v2.1.199, `"off"` também oculta a skill das listas de comandos anunciadas para clientes [Remote Control](/pt/remote-control) e para chamadores [Agent SDK](/pt/agent-sdk/slash-commands), não apenas o menu `/` do terminal. Invocar uma skill oculta pelo seu nome completo ainda retorna o erro `skillOverrides` em vez de executá-la.

632

627Uma skill que está ausente de `skillOverrides` é tratada como `"on"`. O exemplo abaixo colapsa uma skill para seu nome e desativa outra inteiramente:633Uma skill que está ausente de `skillOverrides` é tratada como `"on"`. O exemplo abaixo colapsa uma skill para seu nome e desativa outra inteiramente:

628 634

629```json theme={null}635```json theme={null}

sub-agents.md +85 −67

Details

24 24

25Claude usa a descrição de cada subagente para decidir quando delegar tarefas. Quando você cria um subagente, escreva uma descrição clara para que Claude saiba quando usá-lo.25Claude usa a descrição de cada subagente para decidir quando delegar tarefas. Quando você cria um subagente, escreva uma descrição clara para que Claude saiba quando usá-lo.

26 26

~~27Claude Code inclui vários subagentes integrados como **Explore**, **Plan** e **general-purpose**. Você também pode criar subagentes personalizados para lidar com tarefas específicas.~~27Claude Code inclui vários subagentes integrados como Explore, Plan e general-purpose. Você também pode criar subagentes personalizados para lidar com tarefas específicas.

28 28

29<h2 id="built-in-subagents">29<h2 id="built-in-subagents">

30 Subagentes integrados30 Subagentes integrados

38 <Tab title="Explore">38 <Tab title="Explore">

39 Um agente rápido e somente leitura otimizado para pesquisar e analisar bases de código.39 Um agente rápido e somente leitura otimizado para pesquisar e analisar bases de código.

40 40

~~41 * **Model**: Haiku, que é rápido e de baixa latência~~41 * **Model**: herda da conversa principal, limitado a Opus na Claude API, portanto Explore nunca é executado em um modelo mais caro do que aquele que você já escolheu para a sessão

42 * **Tools**: ferramentas somente leitura; Write e Edit são negados42 * **Tools**: ferramentas somente leitura; Write e Edit são negados

43 * **Purpose**: descoberta de arquivos, pesquisa de código, exploração de base de código43 * **Purpose**: descoberta de arquivos, pesquisa de código, exploração de base de código

44 44

45 {/* min-version: 2.1.198 */}A partir da v2.1.198, Explore herda o modelo da conversa principal em vez de sempre ser executado em Haiku. Na Claude API, o modelo herdado é limitado a Opus: uma conversa principal em um nível superior executa Explore em Opus, e uma conversa principal em Sonnet ou Haiku executa Explore nesse mesmo modelo. Em qualquer outro provedor, como [Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, ou Claude Platform on AWS](/pt/third-party-integrations), Explore herda o modelo da conversa principal diretamente.

47 Um [subagente de usuário ou projeto](#choose-the-subagent-scope) nomeado `Explore` substitui o integrado e mantém seu próprio campo `model`, portanto defina um com `model: haiku` para manter a exploração em um modelo de menor custo.

45 Claude delega para Explore quando precisa pesquisar ou entender uma base de código sem fazer alterações. Isso mantém os resultados da exploração fora do contexto da sua conversa principal.49 Claude delega para Explore quando precisa pesquisar ou entender uma base de código sem fazer alterações. Isso mantém os resultados da exploração fora do contexto da sua conversa principal.

46 50

47 Ao invocar Explore, Claude especifica um nível de minuciosidade: **quick** para buscas direcionadas, **medium** para exploração equilibrada, ou **very thorough** para análise abrangente.51 Ao invocar Explore, Claude especifica um nível de minuciosidade: **quick** para buscas direcionadas, **medium** para exploração equilibrada, ou **very thorough** para análise abrangente.

77 </Tab>81 </Tab>

78</Tabs>82</Tabs>

79 83

~~80Os subagentes integrados são sempre registrados em sessões interativas. Para restringi-los:~~84Os subagentes integrados são registrados por padrão em sessões interativas. Para restringi-los:

81 85

82* Para bloquear um tipo integrado específico, adicione-o a `permissions.deny` conforme mostrado em [Desabilitar subagentes específicos](#disable-specific-subagents).86* Para bloquear um tipo integrado específico, adicione-o a `permissions.deny` conforme mostrado em [Desabilitar subagentes específicos](#disable-specific-subagents).

83* Para impedir que Claude delegue a qualquer subagente, negue a ferramenta `Agent` em si com [`permissions.deny`](/pt/permissions#tool-specific-permission-rules).87* Para impedir que Claude delegue a qualquer subagente, negue a ferramenta `Agent` em si com [`permissions.deny`](/pt/permissions#tool-specific-permission-rules).

88* {/* min-version: 2.1.198 */}Para remover apenas os subagentes integrados `Explore` e `Plan`, defina [`CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1`](/pt/env-vars). Claude lê e explora arquivos diretamente em vez de delegar para eles. Requer Claude Code v2.1.198 ou posterior.

84* Em [modo não interativo](/pt/headless) e no [Agent SDK](/pt/agent-sdk/overview), defina [`CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1`](/pt/env-vars) para remover todos os tipos integrados e fornecer apenas os seus próprios.89* Em [modo não interativo](/pt/headless) e no [Agent SDK](/pt/agent-sdk/overview), defina [`CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1`](/pt/env-vars) para remover todos os tipos integrados e fornecer apenas os seus próprios.

85 90

86Além desses subagentes integrados, você pode criar os seus próprios com prompts personalizados, restrições de ferramentas, modos de permissão, hooks e skills. As seções a seguir mostram como começar e personalizar subagentes.91Além desses subagentes integrados, você pode criar os seus próprios com prompts personalizados, restrições de ferramentas, modos de permissão, hooks e skills. As seções a seguir mostram como começar e personalizar subagentes.

89 Quickstart: criar seu primeiro subagente94 Quickstart: criar seu primeiro subagente

90</h2>95</h2>

91 96

~~92Subagentes são definidos em arquivos Markdown com frontmatter YAML. Você pode [criá-los manualmente](#write-subagent-files) ou usar o comando `/agents`.~~97Subagentes são arquivos Markdown com frontmatter YAML. Para criar um, peça ao Claude para escrevê-lo para você, ou [escreva o arquivo você mesmo](#write-subagent-files).

99{/* min-version: 2.1.198 */}A partir da v2.1.198, o comando `/agents` não abre mais o assistente de criação interativo; executá-lo imprime um lembrete para pedir ao Claude ou editar `.claude/agents/` diretamente. Os arquivos de subagente, campos de frontmatter e os locais `.claude/agents/` e `~/.claude/agents/` permanecem inalterados; apenas o assistente de terminal foi removido.

93 100

~~94Este passo a passo o guia através da criação de um subagente no nível do usuário com o comando `/agents`. O subagente revisa código e sugere melhorias para a base de código.~~101Este passo a passo cria um subagente no nível do usuário que revisa código e sugere melhorias.

95 102

96<Steps>103<Steps>

~~97 <Step title="Abrir a interface de subagentes">~~104 <Step title="Peça ao Claude para criar o subagente">

~~98 No Claude Code, execute:~~105 No Claude Code, descreva o subagente que você deseja e onde salvá-lo:

99 106

100 ```text wrap theme={null}107 ```text wrap theme={null}

101 /agents108 Create a personal code-improver subagent in ~/.claude/agents/ that scans

109 files and suggests improvements for readability, performance, and best

110 practices. It should explain each issue, show the current code, and

111 provide an improved version. Make it read-only and have it use Sonnet.

102 ```112 ```

103 </Step>

104 113

105 <Step title="Escolher um local">114 Claude escreve o arquivo com um `name`, uma `description`, uma lista de `tools`, um `model` e um prompt de sistema.

106 Mude para a aba **Library**, selecione **Create new agent**, depois escolha **Personal**. Isso salva o subagente em `~/.claude/agents/` para que esteja disponível em todos os seus projetos.

107 </Step>115 </Step>

108 116

109 <Step title="Gerar com Claude">117 <Step title="Revise o arquivo">

110 Selecione **Generate with Claude**. Quando solicitado, descreva o subagente:118 Abra `~/.claude/agents/code-improver.md` e confirme que o frontmatter corresponde ao que você pediu. O resultado se parece com isto:

111 119

112 ```text wrap theme={null}120 ```markdown theme={null}

113 A code improvement agent that scans files and suggests improvements121 ---

114 for readability, performance, and best practices. It should explain122 name: code-improver

115 each issue, show the current code, and provide an improved version.123 description: Scans files and suggests improvements for readability, performance, and best practices. Use after writing or modifying code.

124 tools: Read, Grep, Glob

125 model: sonnet

126 ---

127

128 You are a code improvement specialist. For each issue you find, explain

129 the problem, show the current code, and provide an improved version.

116 ```130 ```

117 131

118 Claude gera o identificador, descrição e prompt de sistema para você.132 Como o arquivo está em `~/.claude/agents/`, o subagente está disponível em todos os projetos em sua máquina. Para limitá-lo a um projeto, mova-o para o diretório `.claude/agents/` desse projeto. [Escolha o escopo do subagente](#choose-the-subagent-scope) compara os dois.

119 </Step>

~~120~~

121 <Step title="Selecionar ferramentas">

122 Para um revisor somente leitura, desselecione tudo exceto **Read-only tools**. Se você manter todas as ferramentas selecionadas, o subagente herda todas as ferramentas disponíveis para a conversa principal.

123 </Step>133 </Step>

124 134

125 <Step title="Selecionar modelo">135 <Step title="Teste-o">

126 Escolha qual modelo o subagente usa. Para este agente de exemplo, selecione **Sonnet**, que equilibra capacidade e velocidade para analisar padrões de código.136 Peça ao Claude para delegar para o novo subagente:

127 </Step>

~~128~~

129 <Step title="Escolher uma cor">

130 Escolha uma cor de fundo para o subagente. Isso ajuda você a identificar qual subagente está sendo executado na interface do usuário.

131 </Step>

~~132~~

133 <Step title="Configurar memória">

134 Selecione **User scope** para dar ao subagente um [diretório de memória persistente](#enable-persistent-memory) em `~/.claude/agent-memory/`. O subagente usa isso para acumular insights entre conversas, como padrões de base de código e problemas recorrentes. Selecione **None** se você não quiser que o subagente persista aprendizados.

135 </Step>

~~136~~

137 <Step title="Salvar e testar">

138 Revise o resumo de configuração. Pressione `s` ou `Enter` para salvar, ou pressione `e` para salvar e editar o arquivo em seu editor. O subagente está disponível imediatamente. Teste-o:

139 137

140 ```text wrap theme={null}138 ```text wrap theme={null}

141 Use the code-improver agent to suggest improvements in this project139 Use the code-improver agent to suggest improvements in this project

142 ```140 ```

143 141

144 Claude delega para seu novo subagente, que verifica a base de código e retorna sugestões de melhoria.142 Claude delega para seu novo subagente, que verifica a base de código e retorna sugestões de melhoria.

143

144 Se Claude não conseguir encontrar o novo subagente, reinicie o Claude Code e tente novamente. Isso acontece apenas quando `~/.claude/agents/` não existia antes da sessão começar, porque uma sessão em execução não detecta um diretório `agents` recém-criado.

145 </Step>145 </Step>

146</Steps>146</Steps>

147 147

148Agora você tem um subagente que pode usar em qualquer projeto em sua máquina para analisar bases de código e sugerir melhorias.148Agora você tem um subagente que pode usar em qualquer projeto em sua máquina para analisar bases de código e sugerir melhorias.

149 149

150Você também pode criar subagentes manualmente como arquivos Markdown, defini-los via flags CLI, ou distribuí-los através de plugins. As seções a seguir cobrem todas as opções de configuração.150Você também pode escrever arquivos de subagente manualmente, defini-los via flags CLI ou distribuí-los através de plugins. As seções a seguir cobrem todas as opções de configuração.

151

152<Note>

153 No Claude Code v2.1.197 e anterior, `/agents` abre um assistente interativo com uma aba **Running** que lista subagentes ativos e uma aba **Library** para criá-los, editá-los e deletá-los. {/* max-version: 2.1.197 */}

154</Note>

151 155

152<h2 id="configure-subagents">156<h2 id="configure-subagents">

153 Configurar subagentes157 Configurar subagentes

154</h2>158</h2>

155 159

156<h3 id="use-the-/agents-command">160A localização do arquivo de um subagente determina quem tem acesso a ele, e seu frontmatter determina o que ele pode fazer. Esta seção aborda onde os arquivos de subagente residem e cada campo que eles suportam.

157 Usar o comando /agents

158</h3>

~~159~~

160O comando `/agents` abre uma interface com abas para gerenciar subagentes. A aba **Running** lista subagentes ao vivo e recentemente finalizados e permite que você os abra ou pare. A aba **Library** permite que você:

~~161~~

162* Visualize todos os subagentes disponíveis (integrados, usuário, projeto e plugin)

163* Crie novos subagentes com configuração guiada ou geração por Claude

164* Edite configuração de subagente existente e acesso a ferramentas

165* Delete subagentes personalizados

166* Veja quais subagentes estão ativos quando duplicatas existem

~~167~~

168Esta é a forma recomendada de criar e gerenciar subagentes. Para criação manual ou automação, você também pode adicionar arquivos de subagente diretamente.

169 161

170<h3 id="choose-the-subagent-scope">162<h3 id="choose-the-subagent-scope">

171 Escolher o escopo do subagente163 Escolher o escopo do subagente

172</h3>164</h3>

173 165

174Subagentes são arquivos Markdown com frontmatter YAML. Armazene-os em locais diferentes dependendo do escopo. Quando múltiplos subagentes compartilham o mesmo nome, Claude Code usa o que está no local de prioridade mais alta.166Armazene arquivos de subagente em locais diferentes dependendo do escopo. Quando múltiplos subagentes compartilham o mesmo nome, Claude Code usa o que está no local de prioridade mais alta.

175 167

177| :--------------------------- | :---------------------- | :---------- | :-------------------------------------------- |169| :--------------------------- | :---------------------- | :---------- | :-------------------------------------------- |

183 175

184**Subagentes de projeto** (`.claude/agents/`) são ideais para subagentes específicos de uma base de código. Verifique-os no controle de versão para que sua equipe possa usá-los e melhorá-los colaborativamente.176**Subagentes de projeto** (`.claude/agents/`) são ideais para subagentes específicos de uma base de código. Verifique-os no controle de versão para que sua equipe possa usá-los e melhorá-los colaborativamente.

239 231

240**Subagentes gerenciados** são implantados por administradores da organização. Coloque arquivos markdown em `.claude/agents/` dentro do [diretório de configurações gerenciadas](/pt/settings#settings-files), usando o mesmo formato de frontmatter que subagentes de projeto e usuário. Definições gerenciadas têm precedência sobre subagentes de projeto e usuário com o mesmo nome.232**Subagentes gerenciados** são implantados por administradores da organização. Coloque arquivos markdown em `.claude/agents/` dentro do [diretório de configurações gerenciadas](/pt/settings#settings-files), usando o mesmo formato de frontmatter que subagentes de projeto e usuário. Definições gerenciadas têm precedência sobre subagentes de projeto e usuário com o mesmo nome.

241 233

242**Subagentes de plugin** vêm de [plugins](/pt/plugins) que você instalou. Eles aparecem em `/agents` junto com seus subagentes personalizados. Veja a [referência de componentes de plugin](/pt/plugins-reference#agents) para detalhes sobre como criar subagentes de plugin.234**Subagentes de plugin** vêm de [plugins](/pt/plugins) que você instalou. Eles carregam junto com seus subagentes personalizados e aparecem na digitação de @-menção sob seu nome com escopo. Veja a [referência de componentes de plugin](/pt/plugins-reference#agents) para detalhes sobre como criar subagentes de plugin.

243 235

244<Note>236<Note>

245 Por razões de segurança, subagentes de plugin não suportam os campos de frontmatter `hooks`, `mcpServers` ou `permissionMode`. Estes campos são ignorados ao carregar agentes de um plugin. Se você precisar deles, copie o arquivo do agente para `.claude/agents/` ou `~/.claude/agents/`. Você também pode adicionar regras a [`permissions.allow`](/pt/settings#permission-settings) em `settings.json` ou `settings.local.json`, mas estas regras se aplicam a toda a sessão, não apenas ao subagente do plugin.237 Por razões de segurança, subagentes de plugin não suportam os campos de frontmatter `hooks`, `mcpServers` ou `permissionMode`. Estes campos são ignorados ao carregar agentes de um plugin. Se você precisar deles, copie o arquivo do agente para `.claude/agents/` ou `~/.claude/agents/`. Você também pode adicionar regras a [`permissions.allow`](/pt/settings#permission-settings) em `settings.json` ou `settings.local.json`, mas estas regras se aplicam a toda a sessão, não apenas ao subagente do plugin.

254Arquivos de subagente usam frontmatter YAML para configuração, seguido pelo prompt de sistema em Markdown:246Arquivos de subagente usam frontmatter YAML para configuração, seguido pelo prompt de sistema em Markdown:

255 247

256<Note>248<Note>

257 Subagentes são carregados no início da sessão. Se você adicionar ou editar um arquivo de subagente diretamente no disco, reinicie sua sessão para carregá-lo. Subagentes criados através da interface `/agents` entram em efeito imediatamente sem uma reinicialização.249 Claude Code observa `~/.claude/agents/` e `.claude/agents/`. Quando você adiciona ou edita um arquivo de subagente no disco, ou pede a Claude para escrever um para você, Claude Code detecta a alteração em alguns segundos e a próxima delegação usa a definição atualizada, sem necessidade de reinicialização.

250

251 Dois casos ainda precisam de uma reinicialização:

252

253 * O observador cobre apenas diretórios que existiam quando a sessão começou, portanto após criar o primeiro arquivo de agente de um escopo em um novo diretório `agents`, reinicie para carregá-lo.

254 * Sessões iniciadas com `--disable-slash-commands` não observam esses diretórios.

258</Note>255</Note>

259 256

260```markdown theme={null}257```markdown theme={null}

292| `mcpServers` | No | [MCP servers](/pt/mcp) disponíveis para este subagente. Cada entrada é um nome de servidor referenciando um servidor já configurado (por exemplo, `"slack"`) ou uma definição inline com o nome do servidor como chave e uma [configuração completa de MCP server](/pt/mcp#installing-mcp-servers) como valor. Ignorado para [subagentes de plugin](#choose-the-subagent-scope) |289| `mcpServers` | No | [MCP servers](/pt/mcp) disponíveis para este subagente. Cada entrada é um nome de servidor referenciando um servidor já configurado (por exemplo, `"slack"`) ou uma definição inline com o nome do servidor como chave e uma [configuração completa de MCP server](/pt/mcp#installing-mcp-servers) como valor. Ignorado para [subagentes de plugin](#choose-the-subagent-scope) |

293| `hooks` | No | [Lifecycle hooks](#define-hooks-for-subagents) com escopo para este subagente. Ignorado para [subagentes de plugin](#choose-the-subagent-scope) |290| `hooks` | No | [Lifecycle hooks](#define-hooks-for-subagents) com escopo para este subagente. Ignorado para [subagentes de plugin](#choose-the-subagent-scope) |

294| `memory` | No | [Escopo de memória persistente](#enable-persistent-memory): `user`, `project`, ou `local`. Habilita aprendizado entre sessões |291| `memory` | No | [Escopo de memória persistente](#enable-persistent-memory): `user`, `project`, ou `local`. Habilita aprendizado entre sessões |

295| `background` | No | Defina como `true` para sempre executar este subagente como uma [tarefa em background](#run-subagents-in-foreground-or-background). Padrão: `false` |292| `background` | No | Defina como `true` para sempre executar este subagente como uma [tarefa em background](#run-subagents-in-foreground-or-background), mesmo quando Claude precisa de seu resultado imediatamente. Quando não definido, Claude escolhe, e {/* min-version: 2.1.198 */}a partir da v2.1.198 ele executa subagentes em background por padrão |

296| `effort` | No | Nível de esforço quando este subagente está ativo. Sobrescreve o nível de esforço da sessão. Padrão: herda da sessão. Opções: `low`, `medium`, `high`, `xhigh`, `max`; os níveis disponíveis dependem do modelo |293| `effort` | No | Nível de esforço quando este subagente está ativo. Sobrescreve o nível de esforço da sessão. Padrão: herda da sessão. Opções: `low`, `medium`, `high`, `xhigh`, `max`; os níveis disponíveis dependem do modelo |

297| `isolation` | No | Defina como `worktree` para executar o subagente em um [git worktree](/pt/worktrees) temporário, dando-lhe uma cópia isolada do repositório ramificada por padrão a partir de sua [branch padrão](/pt/worktrees#choose-the-base-branch) em vez do `HEAD` da sessão pai. O worktree é automaticamente limpo se o subagente não fizer alterações |294| `isolation` | No | Defina como `worktree` para executar o subagente em um [git worktree](/pt/worktrees) temporário, dando-lhe uma cópia isolada do repositório ramificada por padrão a partir de sua [branch padrão](/pt/worktrees#choose-the-base-branch) em vez do `HEAD` da sessão pai. O worktree é automaticamente limpo se o subagente não fizer alterações |

298| `color` | No | Cor de exibição para o subagente na lista de tarefas e transcrição. Aceita `red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink`, ou `cyan` |295| `color` | No | Cor de exibição para o subagente na lista de tarefas e transcrição. Aceita `red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink`, ou `cyan` |

318 315

319{/* min-version: 2.1.196 */}A partir da v2.1.196, definir `CLAUDE_CODE_SUBAGENT_MODEL` para `inherit` é o mesmo que deixá-lo indefinido: a resolução continua com o parâmetro `model` por invocação, depois o frontmatter. Em versões anteriores, `inherit` forçava subagentes para o modelo da conversa principal e ignorava ambas essas fontes.316{/* min-version: 2.1.196 */}A partir da v2.1.196, definir `CLAUDE_CODE_SUBAGENT_MODEL` para `inherit` é o mesmo que deixá-lo indefinido: a resolução continua com o parâmetro `model` por invocação, depois o frontmatter. Em versões anteriores, `inherit` forçava subagentes para o modelo da conversa principal e ignorava ambas essas fontes.

320 317

321O valor da variável de ambiente, parâmetro por invocação e valores de frontmatter são verificados contra a lista de permissões [`availableModels`](/pt/model-config#restrict-model-selection) da sua organização. Um valor que se resolve para um modelo excluído não é usado e o subagente é executado no modelo herdado em vez disso.318Claude Code verifica o valor da variável de ambiente, parâmetro por invocação e valores de frontmatter contra a lista de permissões [`availableModels`](/pt/model-config#restrict-model-selection) da sua organização. Um valor que se resolve para um modelo excluído é ignorado e o subagente é executado no modelo herdado em vez disso.

319

320{/* min-version: 2.1.198 */}A partir da v2.1.198, subagentes também herdam a configuração de [pensamento estendido](/pt/model-config#extended-thinking) da conversa principal: se o pensamento está ativado em sua sessão, está ativado para o subagente, e se está desativado, permanece desativado. Não há configuração de pensamento por subagente. Antes da v2.1.198, subagentes eram executados com pensamento estendido desabilitado independentemente da configuração da conversa principal.

322 321

323<h3 id="control-subagent-capabilities">322<h3 id="control-subagent-capabilities">

324 Controlar capacidades do subagente323 Controlar capacidades do subagente

338* `ScheduleWakeup`337* `ScheduleWakeup`

339* `WaitForMcpServers`338* `WaitForMcpServers`

340 339

341Para restringir ferramentas, use o campo `tools` (lista de permissões) ou campo `disallowedTools` (lista de negação). Este exemplo usa `tools` para permitir exclusivamente Read, Grep, Glob e Bash. O subagente não pode editar arquivos, escrever arquivos ou usar qualquer ferramenta MCP:340Para restringir ferramentas, use o campo `tools` como uma lista de permissões ou o campo `disallowedTools` como uma lista de negação. Este exemplo usa `tools` para permitir exclusivamente Read, Grep, Glob e Bash. O subagente não pode editar arquivos, escrever arquivos ou usar qualquer ferramenta MCP:

342 341

343```yaml theme={null}342```yaml theme={null}

344---343---

432Use the Playwright tools to navigate, screenshot, and interact with pages.431Use the Playwright tools to navigate, screenshot, and interact with pages.

433```432```

434 433

435Definições inline usam o mesmo schema que entradas de servidor `.mcp.json` (`stdio`, `http`, `sse`, `ws`), com chave pelo nome do servidor.434Definições inline usam o mesmo schema que entradas de servidor `.mcp.json`, com chave pelo nome do servidor, e suportam os tipos `stdio`, `http`, `sse` e `ws`.

436 435

437Para manter um MCP server fora da conversa principal inteiramente e evitar que suas descrições de ferramentas consumam contexto lá, defina-o inline aqui em vez de em `.mcp.json`. O subagente obtém as ferramentas; a conversa pai não.436Para manter um MCP server fora da conversa principal inteiramente e evitar que suas descrições de ferramentas consumam contexto lá, defina-o inline aqui em vez de em `.mcp.json`. O subagente obtém as ferramentas; a conversa pai não.

438 437

528 Dicas de memória persistente527 Dicas de memória persistente

529</h5>528</h5>

530 529

531* `project` é o escopo padrão recomendado. Ele torna o conhecimento do subagente compartilhável via controle de versão. Use `user` quando o conhecimento do subagente é amplamente aplicável entre projetos, ou `local` quando o conhecimento não deve ser verificado no controle de versão.530* `project` é o escopo padrão recomendado. Ele torna o conhecimento do subagente compartilhável via controle de versão.

532* Peça ao subagente para consultar sua memória antes de começar o trabalho: "Review this PR, and check your memory for patterns you've seen before."531* Peça ao subagente para consultar sua memória antes de começar o trabalho: "Review this PR, and check your memory for patterns you've seen before."

533* Peça ao subagente para atualizar sua memória após completar uma tarefa: "Now that you're done, save what you learned to your memory." Ao longo do tempo, isso constrói uma base de conhecimento que torna o subagente mais eficaz.532* Peça ao subagente para atualizar sua memória após completar uma tarefa: "Now that you're done, save what you learned to your memory." Ao longo do tempo, isso constrói uma base de conhecimento que torna o subagente mais eficaz.

534* Inclua instruções de memória diretamente no arquivo markdown do subagente para que ele mantenha proativamente sua própria base de conhecimento:533* Inclua instruções de memória diretamente no arquivo markdown do subagente para que ele mantenha proativamente sua própria base de conhecimento:

776* **Subagentes em foreground** bloqueiam a conversa principal até completar. Prompts de permissão são passados para você conforme surgem.775* **Subagentes em foreground** bloqueiam a conversa principal até completar. Prompts de permissão são passados para você conforme surgem.

777* **Subagentes em background** são executados concorrentemente enquanto você continua trabalhando. {/* min-version: 2.1.186 */}A partir da v2.1.186, quando um subagente em background atinge uma chamada de ferramenta que precisa de permissão, o prompt aparece em sua sessão principal e nomeia o subagente que está pedindo. Aprove para deixar o subagente continuar, ou pressione Esc para negar essa chamada de ferramenta sem parar o subagente. Antes da v2.1.186, subagentes em background auto-negavam qualquer chamada de ferramenta que teria solicitado.776* **Subagentes em background** são executados concorrentemente enquanto você continua trabalhando. {/* min-version: 2.1.186 */}A partir da v2.1.186, quando um subagente em background atinge uma chamada de ferramenta que precisa de permissão, o prompt aparece em sua sessão principal e nomeia o subagente que está pedindo. Aprove para deixar o subagente continuar, ou pressione Esc para negar essa chamada de ferramenta sem parar o subagente. Antes da v2.1.186, subagentes em background auto-negavam qualquer chamada de ferramenta que teria solicitado.

778 777

779Claude decide se deve executar subagentes em foreground ou background baseado na tarefa. Você também pode:778{/* min-version: 2.1.198 */}A partir da v2.1.198, subagentes são executados em background por padrão. Claude executa um subagente em foreground quando precisa do resultado antes de continuar. O padrão muda onde um subagente é executado, não o que é permitido fazer: subagentes em background ainda exibem cada prompt de permissão em sua sessão principal. Antes da v2.1.198, Claude escolhia entre foreground e background baseado na tarefa.

779

780Você também pode direcionar isso você mesmo:

780 781

781* Pedir a Claude para "run this in the background"782* Peça a Claude para executar uma tarefa em background ou em foreground

782* Pressionar **Ctrl+B** para colocar uma tarefa em background783* Pressione **Ctrl+B** para colocar uma tarefa em execução em background

783 784

784Para desabilitar toda a funcionalidade de tarefa em background, defina a variável de ambiente `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` para `1`. Veja [Variáveis de ambiente](/pt/env-vars).785Para desabilitar toda a funcionalidade de tarefa em background, defina a variável de ambiente `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` para `1`. Veja [Variáveis de ambiente](/pt/env-vars).

785 786

786Quando [`CLAUDE_CODE_FORK_SUBAGENT`](#fork-the-current-conversation) está definido para `1`, cada spawn de subagente é executado em background independentemente do campo `background`. Prompts de permissão desses subagentes em background aparecem em sua sessão principal conforme descrito acima.787Quando [`CLAUDE_CODE_FORK_SUBAGENT`](#fork-the-current-conversation) está definido para `1`, cada spawn de subagente é executado em background e o campo frontmatter `background` não tem efeito, porque o modo fork remove o parâmetro `run_in_background` da ferramenta `Agent`. `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` tem precedência sobre o modo fork e mantém spawns de subagente em foreground.

788

789<h3 id="api-errors-in-subagents">

790 Erros de API em subagentes

791</h3>

792

793{/* min-version: 2.1.199 */}A partir da v2.1.199, um subagente cuja execução termina em um erro de API, como um limite de uso ou um erro de servidor repetido, relata essa falha de volta para Claude em vez de retornar o texto de erro como se fossem os achados do subagente. O que Claude recebe depende de onde o subagente foi executado:

794

795* **Foreground**: se um limite de taxa, sobrecarga ou erro de servidor corta um subagente que já produziu saída, a ferramenta Agent retorna essa saída parcial com uma nota de que o subagente foi cortado e não completou sua tarefa. Caso contrário, a chamada de ferramenta falha com [`Agent terminated early due to an API error`](/pt/errors#agent-terminated-early-due-to-an-api-error), seguido pelo detalhe do erro.

796* **Background**: o subagente é marcado como falho, e a mensagem que Claude recebe quando termina nomeia o erro de API e inclui a última saída do subagente, então o trabalho parcial não é perdido.

797

798Uma vez que o erro de API subjacente seja resolvido, peça a Claude para tentar novamente a tarefa ou [retomar o subagente](#resume-subagents).

787 799

788<h3 id="common-patterns">800<h3 id="common-patterns">

789 Padrões comuns801 Padrões comuns

854 866

855{/* min-version: 2.1.172 */}A partir do Claude Code v2.1.172, um subagente pode gerar seus próprios subagentes. Use isso quando uma tarefa delegada em si se divide em subtarefas paralelas, como um subagente revisor que distribui um verificador por descoberta, para que a saída intermediária nunca alcance sua conversa principal. Apenas o resumo do subagente de nível superior retorna para você.867{/* min-version: 2.1.172 */}A partir do Claude Code v2.1.172, um subagente pode gerar seus próprios subagentes. Use isso quando uma tarefa delegada em si se divide em subtarefas paralelas, como um subagente revisor que distribui um verificador por descoberta, para que a saída intermediária nunca alcance sua conversa principal. Apenas o resumo do subagente de nível superior retorna para você.

856 868

857Um subagente aninhado é configurado da mesma forma que um de nível superior e é resolvido dos mesmos [escopos](#choose-the-subagent-scope). O painel de subagente abaixo da entrada de prompt mostra a árvore completa: cada linha exibe uma contagem `(+N)` de descendentes, e {/* min-version: 2.1.193 */}a partir da v2.1.193, abrir uma linha mostra os irmãos desse subagente e filhos diretos com um caminho de volta para `main`. A aba Running em [`/agents`](#use-the-%2Fagents-command) lista subagentes em execução como uma lista plana.869Um subagente aninhado é configurado da mesma forma que um de nível superior e é resolvido dos mesmos [escopos](#choose-the-subagent-scope). O painel de subagente abaixo da entrada de prompt mostra a árvore completa: cada linha exibe uma contagem `(+N)` de descendentes, e {/* min-version: 2.1.193 */}a partir da v2.1.193, abrir uma linha mostra os irmãos desse subagente e filhos diretos com um caminho de volta para `main`.

858 870

859A profundidade é contada como o número de níveis de subagente abaixo da conversa principal, independentemente de cada nível ser executado em [foreground ou background](#run-subagents-in-foreground-or-background). Um subagente na profundidade cinco não recebe a ferramenta Agent e não pode gerar mais. O limite é fixo e não configurável.871A profundidade é contada como o número de níveis de subagente abaixo da conversa principal, independentemente de cada nível ser executado em [foreground ou background](#run-subagents-in-foreground-or-background). Um subagente na profundidade cinco não recebe a ferramenta Agent e não pode gerar mais. O limite é fixo e não configurável.

860 872

896 908

897Quando um subagente completa, Claude recebe seu ID de agente. Os agentes integrados Explore e Plan são de uma única execução e não retornam ID de agente, então eles não podem ser retomados; use `general-purpose` ou um subagente personalizado quando você precisar continuar o trabalho.909Quando um subagente completa, Claude recebe seu ID de agente. Os agentes integrados Explore e Plan são de uma única execução e não retornam ID de agente, então eles não podem ser retomados; use `general-purpose` ou um subagente personalizado quando você precisar continuar o trabalho.

898 910

899Claude usa a ferramenta `SendMessage` com o ID do agente como campo `to` para retomá-lo. A ferramenta `SendMessage` está sempre disponível para retomar subagentes por ID ou nome de agente. Mensagens de protocolo de equipe estruturadas como `shutdown_request` e `plan_approval_response` exigem que [equipes de agentes](/pt/agent-teams) estejam habilitadas.911Claude usa a ferramenta `SendMessage` com o ID do agente ou nome do agente como campo `to` para retomá-lo. `SendMessage` não requer que [equipes de agentes](/pt/agent-teams) estejam habilitadas; apenas mensagens de protocolo de equipe estruturadas como `shutdown_request` e `plan_approval_response` fazem.

900 912

901Para retomar um subagente, peça a Claude para continuar o trabalho anterior:913Para retomar um subagente, peça a Claude para continuar o trabalho anterior:

902 914

910 922

911Se um subagente parado recebe um `SendMessage`, ele auto-retoma em background sem exigir uma nova invocação de `Agent`.923Se um subagente parado recebe um `SendMessage`, ele auto-retoma em background sem exigir uma nova invocação de `Agent`.

912 924

925{/* min-version: 2.1.199 */}A partir da v2.1.199, `SendMessage` verifica que um nome ainda se refere ao mesmo agente que alcançou anteriormente na conversa. Se um agente mais novo assumiu o nome, como um agente em background re-gerado que o reutilizou, Claude Code recusa o envio em vez de entregá-lo ao agente errado, e o erro relata qual agente o nome agora alcança para que Claude possa redirecionar. Para alcançar o agente anterior enquanto ainda está em execução, Claude o endereça pelo ID do agente do resultado de spawn. A verificação é escopo da conversa atual e é redefinida em `/clear`.

926

927{/* min-version: 2.1.198 */}A partir da v2.1.198, um subagente trata mensagens do agente que o lançou como direção de tarefa normal, incluindo correções de curso no meio da tarefa, e age sobre elas dentro de suas próprias configurações de permissão. Dois limites ainda se mantêm independentemente de quem enviou a mensagem: nenhuma mensagem de qualquer agente conta como sua aprovação para um prompt de permissão pendente, e nenhuma mensagem de agente pode mudar as configurações de permissão, `CLAUDE.md` ou configuração de um subagente. Apenas o sistema de permissão ou suas próprias mensagens podem conceder aprovação.

928

913Você também pode pedir a Claude pelo ID do agente se quiser referenciá-lo explicitamente, ou encontrar IDs nos arquivos de transcrição em `~/.claude/projects/{project}/{sessionId}/subagents/`. Cada transcrição é armazenada como `agent-{agentId}.jsonl`.929Você também pode pedir a Claude pelo ID do agente se quiser referenciá-lo explicitamente, ou encontrar IDs nos arquivos de transcrição em `~/.claude/projects/{project}/{sessionId}/subagents/`. Cada transcrição é armazenada como `agent-{agentId}.jsonl`.

914 930

915Transcrições de subagente persistem independentemente da conversa principal:931Transcrições de subagente persistem independentemente da conversa principal:

977| `x` | Descartar uma bifurcação terminada ou parar uma em execução |993| `x` | Descartar uma bifurcação terminada ou parar uma em execução |

978| `Esc` | Retornar foco para a entrada de prompt |994| `Esc` | Retornar foco para a entrada de prompt |

979 995

996Com a transcrição de uma bifurcação ou subagente aberta, mensagens de acompanhamento e [skills](/pt/skills) vão para esse agente, mas comandos integrados ainda são executados em sua conversa principal. {/* min-version: 2.1.199 */}A partir da v2.1.199, digitar `/model` ou `/fast` nessa visualização mostra um aviso de que isso muda o modelo da conversa principal ou modo rápido, não do agente visualizado, em vez de executá-lo silenciosamente.

997

980<h3 id="how-forks-differ-from-named-subagents">998<h3 id="how-forks-differ-from-named-subagents">

981 Como bifurcações diferem de subagentes nomeados999 Como bifurcações diferem de subagentes nomeados

982</h3>1000</h3>

1020 Revisor de código1038 Revisor de código

1021</h3>1039</h3>

1022 1040

1023Um subagente somente leitura que revisa código sem modificá-lo. Este exemplo mostra como projetar um subagente focado com acesso limitado a ferramentas (sem Edit ou Write) e um prompt detalhado que especifica exatamente o que procurar e como formatar a saída.1041Um subagente somente leitura que revisa código sem modificá-lo. Este exemplo mostra como projetar um subagente focado com acesso limitado a ferramentas que exclui Edit e Write, e um prompt detalhado que especifica exatamente o que procurar e como formatar a saída.

1024 1042

1025```markdown theme={null}1043```markdown theme={null}

1026---1044---

third-party-integrations.md +1 −1

Details

196 196

197* [Claude for Teams ou Enterprise](/pt/authentication#claude-for-teams-or-enterprise)197* [Claude for Teams ou Enterprise](/pt/authentication#claude-for-teams-or-enterprise)

198* [Anthropic Console](/pt/authentication#claude-console-authentication)198* [Anthropic Console](/pt/authentication#claude-console-authentication)

199* [Claude apps gateway](/pt/claude-apps-gateway), um gateway auto-hospedado que adiciona entrada de IdP na frente do Amazon Bedrock, Google Vertex AI, Microsoft Foundry ou da API Anthropic199* [Claude apps gateway](/pt/claude-apps-gateway), um gateway auto-hospedado que adiciona entrada de IdP na frente do Amazon Bedrock, Claude Platform on AWS, Google Vertex AI, Microsoft Foundry ou da API Anthropic

200* [Amazon Bedrock](/pt/amazon-bedrock)200* [Amazon Bedrock](/pt/amazon-bedrock)

201* [Claude Platform on AWS](/pt/claude-platform-on-aws)201* [Claude Platform on AWS](/pt/claude-platform-on-aws)

202* [Google Vertex AI](/pt/google-vertex-ai)202* [Google Vertex AI](/pt/google-vertex-ai)

tools-reference.md +22 −12

Details

11Para adicionar ferramentas personalizadas, conecte um [servidor MCP](/pt/mcp). Para estender Claude com fluxos de trabalho baseados em prompts reutilizáveis, escreva uma [skill](/pt/skills), que é executada através da ferramenta `Skill` existente em vez de adicionar uma nova entrada de ferramenta.11Para adicionar ferramentas personalizadas, conecte um [servidor MCP](/pt/mcp). Para estender Claude com fluxos de trabalho baseados em prompts reutilizáveis, escreva uma [skill](/pt/skills), que é executada através da ferramenta `Skill` existente em vez de adicionar uma nova entrada de ferramenta.

12 12

14| :--------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------- |14| :--------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------- |

15| `Agent` | Cria um [subagent](/pt/sub-agents) com sua própria janela de contexto para lidar com uma tarefa. Veja [comportamento da ferramenta Agent](#agent-tool-behavior) | Não |15| `Agent` | Cria um [subagent](/pt/sub-agents) com sua própria janela de contexto para lidar com uma tarefa. Veja [comportamento da ferramenta Agent](#agent-tool-behavior) | Não |

16| `Artifact` | Publica um arquivo HTML ou Markdown como um [artifact](/pt/artifacts): uma página privada e interativa no claude.ai. Em planos Team e Enterprise, você pode compartilhá-lo dentro de sua organização. {/* plan-availability: feature=artifacts plans=pro,max,team,enterprise providers=anthropic */}Requer um plano Pro, Max, Team ou Enterprise e autenticação `/login`; veja [Disponibilidade](/pt/artifacts#availability) | Sim |16| `Artifact` | Publica um arquivo HTML ou Markdown como um [artifact](/pt/artifacts): uma página privada e interativa no claude.ai. Em planos Team e Enterprise, você pode compartilhá-lo dentro de sua organização. {/* plan-availability: feature=artifacts plans=pro,max,team,enterprise providers=anthropic */}Requer um plano Pro, Max, Team ou Enterprise e autenticação `/login`; veja [Disponibilidade](/pt/artifacts#availability) | Sim |

17| `AskUserQuestion` | Faz perguntas de múltipla escolha para coletar requisitos ou esclarecer ambiguidades | Não |17| `AskUserQuestion` | Faz perguntas de múltipla escolha para coletar requisitos ou esclarecer ambiguidades. {/* min-version: 2.1.198 */}A partir de v2.1.198, se você não responder dentro de 60 segundos, o diálogo fecha automaticamente: ele envia todas as opções que você já havia selecionado e diz a Claude que você pode estar longe do teclado, para que Claude prossiga com seu próprio julgamento e possa fazer perguntas novamente mais tarde. Uma contagem regressiva aparece nos últimos 20 segundos. Qualquer pressionamento de tecla mantém o diálogo aberto, assim como uma janela focada em terminais que relatam foco. Defina a variável de ambiente [`CLAUDE_AFK_TIMEOUT_MS`](/pt/env-vars#variables) para alterar quanto tempo Claude Code aguarda, ou para um valor grande como `86400000`, 24 horas, para manter as perguntas abertas enquanto você está ausente. Este tempo limite se aplica apenas às perguntas de múltipla escolha do `AskUserQuestion`; prompts de permissão, incluindo aprovação de plano, nunca se resolvem automaticamente em inatividade | Não |

18| `Bash` | Executa comandos de shell em seu ambiente. Veja [comportamento da ferramenta Bash](#bash-tool-behavior) | Sim |18| `Bash` | Executa comandos de shell em seu ambiente. Veja [comportamento da ferramenta Bash](#bash-tool-behavior) | Sim |

19| `CronCreate` | Agenda uma solicitação recorrente ou única dentro da sessão atual. As tarefas têm escopo de sessão e são restauradas em `--resume` ou `--continue` se não expiradas. Veja [tarefas agendadas](/pt/scheduled-tasks) | Não |19| `CronCreate` | Agenda uma solicitação recorrente ou única dentro da sessão atual. As tarefas têm escopo de sessão e são restauradas em `--resume` ou `--continue` se não expiradas. Veja [tarefas agendadas](/pt/scheduled-tasks) | Não |

20| `CronDelete` | Cancela uma tarefa agendada por ID | Não |20| `CronDelete` | Cancela uma tarefa agendada por ID | Não |

35| `Read` | Lê o conteúdo de arquivos. Veja [comportamento da ferramenta Read](#read-tool-behavior) | Não |35| `Read` | Lê o conteúdo de arquivos. Veja [comportamento da ferramenta Read](#read-tool-behavior) | Não |

36| `ReadMcpResourceTool` | Lê um recurso MCP específico por URI | Não |36| `ReadMcpResourceTool` | Lê um recurso MCP específico por URI | Não |

37| `RemoteTrigger` | Cria, atualiza, executa e lista [Routines](/pt/routines) no claude.ai. Suporta o comando `/schedule`. {/* plan-availability: feature=routines plans=pro,max,team,enterprise providers=anthropic */}Routines vivem no claude.ai e requerem um plano Pro, Max, Team ou Enterprise, portanto esta ferramenta não é acessível do Amazon Bedrock, Google Vertex AI ou Microsoft Foundry | Não |37| `RemoteTrigger` | Cria, atualiza, executa e lista [Routines](/pt/routines) no claude.ai. Suporta o comando `/schedule`. {/* plan-availability: feature=routines plans=pro,max,team,enterprise providers=anthropic */}Routines vivem no claude.ai e requerem um plano Pro, Max, Team ou Enterprise, portanto esta ferramenta não é acessível do Amazon Bedrock, Google Vertex AI ou Microsoft Foundry | Não |

38| `ReportFindings` | Relata descobertas de revisão de código como uma lista estruturada, com um arquivo, resumo e cenário de falha por descoberta, para que Claude Code possa renderizá-las em vez de imprimi-las como texto. Claude a chama quando instruções ativas de revisão de código dizem para fazê-lo. {/* min-version: 2.1.196 */}Requer Claude Code v2.1.196 ou posterior | Não |38| `ReportFindings` | Relata descobertas de revisão de código como uma lista estruturada, com um arquivo, resumo e cenário de falha por descoberta, para que Claude Code possa renderizá-las em vez de imprimi-las como texto. Claude a chama quando instruções ativas de revisão de código dizem para fazê-lo. {/* min-version: 2.1.196 */}Requer Claude Code v2.1.196 ou posterior. {/* min-version: 2.1.199 */}A partir de v2.1.199, uma descoberta também pode carregar um slug `category` opcional, como `correctness` ou `test-coverage`, mostrado ao lado da localização do arquivo na lista renderizada | Não |

39| `ScheduleWakeup` | Reagenda a próxima iteração de um [`/loop` auto-paced](/pt/scheduled-tasks#let-claude-choose-the-interval). Claude chama isso no final de cada iteração para escolher quando a próxima será executada, entre um minuto e uma hora; você não a chama diretamente. O wakeup pendente aparece em `session_crons` em [Stop hook input](/pt/hooks#stop-input). {/* plan-availability: feature=loop-dynamic providers=anthropic */}Não disponível no Amazon Bedrock, Google Vertex AI ou Microsoft Foundry, onde um prompt `/loop` sem intervalo é executado em um cronograma fixo | Não |39| `ScheduleWakeup` | Reagenda a próxima iteração de um [`/loop` auto-paced](/pt/scheduled-tasks#let-claude-choose-the-interval). Claude chama isso no final de cada iteração para escolher quando a próxima será executada, entre um minuto e uma hora; você não a chama diretamente. O wakeup pendente aparece em `session_crons` em [Stop hook input](/pt/hooks#stop-input). {/* plan-availability: feature=loop-dynamic providers=anthropic */}Não disponível no Amazon Bedrock, Google Vertex AI ou Microsoft Foundry, onde um prompt `/loop` sem intervalo é executado em um cronograma fixo | Não |

40| `SendMessage` | Envia uma mensagem para um [membro da equipe de agentes](/pt/agent-teams), ou [retoma um subagent](/pt/sub-agents#resume-subagents) por seu ID de agente. Subagents parados retomam automaticamente em segundo plano. Mensagens de protocolo de equipe estruturadas requerem equipes de agentes | Não |40| `SendMessage` | Envia uma mensagem para um [membro da equipe de agentes](/pt/agent-teams), ou [retoma um subagent](/pt/sub-agents#resume-subagents) por seu ID de agente ou nome. Subagents parados retomam automaticamente em segundo plano. Mensagens de protocolo de equipe estruturadas requerem equipes de agentes. Um receptor nunca trata uma mensagem de outro agente como seu consentimento ou aprovação. {/* min-version: 2.1.198 */}A partir de v2.1.198, um subagent trata uma mensagem do agente que o lançou como direção de tarefa normal em vez de como uma solicitação de pares. {/* min-version: 2.1.199 */}A partir de v2.1.199, um envio para um nome que agora se resolve para um agente diferente do que fez anteriormente na conversa é recusado em vez de entregue; veja [Retomar subagents](/pt/sub-agents#resume-subagents) | Não |

41| `SendUserFile` | Envia arquivos da sessão para você com uma legenda opcional, para que um relatório gerado, diagrama, captura de tela ou artefato construído chegue ao seu dispositivo em vez de apenas ser mencionado na transcrição. {/* min-version: 2.1.196 */}A partir de v2.1.196, a entrada `display` opcional controla a apresentação: `render` abre o arquivo inline no cliente, `attach` mostra apenas um cartão de download, e quando não definido o cliente decide pelo tipo de arquivo. Disponível quando um cliente [Remote Control](/pt/remote-control) está conectado ou a sessão é executada em um ambiente de nuvem gerenciado como [Claude Code na web](/pt/claude-code-on-the-web). A entrega é executada através de infraestrutura hospedada pela Anthropic, portanto a ferramenta não está disponível no Amazon Bedrock, Google Vertex AI ou Microsoft Foundry | Não |41| `SendUserFile` | Envia arquivos da sessão para você com uma legenda opcional, para que um relatório gerado, diagrama, captura de tela ou artefato construído chegue ao seu dispositivo em vez de apenas ser mencionado na transcrição. {/* min-version: 2.1.196 */}A partir de v2.1.196, a entrada `display` opcional controla a apresentação: `render` abre o arquivo inline no cliente, `attach` mostra apenas um cartão de download, e quando não definido o cliente decide pelo tipo de arquivo. Disponível quando um cliente [Remote Control](/pt/remote-control) está conectado ou a sessão é executada em um ambiente de nuvem gerenciado como [Claude Code na web](/pt/claude-code-on-the-web). A entrega é executada através de infraestrutura hospedada pela Anthropic, portanto a ferramenta não está disponível no Amazon Bedrock, Google Vertex AI ou Microsoft Foundry | Não |

42| `ShareOnboardingGuide` | {/* plan-availability: feature=onboarding-guide-share plans=pro,max,team,enterprise providers=anthropic */}Carrega `ONBOARDING.md` e retorna um link de compartilhamento que colegas podem abrir no Claude Code. Chamado de `/team-onboarding` após o guia ser escrito. Disponível para assinantes do claude.ai em planos Pro, Max, Team e Enterprise | Sim |42| `ShareOnboardingGuide` | {/* plan-availability: feature=onboarding-guide-share plans=pro,max,team,enterprise providers=anthropic */}Carrega `ONBOARDING.md` e retorna um link de compartilhamento que colegas podem abrir no Claude Code. Chamado de `/team-onboarding` após o guia ser escrito. Disponível para assinantes do claude.ai em planos Pro, Max, Team e Enterprise | Sim |

43| `Skill` | Executa uma [skill](/pt/skills#control-who-invokes-a-skill) dentro da conversa principal | Sim |43| `Skill` | Executa uma [skill](/pt/skills#control-who-invokes-a-skill) dentro da conversa principal | Sim |

45| `TaskGet` | Recupera detalhes completos para uma tarefa específica | Não |45| `TaskGet` | Recupera detalhes completos para uma tarefa específica | Não |

46| `TaskList` | Lista todas as tarefas com seu status atual | Não |46| `TaskList` | Lista todas as tarefas com seu status atual | Não |

47| `TaskOutput` | (Descontinuado) Recupera saída de uma tarefa em segundo plano. Prefira `Read` no caminho do arquivo de saída da tarefa | Não |47| `TaskOutput` | (Descontinuado) Recupera saída de uma tarefa em segundo plano. Prefira `Read` no caminho do arquivo de saída da tarefa | Não |

48| `TaskStop` | Mata uma tarefa em segundo plano em execução por ID | Não |48| `TaskStop` | Para uma tarefa em segundo plano em execução por ID. {/* min-version: 2.1.198 */}A partir de v2.1.198, também aceita um [membro da equipe de agentes](/pt/agent-teams) ou um agente de fundo nomeado por ID de agente ou nome | Não |

49| `TaskUpdate` | Atualiza status da tarefa, dependências, detalhes ou deleta tarefas | Não |49| `TaskUpdate` | Atualiza status da tarefa, dependências, detalhes ou deleta tarefas | Não |

50| `TodoWrite` | {/* min-version: 2.1.142 */}Gerencia a lista de verificação de tarefas da sessão. Desabilitado por padrão a partir de v2.1.142 em favor de `TaskCreate`, `TaskGet`, `TaskList` e `TaskUpdate`. Defina `CLAUDE_CODE_ENABLE_TASKS=0` para reabilitar | Não |50| `TodoWrite` | {/* min-version: 2.1.142 */}Gerencia a lista de verificação de tarefas da sessão. Desabilitado por padrão a partir de v2.1.142 em favor de `TaskCreate`, `TaskGet`, `TaskList` e `TaskUpdate`. Defina `CLAUDE_CODE_ENABLE_TASKS=0` para reabilitar | Não |

51| `ToolSearch` | Pesquisa e carrega ferramentas diferidas quando [pesquisa de ferramentas](/pt/mcp#scale-with-mcp-tool-search) está ativada | Não |51| `ToolSearch` | Pesquisa e carrega ferramentas diferidas quando [pesquisa de ferramentas](/pt/mcp#scale-with-mcp-tool-search) está ativada | Não |

52| `WaitForMcpServers` | {/* min-version: 2.1.142 */}Aguarda um ou mais [servidores MCP](/pt/mcp) que ainda estão se conectando em segundo plano, para que uma solicitação possa usar suas ferramentas sem reiniciar a sessão. Claude a chama quando um servidor necessário ainda não está conectado. Aparece apenas quando [pesquisa de ferramentas](/pt/mcp#scale-with-mcp-tool-search) está desabilitada, já que `ToolSearch` lida com a espera quando está ativada | Não |52| `WaitForMcpServers` | Aguarda um ou mais [servidores MCP](/pt/mcp) que ainda estão se conectando em segundo plano, para que uma solicitação possa usar suas ferramentas sem reiniciar a sessão. Claude a chama quando um servidor necessário ainda não está conectado. Aparece apenas quando [pesquisa de ferramentas](/pt/mcp#scale-with-mcp-tool-search) está desabilitada, já que `ToolSearch` lida com a espera quando está ativada | Não |

53| `WebFetch` | Busca conteúdo de uma URL especificada. Veja [comportamento da ferramenta WebFetch](#webfetch-tool-behavior) | Sim |53| `WebFetch` | Busca conteúdo de uma URL especificada. Veja [comportamento da ferramenta WebFetch](#webfetch-tool-behavior) | Sim |

54| `WebSearch` | Realiza pesquisas na web. Veja [comportamento da ferramenta WebSearch](#websearch-tool-behavior) | Sim |54| `WebSearch` | Realiza pesquisas na web. Veja [comportamento da ferramenta WebSearch](#websearch-tool-behavior) | Sim |

55| `Workflow` | Executa um [fluxo de trabalho dinâmico](/pt/workflows): um script que orquestra muitos subagents em segundo plano e retorna um resultado consolidado | Sim |55| `Workflow` | Executa um [fluxo de trabalho dinâmico](/pt/workflows): um script que orquestra muitos subagents em segundo plano e retorna um resultado consolidado | Sim |

91 Comportamento da ferramenta Agent91 Comportamento da ferramenta Agent

92</h2>92</h2>

93 93

94A ferramenta Agent cria um subagent em uma janela de contexto separada. O subagent trabalha através de sua tarefa autonomamente, depois retorna um único resultado de texto para a conversa pai. O pai não vê as chamadas de ferramenta intermediárias ou saídas do subagent, apenas esse resultado final. Para limitar quantas voltas um subagent executa, defina `maxTurns` na [definição do subagent](/pt/sub-agents#supported-frontmatter-fields).94A ferramenta Agent cria um subagent em uma janela de contexto separada. O subagent trabalha através de sua tarefa autonomamente, depois retorna um único resultado de texto para a conversa pai. O pai não vê as chamadas de ferramenta intermediárias ou saídas do subagent, apenas esse resultado final.

96Para limitar quantas voltas um subagent executa, defina `maxTurns` na [definição do subagent](/pt/sub-agents#supported-frontmatter-fields).

95 97

96A mesma ferramenta Agent também inicia [subagents bifurcados](/pt/sub-agents#fork-the-current-conversation) quando o modo de bifurcação está ativado. Uma bifurcação herda a conversa pai completa em vez de começar do zero, sempre é executada em segundo plano e ainda exibe prompts de permissão em seu terminal. O resto desta seção descreve subagents nomeados.98A mesma ferramenta Agent também inicia [subagents bifurcados](/pt/sub-agents#fork-the-current-conversation) quando o modo de bifurcação está ativado. Uma bifurcação herda a conversa pai completa em vez de começar do zero, sempre é executada em segundo plano e ainda exibe prompts de permissão em seu terminal. O resto desta seção descreve subagents nomeados.

97 99

102* **Apenas `disallowedTools`**: o subagent obtém todas as ferramentas pai exceto as listadas.104* **Apenas `disallowedTools`**: o subagent obtém todas as ferramentas pai exceto as listadas.

103* **Ambos definidos**: `disallowedTools` tem precedência. Uma ferramenta listada em ambos é removida.105* **Ambos definidos**: `disallowedTools` tem precedência. Uma ferramenta listada em ambos é removida.

104 106

105Iniciar o subagent não solicita permissão por si só. As chamadas de ferramenta do subagent são verificadas contra suas regras de permissão conforme ele é executado:107Iniciar o subagent não solicita permissão por si só. Claude Code verifica as chamadas de ferramenta do subagent contra suas regras de permissão conforme ele é executado.

108

109{/* min-version: 2.1.198 */}A partir da v2.1.198, subagents são executados em segundo plano por padrão; Claude executa um em primeiro plano quando precisa do resultado antes de continuar.

106 110

107* **Subagents em primeiro plano** mostram os mesmos prompts de permissão que você veria na conversa principal, no momento em que cada chamada de ferramenta acontece.111* **Subagents em primeiro plano** mostram os mesmos prompts de permissão que você veria na conversa principal, no momento em que cada chamada de ferramenta acontece.

108* **Subagents em segundo plano** {/* min-version: 2.1.186 */}exibem prompts de permissão em sua sessão principal a partir da v2.1.186. O prompt indica qual subagent está solicitando, e pressionar Esc nega essa chamada de ferramenta sem parar o subagent. Antes da v2.1.186, subagents em segundo plano negavam automaticamente qualquer chamada de ferramenta que de outra forma solicitaria e continuavam sem essa ferramenta.112* **Subagents em segundo plano** {/* min-version: 2.1.186 */}exibem prompts de permissão em sua sessão principal a partir da v2.1.186. O prompt indica qual subagent está solicitando, e pressionar Esc nega essa chamada de ferramenta sem parar o subagent. Antes da v2.1.186, subagents em segundo plano negavam automaticamente qualquer chamada de ferramenta que de outra forma solicitaria e continuavam sem essa ferramenta.

266 Ferramenta PowerShell270 Ferramenta PowerShell

267</h2>271</h2>

268 272

269A ferramenta PowerShell permite que Claude execute comandos PowerShell nativamente. No Windows, isso significa que os comandos são executados no PowerShell em vez de serem roteados através do Git Bash. No Windows sem Git Bash, a ferramenta é ativada automaticamente. No Windows com Git Bash instalado, a ferramenta está sendo lançada progressivamente. No Linux, macOS e WSL, a ferramenta é opcional.273A ferramenta PowerShell permite que Claude execute comandos PowerShell nativamente. No Windows, isso significa que os comandos são executados no PowerShell em vez de serem roteados através do Git Bash. Como a ferramenta fica disponível depende da sua plataforma:

274

275* **Windows sem Git Bash**: a ferramenta é ativada automaticamente.

276* **Windows com Git Bash instalado**: a ferramenta está sendo lançada progressivamente.

277* **Linux, macOS e WSL**: a ferramenta é opcional.

270 278

271<h3 id="enable-the-powershell-tool">279<h3 id="enable-the-powershell-tool">

272 Ativar a ferramenta PowerShell280 Ativar a ferramenta PowerShell

286 294

287No Windows, Claude Code detecta automaticamente `pwsh.exe` para PowerShell 7+ com fallback para `powershell.exe` para PowerShell 5.1. Quando a ferramenta está ativada, Claude trata PowerShell como o shell primário. A ferramenta Bash permanece disponível para scripts POSIX quando Git Bash está instalado.295No Windows, Claude Code detecta automaticamente `pwsh.exe` para PowerShell 7+ com fallback para `powershell.exe` para PowerShell 5.1. Quando a ferramenta está ativada, Claude trata PowerShell como o shell primário. A ferramenta Bash permanece disponível para scripts POSIX quando Git Bash está instalado.

288 296

289Claude Code inicia PowerShell com `-ExecutionPolicy Bypass` apenas no escopo do processo, portanto scripts `.ps1` e importações de módulo funcionam em instalações padrão do Windows sem alterar a política da máquina. O bypass no escopo do processo não substitui a Group Policy `MachinePolicy` ou `UserPolicy`, portanto os bloqueios corporativos ainda se aplicam. Para respeitar a política de execução efetiva da máquina, defina `CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY=1`.297Claude Code inicia PowerShell com `-ExecutionPolicy Bypass` apenas no escopo do processo, portanto scripts `.ps1` e importações de módulo funcionam em instalações padrão do Windows sem alterar a política da máquina. O bypass no escopo do processo não substitui a Group Policy `MachinePolicy` ou `UserPolicy`, portanto as políticas corporativas ainda se aplicam. Para respeitar a política de execução efetiva da máquina, defina `CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY=1`.

290 298

291<h3 id="shell-selection-in-settings-hooks-and-skills">299<h3 id="shell-selection-in-settings-hooks-and-skills">

292 Seleção de shell em configurações, hooks e skills300 Seleção de shell em configurações, hooks e skills

346 354

347Uma regra explícita `WebFetch(domain:...)` em `deny`, `ask` ou `allow` tem precedência sobre o conjunto pré-aprovado, portanto você pode bloquear um domínio pré-aprovado ou exigir um prompt para ele.355Uma regra explícita `WebFetch(domain:...)` em `deny`, `ask` ou `allow` tem precedência sobre o conjunto pré-aprovado, portanto você pode bloquear um domínio pré-aprovado ou exigir um prompt para ele.

348 356

349WebFetch define um cabeçalho `User-Agent` começando com `Claude-User` e um cabeçalho `Accept` que prefere Markdown sobre HTML para que servidores que suportam negociação de conteúdo possam retornar Markdown diretamente. [Sandbox](/pt/sandboxing) regras de rede são configuradas separadamente, portanto um domínio que você quer que um processo em sandbox alcance ainda precisa de uma regra de permissão de sandbox explícita.357WebFetch define um cabeçalho `User-Agent` começando com `Claude-User` e um cabeçalho `Accept` que prefere Markdown sobre HTML para que servidores que suportam negociação de conteúdo possam retornar Markdown diretamente.

358

359Você configura regras de rede [sandbox](/pt/sandboxing) separadamente, portanto um domínio que você quer que um processo em sandbox alcance ainda precisa de uma regra de permissão de sandbox explícita.

350 360

351<h2 id="websearch-tool-behavior">361<h2 id="websearch-tool-behavior">

352 Comportamento da ferramenta WebSearch362 Comportamento da ferramenta WebSearch

361Regras de permissão WebSearch não levam especificador. Uma entrada `WebSearch` simples em `allow` ou `deny` é a única forma.371Regras de permissão WebSearch não levam especificador. Uma entrada `WebSearch` simples em `allow` ou `deny` é a única forma.

362 372

363<Note>373<Note>

364 WebSearch está disponível na Claude API e Microsoft Foundry. No Google Cloud Vertex AI funciona com modelos Claude 4 e posteriores, incluindo Opus, Sonnet e Haiku. Amazon Bedrock não expõe a ferramenta de pesquisa na web do lado do servidor.374 WebSearch está disponível na Claude API, [Claude Platform on AWS](/pt/claude-platform-on-aws), e Microsoft Foundry. No Google Cloud Vertex AI funciona com modelos Claude 4 e posteriores, incluindo Opus, Sonnet e Haiku. Amazon Bedrock não expõe a ferramenta de pesquisa na web do lado do servidor.

365</Note>375</Note>

366 376

367<h2 id="write-tool-behavior">377<h2 id="write-tool-behavior">

worktrees.md +2 −0

Details

36 36

37Você também pode pedir ao Claude para "trabalhar em uma worktree" durante uma sessão, e ele criará uma com a ferramenta [`EnterWorktree`](/pt/tools-reference). Uma vez em uma worktree, Claude pode alternar diretamente para outra em `.claude/worktrees/` chamando `EnterWorktree` com o caminho de destino. A worktree anterior permanece no disco intacta.37Você também pode pedir ao Claude para "trabalhar em uma worktree" durante uma sessão, e ele criará uma com a ferramenta [`EnterWorktree`](/pt/tools-reference). Uma vez em uma worktree, Claude pode alternar diretamente para outra em `.claude/worktrees/` chamando `EnterWorktree` com o caminho de destino. A worktree anterior permanece no disco intacta.

38 38

39{/* min-version: 2.1.198 */}A partir da v2.1.198, entrar ou sair de uma worktree também realoca a transcrição da sessão para o armazenamento de projeto desse diretório, da mesma forma que [`/cd`](/pt/commands) faz, então `/desktop` e `--resume` encontram a sessão lá depois. Worktrees criadas por um hook [`WorktreeCreate`](#non-git-version-control) são excluídas e mantêm a transcrição no diretório de inicialização.

39Antes de usar `--worktree` interativamente em um diretório pela primeira vez, aceite o diálogo de confiança do workspace executando `claude` uma vez nesse diretório. Se a confiança ainda não foi aceita, `--worktree` sai com um erro e solicita que você execute `claude` no diretório primeiro. Execuções não interativas com `-p` pulam a [verificação de confiança](/pt/security), então `claude -p --worktree` prossegue sem ela.41Antes de usar `--worktree` interativamente em um diretório pela primeira vez, aceite o diálogo de confiança do workspace executando `claude` uma vez nesse diretório. Se a confiança ainda não foi aceita, `--worktree` sai com um erro e solicita que você execute `claude` no diretório primeiro. Execuções não interativas com `-p` pulam a [verificação de confiança](/pt/security), então `claude -p --worktree` prossegue sem ela.

40 42

41<Tip>43<Tip>

Documentation 2026-07-02 23:59 UTC to 2026-07-03 23:00 UTC