Documentation — Spybara

agent-sdk/agent-loop.md +395 −0 created

Details

1> ## Documentation Index

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

5# Como o loop do agente funciona

7> Entenda o ciclo de vida das mensagens, execução de ferramentas, janela de contexto e arquitetura que alimentam seus agentes SDK.

9O Agent SDK permite que você incorpore o loop do agente autônomo do Claude Code em suas próprias aplicações. O SDK é um pacote independente que oferece controle programático sobre ferramentas, permissões, limites de custo e saída. Você não precisa ter o CLI do Claude Code instalado para usá-lo.

11Quando você inicia um agente, o SDK executa o mesmo [loop de execução que alimenta o Claude Code](/pt/how-claude-code-works#the-agentic-loop): Claude avalia seu prompt, chama ferramentas para agir, recebe os resultados e repete até que a tarefa seja concluída. Esta página explica o que acontece dentro desse loop para que você possa construir, depurar e otimizar seus agentes de forma eficaz.

13## O loop em um relance

15Cada sessão de agente segue o mesmo ciclo:

17<img src="https://mintcdn.com/claude-code/gvy2DIUELtNA8qD3/images/agent-loop-diagram.svg?fit=max&auto=format&n=gvy2DIUELtNA8qD3&q=85&s=192e1bd6c8a2950a16e5ee0b94e27e26" alt="Agent loop: prompt entra, Claude avalia, ramifica para chamadas de ferramentas ou resposta final" width="680" height="150" data-path="images/agent-loop-diagram.svg" />

191. **Receber prompt.** Claude recebe seu prompt, junto com o prompt do sistema, definições de ferramentas e histórico de conversa. O SDK produz uma [`SystemMessage`](#message-types) com subtipo `"init"` contendo metadados da sessão.

202. **Avaliar e responder.** Claude avalia o estado atual e determina como proceder. Pode responder com texto, solicitar uma ou mais chamadas de ferramentas, ou ambos. O SDK produz uma [`AssistantMessage`](#message-types) contendo o texto e quaisquer solicitações de chamadas de ferramentas.

213. **Executar ferramentas.** O SDK executa cada ferramenta solicitada e coleta os resultados. Cada conjunto de resultados de ferramentas retorna para Claude para a próxima decisão. Você pode usar [hooks](/pt/agent-sdk/hooks) para interceptar, modificar ou bloquear chamadas de ferramentas antes de serem executadas.

224. **Repetir.** Os passos 2 e 3 se repetem como um ciclo. Cada ciclo completo é uma volta. Claude continua chamando ferramentas e processando resultados até produzir uma resposta sem chamadas de ferramentas.

235. **Retornar resultado.** O SDK produz uma [`AssistantMessage`](#message-types) final com a resposta de texto (sem chamadas de ferramentas), seguida por uma [`ResultMessage`](#message-types) com o texto final, uso de tokens, custo e ID da sessão.

25Uma pergunta rápida ("quais arquivos estão aqui?") pode levar uma ou duas voltas chamando `Glob` e respondendo com os resultados. Uma tarefa complexa ("refatore o módulo de autenticação e atualize os testes") pode encadear dezenas de chamadas de ferramentas em muitas voltas, lendo arquivos, editando código e executando testes, com Claude ajustando sua abordagem com base em cada resultado.

27## Voltas e mensagens

29Uma volta é uma rodada dentro do loop: Claude produz saída que inclui chamadas de ferramentas, o SDK executa essas ferramentas e os resultados retornam para Claude automaticamente. Isso acontece sem ceder o controle de volta para seu código. As voltas continuam até que Claude produza saída sem chamadas de ferramentas, momento em que o loop termina e o resultado final é entregue.

31Considere como uma sessão completa pode parecer para o prompt "Corrija os testes falhando em auth.ts".

33Primeiro, o SDK envia seu prompt para Claude e produz uma [`SystemMessage`](#message-types) com os metadados da sessão. Então o loop começa:

351. **Volta 1:** Claude chama `Bash` para executar `npm test`. O SDK produz uma [`AssistantMessage`](#message-types) com a chamada de ferramenta, executa o comando, então produz uma [`UserMessage`](#message-types) com a saída (três falhas).

362. **Volta 2:** Claude chama `Read` em `auth.ts` e `auth.test.ts`. O SDK retorna o conteúdo dos arquivos e produz uma `AssistantMessage`.

373. **Volta 3:** Claude chama `Edit` para corrigir `auth.ts`, então chama `Bash` para executar novamente `npm test`. Todos os três testes passam. O SDK produz uma `AssistantMessage`.

384. **Volta final:** Claude produz uma resposta apenas com texto sem chamadas de ferramentas: "Corrigi o bug de autenticação, todos os três testes passam agora." O SDK produz uma `AssistantMessage` final com este texto, então uma [`ResultMessage`](#message-types) com o mesmo texto mais custo e uso.

40Foram quatro voltas: três com chamadas de ferramentas, uma resposta final apenas com texto.

42Você pode limitar o loop com `max_turns` / `maxTurns`, que conta apenas voltas de uso de ferramentas. Por exemplo, `max_turns=2` no loop acima teria parado antes da etapa de edição. Você também pode usar `max_budget_usd` / `maxBudgetUsd` para limitar voltas com base em um limite de gastos.

44Sem limites, o loop é executado até que Claude termine por conta própria, o que é bom para tarefas bem definidas, mas pode ser longo em prompts abertos ("melhore esta base de código"). Definir um orçamento é um bom padrão para agentes em produção. Veja [Voltas e orçamento](#turns-and-budget) abaixo para a referência de opções.

46## Tipos de mensagens

48Conforme o loop é executado, o SDK produz um fluxo de mensagens. Cada mensagem carrega um tipo que informa em qual estágio do loop ela veio. Os cinco tipos principais são:

50* **`SystemMessage`:** eventos do ciclo de vida da sessão. O campo `subtype` os distingue: `"init"` é a primeira mensagem (metadados da sessão), e `"compact_boundary"` dispara após [compactação](#automatic-compaction). Em TypeScript, o limite de compactação é seu próprio tipo [`SDKCompactBoundaryMessage`](/pt/agent-sdk/typescript#sdkcompactboundarymessage) em vez de um subtipo de `SDKSystemMessage`.

51* **`AssistantMessage`:** emitida após cada resposta do Claude, incluindo a final apenas com texto. Contém blocos de conteúdo de texto e blocos de chamadas de ferramentas dessa volta.

52* **`UserMessage`:** emitida após cada execução de ferramenta com o conteúdo do resultado da ferramenta enviado de volta para Claude. Também emitida para quaisquer entradas do usuário que você transmita no meio do loop.

53* **`StreamEvent`:** emitida apenas quando mensagens parciais estão habilitadas. Contém eventos brutos de streaming da API (deltas de texto, pedaços de entrada de ferramentas). Veja [Respostas de streaming](/pt/agent-sdk/streaming-output).

54* **`ResultMessage`:** marca o fim do loop do agente. Contém o resultado de texto final, uso de tokens, custo e ID da sessão. Verifique o campo `subtype` para determinar se a tarefa foi bem-sucedida ou atingiu um limite. Um pequeno número de eventos de sistema finais, como `prompt_suggestion`, pode chegar após ele, então itere o fluxo até a conclusão em vez de quebrar no resultado. Veja [Lidar com o resultado](#handle-the-result).

56Esses cinco tipos cobrem o ciclo de vida completo do loop do agente em ambos os SDKs. O SDK TypeScript também produz eventos de observabilidade adicionais (eventos de hooks, progresso de ferramentas, limites de taxa, notificações de tarefas) que fornecem detalhes extras, mas não são necessários para conduzir o loop. Veja a [referência de tipos de mensagens Python](/pt/agent-sdk/python#message-types) e [referência de tipos de mensagens TypeScript](/pt/agent-sdk/typescript#message-types) para as listas completas.

58### Lidar com mensagens

60Quais mensagens você lida depende do que você está construindo:

62* **Apenas resultados finais:** lide com `ResultMessage` para obter a saída, custo e se a tarefa foi bem-sucedida ou atingiu um limite.

63* **Atualizações de progresso:** lide com `AssistantMessage` para ver o que Claude está fazendo a cada volta, incluindo quais ferramentas chamou.

64* **Streaming ao vivo:** habilite mensagens parciais (`include_partial_messages` em Python, `includePartialMessages` em TypeScript) para obter mensagens `StreamEvent` em tempo real. Veja [Respostas de streaming em tempo real](/pt/agent-sdk/streaming-output).

66Como você verifica tipos de mensagens depende do SDK:

68* **Python:** verifique tipos de mensagens com `isinstance()` contra classes importadas de `claude_agent_sdk` (por exemplo, `isinstance(message, ResultMessage)`).

69* **TypeScript:** verifique o campo de string `type` (por exemplo, `message.type === "result"`). `AssistantMessage` e `UserMessage` envolvem a mensagem bruta da API em um campo `.message`, então blocos de conteúdo estão em `message.message.content`, não em `message.content`.

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

72 <CodeGroup>

73 ```python Python theme={null}

74 from claude_agent_sdk import query, AssistantMessage, ResultMessage

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

77 if isinstance(message, AssistantMessage):

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

79 if isinstance(message, ResultMessage):

80 if message.subtype == "success":

81 print(message.result)

82 else:

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

84 ```

86 ```typescript TypeScript theme={null}

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

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

90 if (message.type === "assistant") {

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

92 }

93 if (message.type === "result") {

94 if (message.subtype === "success") {

95 console.log(message.result);

96 } else {

97 console.log(`Stopped: ${message.subtype}`);

98 }

99 }

100 }

101 ```

102 </CodeGroup>

103</Accordion>

104

105## Execução de ferramentas

106

107Ferramentas dão ao seu agente a capacidade de agir. Sem ferramentas, Claude pode apenas responder com texto. Com ferramentas, Claude pode ler arquivos, executar comandos, pesquisar código e interagir com serviços externos.

108

109### Ferramentas integradas

110

111O SDK inclui as mesmas ferramentas que alimentam o Claude Code:

112

113| Categoria | Ferramentas | O que fazem |

114| :----------------------- | :----------------------------------------------- | :------------------------------------------------------------------------------------------- |

115| **Operações de arquivo** | `Read`, `Edit`, `Write` | Ler, modificar e criar arquivos |

116| **Pesquisa** | `Glob`, `Grep` | Encontrar arquivos por padrão, pesquisar conteúdo com regex |

117| **Execução** | `Bash` | Executar comandos de shell, scripts, operações git |

118| **Web** | `WebSearch`, `WebFetch` | Pesquisar a web, buscar e analisar páginas |

119| **Descoberta** | `ToolSearch` | Encontrar e carregar ferramentas dinamicamente sob demanda em vez de pré-carregar todas elas |

120| **Orquestração** | `Agent`, `Skill`, `AskUserQuestion`, `TodoWrite` | Gerar subagentes, invocar skills, perguntar ao usuário, rastrear tarefas |

121

122Além das ferramentas integradas, você pode:

123

124* **Conectar serviços externos** com [servidores MCP](/pt/agent-sdk/mcp) (bancos de dados, navegadores, APIs)

125* **Definir ferramentas personalizadas** com [manipuladores de ferramentas personalizadas](/pt/agent-sdk/custom-tools)

126* **Carregar skills do projeto** via [fontes de configuração](/pt/agent-sdk/claude-code-features) para fluxos de trabalho reutilizáveis

127

128### Permissões de ferramentas

129

130Claude determina quais ferramentas chamar com base na tarefa, mas você controla se essas chamadas podem ser executadas. Você pode aprovar automaticamente ferramentas específicas, bloquear outras completamente ou exigir aprovação para tudo. Três opções funcionam juntas para determinar o que é executado:

131

132* **`allowed_tools` / `allowedTools`** aprova automaticamente ferramentas listadas. Um agente somente leitura com `["Read", "Glob", "Grep"]` em sua lista de ferramentas permitidas executa essas ferramentas sem avisar. Ferramentas não listadas ainda estão disponíveis, mas exigem permissão.

133* **`disallowed_tools` / `disallowedTools`** bloqueia ferramentas listadas, independentemente de outras configurações. Veja [Permissões](/pt/agent-sdk/permissions) para a ordem em que as regras são verificadas antes de uma ferramenta ser executada.

134* **`permission_mode` / `permissionMode`** controla o que acontece com ferramentas que não são cobertas por regras de permissão ou negação. Veja [Modo de permissão](#permission-mode) para os modos disponíveis.

135

136Você também pode escopo ferramentas individuais com regras como `"Bash(npm *)"` para permitir apenas comandos específicos. Veja [Permissões](/pt/agent-sdk/permissions) para a sintaxe completa de regras.

137

138Quando uma ferramenta é negada, Claude recebe uma mensagem de rejeição como resultado da ferramenta e normalmente tenta uma abordagem diferente ou relata que não pôde prosseguir.

139

140### Execução paralela de ferramentas

141

142Quando Claude solicita múltiplas chamadas de ferramentas em uma única volta, ambos os SDKs podem executá-las concorrentemente ou sequencialmente dependendo da ferramenta. Ferramentas somente leitura (como `Read`, `Glob`, `Grep` e ferramentas MCP marcadas como somente leitura) podem ser executadas concorrentemente. Ferramentas que modificam estado (como `Edit`, `Write` e `Bash`) são executadas sequencialmente para evitar conflitos.

143

144Ferramentas personalizadas padrão para execução sequencial. Para habilitar execução paralela para uma ferramenta personalizada, defina `readOnlyHint` em suas anotações. Ambos os SDKs [TypeScript](/pt/agent-sdk/typescript#tool) e [Python](/pt/agent-sdk/python#tool) usam este nome de campo do SDK MCP.

145

146## Controlar como o loop é executado

147

148Você pode limitar quantas voltas o loop leva, quanto custa, quão profundamente Claude raciocina e se as ferramentas exigem aprovação antes de serem executadas. Todas essas são campos em [`ClaudeAgentOptions`](/pt/agent-sdk/python#claudeagentoptions) (Python) / [`Options`](/pt/agent-sdk/typescript#options) (TypeScript).

149

150### Voltas e orçamento

151

152| Opção | O que controla | Padrão |

153| :--------------------------------------------- | :-------------------------------------- | :--------- |

154| Max turns (`max_turns` / `maxTurns`) | Máximo de rodadas de uso de ferramentas | Sem limite |

155| Max budget (`max_budget_usd` / `maxBudgetUsd`) | Custo máximo antes de parar | Sem limite |

156

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

158

159### Nível de esforço

160

161A opção `effort` controla quanto raciocínio Claude aplica. Níveis de esforço mais baixos usam menos tokens por volta e reduzem custo. Nem todos os modelos suportam o parâmetro de esforço. Veja [Esforço](https://platform.claude.com/docs/en/build-with-claude/effort) para quais modelos o suportam.

162

163| Nível | Comportamento | Bom para |

164| :--------- | :----------------------------------- | :-------------------------------------------------------- |

165| `"low"` | Raciocínio mínimo, respostas rápidas | Buscas de arquivo, listagem de diretórios |

166| `"medium"` | Raciocínio equilibrado | Edições rotineiras, tarefas padrão |

167| `"high"` | Análise completa | Refatorações, depuração |

168| `"xhigh"` | Profundidade de raciocínio estendida | Tarefas de codificação e agentes; recomendado em Opus 4.7 |

169| `"max"` | Profundidade máxima de raciocínio | Problemas multi-etapas que exigem análise profunda |

170

171Se você não definir `effort`, o SDK Python deixa o parâmetro indefinido e defere para o comportamento padrão do modelo. O SDK TypeScript padrão é `"high"`.

172

173<Note>

174 `effort` negocia latência e custo de token por profundidade de raciocínio dentro de cada resposta. [Extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) é um recurso separado que produz blocos de cadeia de pensamento visíveis na saída. Eles são independentes: você pode definir `effort: "low"` com extended thinking habilitado, ou `effort: "max"` sem ele.

175</Note>

176

177Use esforço mais baixo para agentes fazendo tarefas simples e bem definidas (como listar arquivos ou executar um único grep) para reduzir custo e latência. Defina `effort` nas opções de nível superior `query()` para toda a sessão, ou por subagente com o campo `effort` em [`AgentDefinition`](/pt/agent-sdk/subagents#agentdefinition-configuration) para sobrescrever o nível de sessão.

178

179### Modo de permissão

180

181A opção de modo de permissão (`permission_mode` em Python, `permissionMode` em TypeScript) controla se o agente pede aprovação antes de usar ferramentas:

182

183| Modo | Comportamento |

184| :--------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

185| `"default"` | Ferramentas não cobertas por regras de permissão acionam seu callback de aprovação; sem callback significa negar |

186| `"acceptEdits"` | Aprova automaticamente edições de arquivo e comandos comuns do sistema de arquivos (`mkdir`, `touch`, `mv`, `cp`, etc.); outros comandos Bash seguem regras padrão |

187| `"plan"` | Ferramentas somente leitura são executadas; Claude explora e produz um plano sem editar seus arquivos de origem |

188| `"dontAsk"` | Nunca avisa. Ferramentas pré-aprovadas por [regras de permissão](/pt/settings#permission-settings) são executadas, tudo mais é negado |

189| `"auto"` (apenas TypeScript) | Usa um classificador de modelo para aprovar ou negar cada chamada de ferramenta. Veja [Modo Auto](/pt/permission-modes#eliminate-prompts-with-auto-mode) para disponibilidade e comportamento |

190| `"bypassPermissions"` | Executa todas as ferramentas permitidas sem avisar. Não pode ser usado ao executar como root em Unix. Use apenas em ambientes isolados onde as ações do agente não podem afetar sistemas que você se importa |

191

192Para aplicações interativas, use `"default"` com um callback de aprovação de ferramenta para exibir avisos de aprovação. Para agentes autônomos em uma máquina de desenvolvimento, `"acceptEdits"` aprova automaticamente edições de arquivo e comandos comuns do sistema de arquivos (`mkdir`, `touch`, `mv`, `cp`, etc.) enquanto ainda controla outros comandos `Bash` atrás de regras de permissão. Reserve `"bypassPermissions"` para CI, contêineres ou outros ambientes isolados. Veja [Permissões](/pt/agent-sdk/permissions) para detalhes completos.

193

194### Modelo

195

196Se você não definir `model`, o SDK usa o padrão do Claude Code, que depende do seu método de autenticação e assinatura. Defina explicitamente (por exemplo, `model="claude-sonnet-4-6"`) para fixar um modelo específico ou usar um modelo menor para agentes mais rápidos e baratos. Veja [modelos](https://platform.claude.com/docs/en/about-claude/models) para IDs disponíveis.

197

198## A janela de contexto

199

200A janela de contexto é a quantidade total de informações disponíveis para Claude durante uma sessão. Ela não é redefinida entre voltas dentro de uma sessão. Tudo se acumula: o prompt do sistema, definições de ferramentas, histórico de conversa, entradas de ferramentas e saídas de ferramentas. Conteúdo que permanece igual entre voltas (prompt do sistema, definições de ferramentas, CLAUDE.md) é automaticamente [prompt cached](https://platform.claude.com/docs/en/build-with-claude/prompt-caching), o que reduz custo e latência para prefixos repetidos.

201

202### O que consome contexto

203

204Aqui está como cada componente afeta o contexto no SDK:

205

206| Fonte | Quando carrega | Impacto |

207| :---------------------------- | :--------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

208| **Prompt do sistema** | Cada requisição | Custo fixo pequeno, sempre presente |

209| **Arquivos CLAUDE.md** | Início da sessão, via [`settingSources`](/pt/agent-sdk/claude-code-features) | Conteúdo completo em cada requisição (mas prompt-cached, então apenas a primeira requisição paga o custo completo) |

210| **Definições de ferramentas** | Cada requisição | Cada ferramenta adiciona seu schema; use [busca de ferramentas MCP](/pt/agent-sdk/mcp#mcp-tool-search) para carregar ferramentas sob demanda em vez de todas de uma vez |

211| **Histórico de conversa** | Acumula entre voltas | Cresce a cada volta: prompts, respostas, entradas de ferramentas, saídas de ferramentas |

212| **Descrições de skills** | Início da sessão, via fontes de configuração | Resumos curtos; conteúdo completo carrega apenas quando invocado |

213

214Grandes saídas de ferramentas consomem contexto significativo. Ler um arquivo grande ou executar um comando com saída detalhada pode usar milhares de tokens em uma única volta. O contexto se acumula entre voltas, então sessões mais longas com muitas chamadas de ferramentas acumulam significativamente mais contexto do que as curtas.

215

216### Compactação automática

217

218Quando a janela de contexto se aproxima de seu limite, o SDK compacta automaticamente a conversa: resume o histórico mais antigo para liberar espaço, mantendo suas trocas mais recentes e decisões-chave intactas. O SDK emite uma mensagem com `type: "system"` e `subtype: "compact_boundary"` no fluxo quando isso acontece (em Python isso é uma `SystemMessage`; em TypeScript é um tipo separado `SDKCompactBoundaryMessage`).

219

220A compactação substitui mensagens mais antigas por um resumo, então instruções específicas do início da conversa podem não ser preservadas. Regras persistentes pertencem a CLAUDE.md (carregado via [`settingSources`](/pt/agent-sdk/claude-code-features)) em vez do prompt inicial, porque o conteúdo CLAUDE.md é reinjetado em cada requisição.

221

222Você pode personalizar o comportamento de compactação de várias maneiras:

223

224* **Instruções de sumarização em CLAUDE.md:** O compactador lê seu CLAUDE.md como qualquer outro contexto, então você pode incluir uma seção dizendo a ele o que preservar ao resumir. O cabeçalho da seção é livre (não uma string mágica); o compactador corresponde à intenção.

225* **Hook `PreCompact`:** Execute lógica personalizada antes da compactação ocorrer, por exemplo para arquivar a transcrição completa. O hook recebe um campo `trigger` (`manual` ou `auto`). Veja [hooks](/pt/agent-sdk/hooks).

226* **Compactação manual:** Envie `/compact` como uma string de prompt para acionar compactação sob demanda. (Slash commands enviados desta forma são entradas SDK, não atalhos apenas CLI. Veja [slash commands no SDK](/pt/agent-sdk/slash-commands).)

227

228<Accordion title="Exemplo: Instruções de sumarização em CLAUDE.md">

229 Adicione uma seção ao CLAUDE.md do seu projeto dizendo ao compactador o que preservar. O nome do cabeçalho não é especial; use qualquer rótulo claro.

230

231 ```markdown CLAUDE.md theme={null}

232 # Summary instructions

233

234 When summarizing this conversation, always preserve:

235 - The current task objective and acceptance criteria

236 - File paths that have been read or modified

237 - Test results and error messages

238 - Decisions made and the reasoning behind them

239 ```

240</Accordion>

241

242### Manter contexto eficiente

243

244Algumas estratégias para agentes de longa duração:

245

246* **Use subagentes para subtarefas.** Cada subagente começa com uma conversa fresca (sem histórico de mensagens anterior, embora carregue seu próprio prompt do sistema e contexto de nível de projeto como CLAUDE.md). Ele não vê as voltas do pai, e apenas sua resposta final retorna ao pai como resultado de ferramenta. O contexto do agente principal cresce por esse resumo, não pela transcrição completa da subtarefa. Veja [O que subagentes herdam](/pt/agent-sdk/subagents#what-subagents-inherit) para detalhes.

247* **Seja seletivo com ferramentas.** Cada definição de ferramenta ocupa espaço de contexto. Use o campo `tools` em [`AgentDefinition`](/pt/agent-sdk/subagents#agentdefinition-configuration) para escopo subagentes ao conjunto mínimo que precisam, e use [busca de ferramentas MCP](/pt/agent-sdk/mcp#mcp-tool-search) para carregar ferramentas sob demanda em vez de pré-carregar todas elas.

248* **Observe custos de servidor MCP.** Cada servidor MCP adiciona todos os seus schemas de ferramentas a cada requisição. Alguns servidores com muitas ferramentas podem consumir contexto significativo antes do agente fazer qualquer trabalho. A ferramenta `ToolSearch` pode ajudar carregando ferramentas sob demanda em vez de pré-carregar todas elas. Veja [busca de ferramentas MCP](/pt/agent-sdk/mcp#mcp-tool-search) para configuração.

249* **Use esforço mais baixo para tarefas rotineiras.** Defina [esforço](#effort-level) para `"low"` para agentes que apenas precisam ler arquivos ou listar diretórios. Isso reduz uso de tokens e custo.

250

251Para um detalhamento detalhado dos custos de contexto por recurso, veja [Entender custos de contexto](/pt/features-overview#understand-context-costs).

252

253## Sessões e continuidade

254

255Cada interação com o SDK cria ou continua uma sessão. Capture o ID da sessão de `ResultMessage.session_id` (disponível em ambos os SDKs) para retomar mais tarde. O SDK TypeScript também o expõe como um campo direto na `SystemMessage` init; em Python está aninhado em `SystemMessage.data`.

256

257Quando você retoma, o contexto completo de voltas anteriores é restaurado: arquivos que foram lidos, análise que foi realizada e ações que foram tomadas. Você também pode bifurcar uma sessão para ramificar em uma abordagem diferente sem modificar a original.

258

259Veja [Gerenciamento de sessão](/pt/agent-sdk/sessions) para o guia completo em padrões de retomada, continuação e bifurcação.

260

261<Note>

262 Em Python, `ClaudeSDKClient` lida com IDs de sessão automaticamente em múltiplas chamadas. Veja a [referência do SDK Python](/pt/agent-sdk/python#choosing-between-query-and-claudesdkclient) para detalhes.

263</Note>

264

265## Lidar com o resultado

266

267Quando o loop termina, a `ResultMessage` informa o que aconteceu e fornece a saída. O campo `subtype` (disponível em ambos os SDKs) é a forma principal de verificar o estado de término.

268

269| Subtipo de resultado | O que aconteceu | Campo `result` disponível? |

270| :------------------------------------ | :----------------------------------------------------------------------------- | :------------------------: |

271| `success` | Claude terminou a tarefa normalmente | Sim |

272| `error_max_turns` | Atingiu o limite de `maxTurns` antes de terminar | Não |

273| `error_max_budget_usd` | Atingiu o limite de `maxBudgetUsd` antes de terminar | Não |

274| `error_during_execution` | Um erro interrompeu o loop (por exemplo, falha de API ou requisição cancelada) | Não |

275| `error_max_structured_output_retries` | Validação de saída estruturada falhou após o limite de tentativas configurado | Não |

276

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

278

279O 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.

280

281## Hooks

282

283[Hooks](/pt/agent-sdk/hooks) são callbacks que disparam em pontos específicos do loop: antes de uma ferramenta ser executada, depois que retorna, quando o agente termina e assim por diante. Alguns hooks comumente usados são:

284

285| Hook | Quando dispara | Usos comuns |

286| :------------------------------- | :--------------------------------------- | :------------------------------------------------- |

287| `PreToolUse` | Antes de uma ferramenta ser executada | Validar entradas, bloquear comandos perigosos |

288| `PostToolUse` | Depois que uma ferramenta retorna | Auditar saídas, acionar efeitos colaterais |

289| `UserPromptSubmit` | Quando um prompt é enviado | Injetar contexto adicional em prompts |

290| `Stop` | Quando o agente termina | Validar o resultado, salvar estado da sessão |

291| `SubagentStart` / `SubagentStop` | Quando um subagente é gerado ou completa | Rastrear e agregar resultados de tarefas paralelas |

292| `PreCompact` | Antes da compactação de contexto | Arquivar transcrição completa antes de resumir |

293

294Hooks são executados no processo de sua aplicação, não dentro da janela de contexto do agente, então não consomem contexto. Hooks também podem interromper o loop: um hook `PreToolUse` que rejeita uma chamada de ferramenta impede sua execução, e Claude recebe a mensagem de rejeição em vez disso.

295

296Ambos os SDKs suportam todos os eventos acima. O SDK TypeScript inclui eventos adicionais que Python ainda não suporta. Veja [Controlar execução com hooks](/pt/agent-sdk/hooks) para a lista completa de eventos, disponibilidade por SDK e a API de callback completa.

297

298## Juntar tudo

299

300Este 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.

301

302<CodeGroup>

303 ```python Python theme={null}

304 import asyncio

305 from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage

306

307

308 async def run_agent():

309 session_id = None

310

311 async for message in query(

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

313 options=ClaudeAgentOptions(

314 allowed_tools=[

315 "Read",

316 "Edit",

317 "Bash",

318 "Glob",

319 "Grep",

320 ], # Listing tools here auto-approves them (no prompting)

321 setting_sources=[

322 "project"

323 ], # Load CLAUDE.md, skills, hooks from current directory

324 max_turns=30, # Prevent runaway sessions

325 effort="high", # Thorough reasoning for complex debugging

326 ),

327 ):

328 # Handle the final result

329 if isinstance(message, ResultMessage):

330 session_id = message.session_id # Save for potential resumption

331

332 if message.subtype == "success":

333 print(f"Done: {message.result}")

334 elif message.subtype == "error_max_turns":

335 # Agent ran out of turns. Resume with a higher limit.

336 print(f"Hit turn limit. Resume session {session_id} to continue.")

337 elif message.subtype == "error_max_budget_usd":

338 print("Hit budget limit.")

339 else:

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

341 if message.total_cost_usd is not None:

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

343

344

345 asyncio.run(run_agent())

346 ```

347

348 ```typescript TypeScript theme={null}

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

350

351 let sessionId: string | undefined;

352

353 for await (const message of query({

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

355 options: {

356 allowedTools: ["Read", "Edit", "Bash", "Glob", "Grep"], // Listing tools here auto-approves them (no prompting)

357 settingSources: ["project"], // Load CLAUDE.md, skills, hooks from current directory

358 maxTurns: 30, // Prevent runaway sessions

359 effort: "high" // Thorough reasoning for complex debugging

360 }

361 })) {

362 // Save the session ID to resume later if needed

363 if (message.type === "system" && message.subtype === "init") {

364 sessionId = message.session_id;

365 }

366

367 // Handle the final result

368 if (message.type === "result") {

369 if (message.subtype === "success") {

370 console.log(`Done: ${message.result}`);

371 } else if (message.subtype === "error_max_turns") {

372 // Agent ran out of turns. Resume with a higher limit.

373 console.log(`Hit turn limit. Resume session ${sessionId} to continue.`);

374 } else if (message.subtype === "error_max_budget_usd") {

375 console.log("Hit budget limit.");

376 } else {

377 console.log(`Stopped: ${message.subtype}`);

378 }

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

380 }

381 }

382 ```

383</CodeGroup>

384

385## Próximos passos

386

387Agora que você entende o loop, aqui está para onde ir dependendo do que você está construindo:

388

389* **Ainda não executou um agente?** Comece com o [quickstart](/pt/agent-sdk/quickstart) para obter o SDK instalado e ver um exemplo completo sendo executado de ponta a ponta.

390* **Pronto para conectar ao seu projeto?** [Carregue CLAUDE.md, skills e hooks do sistema de arquivos](/pt/agent-sdk/claude-code-features) para que o agente siga suas convenções de projeto automaticamente.

391* **Construindo uma UI interativa?** Habilite [streaming](/pt/agent-sdk/streaming-output) para mostrar texto ao vivo e chamadas de ferramentas conforme o loop é executado.

392* **Precisa de controle mais apertado sobre o que o agente pode fazer?** Bloqueie o acesso a ferramentas com [permissões](/pt/agent-sdk/permissions) e use [hooks](/pt/agent-sdk/hooks) para auditar, bloquear ou transformar chamadas de ferramentas antes de serem executadas.

393* **Executando tarefas longas ou caras?** Descarregue trabalho isolado para [subagentes](/pt/agent-sdk/subagents) para manter seu contexto principal enxuto.

394

395Para a imagem conceitual mais ampla do loop agente (não específica do SDK), veja [Como o Claude Code funciona](/pt/how-claude-code-works).

agent-sdk/hooks.md +11 −11

Details

236Seu callback retorna um objeto com duas categorias de campos:236Seu callback retorna um objeto com duas categorias de campos:

237 237

238* **Campos de nível superior** controlam a conversa: `systemMessage` injeta uma mensagem na conversa visível ao modelo, e `continue` (`continue_` em Python) determina se o agente continua executando após este hook.238* **Campos de nível superior** controlam a conversa: `systemMessage` injeta uma mensagem na conversa visível ao modelo, e `continue` (`continue_` em Python) determina se o agente continua executando após este hook.

239* **`hookSpecificOutput`** controla a operação atual. Os campos dentro dependem do tipo de evento de hook. Para hooks `PreToolUse`, é aqui que você define `permissionDecision` (`"allow"`, `"deny"` ou `"ask"`), `permissionDecisionReason` e `updatedInput`. No SDK TypeScript, `permissionDecision` também aceita `"defer"` para encerrar a consulta e [retomar depois](/pt/hooks#defer-a-tool-call-for-later); este valor não está disponível no SDK Python. Para hooks `PostToolUse`, você pode definir `additionalContext` para anexar informações ao resultado da ferramenta.239* **`hookSpecificOutput`** controla a operação atual. Os campos dentro dependem do tipo de evento de hook. Para hooks `PreToolUse`, é aqui que você define `permissionDecision` (`"allow"`, `"deny"` ou `"ask"`), `permissionDecisionReason` e `updatedInput`. No SDK TypeScript, `permissionDecision` também aceita `"defer"` para encerrar a consulta e [retomar depois](/pt/hooks#defer-a-tool-call-for-later); este valor não está disponível no SDK Python. Para hooks `PostToolUse`, você pode definir `additionalContext` para anexar informações ao resultado da ferramenta, ou `updatedToolOutput` para substituir completamente a saída da ferramenta antes de Claude vê-la.

240 240

241Retorne `{}` para permitir a operação sem alterações. Hooks de callback do SDK usam o mesmo formato de saída JSON que [hooks de comando shell do Claude Code](/pt/hooks#json-output), que documenta cada campo e opção específica do evento. Para as definições de tipo do SDK, veja as referências do SDK [TypeScript](/pt/agent-sdk/typescript#sync-hook-json-output) e [Python](/pt/agent-sdk/python#sync-hook-json-output).241Retorne `{}` para permitir a operação sem alterações. Hooks de callback do SDK usam o mesmo formato de saída JSON que [hooks de comando shell do Claude Code](/pt/hooks#json-output), que documenta cada campo e opção específica do evento. Para as definições de tipo do SDK, veja as referências do SDK [TypeScript](/pt/agent-sdk/typescript#sync-hook-json-output) e [Python](/pt/agent-sdk/python#sync-hook-json-output).

242 242

417 ```417 ```

418</CodeGroup>418</CodeGroup>

419 419

420### Encadear múltiplos hooks420### Registrar múltiplos hooks

421 421

422Hooks são executados na ordem em que aparecem no array. Mantenha cada hook focado em uma única responsabilidade e encadeie múltiplos hooks para lógica complexa:422Quando um evento é disparado, todos os hooks correspondentes são executados em paralelo. Para decisões de permissão, o resultado mais restritivo vence: um único `deny` bloqueia a chamada de ferramenta independentemente do que os outros hooks retornam. Como a ordem de conclusão é não-determinística, escreva cada hook para agir independentemente em vez de depender de outro hook ter sido executado primeiro.

423

424O exemplo abaixo registra três verificações independentes para cada chamada de ferramenta:

423 425

424<CodeGroup>426<CodeGroup>

425 ```python Python theme={null}427 ```python Python theme={null}

426 options = ClaudeAgentOptions(428 options = ClaudeAgentOptions(

427 hooks={429 hooks={

428 "PreToolUse": [430 "PreToolUse": [

429 HookMatcher(hooks=[rate_limiter]), # First: check rate limits431 HookMatcher(hooks=[authorization_check]),

430 HookMatcher(hooks=[authorization_check]), # Second: verify permissions432 HookMatcher(hooks=[input_validator]),

431 HookMatcher(hooks=[input_sanitizer]), # Third: sanitize inputs433 HookMatcher(hooks=[audit_logger]),

432 HookMatcher(hooks=[audit_logger]), # Last: log the action

433 ]434 ]

434 }435 }

435 )436 )

439 const options = {440 const options = {

440 hooks: {441 hooks: {

441 PreToolUse: [442 PreToolUse: [

442 { hooks: [rateLimiter] }, // First: check rate limits443 { hooks: [authorizationCheck] },

443 { hooks: [authorizationCheck] }, // Second: verify permissions444 { hooks: [inputValidator] },

444 { hooks: [inputSanitizer] }, // Third: sanitize inputs445 { hooks: [auditLogger] }

445 { hooks: [auditLogger] } // Last: log the action

446 ]446 ]

447 }447 }

448 };448 };

agent-sdk/migration-guide.md +289 −0 created

Details

1> ## Documentation Index

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

5# Migrar para Claude Agent SDK

7> Guia para migrar os SDKs TypeScript e Python do Claude Code para o Claude Agent SDK

9## Visão Geral

11O Claude Code SDK foi renomeado para o **Claude Agent SDK** e sua documentação foi reorganizada. Esta mudança reflete as capacidades mais amplas do SDK para construir agentes de IA além de apenas tarefas de codificação.

13## O Que Mudou

15| Aspecto | Antigo | Novo |

16| :------------------------- | :-------------------------- | :------------------------------- |

17| **Nome do Pacote (TS/JS)** | `@anthropic-ai/claude-code` | `@anthropic-ai/claude-agent-sdk` |

18| **Pacote Python** | `claude-code-sdk` | `claude-agent-sdk` |

19| **Local da Documentação** | Documentação do Claude Code | API Guide → Seção Agent SDK |

21<Note>

22 **Mudanças na Documentação:** A documentação do Agent SDK foi movida da documentação do Claude Code para o API Guide em uma seção dedicada [Agent SDK](/pt/agent-sdk/overview). A documentação do Claude Code agora se concentra na ferramenta CLI e recursos de automação.

23</Note>

25## Etapas de Migração

27### Para Projetos TypeScript/JavaScript

29**1. Desinstale o pacote antigo:**

31```bash theme={null}

32npm uninstall @anthropic-ai/claude-code

33```

35**2. Instale o novo pacote:**

37```bash theme={null}

38npm install @anthropic-ai/claude-agent-sdk

39```

41**3. Atualize suas importações:**

43Altere todas as importações de `@anthropic-ai/claude-code` para `@anthropic-ai/claude-agent-sdk`:

45```typescript theme={null}

46// Antes

47import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-code";

49// Depois

50import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";

51```

53**4. Atualize as dependências do package.json:**

55Se você tiver o pacote listado em seu `package.json`, atualize-o:

57Antes:

59```json theme={null}

60{

61 "dependencies": {

62 "@anthropic-ai/claude-code": "^0.0.42"

63 }

64}

65```

67Depois:

69```json theme={null}

70{

71 "dependencies": {

72 "@anthropic-ai/claude-agent-sdk": "^0.2.0"

73 }

74}

75```

77Pronto! Nenhuma outra alteração de código é necessária.

79### Para Projetos Python

81**1. Desinstale o pacote antigo:**

83```bash theme={null}

84pip uninstall claude-code-sdk

85```

87**2. Instale o novo pacote:**

89```bash theme={null}

90pip install claude-agent-sdk

91```

93**3. Atualize suas importações:**

95Altere todas as importações de `claude_code_sdk` para `claude_agent_sdk`:

97```python theme={null}

98# Antes

99from claude_code_sdk import query, ClaudeCodeOptions

100

101# Depois

102from claude_agent_sdk import query, ClaudeAgentOptions

103```

104

105**4. Atualize os nomes dos tipos:**

106

107Altere `ClaudeCodeOptions` para `ClaudeAgentOptions`:

108

109```python theme={null}

110# Antes

111from claude_code_sdk import query, ClaudeCodeOptions

112

113options = ClaudeCodeOptions(model="claude-opus-4-7")

114

115# Depois

116from claude_agent_sdk import query, ClaudeAgentOptions

117

118options = ClaudeAgentOptions(model="claude-opus-4-7")

119```

120

121**5. Revise [mudanças significativas](#breaking-changes)**

122

123Faça as alterações de código necessárias para concluir a migração.

124

125## Mudanças significativas

126

127<Warning>

128 Para melhorar o isolamento e a configuração explícita, o Claude Agent SDK v0.1.0 introduz mudanças significativas para usuários que migram do Claude Code SDK. Revise esta seção cuidadosamente antes de migrar.

129</Warning>

130

131### Python: ClaudeCodeOptions renomeado para ClaudeAgentOptions

132

133**O que mudou:** O tipo `ClaudeCodeOptions` do SDK Python foi renomeado para `ClaudeAgentOptions`.

134

135**Migração:**

136

137```python theme={null}

138# ANTES (claude-code-sdk)

139from claude_code_sdk import query, ClaudeCodeOptions

140

141options = ClaudeCodeOptions(model="claude-opus-4-7", permission_mode="acceptEdits")

142

143# DEPOIS (claude-agent-sdk)

144from claude_agent_sdk import query, ClaudeAgentOptions

145

146options = ClaudeAgentOptions(model="claude-opus-4-7", permission_mode="acceptEdits")

147```

148

149**Por que isso mudou:** O nome do tipo agora corresponde à marca "Claude Agent SDK" e fornece consistência nas convenções de nomenclatura do SDK.

150

151### Prompt do sistema não é mais padrão

152

153**O que mudou:** O SDK não usa mais o prompt do sistema do Claude Code por padrão.

154

155**Migração:**

156

157<CodeGroup>

158 ```typescript TypeScript theme={null}

159 // ANTES (v0.0.x) - Usava o prompt do sistema do Claude Code por padrão

160 const result = query({ prompt: "Hello" });

161

162 // DEPOIS (v0.1.0) - Usa prompt do sistema mínimo por padrão

163 // Para obter o comportamento antigo, solicite explicitamente a predefinição do Claude Code:

164 const result = query({

165 prompt: "Hello",

166 options: {

167 systemPrompt: { type: "preset", preset: "claude_code" }

168 }

169 });

170

171 // Ou use um prompt do sistema personalizado:

172 const result = query({

173 prompt: "Hello",

174 options: {

175 systemPrompt: "You are a helpful coding assistant"

176 }

177 });

178 ```

179

180 ```python Python theme={null}

181 # ANTES (v0.0.x) - Usava o prompt do sistema do Claude Code por padrão

182 async for message in query(prompt="Hello"):

183 print(message)

184

185 # DEPOIS (v0.1.0) - Usa prompt do sistema mínimo por padrão

186 # Para obter o comportamento antigo, solicite explicitamente a predefinição do Claude Code:

187 from claude_agent_sdk import query, ClaudeAgentOptions

188

189 async for message in query(

190 prompt="Hello",

191 options=ClaudeAgentOptions(

192 system_prompt={"type": "preset", "preset": "claude_code"} # Use a predefinição

193 ),

194 ):

195 print(message)

196

197 # Ou use um prompt do sistema personalizado:

198 async for message in query(

199 prompt="Hello",

200 options=ClaudeAgentOptions(system_prompt="You are a helpful coding assistant"),

201 ):

202 print(message)

203 ```

204</CodeGroup>

205

206**Por que isso mudou:** Fornece melhor controle e isolamento para aplicações SDK. Você agora pode construir agentes com comportamento personalizado sem herdar as instruções focadas em CLI do Claude Code.

207

208### Padrão de fontes de configurações

209

210Este padrão foi brevemente alterado em v0.1.0 e depois revertido, portanto nenhuma ação de migração é necessária.

211

212**Comportamento atual:** Omitir `settingSources` em `query()` carrega configurações de usuário, projeto e sistema de arquivos local, correspondendo ao CLI. Isso inclui `~/.claude/settings.json`, `.claude/settings.json`, `.claude/settings.local.json`, arquivos CLAUDE.md e comandos personalizados.

213

214Para executar isolado das configurações do sistema de arquivos, passe uma matriz vazia:

215

216<CodeGroup>

217 ```typescript TypeScript theme={null}

218 const result = query({

219 prompt: "Hello",

220 options: {

221 settingSources: [] // Nenhuma configuração do sistema de arquivos carregada

222 }

223 });

224

225 // Ou carregue apenas fontes específicas:

226 const result = query({

227 prompt: "Hello",

228 options: {

229 settingSources: ["project"] // Apenas configurações do projeto

230 }

231 });

232 ```

233

234 ```python Python theme={null}

235 from claude_agent_sdk import query, ClaudeAgentOptions

236

237 async for message in query(

238 prompt="Hello",

239 options=ClaudeAgentOptions(setting_sources=[]), # Nenhuma configuração do sistema de arquivos carregada

240 ):

241 print(message)

242

243 # Ou carregue apenas fontes específicas:

244 async for message in query(

245 prompt="Hello",

246 options=ClaudeAgentOptions(

247 setting_sources=["project"] # Apenas configurações do projeto

248 ),

249 ):

250 print(message)

251 ```

252</CodeGroup>

253

254O isolamento é especialmente importante para pipelines CI/CD, aplicações implantadas, ambientes de teste e sistemas multi-tenant onde personalizações locais não devem vazar.

255

256<Note>

257 O SDK v0.1.0 brevemente padronizou para nenhuma configuração carregada; isso foi revertido em versões subsequentes. Python SDK 0.1.59 e anteriores tratavam uma lista vazia da mesma forma que omitir a opção, portanto atualize antes de confiar em `setting_sources=[]`. Veja [O que settingSources não controla](/pt/agent-sdk/claude-code-features#what-settingsources-does-not-control) para entradas que são lidas mesmo quando `settingSources` é `[]`.

258</Note>

259

260## Por Que a Renomeação?

261

262O Claude Code SDK foi originalmente projetado para tarefas de codificação, mas evoluiu para um framework poderoso para construir todos os tipos de agentes de IA. O novo nome "Claude Agent SDK" reflete melhor suas capacidades:

263

264* Construir agentes de negócios (assistentes jurídicos, consultores financeiros, suporte ao cliente)

265* Criar agentes de codificação especializados (bots SRE, revisores de segurança, agentes de revisão de código)

266* Desenvolver agentes personalizados para qualquer domínio com uso de ferramentas, integração MCP e muito mais

267

268## Obtendo Ajuda

269

270Se você encontrar algum problema durante a migração:

271

272**Para TypeScript/JavaScript:**

273

2741. Verifique se todas as importações foram atualizadas para usar `@anthropic-ai/claude-agent-sdk`

2752. Verifique se seu package.json tem o novo nome do pacote

2763. Execute `npm install` para garantir que as dependências sejam atualizadas

277

278**Para Python:**

279

2801. Verifique se todas as importações foram atualizadas para usar `claude_agent_sdk`

2812. Verifique se seu requirements.txt ou pyproject.toml tem o novo nome do pacote

2823. Execute `pip install claude-agent-sdk` para garantir que o pacote seja instalado

283

284## Próximas Etapas

285

286* Explore a [Visão Geral do Agent SDK](/pt/agent-sdk/overview) para aprender sobre os recursos disponíveis

287* Confira a [Referência do SDK TypeScript](/pt/agent-sdk/typescript) para documentação detalhada da API

288* Revise a [Referência do SDK Python](/pt/agent-sdk/python) para documentação específica do Python

289* Aprenda sobre [Ferramentas Personalizadas](/pt/agent-sdk/custom-tools) e [Integração MCP](/pt/agent-sdk/mcp)

agent-sdk/permissions.md +242 −0 created

Details

1> ## Documentation Index

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

5# Configurar permissões

7> Controle como seu agente usa ferramentas com modos de permissão, hooks e regras declarativas de permitir/negar.

9O Claude Agent SDK fornece controles de permissão para gerenciar como Claude usa ferramentas. Use modos de permissão e regras para definir o que é permitido automaticamente, e o callback [`canUseTool`](/pt/agent-sdk/user-input) para lidar com tudo mais em tempo de execução.

11<Note>

12 Esta página cobre modos de permissão e regras. Para construir fluxos de aprovação interativos onde os usuários aprovam ou negam solicitações de ferramentas em tempo de execução, consulte [Lidar com aprovações e entrada do usuário](/pt/agent-sdk/user-input).

13</Note>

15## Como as permissões são avaliadas

17Quando Claude solicita uma ferramenta, o SDK verifica as permissões nesta ordem:

19<Steps>

20 <Step title="Hooks">

21 Execute [hooks](/pt/agent-sdk/hooks) primeiro. Um hook pode negar a chamada completamente ou passá-la adiante. Um hook que retorna `allow` não ignora as regras de negar e perguntar abaixo; essas são avaliadas independentemente do resultado do hook.

22 </Step>

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

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

26 </Step>

28 <Step title="Modo de permissão">

29 Aplique o [modo de permissão](#permission-modes) ativo. `bypassPermissions` aprova tudo que chega a este passo. `acceptEdits` aprova operações de arquivo. Outros modos passam adiante.

30 </Step>

32 <Step title="Regras de permissão">

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

34 </Step>

36 <Step title="Callback canUseTool">

37 Se não for resolvido por nenhum dos anteriores, chame seu callback [`canUseTool`](/pt/agent-sdk/user-input) para uma decisão. No modo `dontAsk`, este passo é ignorado e a ferramenta é negada.

38 </Step>

39</Steps>

41<img src="https://mintcdn.com/claude-code/FEspvVUyRuaWjm0s/images/agent-sdk/permissions-flow.svg?fit=max&auto=format&n=FEspvVUyRuaWjm0s&q=85&s=a1759b0cf4541281a9fdd8f5348228e8" alt="Diagrama de fluxo de avaliação de permissões" width="920" height="260" data-path="images/agent-sdk/permissions-flow.svg" />

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

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

46* **Callback canUseTool:** solicite aprovação dos usuários em tempo de execução. Consulte [Lidar com aprovações e entrada do usuário](/pt/agent-sdk/user-input).

48## Regras de permitir e negar

50`allowed_tools` e `disallowed_tools` (TypeScript: `allowedTools` / `disallowedTools`) adicionam entradas às listas de regras de permitir e negar no fluxo de avaliação acima. Eles controlam se uma chamada de ferramenta é aprovada, não se a ferramenta está disponível para Claude.

52| Opção | Efeito |

53| :------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------- |

54| `allowed_tools=["Read", "Grep"]` | `Read` e `Grep` são auto-aprovadas. Ferramentas não listadas aqui ainda existem e passam para o modo de permissão e `canUseTool`. |

55| `disallowed_tools=["Bash"]` | `Bash` é sempre negado. Regras de negação são verificadas primeiro e se mantêm em todos os modos de permissão, incluindo `bypassPermissions`. |

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

59```typescript theme={null}

60const options = {

61 allowedTools: ["Read", "Glob", "Grep"],

62 permissionMode: "dontAsk"

63};

64```

66<Warning>

67 **`allowed_tools` não restringe `bypassPermissions`.** `allowed_tools` apenas pré-aprova as ferramentas que você lista. Ferramentas não listadas não são correspondidas por nenhuma regra de permitir e passam para o modo de permissão, onde `bypassPermissions` as aprova. Definir `allowed_tools=["Read"]` junto com `permission_mode="bypassPermissions"` ainda aprova todas as ferramentas, incluindo `Bash`, `Write` e `Edit`. Se você precisar de `bypassPermissions` mas quiser que ferramentas específicas sejam bloqueadas, use `disallowed_tools`.

68</Warning>

70Você também pode configurar regras de permitir, negar e perguntar declarativamente em `.claude/settings.json`. Essas regras são lidas quando a fonte de configuração `project` está habilitada, o que é o padrão para opções `query()`. Se você definir `setting_sources` (TypeScript: `settingSources`) explicitamente, inclua `"project"` para que se apliquem. Consulte [Configurações de permissão](/pt/settings#permission-settings) para a sintaxe das regras.

72## Modos de permissão

74Os modos de permissão fornecem controle global sobre como Claude usa ferramentas. Você pode definir o modo de permissão ao chamar `query()` ou alterá-lo dinamicamente durante sessões de streaming.

76### Modos disponíveis

78O SDK suporta estes modos de permissão:

80| Modo | Descrição | Comportamento da ferramenta |

81| :------------------------- | :----------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

82| `default` | Comportamento de permissão padrão | Sem auto-aprovações; ferramentas não correspondidas acionam seu callback `canUseTool` |

83| `dontAsk` | Negar em vez de solicitar | Qualquer coisa não pré-aprovada por `allowed_tools` ou regras é negada; `canUseTool` nunca é chamado |

84| `acceptEdits` | Auto-aceitar edições de arquivo | Edições de arquivo e [operações de sistema de arquivos](#accept-edits-mode-acceptedits) (`mkdir`, `rm`, `mv`, etc.) são automaticamente aprovadas |

85| `bypassPermissions` | Ignorar todas as verificações de permissão | Todas as ferramentas são executadas sem solicitações de permissão (use com cuidado) |

86| `plan` | Modo de planejamento | Ferramentas somente leitura são executadas; Claude analisa e planeja sem editar seus arquivos de origem |

87| `auto` (Apenas TypeScript) | Aprovações classificadas por modelo | Um classificador de modelo aprova ou nega cada chamada de ferramenta. Consulte [Modo Auto](/pt/permission-modes#eliminate-prompts-with-auto-mode) para disponibilidade |

89<Warning>

90 **Herança de subagentos:** Quando o pai usa `bypassPermissions`, `acceptEdits` ou `auto`, todos os subagentos herdam esse modo e ele não pode ser substituído por subagentos. Subagentos podem ter prompts de sistema diferentes e comportamento menos restrito do que seu agente principal, portanto herdar `bypassPermissions` concede a eles acesso completo e autônomo ao sistema sem nenhum prompt de aprovação.

91</Warning>

93### Definir modo de permissão

95Você pode definir o modo de permissão uma vez ao iniciar uma consulta, ou alterá-lo dinamicamente enquanto a sessão está ativa.

97<Tabs>

98 <Tab title="No momento da consulta">

99 Passe `permission_mode` (Python) ou `permissionMode` (TypeScript) ao criar uma consulta. Este modo se aplica para toda a sessão, a menos que seja alterado dinamicamente.

100

101 <CodeGroup>

102 ```python Python theme={null}

103 import asyncio

104 from claude_agent_sdk import query, ClaudeAgentOptions

105

106

107 async def main():

108 async for message in query(

109 prompt="Help me refactor this code",

110 options=ClaudeAgentOptions(

111 permission_mode="default", # Set the mode here

112 ),

113 ):

114 if hasattr(message, "result"):

115 print(message.result)

116

117

118 asyncio.run(main())

119 ```

120

121 ```typescript TypeScript theme={null}

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

123

124 async function main() {

125 for await (const message of query({

126 prompt: "Help me refactor this code",

127 options: {

128 permissionMode: "default" // Set the mode here

129 }

130 })) {

131 if ("result" in message) {

132 console.log(message.result);

133 }

134 }

135 }

136

137 main();

138 ```

139 </CodeGroup>

140 </Tab>

141

142 <Tab title="Durante streaming">

143 Chame `set_permission_mode()` (Python) ou `setPermissionMode()` (TypeScript) para alterar o modo no meio da sessão. O novo modo entra em vigor imediatamente para todas as solicitações de ferramentas subsequentes. Isso permite que você comece restritivo e afrouxe as permissões conforme a confiança aumenta, por exemplo, alternando para `acceptEdits` após revisar a abordagem inicial de Claude.

144

145 <CodeGroup>

146 ```python Python theme={null}

147 import asyncio

148 from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions

149

150

151 async def main():

152 async with ClaudeSDKClient(

153 options=ClaudeAgentOptions(

154 permission_mode="default", # Start in default mode

155 )

156 ) as client:

157 await client.query("Help me refactor this code")

158

159 # Change mode dynamically mid-session

160 await client.set_permission_mode("acceptEdits")

161

162 # Process messages with the new permission mode

163 async for message in client.receive_response():

164 if hasattr(message, "result"):

165 print(message.result)

166

167

168 asyncio.run(main())

169 ```

170

171 ```typescript TypeScript theme={null}

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

173

174 async function main() {

175 const q = query({

176 prompt: "Help me refactor this code",

177 options: {

178 permissionMode: "default" // Start in default mode

179 }

180 });

181

182 // Change mode dynamically mid-session

183 await q.setPermissionMode("acceptEdits");

184

185 // Process messages with the new permission mode

186 for await (const message of q) {

187 if ("result" in message) {

188 console.log(message.result);

189 }

190 }

191 }

192

193 main();

194 ```

195 </CodeGroup>

196 </Tab>

197</Tabs>

198

199### Detalhes do modo

200

201#### Modo aceitar edições (`acceptEdits`)

202

203Auto-aprova operações de arquivo para que Claude possa editar código sem solicitar. Outras ferramentas (como comandos Bash que não são operações de sistema de arquivos) ainda requerem permissões normais.

204

205**Operações auto-aprovadas:**

206

207* Edições de arquivo (ferramentas Edit, Write)

208* Comandos de sistema de arquivos: `mkdir`, `touch`, `rm`, `rmdir`, `mv`, `cp`, `sed`

209

210Ambos se aplicam apenas a caminhos dentro do diretório de trabalho ou `additionalDirectories`. Caminhos fora desse escopo e gravações em caminhos protegidos ainda solicitam.

211

212**Use quando:** você confia nas edições de Claude e quer iteração mais rápida, como durante prototipagem ou ao trabalhar em um diretório isolado.

213

214#### Modo não perguntar (`dontAsk`)

215

216Converte qualquer solicitação de permissão em uma negação. Ferramentas pré-aprovadas por `allowed_tools`, regras de permitir em `settings.json` ou um hook são executadas normalmente. Tudo mais é negado sem chamar `canUseTool`.

217

218**Use quando:** você quer uma superfície de ferramenta fixa e explícita para um agente sem cabeça e prefere uma negação dura sobre confiança silenciosa em `canUseTool` estar ausente.

219

220#### Modo ignorar permissões (`bypassPermissions`)

221

222Auto-aprova todos os usos de ferramentas sem solicitações. Hooks ainda são executados e podem bloquear operações se necessário.

223

224<Warning>

225 Use com extrema cautela. Claude tem acesso completo ao sistema neste modo. Use apenas em ambientes controlados onde você confia em todas as operações possíveis.

226

227 `allowed_tools` não restringe este modo. Todas as ferramentas são aprovadas, não apenas as que você listou. Regras de negação (`disallowed_tools`), regras explícitas de `ask` e hooks são avaliados antes da verificação do modo e ainda podem bloquear uma ferramenta.

228</Warning>

229

230#### Modo plano (`plan`)

231

232Restringe Claude a ferramentas somente leitura. Claude pode ler arquivos e executar comandos shell somente leitura para explorar a base de código, mas não edita seus arquivos de origem. Claude pode usar `AskUserQuestion` para esclarecer requisitos antes de finalizar o plano. Consulte [Lidar com aprovações e entrada do usuário](/pt/agent-sdk/user-input#handle-clarifying-questions) para lidar com essas solicitações.

233

234**Use quando:** você quer que Claude proponha mudanças sem executá-las, como durante revisão de código ou quando você precisa aprovar mudanças antes que sejam feitas.

235

236## Recursos relacionados

237

238Para os outros passos no fluxo de avaliação de permissões:

239

240* [Lidar com aprovações e entrada do usuário](/pt/agent-sdk/user-input): solicitações de aprovação interativa e perguntas de esclarecimento

241* [Guia de hooks](/pt/agent-sdk/hooks): execute código personalizado em pontos-chave do ciclo de vida do agente

242* [Regras de permissão](/pt/settings#permission-settings): regras declarativas de permitir/negar em `settings.json`

agent-sdk/python.md +38 −36

Details

113#### Parâmetros113#### Parâmetros

114 114

116| :------------- | :----------------------------------------------- | :--------------------------------------------------------------------- |116| :------------- | :---------------------------------------------- | :--------------------------------------------------------------------- |

117| `name` | `str` | Identificador único para a ferramenta |117| `name` | `str` | Identificador único para a ferramenta |

118| `description` | `str` | Descrição legível por humanos do que a ferramenta faz |118| `description` | `str` | Descrição legível por humanos do que a ferramenta faz |

121 121

122#### Opções de schema de entrada122#### Opções de schema de entrada

123 123

269| `cwd` | `str \| None` | Diretório de trabalho para a sessão |269| `cwd` | `str \| None` | Diretório de trabalho para a sessão |

270| `tag` | `str \| None` | Tag de sessão definida pelo usuário (veja [`tag_session()`](#tag-session)) |270| `tag` | `str \| None` | Tag de sessão definida pelo usuário (veja [`tag_session()`](#tag_session)) |

272 272

273#### Exemplo273#### Exemplo

345 345

346Retorna [`SDKSessionInfo`](#return-type-sdk-session-info), ou `None` se a sessão não for encontrada.346Retorna [`SDKSessionInfo`](#return-type-sdksessioninfo), ou `None` se a sessão não for encontrada.

347 347

348#### Exemplo348#### Exemplo

349 349

381 381

382#### Exemplo382#### Exemplo

383 383

384Renomeie a sessão mais recente para que seja mais fácil encontrá-la depois. O novo título aparece em [`SDKSessionInfo.custom_title`](#return-type-sdk-session-info) em leituras subsequentes.384Renomeie a sessão mais recente para que seja mais fácil encontrá-la depois. O novo título aparece em [`SDKSessionInfo.custom_title`](#return-type-sdksessioninfo) em leituras subsequentes.

385 385

386```python theme={null}386```python theme={null}

387from claude_agent_sdk import list_sessions, rename_session387from claude_agent_sdk import list_sessions, rename_session

478| `rewind_files(user_message_id)` | Restaura arquivos para seu estado na mensagem de usuário especificada. Requer `enable_file_checkpointing=True`. Veja [File checkpointing](/pt/agent-sdk/file-checkpointing) |478| `rewind_files(user_message_id)` | Restaura arquivos para seu estado na mensagem de usuário especificada. Requer `enable_file_checkpointing=True`. Veja [File checkpointing](/pt/agent-sdk/file-checkpointing) |

479| `get_mcp_status()` | Obtém o status de todos os servidores MCP configurados. Retorna [`McpStatusResponse`](#mcp-status-response) |479| `get_mcp_status()` | Obtém o status de todos os servidores MCP configurados. Retorna [`McpStatusResponse`](#mcpstatusresponse) |

481| `toggle_mcp_server(server_name, enabled)` | Ativa ou desativa um servidor MCP no meio da sessão. Desativar remove suas ferramentas |481| `toggle_mcp_server(server_name, enabled)` | Ativa ou desativa um servidor MCP no meio da sessão. Desativar remove suas ferramentas |

482| `stop_task(task_id)` | Para uma tarefa de fundo em execução. Uma [`TaskNotificationMessage`](#task-notification-message) com status `"stopped"` segue no fluxo de mensagens |482| `stop_task(task_id)` | Para uma tarefa de fundo em execução. Uma [`TaskNotificationMessage`](#tasknotificationmessage) com status `"stopped"` segue no fluxo de mensagens |

485 485

791 effort: Literal["low", "medium", "high", "max"] | None = None791 effort: Literal["low", "medium", "high", "max"] | None = None

792 enable_file_checkpointing: bool = False792 enable_file_checkpointing: bool = False

793 session_store: SessionStore | None = None793 session_store: SessionStore | None = None

794 session_store_flush: SessionStoreFlushMode = "batched"

794```795```

795 796

797| :---------------------------- | :------------------------------------------------------------------------------------- | :--------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |798| :---------------------------- | :------------------------------------------------------------------------------------ | :--------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

798| `tools` | `list[str] \| ToolsPreset \| None` | `None` | Configuração de ferramentas. Use `{"type": "preset", "preset": "claude_code"}` para as ferramentas padrão do Claude Code |799| `tools` | `list[str] \| ToolsPreset \| None` | `None` | Configuração de ferramentas. Use `{"type": "preset", "preset": "claude_code"}` para as ferramentas padrão do Claude Code |

799| `allowed_tools` | `list[str]` | `[]` | Ferramentas para auto-aprovar sem solicitar. Isso não restringe Claude apenas a essas ferramentas; ferramentas não listadas caem através de `permission_mode` e `can_use_tool`. Use `disallowed_tools` para bloquear ferramentas. Veja [Permissions](/pt/agent-sdk/permissions#allow-and-deny-rules) |800| `allowed_tools` | `list[str]` | `[]` | Ferramentas para auto-aprovar sem solicitar. Isso não restringe Claude apenas a essas ferramentas; ferramentas não listadas caem através de `permission_mode` e `can_use_tool`. Use `disallowed_tools` para bloquear ferramentas. Veja [Permissions](/pt/agent-sdk/permissions#allow-and-deny-rules) |

800| `system_prompt` | `str \| SystemPromptPreset \| None` | `None` | Configuração de prompt do sistema. Passe uma string para prompt personalizado, ou use `{"type": "preset", "preset": "claude_code"}` para o prompt do sistema do Claude Code. Adicione `"append"` para estender o preset |801| `system_prompt` | `str \| SystemPromptPreset \| None` | `None` | Configuração de prompt do sistema. Passe uma string para prompt personalizado, ou use `{"type": "preset", "preset": "claude_code"}` para o prompt do sistema do Claude Code. Adicione `"append"` para estender o preset |

812| `output_format` | `dict[str, Any] \| None` | `None` | Formato de saída para respostas estruturadas (por exemplo, `{"type": "json_schema", "schema": {...}}`). Veja [Structured outputs](/pt/agent-sdk/structured-outputs) para detalhes |813| `output_format` | `dict[str, Any] \| None` | `None` | Formato de saída para respostas estruturadas (por exemplo, `{"type": "json_schema", "schema": {...}}`). Veja [Structured outputs](/pt/agent-sdk/structured-outputs) para detalhes |

814| `cwd` | `str \| Path \| None` | `None` | Diretório de trabalho atual |815| `cwd` | `str \| Path \| None` | `None` | Diretório de trabalho atual |

831| `setting_sources` | `list[SettingSource] \| None` | `None` (CLI defaults: all sources) | Controle quais configurações do sistema de arquivos carregar. Passe `[]` para desabilitar configurações de usuário, projeto e local. Configurações de política gerenciada carregam independentemente. Veja [Use Claude Code features](/pt/agent-sdk/claude-code-features#what-settingsources-does-not-control) |832| `setting_sources` | `list[SettingSource] \| None` | `None` (CLI defaults: all sources) | Controle quais configurações do sistema de arquivos carregar. Passe `[]` para desabilitar configurações de usuário, projeto e local. Configurações de política gerenciada carregam independentemente. Veja [Use Claude Code features](/pt/agent-sdk/claude-code-features#what-settingsources-does-not-control) |

835| `session_store` | [`SessionStore`](/pt/agent-sdk/session-storage#the-session-store-interface) ` \| None` | `None` | Espelhe transcrições de sessão para um backend externo para que qualquer host possa retomá-las. Veja [Persist sessions to external storage](/pt/agent-sdk/session-storage) |836| `session_store` | [`SessionStore`](/pt/agent-sdk/session-storage#the-sessionstore-interface) ` \| None` | `None` | Espelhe transcrições de sessão para um backend externo para que qualquer host possa retomá-las. Veja [Persist sessions to external storage](/pt/agent-sdk/session-storage) |

837| `session_store_flush` | `Literal["batched", "eager"]` | `"batched"` | Quando fazer flush das entradas de transcrição espelhadas para `session_store`. `"batched"` faz flush uma vez por turno ou quando o buffer enche; `"eager"` dispara um flush de fundo após cada frame. Ignorado quando `session_store` é `None` |

836 838

837### `OutputFormat`839### `OutputFormat`

838 840

1031| `maxTurns` | Não | Número máximo de turnos agênticos antes do agente parar |1033| `maxTurns` | Não | Número máximo de turnos agênticos antes do agente parar |

1032| `background` | Não | Execute este agente como uma tarefa de fundo não bloqueante quando invocado |1034| `background` | Não | Execute este agente como uma tarefa de fundo não bloqueante quando invocado |

1033| `effort` | Não | Nível de esforço de raciocínio para este agente. Aceita um nível nomeado ou um inteiro |1035| `effort` | Não | Nível de esforço de raciocínio para este agente. Aceita um nível nomeado ou um inteiro |

1034| `permissionMode` | Não | Modo de permissão para execução de ferramenta dentro deste agente. Veja [`PermissionMode`](#permission-mode) |1036| `permissionMode` | Não | Modo de permissão para execução de ferramenta dentro deste agente. Veja [`PermissionMode`](#permissionmode) |

1035 1037

1036<Note>1038<Note>

1037 Os nomes de campo `AgentDefinition` usam camelCase, como `disallowedTools`, `permissionMode` e `maxTurns`. Esses nomes mapeiam diretamente para o formato de fio compartilhado com o SDK TypeScript. Isso difere de `ClaudeAgentOptions`, que usa snake\_case Python para campos de nível superior equivalentes como `disallowed_tools` e `permission_mode`. Como `AgentDefinition` é uma dataclass, passar uma palavra-chave snake\_case levanta um `TypeError` no tempo de construção.1039 Os nomes de campo `AgentDefinition` usam camelCase, como `disallowedTools`, `permissionMode` e `maxTurns`. Esses nomes mapeiam diretamente para o formato de fio compartilhado com o SDK TypeScript. Isso difere de `ClaudeAgentOptions`, que usa snake\_case Python para campos de nível superior equivalentes como `disallowed_tools` e `permission_mode`. Como `AgentDefinition` é uma dataclass, passar uma palavra-chave snake\_case levanta um `TypeError` no tempo de construção.

1045PermissionMode = Literal[1047PermissionMode = Literal[

1046 "default", # Standard permission behavior1048 "default", # Standard permission behavior

1047 "acceptEdits", # Auto-accept file edits1049 "acceptEdits", # Auto-accept file edits

1048 "plan", # Planning mode - no execution1050 "plan", # Planning mode - read-only tools only

1049 "dontAsk", # Deny anything not pre-approved instead of prompting1051 "dontAsk", # Deny anything not pre-approved instead of prompting

1050 "bypassPermissions", # Bypass all permission checks (use with caution)1052 "bypassPermissions", # Bypass all permission checks (use with caution)

1051]1053]

1081```1083```

1082 1084

1084| :------------ | :----------------------- | :----------------------------------------------- |1086| :------------ | :----------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

1086| `suggestions` | `list[PermissionUpdate]` | Sugestões de atualização de permissão do CLI |1088| `suggestions` | `list[PermissionUpdate]` | Sugestões de atualização de permissão do CLI. Prompts Bash incluem uma sugestão com o destino `localSettings`, então retorná-la em `updated_permissions` escreve a regra em `.claude/settings.local.json` e persiste entre sessões. |

1087 1089

1088### `PermissionResult`1090### `PermissionResult`

1089 1091

1289 1291

1290### `McpServerStatusConfig`1292### `McpServerStatusConfig`

1291 1293

1292A configuração de um servidor MCP conforme relatado por [`get_mcp_status()`](#methods). Esta é a união de todas as variantes de transporte [`McpServerConfig`](#mcp-server-config) mais uma variante de saída apenas `claudeai-proxy` para servidores proxied através de claude.ai.1294A configuração de um servidor MCP conforme relatado por [`get_mcp_status()`](#methods). Esta é a união de todas as variantes de transporte [`McpServerConfig`](#mcpserverconfig) mais uma variante de saída apenas `claudeai-proxy` para servidores proxied através de claude.ai.

1293 1295

1294```python theme={null}1296```python theme={null}

1295McpServerStatusConfig = (1297McpServerStatusConfig = (

1301)1303)

1302```1304```

1303 1305

1304`McpSdkServerConfigStatus` é a forma serializável de [`McpSdkServerConfig`](#mcp-sdk-server-config) com apenas campos `type` (`"sdk"`) e `name` (`str`); a `instance` em processo é omitida. `McpClaudeAIProxyServerConfig` tem campos `type` (`"claudeai-proxy"`), `url` (`str`), e `id` (`str`).1306`McpSdkServerConfigStatus` é a forma serializável de [`McpSdkServerConfig`](#mcpsdkserverconfig) com apenas campos `type` (`"sdk"`) e `name` (`str`); a `instance` em processo é omitida. `McpClaudeAIProxyServerConfig` tem campos `type` (`"claudeai-proxy"`), `url` (`str`), e `id` (`str`).

1305 1307

1306### `McpStatusResponse`1308### `McpStatusResponse`

1307 1309

1314 1316

1315### `McpServerStatus`1317### `McpServerStatus`

1316 1318

1317Status de um servidor MCP conectado, contido em [`McpStatusResponse`](#mcp-status-response).1319Status de um servidor MCP conectado, contido em [`McpStatusResponse`](#mcpstatusresponse).

1318 1320

1319```python theme={null}1321```python theme={null}

1320class McpServerStatus(TypedDict):1322class McpServerStatus(TypedDict):

1328```1330```

1329 1331

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

1332| `name` | `str` | Nome do servidor |1334| `name` | `str` | Nome do servidor |

1333| `status` | `str` | Um de `"connected"`, `"failed"`, `"needs-auth"`, `"pending"`, ou `"disabled"` |1335| `status` | `str` | Um de `"connected"`, `"failed"`, `"needs-auth"`, `"pending"`, ou `"disabled"` |

1334| `serverInfo` | `dict` (opcional) | Nome e versão do servidor (`{"name": str, "version": str}`) |1336| `serverInfo` | `dict` (opcional) | Nome e versão do servidor (`{"name": str, "version": str}`) |

1336| `config` | [`McpServerStatusConfig`](#mcp-server-status-config) (opcional) | Configuração do servidor. Mesma forma que [`McpServerConfig`](#mcp-server-config) (stdio, SSE, HTTP, ou SDK), mais uma variante `claudeai-proxy` para servidores conectados através de claude.ai |1338| `config` | [`McpServerStatusConfig`](#mcpserverstatusconfig) (opcional) | Configuração do servidor. Mesma forma que [`McpServerConfig`](#mcpserverconfig) (stdio, SSE, HTTP, ou SDK), mais uma variante `claudeai-proxy` para servidores conectados através de claude.ai |

1339 1341

1416```1418```

1417 1419

1419| :------------------- | :------------------------------------------------------------- | :------------------------------------------------------------------------------------- |1421| :------------------- | :----------------------------------------------------------- | :------------------------------------------------------------------------------------ |

1421| `model` | `str` | Modelo que gerou a resposta |1423| `model` | `str` | Modelo que gerou a resposta |

1426 1428

1427### `AssistantMessageError`1429### `AssistantMessageError`

1481| `cache_creation_input_tokens` | `int` | Tokens usados para criar novas entradas de cache. |1483| `cache_creation_input_tokens` | `int` | Tokens usados para criar novas entradas de cache. |

1482| `cache_read_input_tokens` | `int` | Tokens lidos de entradas de cache existentes. |1484| `cache_read_input_tokens` | `int` | Tokens lidos de entradas de cache existentes. |

1483 1485

1484O dict `model_usage` mapeia nomes de modelo para uso por modelo. As chaves do dict interno usam camelCase porque o valor é passado sem modificação do processo CLI subjacente, correspondendo ao tipo TypeScript [`ModelUsage`](/pt/agent-sdk/typescript#model-usage):1486O dict `model_usage` mapeia nomes de modelo para uso por modelo. As chaves do dict interno usam camelCase porque o valor é passado sem modificação do processo CLI subjacente, correspondendo ao tipo TypeScript [`ModelUsage`](/pt/agent-sdk/typescript#modelusage):

1485 1487

1487| -------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |1489| -------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |

1490| `cacheReadInputTokens` | `int` | Tokens de leitura de cache para este modelo. |1492| `cacheReadInputTokens` | `int` | Tokens de leitura de cache para este modelo. |

1491| `cacheCreationInputTokens` | `int` | Tokens de criação de cache para este modelo. |1493| `cacheCreationInputTokens` | `int` | Tokens de criação de cache para este modelo. |

1492| `webSearchRequests` | `int` | Solicitações de busca na web feitas por este modelo. |1494| `webSearchRequests` | `int` | Solicitações de busca na web feitas por este modelo. |

1493| `costUSD` | `float` | Custo estimado em USD para este modelo, computado no lado do cliente. Veja [Track cost and usage](/pt/agent-sdk/cost-tracking) para ressalvas de faturamento. |1495| `costUSD` | `float` | Custo estimado em USD para este modelo, computado no lado do cliente. Veja [Rastrear custo e uso](/pt/agent-sdk/cost-tracking) para ressalvas de faturamento. |

1494| `contextWindow` | `int` | Tamanho da janela de contexto para este modelo. |1496| `contextWindow` | `int` | Tamanho da janela de contexto para este modelo. |

1495| `maxOutputTokens` | `int` | Limite máximo de token de saída para este modelo. |1497| `maxOutputTokens` | `int` | Limite máximo de token de saída para este modelo. |

1496 1498

1527```1529```

1528 1530

1530| :---------------- | :---------------------------------- | :----------------------------- |1532| :---------------- | :-------------------------------- | :----------------------------- |

1532| `uuid` | `str` | Identificador único de evento |1534| `uuid` | `str` | Identificador único de evento |

1533| `session_id` | `str` | Identificador de sessão |1535| `session_id` | `str` | Identificador de sessão |

1534 1536

1535### `RateLimitInfo`1537### `RateLimitInfo`

1536 1538

1537Estado de limite de taxa carregado por [`RateLimitEvent`](#rate-limit-event).1539Estado de limite de taxa carregado por [`RateLimitEvent`](#ratelimitevent).

1538 1540

1539```python theme={null}1541```python theme={null}

1540RateLimitStatus = Literal["allowed", "allowed_warning", "rejected"]1542RateLimitStatus = Literal["allowed", "allowed_warning", "rejected"]

1812 1814

1813Parâmetros:1815Parâmetros:

1814 1816

1815* `input`: Entrada de hook fortemente tipada com uniões discriminadas baseadas em `hook_event_name` (veja [`HookInput`](#hook-input))1817* `input`: Entrada de hook fortemente tipada com uniões discriminadas baseadas em `hook_event_name` (veja [`HookInput`](#hookinput))

1816* `tool_use_id`: Identificador de uso de ferramenta opcional (para hooks relacionados a ferramentas)1818* `tool_use_id`: Identificador de uso de ferramenta opcional (para hooks relacionados a ferramentas)

1817* `context`: Contexto de hook com informações adicionais1819* `context`: Contexto de hook com informações adicionais

1818 1820

1819Retorna um [`HookJSONOutput`](#hook-json-output) que pode conter:1821Retorna um [`HookJSONOutput`](#hookjsonoutput) que pode conter:

1820 1822

1821* `decision`: `"block"` para bloquear a ação1823* `decision`: `"block"` para bloquear a ação

1822* `systemMessage`: Mensagem do sistema a adicionar à transcrição1824* `systemMessage`: Mensagem do sistema a adicionar à transcrição

3109```3111```

3110 3112

3112| :-------------------------- | :------------------------------------------------------ | :------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |3114| :-------------------------- | :---------------------------------------------------- | :------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

3116| `allowUnsandboxedCommands` | `bool` | `True` | Permite que o modelo solicite executar comandos fora do sandbox. Quando `True`, o modelo pode definir `dangerouslyDisableSandbox` na entrada da ferramenta, que volta para o [sistema de permissões](#permissions-fallback-for-unsandboxed-commands) |3118| `allowUnsandboxedCommands` | `bool` | `True` | Permite que o modelo solicite executar comandos fora do sandbox. Quando `True`, o modelo pode definir `dangerouslyDisableSandbox` na entrada da ferramenta, que volta para o [sistema de permissões](#permissions-fallback-for-unsandboxed-commands) |

3120 3122

3121#### Exemplo de uso3123#### Exemplo de uso

agent-sdk/streaming-output.md +396 −0 created

Details

1> ## Documentation Index

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

5# Transmitir respostas em tempo real

7> Obtenha respostas em tempo real do Agent SDK conforme o texto e as chamadas de ferramentas são transmitidas

9Por padrão, o Agent SDK produz objetos `AssistantMessage` completos após Claude terminar de gerar cada resposta. Para receber atualizações incrementais conforme o texto e as chamadas de ferramentas são geradas, ative o streaming de mensagens parciais definindo `include_partial_messages` (Python) ou `includePartialMessages` (TypeScript) como `true` nas suas opções.

11<Tip>

12 Esta página aborda o streaming de saída (recebimento de tokens em tempo real). Para modos de entrada (como você envia mensagens), consulte [Enviar mensagens para agentes](/pt/agent-sdk/streaming-vs-single-mode). Você também pode [transmitir respostas usando o Agent SDK via CLI](/pt/headless).

13</Tip>

15## Ativar streaming de saída

17Para ativar o streaming, defina `include_partial_messages` (Python) ou `includePartialMessages` (TypeScript) como `true` nas suas opções. Isso faz com que o SDK produza mensagens `StreamEvent` contendo eventos brutos da API conforme chegam, além das mensagens `AssistantMessage` e `ResultMessage` usuais.

19Seu código então precisa:

211. Verificar o tipo de cada mensagem para distinguir `StreamEvent` de outros tipos de mensagem

222. Para `StreamEvent`, extrair o campo `event` e verificar seu `type`

233. Procurar por eventos `content_block_delta` onde `delta.type` é `text_delta`, que contêm os chunks de texto reais

25O exemplo abaixo ativa o streaming e imprime chunks de texto conforme chegam. Observe as verificações de tipo aninhadas: primeiro para `StreamEvent`, depois para `content_block_delta`, depois para `text_delta`:

27<CodeGroup>

28 ```python Python theme={null}

29 from claude_agent_sdk import query, ClaudeAgentOptions

30 from claude_agent_sdk.types import StreamEvent

31 import asyncio

34 async def stream_response():

35 options = ClaudeAgentOptions(

36 include_partial_messages=True,

37 allowed_tools=["Bash", "Read"],

38 )

40 async for message in query(prompt="List the files in my project", options=options):

41 if isinstance(message, StreamEvent):

42 event = message.event

43 if event.get("type") == "content_block_delta":

44 delta = event.get("delta", {})

45 if delta.get("type") == "text_delta":

46 print(delta.get("text", ""), end="", flush=True)

49 asyncio.run(stream_response())

50 ```

52 ```typescript TypeScript theme={null}

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

55 for await (const message of query({

56 prompt: "List the files in my project",

57 options: {

58 includePartialMessages: true,

59 allowedTools: ["Bash", "Read"]

60 }

61 })) {

62 if (message.type === "stream_event") {

63 const event = message.event;

64 if (event.type === "content_block_delta") {

65 if (event.delta.type === "text_delta") {

66 process.stdout.write(event.delta.text);

67 }

68 }

69 }

70 }

71 ```

72</CodeGroup>

74## Referência de StreamEvent

76Quando mensagens parciais estão ativadas, você recebe eventos brutos de streaming da Claude API encapsulados em um objeto. O tipo tem nomes diferentes em cada SDK:

78* **Python**: `StreamEvent` (importar de `claude_agent_sdk.types`)

79* **TypeScript**: `SDKPartialAssistantMessage` com `type: 'stream_event'`

81Ambos contêm eventos brutos da Claude API, não texto acumulado. Você precisa extrair e acumular deltas de texto você mesmo. Aqui está a estrutura de cada tipo:

83<CodeGroup>

84 ```python Python theme={null}

85 @dataclass

86 class StreamEvent:

87 uuid: str # Unique identifier for this event

88 session_id: str # Session identifier

89 event: dict[str, Any] # The raw Claude API stream event

90 parent_tool_use_id: str | None # Parent tool ID if from a subagent

91 ```

93 ```typescript TypeScript theme={null}

94 type SDKPartialAssistantMessage = {

95 type: "stream_event";

96 event: BetaRawMessageStreamEvent; // From Anthropic SDK

97 parent_tool_use_id: string | null;

98 uuid: UUID;

99 session_id: string;

100 };

101 ```

102</CodeGroup>

103

104O campo `event` contém o evento de streaming bruto da [Claude API](https://platform.claude.com/docs/en/build-with-claude/streaming#event-types). Os tipos de evento comuns incluem:

105

106| Tipo de Evento | Descrição |

107| :-------------------- | :--------------------------------------------------------------- |

108| `message_start` | Início de uma nova mensagem |

109| `content_block_start` | Início de um novo bloco de conteúdo (texto ou uso de ferramenta) |

110| `content_block_delta` | Atualização incremental do conteúdo |

111| `content_block_stop` | Fim de um bloco de conteúdo |

112| `message_delta` | Atualizações no nível da mensagem (motivo de parada, uso) |

113| `message_stop` | Fim da mensagem |

114

115## Fluxo de mensagens

116

117Com mensagens parciais ativadas, você recebe mensagens nesta ordem:

118

119```text theme={null}

120StreamEvent (message_start)

121StreamEvent (content_block_start) - text block

122StreamEvent (content_block_delta) - text chunks...

123StreamEvent (content_block_stop)

124StreamEvent (content_block_start) - tool_use block

125StreamEvent (content_block_delta) - tool input chunks...

126StreamEvent (content_block_stop)

127StreamEvent (message_delta)

128StreamEvent (message_stop)

129AssistantMessage - complete message with all content

130... tool executes ...

131... more streaming events for next turn ...

132ResultMessage - final result

133```

134

135Sem mensagens parciais ativadas (`include_partial_messages` em Python, `includePartialMessages` em TypeScript), você recebe todos os tipos de mensagem exceto `StreamEvent`. Os tipos comuns incluem `SystemMessage` (inicialização de sessão), `AssistantMessage` (respostas completas), `ResultMessage` (resultado final) e uma mensagem de limite compacta indicando quando o histórico de conversa foi compactado (`SDKCompactBoundaryMessage` em TypeScript; `SystemMessage` com subtipo `"compact_boundary"` em Python).

136

137## Transmitir respostas de texto

138

139Para exibir o texto conforme é gerado, procure por eventos `content_block_delta` onde `delta.type` é `text_delta`. Estes contêm os chunks de texto incrementais. O exemplo abaixo imprime cada chunk conforme chega:

140

141<CodeGroup>

142 ```python Python theme={null}

143 from claude_agent_sdk import query, ClaudeAgentOptions

144 from claude_agent_sdk.types import StreamEvent

145 import asyncio

146

147

148 async def stream_text():

149 options = ClaudeAgentOptions(include_partial_messages=True)

150

151 async for message in query(prompt="Explain how databases work", options=options):

152 if isinstance(message, StreamEvent):

153 event = message.event

154 if event.get("type") == "content_block_delta":

155 delta = event.get("delta", {})

156 if delta.get("type") == "text_delta":

157 # Print each text chunk as it arrives

158 print(delta.get("text", ""), end="", flush=True)

159

160 print() # Final newline

161

162

163 asyncio.run(stream_text())

164 ```

165

166 ```typescript TypeScript theme={null}

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

168

169 for await (const message of query({

170 prompt: "Explain how databases work",

171 options: { includePartialMessages: true }

172 })) {

173 if (message.type === "stream_event") {

174 const event = message.event;

175 if (event.type === "content_block_delta" && event.delta.type === "text_delta") {

176 process.stdout.write(event.delta.text);

177 }

178 }

179 }

180

181 console.log(); // Final newline

182 ```

183</CodeGroup>

184

185## Transmitir chamadas de ferramentas

186

187As chamadas de ferramentas também são transmitidas incrementalmente. Você pode rastrear quando as ferramentas começam, receber sua entrada conforme é gerada e ver quando são concluídas. O exemplo abaixo rastreia a ferramenta atual sendo chamada e acumula a entrada JSON conforme é transmitida. Ele usa três tipos de evento:

188

189* `content_block_start`: ferramenta começa

190* `content_block_delta` com `input_json_delta`: chunks de entrada chegam

191* `content_block_stop`: chamada de ferramenta concluída

192

193<CodeGroup>

194 ```python Python theme={null}

195 from claude_agent_sdk import query, ClaudeAgentOptions

196 from claude_agent_sdk.types import StreamEvent

197 import asyncio

198

199

200 async def stream_tool_calls():

201 options = ClaudeAgentOptions(

202 include_partial_messages=True,

203 allowed_tools=["Read", "Bash"],

204 )

205

206 # Track the current tool and accumulate its input JSON

207 current_tool = None

208 tool_input = ""

209

210 async for message in query(prompt="Read the README.md file", options=options):

211 if isinstance(message, StreamEvent):

212 event = message.event

213 event_type = event.get("type")

214

215 if event_type == "content_block_start":

216 # New tool call is starting

217 content_block = event.get("content_block", {})

218 if content_block.get("type") == "tool_use":

219 current_tool = content_block.get("name")

220 tool_input = ""

221 print(f"Starting tool: {current_tool}")

222

223 elif event_type == "content_block_delta":

224 delta = event.get("delta", {})

225 if delta.get("type") == "input_json_delta":

226 # Accumulate JSON input as it streams in

227 chunk = delta.get("partial_json", "")

228 tool_input += chunk

229 print(f" Input chunk: {chunk}")

230

231 elif event_type == "content_block_stop":

232 # Tool call complete - show final input

233 if current_tool:

234 print(f"Tool {current_tool} called with: {tool_input}")

235 current_tool = None

236

237

238 asyncio.run(stream_tool_calls())

239 ```

240

241 ```typescript TypeScript theme={null}

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

243

244 // Track the current tool and accumulate its input JSON

245 let currentTool: string | null = null;

246 let toolInput = "";

247

248 for await (const message of query({

249 prompt: "Read the README.md file",

250 options: {

251 includePartialMessages: true,

252 allowedTools: ["Read", "Bash"]

253 }

254 })) {

255 if (message.type === "stream_event") {

256 const event = message.event;

257

258 if (event.type === "content_block_start") {

259 // New tool call is starting

260 if (event.content_block.type === "tool_use") {

261 currentTool = event.content_block.name;

262 toolInput = "";

263 console.log(`Starting tool: ${currentTool}`);

264 }

265 } else if (event.type === "content_block_delta") {

266 if (event.delta.type === "input_json_delta") {

267 // Accumulate JSON input as it streams in

268 const chunk = event.delta.partial_json;

269 toolInput += chunk;

270 console.log(` Input chunk: ${chunk}`);

271 }

272 } else if (event.type === "content_block_stop") {

273 // Tool call complete - show final input

274 if (currentTool) {

275 console.log(`Tool ${currentTool} called with: ${toolInput}`);

276 currentTool = null;

277 }

278 }

279 }

280 }

281 ```

282</CodeGroup>

283

284## Construir uma interface de usuário de streaming

285

286Este exemplo combina streaming de texto e ferramentas em uma interface coerente. Ele rastreia se o agente está executando uma ferramenta (usando um sinalizador `in_tool`) para mostrar indicadores de status como `[Using Read...]` enquanto as ferramentas são executadas. O texto é transmitido normalmente quando não está em uma ferramenta, e a conclusão da ferramenta dispara uma mensagem "done". Este padrão é útil para interfaces de chat que precisam mostrar progresso durante tarefas de agente em várias etapas.

287

288<CodeGroup>

289 ```python Python theme={null}

290 from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage

291 from claude_agent_sdk.types import StreamEvent

292 import asyncio

293 import sys

294

295

296 async def streaming_ui():

297 options = ClaudeAgentOptions(

298 include_partial_messages=True,

299 allowed_tools=["Read", "Bash", "Grep"],

300 )

301

302 # Track whether we're currently in a tool call

303 in_tool = False

304

305 async for message in query(

306 prompt="Find all TODO comments in the codebase", options=options

307 ):

308 if isinstance(message, StreamEvent):

309 event = message.event

310 event_type = event.get("type")

311

312 if event_type == "content_block_start":

313 content_block = event.get("content_block", {})

314 if content_block.get("type") == "tool_use":

315 # Tool call is starting - show status indicator

316 tool_name = content_block.get("name")

317 print(f"\n[Using {tool_name}...]", end="", flush=True)

318 in_tool = True

319

320 elif event_type == "content_block_delta":

321 delta = event.get("delta", {})

322 # Only stream text when not executing a tool

323 if delta.get("type") == "text_delta" and not in_tool:

324 sys.stdout.write(delta.get("text", ""))

325 sys.stdout.flush()

326

327 elif event_type == "content_block_stop":

328 if in_tool:

329 # Tool call finished

330 print(" done", flush=True)

331 in_tool = False

332

333 elif isinstance(message, ResultMessage):

334 # Agent finished all work

335 print(f"\n\n--- Complete ---")

336

337

338 asyncio.run(streaming_ui())

339 ```

340

341 ```typescript TypeScript theme={null}

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

343

344 // Track whether we're currently in a tool call

345 let inTool = false;

346

347 for await (const message of query({

348 prompt: "Find all TODO comments in the codebase",

349 options: {

350 includePartialMessages: true,

351 allowedTools: ["Read", "Bash", "Grep"]

352 }

353 })) {

354 if (message.type === "stream_event") {

355 const event = message.event;

356

357 if (event.type === "content_block_start") {

358 if (event.content_block.type === "tool_use") {

359 // Tool call is starting - show status indicator

360 process.stdout.write(`\n[Using ${event.content_block.name}...]`);

361 inTool = true;

362 }

363 } else if (event.type === "content_block_delta") {

364 // Only stream text when not executing a tool

365 if (event.delta.type === "text_delta" && !inTool) {

366 process.stdout.write(event.delta.text);

367 }

368 } else if (event.type === "content_block_stop") {

369 if (inTool) {

370 // Tool call finished

371 console.log(" done");

372 inTool = false;

373 }

374 }

375 } else if (message.type === "result") {

376 // Agent finished all work

377 console.log("\n\n--- Complete ---");

378 }

379 }

380 ```

381</CodeGroup>

382

383## Limitações conhecidas

384

385Alguns recursos do SDK são incompatíveis com streaming:

386

387* **Extended thinking**: quando você define explicitamente `max_thinking_tokens` (Python) ou `maxThinkingTokens` (TypeScript), mensagens `StreamEvent` não são emitidas. Você receberá apenas mensagens completas após cada turno. Observe que o thinking é desativado por padrão no SDK, portanto o streaming funciona a menos que você o ative.

388* **Structured output**: o resultado JSON aparece apenas no `ResultMessage.structured_output` final, não como deltas de streaming. Consulte [structured outputs](/pt/agent-sdk/structured-outputs) para detalhes.

389

390## Próximas etapas

391

392Agora que você pode transmitir texto e chamadas de ferramentas em tempo real, explore estes tópicos relacionados:

393

394* [Interactive vs one-shot queries](/pt/agent-sdk/streaming-vs-single-mode): escolha entre modos de entrada para seu caso de uso

395* [Structured outputs](/pt/agent-sdk/structured-outputs): obtenha respostas JSON digitadas do agente

396* [Permissions](/pt/agent-sdk/permissions): controle quais ferramentas o agente pode usar

agent-sdk/todo-tracking.md +189 −0 created

Details

1> ## Documentation Index

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

5# Listas de Tarefas

7> Rastreie e exiba tarefas usando o Claude Agent SDK para gerenciamento organizado de 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.

11### Ciclo de Vida das Tarefas

13As tarefas seguem um ciclo de vida previsível:

151. **Criadas** como `pending` quando as tarefas são identificadas

162. **Ativadas** para `in_progress` quando o trabalho começa

173. **Concluídas** quando a tarefa termina com sucesso

184. **Removidas** quando todas as tarefas em um grupo são concluídas

20### Quando as Tarefas São Usadas

22O SDK cria automaticamente tarefas para:

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

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

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

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

29## Exemplos

31### Monitorando Mudanças de Tarefas

33<CodeGroup>

34 ```typescript TypeScript theme={null}

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

37 for await (const message of query({

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

39 options: { maxTurns: 15 }

40 })) {

41 // Todo updates are reflected in the message stream

42 if (message.type === "assistant") {

43 for (const block of message.message.content) {

44 if (block.type === "tool_use" && block.name === "TodoWrite") {

45 const todos = block.input.todos;

47 console.log("Todo Status Update:");

48 todos.forEach((todo, index) => {

49 const status =

50 todo.status === "completed" ? "✅" : todo.status === "in_progress" ? "🔧" : "❌";

51 console.log(`${index + 1}. ${status} ${todo.content}`);

52 });

53 }

54 }

55 }

56 }

57 ```

59 ```python Python theme={null}

60 from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ToolUseBlock

62 async for message in query(

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

64 options=ClaudeAgentOptions(max_turns=15),

65 ):

66 # Todo updates are reflected in the message stream

67 if isinstance(message, AssistantMessage):

68 for block in message.content:

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

70 todos = block.input["todos"]

72 print("Todo Status Update:")

73 for i, todo in enumerate(todos):

74 status = (

75 "✅"

76 if todo["status"] == "completed"

77 else "🔧"

78 if todo["status"] == "in_progress"

79 else "❌"

80 )

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

82 ```

83</CodeGroup>

85### Exibição de Progresso em Tempo Real

87<CodeGroup>

88 ```typescript TypeScript theme={null}

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

91 class TodoTracker {

92 private todos: any[] = [];

94 displayProgress() {

95 if (this.todos.length === 0) return;

97 const completed = this.todos.filter((t) => t.status === "completed").length;

98 const inProgress = this.todos.filter((t) => t.status === "in_progress").length;

99 const total = this.todos.length;

100

101 console.log(`\nProgress: ${completed}/${total} completed`);

102 console.log(`Currently working on: ${inProgress} task(s)\n`);

103

104 this.todos.forEach((todo, index) => {

105 const icon =

106 todo.status === "completed" ? "✅" : todo.status === "in_progress" ? "🔧" : "❌";

107 const text = todo.status === "in_progress" ? todo.activeForm : todo.content;

108 console.log(`${index + 1}. ${icon} ${text}`);

109 });

110 }

111

112 async trackQuery(prompt: string) {

113 for await (const message of query({

114 prompt,

115 options: { maxTurns: 20 }

116 })) {

117 if (message.type === "assistant") {

118 for (const block of message.message.content) {

119 if (block.type === "tool_use" && block.name === "TodoWrite") {

120 this.todos = block.input.todos;

121 this.displayProgress();

122 }

123 }

124 }

125 }

126 }

127 }

128

129 // Usage

130 const tracker = new TodoTracker();

131 await tracker.trackQuery("Build a complete authentication system with todos");

132 ```

133

134 ```python Python theme={null}

135 from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ToolUseBlock

136 from typing import List, Dict

137

138

139 class TodoTracker:

140 def __init__(self):

141 self.todos: List[Dict] = []

142

143 def display_progress(self):

144 if not self.todos:

145 return

146

147 completed = len([t for t in self.todos if t["status"] == "completed"])

148 in_progress = len([t for t in self.todos if t["status"] == "in_progress"])

149 total = len(self.todos)

150

151 print(f"\nProgress: {completed}/{total} completed")

152 print(f"Currently working on: {in_progress} task(s)\n")

153

154 for i, todo in enumerate(self.todos):

155 icon = (

156 "✅"

157 if todo["status"] == "completed"

158 else "🔧"

159 if todo["status"] == "in_progress"

160 else "❌"

161 )

162 text = (

163 todo["activeForm"]

164 if todo["status"] == "in_progress"

165 else todo["content"]

166 )

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

168

169 async def track_query(self, prompt: str):

170 async for message in query(prompt=prompt, options=ClaudeAgentOptions(max_turns=20)):

171 if isinstance(message, AssistantMessage):

172 for block in message.content:

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

174 self.todos = block.input["todos"]

175 self.display_progress()

176

177

178 # Usage

179 tracker = TodoTracker()

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

181 ```

182</CodeGroup>

183

184## Documentação Relacionada

185

186* [Referência do SDK TypeScript](/pt/agent-sdk/typescript)

187* [Referência do SDK Python](/pt/agent-sdk/python)

188* [Streaming vs Modo Único](/pt/agent-sdk/streaming-vs-single-mode)

189* [Ferramentas Personalizadas](/pt/agent-sdk/custom-tools)

agent-sdk/typescript.md +31 −31

Details

41#### Parâmetros41#### Parâmetros

42 42

~~44| :-------- | :---------------------------------------------------------------- | :---------------------------------------------------------------------------------- |~~44| :-------- | :--------------------------------------------------------------- | :---------------------------------------------------------------------------------- |

47 47

48#### Retorna48#### Retorna

49 49

~~50Retorna um objeto [`Query`](#query-object) que estende `AsyncGenerator<`[`SDKMessage`](#sdk-message)`, void>` com métodos adicionais.~~50Retorna um objeto [`Query`](#query-object) que estende `AsyncGenerator<`[`SDKMessage`](#sdkmessage)`, void>` com métodos adicionais.

51 51

52### `startup()`52### `startup()`

53 53

54Pré-aquece o subprocesso CLI gerando-o e completando o handshake de inicialização antes de um prompt estar disponível. O handle [`WarmQuery`](#warm-query) retornado aceita um prompt depois e o escreve em um processo já pronto, então a primeira chamada `query()` é resolvida sem pagar o custo de geração e inicialização do subprocesso inline.54Pré-aquece o subprocesso CLI gerando-o e completando o handshake de inicialização antes de um prompt estar disponível. O handle [`WarmQuery`](#warmquery) retornado aceita um prompt depois e o escreve em um processo já pronto, então a primeira chamada `query()` é resolvida sem pagar o custo de geração e inicialização do subprocesso inline.

55 55

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

57function startup(params?: {57function startup(params?: {

69 69

70#### Retorna70#### Retorna

71 71

~~72Retorna uma `Promise<`[`WarmQuery`](#warm-query)`>` que é resolvida assim que o subprocesso é gerado e completa seu handshake de inicialização.~~72Retorna uma `Promise<`[`WarmQuery`](#warmquery)`>` que é resolvida assim que o subprocesso é gerado e completa seu handshake de inicialização.

73 73

74#### Exemplo74#### Exemplo

75 75

104#### Parâmetros104#### Parâmetros

105 105

107| :------------ | :------------------------------------------------------------------ | :---------------------------------------------------------------------------------- |107| :------------ | :---------------------------------------------------------------- | :---------------------------------------------------------------------------------- |

112| `extras` | `{ annotations?: `[`ToolAnnotations`](#tool-annotations)` }` | Anotações MCP opcionais da ferramenta fornecendo dicas comportamentais aos clientes |112| `extras` | `{ annotations?: `[`ToolAnnotations`](#toolannotations)` }` | Anotações MCP opcionais da ferramenta fornecendo dicas comportamentais aos clientes |

113 113

114#### `ToolAnnotations`114#### `ToolAnnotations`

115 115

191 191

192#### Exemplo192#### Exemplo

272 272

273Retorna [`SDKSessionInfo`](#return-type-sdk-session-info), ou `undefined` se a sessão não for encontrada.273Retorna [`SDKSessionInfo`](#return-type-sdksessioninfo), ou `undefined` se a sessão não for encontrada.

274 274

275### `renameSession()`275### `renameSession()`

276 276

328| `allowedTools` | `string[]` | `[]` | Ferramentas para auto-aprovar sem solicitar. Isso não restringe Claude apenas a essas ferramentas; ferramentas não listadas caem em `permissionMode` e `canUseTool`. Use `disallowedTools` para bloquear ferramentas. Veja [Permissões](/pt/agent-sdk/permissions#allow-and-deny-rules) |328| `allowedTools` | `string[]` | `[]` | Ferramentas para auto-aprovar sem solicitar. Isso não restringe Claude apenas a essas ferramentas; ferramentas não listadas caem em `permissionMode` e `canUseTool`. Use `disallowedTools` para bloquear ferramentas. Veja [Permissões](/pt/agent-sdk/permissions#allow-and-deny-rules) |

341| `extraArgs` | `Record<string, string \| null>` | `{}` | Argumentos adicionais |341| `extraArgs` | `Record<string, string \| null>` | `{}` | Argumentos adicionais |

344| `hooks` | `Partial<Record<`[`HookEvent`](#hook-event)`, `[`HookCallbackMatcher`](#hook-callback-matcher)`[]>>` | `{}` | Callbacks de hook para eventos |344| `hooks` | `Partial<Record<`[`HookEvent`](#hookevent)`, `[`HookCallbackMatcher`](#hookcallbackmatcher)`[]>>` | `{}` | Callbacks de hook para eventos |

346| `maxBudgetUsd` | `number` | `undefined` | Parar a consulta quando a estimativa de custo do lado do cliente atingir este valor em USD. Comparado com a mesma estimativa que `total_cost_usd`; veja [Rastrear custo e uso](/pt/agent-sdk/cost-tracking) para ressalvas de precisão |346| `maxBudgetUsd` | `number` | `undefined` | Parar a consulta quando a estimativa de custo do lado do cliente atingir este valor em USD. Comparado com a mesma estimativa que `total_cost_usd`; veja [Rastrear custo e uso](/pt/agent-sdk/cost-tracking) para ressalvas de precisão |

349| `mcpServers` | `Record<string, [`McpServerConfig`](#mcp-server-config)>` | `{}` | Configurações de servidor MCP |349| `mcpServers` | `Record<string, [`McpServerConfig`](#mcpserverconfig)>` | `{}` | Configurações de servidor MCP |

351| `outputFormat` | `{ type: 'json_schema', schema: JSONSchema }` | `undefined` | Defina o formato de saída para resultados de agente. Veja [Structured outputs](/pt/agent-sdk/structured-outputs) para detalhes |351| `outputFormat` | `{ type: 'json_schema', schema: JSONSchema }` | `undefined` | Defina o formato de saída para resultados de agente. Veja [Structured outputs](/pt/agent-sdk/structured-outputs) para detalhes |

352| `pathToClaudeCodeExecutable` | `string` | Auto-resolvido do binário nativo agrupado | Caminho para executável Claude Code. Apenas necessário se dependências opcionais foram puladas durante a instalação ou sua plataforma não está no conjunto suportado |352| `pathToClaudeCodeExecutable` | `string` | Auto-resolvido do binário nativo agrupado | Caminho para executável Claude Code. Apenas necessário se dependências opcionais foram puladas durante a instalação ou sua plataforma não está no conjunto suportado |

362| `sessionStore` | [`SessionStore`](/pt/agent-sdk/session-storage#the-session-store-interface) | `undefined` | Espelhar transcrições de sessão para um backend externo para que qualquer host possa retomá-las. Veja [Persist sessions to external storage](/pt/agent-sdk/session-storage) |362| `sessionStore` | [`SessionStore`](/pt/agent-sdk/session-storage#the-sessionstore-interface) | `undefined` | Espelhar transcrições de sessão para um backend externo para que qualquer host possa retomá-las. Veja [Persist sessions to external storage](/pt/agent-sdk/session-storage) |

363| `settingSources` | [`SettingSource`](#setting-source)`[]` | Padrões da CLI (todas as fontes) | Controle quais configurações do sistema de arquivos carregar. Passe `[]` para desativar configurações de usuário, projeto e local. Configurações de política gerenciada carregam independentemente. Veja [Use Claude Code features](/pt/agent-sdk/claude-code-features#what-settingsources-does-not-control) |363| `settingSources` | [`SettingSource`](#settingsource)`[]` | Padrões da CLI (todas as fontes) | Controle quais configurações do sistema de arquivos carregar. Passe `[]` para desativar configurações de usuário, projeto e local. Configurações de política gerenciada carregam independentemente. Veja [Use Claude Code features](/pt/agent-sdk/claude-code-features#what-settingsources-does-not-control) |

364| `spawnClaudeCodeProcess` | `(options: SpawnOptions) => SpawnedProcess` | `undefined` | Função personalizada para gerar o processo Claude Code. Use para executar Claude Code em VMs, contêineres ou ambientes remotos |364| `spawnClaudeCodeProcess` | `(options: SpawnOptions) => SpawnedProcess` | `undefined` | Função personalizada para gerar o processo Claude Code. Use para executar Claude Code em VMs, contêineres ou ambientes remotos |

367| `systemPrompt` | `string \| { type: 'preset'; preset: 'claude_code'; append?: string; excludeDynamicSections?: boolean }` | `undefined` (prompt mínimo) | Configuração de prompt do sistema. Passe uma string para prompt personalizado, ou `{ type: 'preset', preset: 'claude_code' }` para usar o prompt do sistema do Claude Code. Ao usar a forma de objeto preset, adicione `append` para estendê-lo com instruções adicionais, e defina `excludeDynamicSections: true` para mover contexto por sessão para a primeira mensagem do usuário para [melhor reutilização de cache de prompt entre máquinas](/pt/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines) |367| `systemPrompt` | `string \| { type: 'preset'; preset: 'claude_code'; append?: string; excludeDynamicSections?: boolean }` | `undefined` (prompt mínimo) | Configuração de prompt do sistema. Passe uma string para prompt personalizado, ou `{ type: 'preset', preset: 'claude_code' }` para usar o prompt do sistema do Claude Code. Ao usar a forma de objeto preset, adicione `append` para estendê-lo com instruções adicionais, e defina `excludeDynamicSections: true` para mover contexto por sessão para a primeira mensagem do usuário para [melhor reutilização de cache de prompt entre máquinas](/pt/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines) |

368| `thinking` | [`ThinkingConfig`](#thinking-config) | `{ type: 'adaptive' }` para modelos suportados | Controla o comportamento de pensamento/raciocínio do Claude. Veja [`ThinkingConfig`](#thinking-config) para opções |368| `thinking` | [`ThinkingConfig`](#thinkingconfig) | `{ type: 'adaptive' }` para modelos suportados | Controla o comportamento de pensamento/raciocínio do Claude. Veja [`ThinkingConfig`](#thinkingconfig) para opções |

370| `tools` | `string[] \| { type: 'preset'; preset: 'claude_code' }` | `undefined` | Configuração de ferramenta. Passe um array de nomes de ferramentas ou use o preset para obter as ferramentas padrão do Claude Code |370| `tools` | `string[] \| { type: 'preset'; preset: 'claude_code' }` | `undefined` | Configuração de ferramenta. Passe um array de nomes de ferramentas ou use o preset para obter as ferramentas padrão do Claude Code |

371 371

372### Objeto `Query`372### Objeto `Query`

410| `initializationResult()` | Retorna o resultado de inicialização completo incluindo comandos suportados, modelos, informações de conta e configuração de estilo de saída |410| `initializationResult()` | Retorna o resultado de inicialização completo incluindo comandos suportados, modelos, informações de conta e configuração de estilo de saída |

493| `background` | Não | Executar este agente como uma tarefa de fundo não-bloqueante quando invocado |493| `background` | Não | Executar este agente como uma tarefa de fundo não-bloqueante quando invocado |

494| `memory` | Não | Fonte de memória para este agente: `'user'`, `'project'`, ou `'local'` |494| `memory` | Não | Fonte de memória para este agente: `'user'`, `'project'`, ou `'local'` |

495| `effort` | Não | Nível de esforço de raciocínio para este agente. Aceita um nível nomeado ou um inteiro |495| `effort` | Não | Nível de esforço de raciocínio para este agente. Aceita um nível nomeado ou um inteiro |

496| `permissionMode` | Não | Modo de permissão para execução de ferramenta dentro deste agente. Veja [`PermissionMode`](#permission-mode) |496| `permissionMode` | Não | Modo de permissão para execução de ferramenta dentro deste agente. Veja [`PermissionMode`](#permissionmode) |

497| `criticalSystemReminder_EXPERIMENTAL` | Não | Experimental: Lembrete crítico adicionado ao prompt do sistema |497| `criticalSystemReminder_EXPERIMENTAL` | Não | Experimental: Lembrete crítico adicionado ao prompt do sistema |

498 498

499### `AgentMcpServerSpec`499### `AgentMcpServerSpec`

626 | "default" // Comportamento de permissão padrão626 | "default" // Comportamento de permissão padrão

627 | "acceptEdits" // Auto-aceitar edições de arquivo627 | "acceptEdits" // Auto-aceitar edições de arquivo

628 | "bypassPermissions" // Bypass de todas as verificações de permissão628 | "bypassPermissions" // Bypass de todas as verificações de permissão

629 | "plan" // Modo de planejamento - sem execução629 | "plan" // Modo de planejamento - ferramentas somente leitura

630 | "dontAsk" // Não solicitar permissões, negar se não pré-aprovado630 | "dontAsk" // Não solicitar permissões, negar se não pré-aprovado

631 | "auto"; // Usar um classificador de modelo para aprovar ou negar cada chamada de ferramenta631 | "auto"; // Usar um classificador de modelo para aprovar ou negar cada chamada de ferramenta

632```632```

651```651```

652 652

654| :--------------- | :------------------------------------------- | :-------------------------------------------------------------------------------------------------------- |654| :--------------- | :------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

656| `suggestions` | [`PermissionUpdate`](#permission-update)`[]` | Atualizações de permissão sugeridas para que o usuário não seja solicitado novamente para esta ferramenta |656| `suggestions` | [`PermissionUpdate`](#permissionupdate)`[]` | Atualizações de permissão sugeridas para que o usuário não seja solicitado novamente para esta ferramenta. Prompts de Bash incluem uma sugestão com o destino `localSettings` [destination](#permissionupdatedestination), então retorná-la em `updatedPermissions` escreve a regra em `.claude/settings.local.json` e persiste entre sessões. |

2379 | McpClaudeAIProxyServerConfig;2379 | McpClaudeAIProxyServerConfig;

2380```2380```

2381 2381

2382Veja [`McpServerConfig`](#mcp-server-config) para detalhes sobre cada tipo de transporte.2382Veja [`McpServerConfig`](#mcpserverconfig) para detalhes sobre cada tipo de transporte.

2383 2383

2384### `AccountInfo`2384### `AccountInfo`

2385 2385

2825```2825```

2826 2826

2828| :-------------------------- | :------------------------------------------------------ | :---------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |2828| :-------------------------- | :---------------------------------------------------- | :---------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

2832| `allowUnsandboxedCommands` | `boolean` | `true` | Permitir que o modelo solicite executar comandos fora do sandbox. Quando `true`, o modelo pode definir `dangerouslyDisableSandbox` na entrada da ferramenta, que volta para o [sistema de permissões](#permissions-fallback-for-unsandboxed-commands) |2832| `allowUnsandboxedCommands` | `boolean` | `true` | Permitir que o modelo solicite executar comandos fora do sandbox. Quando `true`, o modelo pode definir `dangerouslyDisableSandbox` na entrada da ferramenta, que volta para o [sistema de permissões](#permissions-fallback-for-unsandboxed-commands) |

2835| `ignoreViolations` | `Record<string, string[]>` | `undefined` | Mapa de categorias de violação para padrões a ignorar (por exemplo, `{ file: ['/tmp/*'], network: ['localhost'] }`) |2835| `ignoreViolations` | `Record<string, string[]>` | `undefined` | Mapa de categorias de violação para padrões a ignorar (por exemplo, `{ file: ['/tmp/*'], network: ['localhost'] }`) |

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

data-usage.md +1 −1

Details

67 67

68O diagrama abaixo mostra como Claude Code se conecta a serviços externos durante a instalação e operação normal. Linhas sólidas indicam conexões obrigatórias, enquanto linhas tracejadas representam fluxos de dados opcionais ou iniciados pelo usuário.68O diagrama abaixo mostra como Claude Code se conecta a serviços externos durante a instalação e operação normal. Linhas sólidas indicam conexões obrigatórias, enquanto linhas tracejadas representam fluxos de dados opcionais ou iniciados pelo usuário.

69 69

70<img src="https://mintcdn.com/claude-code/YcBW2H7CArGcduPb/images/claude-code-data-flow.svg?fit=max&auto=format&n=YcBW2H7CArGcduPb&q=85&s=b600a89f84fc86f9ff7be00a466c0635" alt="Diagram showing Claude Code's external connections: install/update connects to the distribution server, and user requests connect to Anthropic services including Console auth, public-api, and optionally Statsig, Sentry, and bug reporting" width="720" height="520" data-path="images/claude-code-data-flow.svg" />70<img src="https://mintcdn.com/claude-code/RcOyXc06Ja8cuvMZ/images/claude-code-data-flow.svg?fit=max&auto=format&n=RcOyXc06Ja8cuvMZ&q=85&s=b5be40abf333defe984993af89546c19" alt="Diagram showing Claude Code's external connections: install/update connects to the distribution server, and user requests connect to Anthropic services including Console auth, public-api, and optionally Statsig, Sentry, and bug reporting" width="720" height="520" data-path="images/claude-code-data-flow.svg" />

71 71

72Claude Code é executado localmente. Para interagir com o LLM, Claude Code envia dados pela rede. Esses dados incluem todos os prompts do usuário e saídas do modelo, criptografados em trânsito via TLS 1.2+. Claude Code é compatível com a maioria dos VPNs e proxies LLM populares.72Claude Code é executado localmente. Para interagir com o LLM, Claude Code envia dados pela rede. Esses dados incluem todos os prompts do usuário e saídas do modelo, criptografados em trânsito via TLS 1.2+. Claude Code é compatível com a maioria dos VPNs e proxies LLM populares.

73 73

desktop.md +5 −3

Details

282 282

283### Trabalhar em paralelo com sessões283### Trabalhar em paralelo com sessões

284 284

285Clique em **+ New session** na barra lateral, ou pressione **Cmd+N** no macOS ou **Ctrl+N** no Windows, para trabalhar em múltiplas tarefas em paralelo. Pressione **Ctrl+Tab** e **Ctrl+Shift+Tab** para ciclar através de sessões na barra lateral. Para repositórios Git, cada sessão obtém sua própria cópia isolada do seu projeto usando [Git worktrees](/pt/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees), para que alterações em uma sessão não afetem outras sessões até que você as faça commit.285Clique em **+ New session** na barra lateral, ou pressione **Cmd+N** no macOS ou **Ctrl+N** no Windows, para trabalhar em múltiplas tarefas em paralelo. Pressione **Ctrl+Tab** e **Ctrl+Shift+Tab** para ciclar através de sessões na barra lateral. Para repositórios Git, cada sessão obtém sua própria cópia isolada do seu projeto usando [Git worktrees](/pt/worktrees), para que alterações em uma sessão não afetem outras sessões até que você as faça commit.

286

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

286 288

287Worktrees são armazenadas em `<project-root>/.claude/worktrees/` por padrão. Você pode alterar isso para um diretório personalizado em Configurações → Claude Code em "Worktree location". Você também pode definir um prefixo de branch que é adicionado a cada nome de branch worktree, o que é útil para manter branches criadas por Claude organizadas. Para remover um worktree quando terminar, passe o mouse sobre a sessão na barra lateral e clique no ícone de arquivo. Para ter sessões se arquivarem automaticamente quando seu pull request mescla ou fecha, ative **Auto-archive after PR merge or close** em Configurações → Claude Code. Auto-archive se aplica apenas a sessões locais que terminaram de executar.289Worktrees são armazenadas em `<project-root>/.claude/worktrees/` por padrão. Você pode alterar isso para um diretório personalizado em Configurações → Claude Code em "Worktree location". Você também pode definir um prefixo de branch que é adicionado a cada nome de branch worktree, o que é útil para manter branches criadas por Claude organizadas. Para remover um worktree quando terminar, passe o mouse sobre a sessão na barra lateral e clique no ícone de arquivo. Para ter sessões se arquivarem automaticamente quando seu pull request mescla ou fecha, ative **Auto-archive after PR merge or close** em Configurações → Claude Code. Auto-archive se aplica apenas a sessões locais que terminaram de executar.

288 290

289Para incluir arquivos gitignored como `.env` em novos worktrees, crie um [arquivo `.worktreeinclude`](/pt/common-workflows#copy-gitignored-files-to-worktrees) na raiz do seu projeto.291Para incluir arquivos gitignored como `.env` em novos worktrees, crie um [arquivo `.worktreeinclude`](/pt/worktrees#copy-gitignored-files-into-worktrees) na raiz do seu projeto.

290 292

291<Note>293<Note>

292 O isolamento de sessão requer [Git](https://git-scm.com/downloads). A maioria dos Macs inclui Git por padrão. Execute `git --version` no Terminal para verificar. No Windows, Git é necessário para a aba Code funcionar: [baixe Git para Windows](https://git-scm.com/downloads/win), instale-o e reinicie o aplicativo. Se você encontrar erros de Git, peça a Claude na aba [Cowork](https://claude.com/product/cowork) para ajudar a solucionar problemas de sua configuração.294 O isolamento de sessão requer [Git](https://git-scm.com/downloads). A maioria dos Macs inclui Git por padrão. Execute `git --version` no Terminal para verificar. No Windows, Git é necessário para a aba Code funcionar: [baixe Git para Windows](https://git-scm.com/downloads/win), instale-o e reinicie o aplicativo. Se você encontrar erros de Git, peça a Claude na aba [Cowork](https://claude.com/product/cowork) para ajudar a solucionar problemas de sua configuração.

516 518

517Para definir variáveis de ambiente para sessões locais e servidores de desenvolvimento em qualquer plataforma, abra o menu suspenso de ambiente na caixa de prompt, passe o mouse sobre **Local** e clique no ícone de engrenagem para abrir o editor de ambiente local. Variáveis que você salva aqui são armazenadas criptografadas em sua máquina e se aplicam a cada sessão local e servidor de visualização que você inicia. Você também pode adicionar variáveis à chave `env` em seu arquivo `~/.claude/settings.json`, embora essas alcancem apenas sessões Claude e não servidores de desenvolvimento. Veja [variáveis de ambiente](/pt/env-vars) para a lista completa de variáveis suportadas.519Para definir variáveis de ambiente para sessões locais e servidores de desenvolvimento em qualquer plataforma, abra o menu suspenso de ambiente na caixa de prompt, passe o mouse sobre **Local** e clique no ícone de engrenagem para abrir o editor de ambiente local. Variáveis que você salva aqui são armazenadas criptografadas em sua máquina e se aplicam a cada sessão local e servidor de visualização que você inicia. Você também pode adicionar variáveis à chave `env` em seu arquivo `~/.claude/settings.json`, embora essas alcancem apenas sessões Claude e não servidores de desenvolvimento. Veja [variáveis de ambiente](/pt/env-vars) para a lista completa de variáveis suportadas.

518 520

519[Extended thinking](/pt/common-workflows#use-extended-thinking-thinking-mode) está ativado por padrão, o que melhora o desempenho em tarefas de raciocínio complexo mas usa tokens adicionais. Para desabilitar o thinking completamente, defina `MAX_THINKING_TOKENS` para `0` no editor de ambiente local. Em modelos com [adaptive reasoning](/pt/model-config#adjust-effort-level), qualquer outro valor de `MAX_THINKING_TOKENS` é ignorado porque adaptive reasoning controla a profundidade do thinking. Em Opus 4.6 e Sonnet 4.6, defina `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` para `1` para usar um orçamento de thinking fixo; Opus 4.7 sempre usa adaptive reasoning e não tem modo de orçamento fixo.521[Extended thinking](/pt/model-config#extended-thinking) está ativado por padrão, o que melhora o desempenho em tarefas de raciocínio complexo mas usa tokens adicionais. Para desabilitar o thinking completamente, defina `MAX_THINKING_TOKENS` para `0` no editor de ambiente local. Em modelos com [adaptive reasoning](/pt/model-config#adjust-effort-level), qualquer outro valor de `MAX_THINKING_TOKENS` é ignorado porque adaptive reasoning controla a profundidade do thinking. Em Opus 4.6 e Sonnet 4.6, defina `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` para `1` para usar um orçamento de thinking fixo; Opus 4.7 sempre usa adaptive reasoning e não tem modo de orçamento fixo.

520 522

521### Remote sessions523### Remote sessions

522 524

features-overview.md +50 −13

Details

12 Para saber como o loop agentic principal funciona, consulte [Como Claude Code funciona](/pt/how-claude-code-works).12 Para saber como o loop agentic principal funciona, consulte [Como Claude Code funciona](/pt/how-claude-code-works).

13</Note>13</Note>

14 14

~~15**Novo no Claude Code?** Comece com [CLAUDE.md](/pt/memory) para convenções de projeto. Adicione outras extensões conforme necessário.~~15**Novo no Claude Code?** Comece com [CLAUDE.md](/pt/memory) para convenções de projeto, depois adicione outras extensões [conforme gatilhos específicos surgirem](#build-your-setup-over-time).

16 16

17## Visão geral17## Visão geral

18 18

23* **[MCP](/pt/mcp)** conecta Claude a serviços e ferramentas externas23* **[MCP](/pt/mcp)** conecta Claude a serviços e ferramentas externas

24* **[Subagents](/pt/sub-agents)** executam seus próprios loops em contexto isolado, retornando resumos24* **[Subagents](/pt/sub-agents)** executam seus próprios loops em contexto isolado, retornando resumos

25* **[Agent teams](/pt/agent-teams)** coordenam múltiplas sessões independentes com tarefas compartilhadas e mensagens ponto a ponto25* **[Agent teams](/pt/agent-teams)** coordenam múltiplas sessões independentes com tarefas compartilhadas e mensagens ponto a ponto

~~26* **[Hooks](/pt/hooks)** executam fora do loop inteiramente como scripts determinísticos~~26* **[Hooks](/pt/hooks-guide)** disparam em eventos de ciclo de vida e podem executar um script, solicitação HTTP, prompt ou subagent

27* **[Plugins](/pt/plugins)** e **[marketplaces](/pt/plugin-marketplaces)** empacotam e distribuem esses recursos27* **[Plugins](/pt/plugins)** e **[marketplaces](/pt/plugin-marketplaces)** empacotam e distribuem esses recursos

28 28

29[Skills](/pt/skills) são a extensão mais flexível. Uma skill é um arquivo markdown contendo conhecimento, fluxos de trabalho ou instruções. Você pode invocar skills com um comando como `/deploy`, ou Claude pode carregá-las automaticamente quando relevante. Skills podem ser executadas em sua conversa atual ou em contexto isolado via subagents.29[Skills](/pt/skills) são a extensão mais flexível. Uma skill é um arquivo markdown contendo conhecimento, fluxos de trabalho ou instruções. Você pode invocar skills com um comando como `/deploy`, ou Claude pode carregá-las automaticamente quando relevante. Skills podem ser executadas em sua conversa atual ou em contexto isolado via subagents.

39| **Subagent** | Contexto de execução isolado que retorna resultados resumidos | Isolamento de contexto, tarefas paralelas, trabalhadores especializados | Tarefa de pesquisa que lê muitos arquivos mas retorna apenas descobertas principais |39| **Subagent** | Contexto de execução isolado que retorna resultados resumidos | Isolamento de contexto, tarefas paralelas, trabalhadores especializados | Tarefa de pesquisa que lê muitos arquivos mas retorna apenas descobertas principais |

40| **[Agent teams](/pt/agent-teams)** | Coordenar múltiplas sessões independentes do Claude Code | Pesquisa paralela, desenvolvimento de novos recursos, depuração com hipóteses concorrentes | Gerar revisores para verificar segurança, desempenho e testes simultaneamente |40| **[Agent teams](/pt/agent-teams)** | Coordenar múltiplas sessões independentes do Claude Code | Pesquisa paralela, desenvolvimento de novos recursos, depuração com hipóteses concorrentes | Gerar revisores para verificar segurança, desempenho e testes simultaneamente |

41| **MCP** | Conectar a serviços externos | Dados ou ações externas | Consultar seu banco de dados, postar no Slack, controlar um navegador |41| **MCP** | Conectar a serviços externos | Dados ou ações externas | Consultar seu banco de dados, postar no Slack, controlar um navegador |

43 43

44**[Plugins](/pt/plugins)** são a camada de empacotamento. Um plugin agrupa skills, hooks, subagents e servidores MCP em uma única unidade instalável. Skills de plugin são nomeadas (como `/my-plugin:review`) para que múltiplos plugins possam coexistir. Use plugins quando quiser reutilizar a mesma configuração em múltiplos repositórios ou distribuir para outros via um **[marketplace](/pt/plugin-marketplaces)**.44**[Plugins](/pt/plugins)** são a camada de empacotamento. Um plugin agrupa skills, hooks, subagents e servidores MCP em uma única unidade instalável. Skills de plugin são nomeadas (como `/my-plugin:review`) para que múltiplos plugins possam coexistir. Use plugins quando quiser reutilizar a mesma configuração em múltiplos repositórios ou distribuir para outros via um **[marketplace](/pt/plugin-marketplaces)**.

45 45

46### Construir sua configuração ao longo do tempo

48Você não precisa configurar tudo antecipadamente. Cada recurso tem um gatilho reconhecível, e a maioria das equipes os adiciona aproximadamente nesta ordem:

50| Gatilho | Adicionar |

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

52| Claude erra uma convenção ou comando duas vezes | Adicione a [CLAUDE.md](/pt/memory) |

53| Você continua digitando o mesmo prompt para iniciar uma tarefa | Salve como uma [skill](/pt/skills) invocável pelo usuário |

54| Você cola o mesmo playbook ou procedimento de múltiplas etapas no chat pela terceira vez | Capture como uma [skill](/pt/skills) |

55| Você continua copiando dados de uma aba do navegador que Claude não consegue ver | Conecte esse sistema como um [servidor MCP](/pt/mcp) |

56| Uma tarefa secundária inunda sua conversa com saída que você não consultará novamente | Encaminhe através de um [subagent](/pt/sub-agents) |

57| Você quer que algo aconteça toda vez sem pedir | Escreva um [hook](/pt/hooks-guide) |

58| Um segundo repositório precisa da mesma configuração | Empacote como um [plugin](/pt/plugins) |

60Os mesmos gatilhos dizem quando atualizar o que você já tem. Um erro repetido ou um comentário de revisão recorrente é uma edição de CLAUDE.md, não uma correção única no chat. Um fluxo de trabalho que você continua ajustando manualmente é uma skill que precisa de outra revisão.

46### Comparar recursos similares62### Comparar recursos similares

47 63

48Alguns recursos podem parecer similares. Aqui está como diferenciá-los.64Alguns recursos podem parecer similares. Aqui está como diferenciá-los.

55 * **Subagents** são trabalhadores isolados que são executados separadamente de sua conversa principal71 * **Subagents** são trabalhadores isolados que são executados separadamente de sua conversa principal

56 72

~~58 | ----------------------- | ------------------------------------------------------------ | ---------------------------------------------------------------------------------- |~~74 | ------------------------------------------------------- | ------------------------------------------------------------ | ---------------------------------------------------------------------------------- |

77 | **Impacto da [janela de contexto](/pt/context-window)** | Adiciona à sua janela principal | Usa uma janela separada com seus próprios tokens de entrada e saída |

62 79

63 **Skills podem ser referência ou ação.** Skills de referência fornecem conhecimento que Claude usa ao longo de sua sessão (como seu guia de estilo de API). Skills de ação dizem a Claude para fazer algo específico (como `/deploy` que executa seu fluxo de trabalho de implantação).80 **Skills podem ser referência ou ação.** Skills de referência fornecem conhecimento que Claude usa ao longo de sua sessão (como seu guia de estilo de API). Skills de ação dizem a Claude para fazer algo específico (como `/deploy` que executa seu fluxo de trabalho de implantação).

142 159

143 Exemplo: Um servidor MCP conecta Claude ao seu banco de dados. Uma skill ensina a Claude seu modelo de dados, padrões de consulta comuns e quais tabelas usar para diferentes tarefas.160 Exemplo: Um servidor MCP conecta Claude ao seu banco de dados. Uma skill ensina a Claude seu modelo de dados, padrões de consulta comuns e quais tabelas usar para diferentes tarefas.

144 </Tab>161 </Tab>

162

163 <Tab title="Hook vs Skill">

164 Um hook dispara em um evento de ciclo de vida; uma skill é carregada em contexto para Claude aplicar.

165

166 | Aspecto | Hook | Skill |

167 | --------------------- | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |

168 | **Executa** | Um comando shell, solicitação HTTP, prompt LLM ou subagent | Instruções que Claude lê e segue |

169 | **Disparado por** | [Eventos de ciclo de vida](/pt/hooks#hook-events) como `PostToolUse` ou `SessionStart` | Você digitando `/<name>`, ou Claude correspondendo a descrição à sua tarefa |

170 | **Determinismo** | Sempre dispara em seu evento; o gatilho é garantido | Claude interpreta as instruções; o resultado pode variar |

171 | **Custo de contexto** | Zero a menos que o hook retorne saída | Descrição carrega a cada sessão; conteúdo completo carrega quando usado |

172 | **Melhor para** | Linting após edições, bloqueio de comandos inseguros, logging, notificações | Fluxos de trabalho que precisam de raciocínio, material de referência, tarefas de múltiplas etapas |

173

174 **Use um hook** quando a ação deve acontecer da mesma forma toda vez e não precisa Claude pensar. Por exemplo: formatar ao salvar, rejeitar `rm -rf /`, postar uma mensagem Slack quando uma sessão termina.

175

176 **Use uma skill** quando Claude deve decidir como aplicar os passos, ou quando o conteúdo é conhecimento em vez de um script. Por exemplo: uma lista de verificação `/release`, seu guia de estilo de API, um playbook de depuração.

177

178 **Coloque guardrails em hooks.** Uma instrução como "nunca edite `.env`" em CLAUDE.md ou uma skill é um pedido, não uma garantia. Um hook `PreToolUse` que bloqueia a edição é execução. Se uma regra deve valer toda vez, faça um hook em vez de uma instrução de prompt.

179

180 **Saída de hook entra em contexto.** Um hook `PostToolUse` que executa seu linter alimenta resultados de volta como texto que Claude lê; uma skill `/fix-lint` diz a Claude como resolvê-los.

181 </Tab>

145</Tabs>182</Tabs>

146 183

147### Entender como os recursos se sobrepõem184### Entender como os recursos se sobrepõem

151* **Arquivos CLAUDE.md** são aditivos: todos os níveis contribuem conteúdo ao contexto de Claude simultaneamente. Arquivos do seu diretório de trabalho e acima carregam no lançamento; subdiretórios carregam conforme você trabalha neles. Quando as instruções entram em conflito, Claude usa julgamento para reconciliá-las, com instruções mais específicas tipicamente tendo precedência. Consulte [como arquivos CLAUDE.md carregam](/pt/memory#how-claudemd-files-load).188* **Arquivos CLAUDE.md** são aditivos: todos os níveis contribuem conteúdo ao contexto de Claude simultaneamente. Arquivos do seu diretório de trabalho e acima carregam no lançamento; subdiretórios carregam conforme você trabalha neles. Quando as instruções entram em conflito, Claude usa julgamento para reconciliá-las, com instruções mais específicas tipicamente tendo precedência. Consulte [como arquivos CLAUDE.md carregam](/pt/memory#how-claudemd-files-load).

152* **Skills e subagents** substituem por nome: quando o mesmo nome existe em múltiplos níveis, uma definição vence com base na prioridade (gerenciado > usuário > projeto para skills; gerenciado > sinalizador CLI > projeto > usuário > plugin para subagents). Skills de plugin são [nomeadas](/pt/plugins#add-skills-to-your-plugin) para evitar conflitos. Consulte [descoberta de skill](/pt/skills#where-skills-live) e [escopo de subagent](/pt/sub-agents#choose-the-subagent-scope).189* **Skills e subagents** substituem por nome: quando o mesmo nome existe em múltiplos níveis, uma definição vence com base na prioridade (gerenciado > usuário > projeto para skills; gerenciado > sinalizador CLI > projeto > usuário > plugin para subagents). Skills de plugin são [nomeadas](/pt/plugins#add-skills-to-your-plugin) para evitar conflitos. Consulte [descoberta de skill](/pt/skills#where-skills-live) e [escopo de subagent](/pt/sub-agents#choose-the-subagent-scope).

153* **Servidores MCP** substituem por nome: local > projeto > usuário. Consulte [escopo MCP](/pt/mcp#scope-hierarchy-and-precedence).190* **Servidores MCP** substituem por nome: local > projeto > usuário. Consulte [escopo MCP](/pt/mcp#scope-hierarchy-and-precedence).

154* **Hooks** se mesclam: todos os hooks registrados disparam para seus eventos correspondentes independentemente da fonte. Consulte [hooks](/pt/hooks).191* **Hooks** se mesclam: todos os hooks registrados disparam para seus eventos correspondentes independentemente da fonte. Consulte [hooks](/pt/hooks-guide).

155 192

156### Combinar recursos193### Combinar recursos

157 194

168 205

169## Entender custos de contexto206## Entender custos de contexto

170 207

171Cada recurso que você adiciona consome algum contexto de Claude. Muito pode preencher sua janela de contexto, mas também pode adicionar ruído que torna Claude menos eficaz; skills podem não disparar corretamente, ou Claude pode perder o controle de suas convenções. Entender esses trade-offs ajuda você a construir uma configuração eficaz.208Cada recurso que você adiciona consome algum contexto de Claude. Muito pode preencher sua janela de contexto, mas também pode adicionar ruído que torna Claude menos eficaz; skills podem não disparar corretamente, ou Claude pode perder o controle de suas convenções. Entender esses trade-offs ajuda você a construir uma configuração eficaz. Para uma visualização interativa de como esses recursos se combinam em uma sessão em execução, consulte [Explorar a janela de contexto](/pt/context-window).

172 209

173### Custo de contexto por recurso210### Custo de contexto por recurso

174 211

178| ------------------ | ------------------------------- | ---------------------------------------------------- | ------------------------------------------------- |215| ------------------ | ------------------------------- | ---------------------------------------------------- | ------------------------------------------------- |

184 221

188 225

189Cada recurso carrega em diferentes pontos em sua sessão. As abas abaixo explicam quando cada um carrega e o que entra em contexto.226Cada recurso carrega em diferentes pontos em sua sessão. As abas abaixo explicam quando cada um carrega e o que entra em contexto.

190 227

191<img src="https://mintcdn.com/claude-code/6yTCYq1p37ZB8-CQ/images/context-loading.svg?fit=max&auto=format&n=6yTCYq1p37ZB8-CQ&q=85&s=5a58ce953a35a2412892015e2ad6cb67" alt="Carregamento de contexto: CLAUDE.md e MCP carregam no início da sessão e permanecem em cada requisição. Skills carregam descrições no início, conteúdo completo na invocação. Subagents obtêm contexto isolado. Hooks são executados externamente." width="720" height="410" data-path="images/context-loading.svg" />228<img src="https://mintcdn.com/claude-code/6yTCYq1p37ZB8-CQ/images/context-loading.svg?fit=max&auto=format&n=6yTCYq1p37ZB8-CQ&q=85&s=5a58ce953a35a2412892015e2ad6cb67" alt="Carregamento de contexto: CLAUDE.md carrega no início da sessão e permanece em cada requisição. Nomes de ferramentas MCP carregam no início com esquemas completos adiados até o uso. Skills carregam descrições no início, conteúdo completo na invocação. Subagents obtêm contexto isolado. Hooks são executados externamente." width="720" height="410" data-path="images/context-loading.svg" />

192 229

193<Tabs>230<Tabs>

194 <Tab title="CLAUDE.md">231 <Tab title="CLAUDE.md">

202 </Tab>239 </Tab>

203 240

204 <Tab title="Skills">241 <Tab title="Skills">

205 Skills são capacidades extras no kit de ferramentas de Claude. Podem ser material de referência (como um guia de estilo de API) ou fluxos de trabalho invocáveis que você dispara com `/<name>` (como `/deploy`). Claude Code vem com [skills agrupadas](/pt/skills#bundled-skills) como `/simplify`, `/batch` e `/debug` que funcionam imediatamente. Você também pode criar as suas próprias. Claude usa skills quando apropriado, ou você pode invocar uma diretamente.242 Skills são capacidades extras no kit de ferramentas de Claude. Podem ser material de referência (como um guia de estilo de API) ou fluxos de trabalho invocáveis que você dispara com `/<name>` (como `/deploy`). Claude Code inclui [skills agrupadas](/pt/commands) como `/simplify`, `/batch` e `/debug` que funcionam imediatamente. Você também pode criar as suas próprias. Claude usa skills quando apropriado, ou você pode invocar uma diretamente.

206 243

207 **Quando:** Depende da configuração da skill. Por padrão, descrições carregam no início da sessão e conteúdo completo carrega quando usado. Para skills apenas de usuário (`disable-model-invocation: true`), nada carrega até que você as invoque.244 **Quando:** Depende da configuração da skill. Por padrão, descrições carregam no início da sessão e conteúdo completo carrega quando usado. Para skills apenas de usuário (`disable-model-invocation: true`), nada carrega até que você as invoque.

208 245

220 <Tab title="Servidores MCP">257 <Tab title="Servidores MCP">

221 **Quando:** Início da sessão.258 **Quando:** Início da sessão.

222 259

223 **O que carrega:** Todas as definições de ferramentas e esquemas JSON de servidores conectados.260 **O que carrega:** Nomes de ferramentas de servidores conectados. Esquemas JSON completos permanecem adiados até Claude precisar de uma ferramenta específica.

224 261

225 **Custo de contexto:** [Busca de ferramentas](/pt/mcp#scale-with-mcp-tool-search) (habilitada por padrão) carrega ferramentas MCP até 10% de contexto e adia o resto até ser necessário.262 **Custo de contexto:** [Busca de ferramentas](/pt/mcp#scale-with-mcp-tool-search) está ativada por padrão, então ferramentas MCP ociosas consomem contexto mínimo.

226 263

227 **Nota de confiabilidade:** Conexões MCP podem falhar silenciosamente no meio da sessão. Se um servidor se desconectar, suas ferramentas desaparecem sem aviso. Claude pode tentar usar uma ferramenta que não existe mais. Se você notar Claude falhando em usar uma ferramenta MCP que anteriormente podia acessar, verifique a conexão com `/mcp`.264 **Nota de confiabilidade:** Conexões MCP podem falhar silenciosamente no meio da sessão. Se um servidor se desconectar, suas ferramentas desaparecem sem aviso. Claude pode tentar usar uma ferramenta que não existe mais. Se você notar Claude falhando em usar uma ferramenta MCP que anteriormente podia acessar, verifique a conexão com `/mcp`.

228 265

245 </Tab>282 </Tab>

246 283

247 <Tab title="Hooks">284 <Tab title="Hooks">

248 **Quando:** No disparo. Hooks disparam em eventos de ciclo de vida específicos como execução de ferramenta, limites de sessão, envio de prompt, solicitações de permissão e compactação. Consulte [Hooks](/pt/hooks) para a lista completa.285 **Quando:** No disparo. Hooks disparam em eventos de ciclo de vida específicos como execução de ferramenta, limites de sessão, envio de prompt, solicitações de permissão e compactação. Consulte [Hooks](/pt/hooks-guide) para a lista completa.

249 286

250 **O que carrega:** Nada por padrão. Hooks são executados como scripts externos.287 **O que carrega:** Nada por padrão. Hooks são executados fora da conversa principal.

251 288

252 **Custo de contexto:** Zero, a menos que o hook retorne saída que seja adicionada como mensagens à sua conversa.289 **Custo de contexto:** Zero, a menos que o hook retorne saída que seja adicionada como mensagens à sua conversa.

253 290

hooks.md +5 −5

Details

974| `decision` | `"block"` previne o prompt de ser processado e o apaga do contexto. Omita para permitir que o prompt prossiga |974| `decision` | `"block"` previne o prompt de ser processado e o apaga do contexto. Omita para permitir que o prompt prossiga |

976| `additionalContext` | String adicionada ao contexto de Claude junto com o prompt submetido. Consulte [Adicionar contexto para Claude](#add-context-for-claude) |976| `additionalContext` | String adicionada ao contexto de Claude junto com o prompt submetido. Consulte [Adicionar contexto para Claude](#add-context-for-claude) |

977| `sessionTitle` | Define o título da sessão, mesmo efeito que `/rename`. Use para nomear sessões automaticamente baseado no conteúdo do prompt |977| `sessionTitle` | Define o título da sessão. Use para nomear sessões automaticamente baseado no conteúdo do prompt |

978 978

979```json theme={null}979```json theme={null}

980{980{

1358 1358

1359| Campo | Descrição |1359| Campo | Descrição |

1360| :--------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------- |1360| :--------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------- |

1361| `decision` | `"block"` solicita ao Claude com a `reason`. Omita para permitir que a ação prossiga |1361| `decision` | `"block"` adiciona a `reason` próxima ao resultado da ferramenta. Claude ainda vê a saída original; para substituí-la, use `updatedToolOutput` |

1363| `additionalContext` | String adicionada ao contexto de Claude junto com o resultado da ferramenta. Consulte [Adicionar contexto para Claude](#add-context-for-claude) |1363| `additionalContext` | String adicionada ao contexto de Claude junto com o resultado da ferramenta. Consulte [Adicionar contexto para Claude](#add-context-for-claude) |

1364| `updatedToolOutput` | Substitui a saída da ferramenta pelo valor fornecido antes de ser enviado ao Claude. O valor deve corresponder à forma de saída da ferramenta |1364| `updatedToolOutput` | Substitui a saída da ferramenta pelo valor fornecido antes de ser enviado ao Claude. O valor deve corresponder à forma de saída da ferramenta |

2407```2407```

2408 2408

2409| Campo | Descrição |2409| Campo | Descrição |

2410| :------- | :------------------------------------------------------------ |2410| :------- | :-------------------------------------------------------------------------------- |

2411| `ok` | `true` permite a ação, `false` a bloqueia |2411| `ok` | `true` permite a ação, `false` a bloqueia. Veja o comportamento por evento abaixo |

2413 2413

2414O que acontece em `ok: false` depende do evento:2414O que acontece em `ok: false` depende do evento:

2415 2415

permissions.md +4 −4

Details

36| :------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |36| :------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

38| `acceptEdits` | Aceita automaticamente edições de arquivo e comandos comuns do sistema de arquivos (`mkdir`, `touch`, `mv`, `cp`, etc.) para caminhos no diretório de trabalho ou `additionalDirectories` |38| `acceptEdits` | Aceita automaticamente edições de arquivo e comandos comuns do sistema de arquivos (`mkdir`, `touch`, `mv`, `cp`, etc.) para caminhos no diretório de trabalho ou `additionalDirectories` |

40| `auto` | Aprova automaticamente chamadas de ferramentas com verificações de segurança em segundo plano que verificam se as ações se alinham com sua solicitação. Atualmente uma visualização de pesquisa |40| `auto` | Aprova automaticamente chamadas de ferramentas com verificações de segurança em segundo plano que verificam se as ações se alinham com sua solicitação. Atualmente uma visualização de pesquisa |

42| `bypassPermissions` | Ignora todos os prompts de permissão. Remoções de diretório raiz e diretório inicial como `rm -rf /` ainda solicitam como um disjuntor |42| `bypassPermissions` | Ignora todos os prompts de permissão. Remoções de diretório raiz e diretório inicial como `rm -rf /` ainda solicitam como um disjuntor |

296 296

297* As regras deny de permissão bloqueiam Claude de até tentar acessar recursos restritos297* As regras deny de permissão bloqueiam Claude de até tentar acessar recursos restritos

298* As restrições de sandbox impedem que comandos Bash alcancem recursos fora dos limites definidos, mesmo se uma injeção de prompt contornar a tomada de decisão de Claude298* As restrições de sandbox impedem que comandos Bash alcancem recursos fora dos limites definidos, mesmo se uma injeção de prompt contornar a tomada de decisão de Claude

299* As restrições de sistema de arquivos no sandbox usam regras deny de Read e Edit, não configuração de sandbox separada299* As restrições de sistema de arquivos no sandbox combinam as configurações [`sandbox.filesystem`](/pt/sandboxing) com regras deny de Read e Edit; ambas são mescladas no limite final do sandbox

300* As restrições de rede combinam regras de permissão WebFetch com as listas `allowedDomains` e `deniedDomains` do sandbox300* As restrições de rede combinam regras de permissão WebFetch com as listas `allowedDomains` e `deniedDomains` do sandbox

301 301

302Quando o sandboxing é ativado com `autoAllowBashIfSandboxed: true`, que é o padrão, comandos Bash em sandbox são executados sem solicitar mesmo se suas permissões incluem `ask: Bash(*)`. O limite do sandbox substitui o prompt por comando. Regras deny explícitas ainda se aplicam, e comandos `rm` ou `rmdir` que visam `/`, seu diretório inicial ou outros caminhos críticos do sistema ainda acionam um prompt. Veja [modos de sandbox](/pt/sandboxing#sandbox-modes) para alterar este comportamento.302Quando o sandboxing é ativado com `autoAllowBashIfSandboxed: true`, que é o padrão, comandos Bash em sandbox são executados sem solicitar mesmo se suas permissões incluem `ask: Bash(*)`. O limite do sandbox substitui o prompt por comando. Regras deny explícitas ainda se aplicam, e comandos `rm` ou `rmdir` que visam `/`, seu diretório inicial ou outros caminhos críticos do sistema ainda acionam um prompt. Veja [modos de sandbox](/pt/sandboxing#sandbox-modes) para alterar este comportamento.

316| `allowManagedMcpServersOnly` | Quando `true`, apenas `allowedMcpServers` de configurações gerenciadas são respeitados. `deniedMcpServers` ainda se mescla de todas as fontes. Veja [Configuração MCP gerenciada](/pt/mcp#managed-mcp-configuration) |316| `allowManagedMcpServersOnly` | Quando `true`, apenas `allowedMcpServers` de configurações gerenciadas são respeitados. `deniedMcpServers` ainda se mescla de todas as fontes. Veja [Configuração MCP gerenciada](/pt/mcp#managed-mcp-configuration) |

317| `allowManagedPermissionRulesOnly` | Quando `true`, impede que configurações de usuário e projeto definam regras de permissão `allow`, `ask` ou `deny`. Apenas regras em configurações gerenciadas se aplicam |317| `allowManagedPermissionRulesOnly` | Quando `true`, impede que configurações de usuário e projeto definam regras de permissão `allow`, `ask` ou `deny`. Apenas regras em configurações gerenciadas se aplicam |

318| `blockedMarketplaces` | Lista de bloqueio de fontes de marketplace. Fontes bloqueadas são verificadas antes do download, portanto nunca tocam o sistema de arquivos. Veja [restrições de marketplace gerenciadas](/pt/plugin-marketplaces#managed-marketplace-restrictions) |318| `blockedMarketplaces` | Lista de bloqueio de fontes de marketplace. Fontes bloqueadas são verificadas antes do download, portanto nunca tocam o sistema de arquivos. Veja [restrições de marketplace gerenciadas](/pt/plugin-marketplaces#managed-marketplace-restrictions) |

319| `channelsEnabled` | Permitir [channels](/pt/channels) para usuários Team e Enterprise. Não definido ou `false` bloqueia entrega de mensagem de canal independentemente do que os usuários passam para `--channels` |319| `channelsEnabled` | Permitir [channels](/pt/channels) para a organização. Veja [controles empresariais](/pt/channels#enterprise-controls) para o padrão em cada plano |

320| `forceRemoteSettingsRefresh` | Quando `true`, bloqueia a inicialização da CLI até que as configurações gerenciadas remotas sejam buscadas recentemente e sai se a busca falhar. Veja [imposição fail-closed](/pt/server-managed-settings#enforce-fail-closed-startup) |320| `forceRemoteSettingsRefresh` | Quando `true`, bloqueia a inicialização da CLI até que as configurações gerenciadas remotas sejam buscadas recentemente e sai se a busca falhar. Veja [imposição fail-closed](/pt/server-managed-settings#enforce-fail-closed-startup) |

322| `sandbox.filesystem.allowManagedReadPathsOnly` | Quando `true`, apenas caminhos `filesystem.allowRead` de configurações gerenciadas são respeitados. `denyRead` ainda se mescla de todas as fontes |322| `sandbox.filesystem.allowManagedReadPathsOnly` | Quando `true`, apenas caminhos `filesystem.allowRead` de configurações gerenciadas são respeitados. `denyRead` ainda se mescla de todas as fontes |

327`disableBypassPermissionsMode` é tipicamente colocado em configurações gerenciadas para impor política organizacional, mas funciona de qualquer escopo. Um usuário pode defini-lo em suas próprias configurações para se bloquear do modo bypass.327`disableBypassPermissionsMode` é tipicamente colocado em configurações gerenciadas para impor política organizacional, mas funciona de qualquer escopo. Um usuário pode defini-lo em suas próprias configurações para se bloquear do modo bypass.

328 328

329<Note>329<Note>

330 O acesso a [Remote Control](/pt/remote-control) e [sessões web](/pt/claude-code-on-the-web) não é controlado por uma chave de configurações gerenciadas. Em planos Team e Enterprise, um admin ativa ou desativa esses recursos em [configurações de admin do Claude Code](https://claude.ai/admin-settings/claude-code).330 Em planos Team e Enterprise, um admin ativa ou desativa [Remote Control](/pt/remote-control) e [sessões web](/pt/claude-code-on-the-web) em toda a organização em [configurações de admin do Claude Code](https://claude.ai/admin-settings/claude-code). Remote Control pode ser adicionalmente desativado por dispositivo com a configuração gerenciada [`disableRemoteControl`](/pt/settings#available-settings). Sessões web não têm chave de configurações gerenciadas por dispositivo.

331</Note>331</Note>

332 332

333## Precedência de configurações333## Precedência de configurações

platforms.md +7 −4

Details

4 4

5# Plataformas e integrações5# Plataformas e integrações

6 6

~~7> Escolha onde executar Claude Code e o que conectar a ele. Compare a CLI, Desktop, VS Code, JetBrains, web e integrações como Chrome, Slack e CI/CD.~~7> Escolha onde executar Claude Code e o que conectar a ele. Compare a CLI, Desktop, VS Code, JetBrains, web, mobile e integrações como Chrome, Slack e CI/CD.

8 8

9Claude Code executa o mesmo mecanismo subjacente em todos os lugares, mas cada superfície é ajustada para uma forma diferente de trabalhar. Esta página ajuda você a escolher a plataforma certa para seu fluxo de trabalho e conectar as ferramentas que você já usa.9Claude Code executa o mesmo mecanismo subjacente em todos os lugares, mas cada superfície é ajustada para uma forma diferente de trabalhar. Esta página ajuda você a escolher a plataforma certa para seu fluxo de trabalho e conectar as ferramentas que você já usa.

10 10

13Escolha uma plataforma com base em como você gosta de trabalhar e onde seu projeto está localizado.13Escolha uma plataforma com base em como você gosta de trabalhar e onde seu projeto está localizado.

14 14

16| :-------------------------------- | :---------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |16| :-------------------------------- | :---------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

17| [CLI](/pt/quickstart) | Fluxos de trabalho de terminal, scripts, servidores remotos | Conjunto completo de recursos, [Agent SDK](/pt/headless), provedores de terceiros |17| [CLI](/pt/quickstart) | Fluxos de trabalho de terminal, scripts, servidores remotos | Conjunto completo de recursos, [Agent SDK](/pt/headless), [computer use](/pt/computer-use) em macOS (Pro e Max), provedores de terceiros |

18| [Desktop](/pt/desktop) | Revisão visual, sessões paralelas, configuração gerenciada | Visualizador de diff, visualização de aplicativo, [computer use](/pt/desktop#let-claude-use-your-computer) e [Dispatch](/pt/desktop#sessions-from-dispatch) em Pro e Max |18| [Desktop](/pt/desktop) | Revisão visual, sessões paralelas, configuração gerenciada | Visualizador de diff, visualização de aplicativo, [computer use](/pt/desktop#let-claude-use-your-computer) e [Dispatch](/pt/desktop#sessions-from-dispatch) em Pro e Max |

21| [Web](/pt/claude-code-on-the-web) | Tarefas de longa duração que não precisam de muito direcionamento, ou trabalho que deve continuar quando você estiver offline | Nuvem gerenciada pela Anthropic, continua após você se desconectar |21| [Web](/pt/claude-code-on-the-web) | Tarefas de longa duração que não precisam de muito direcionamento, ou trabalho que deve continuar quando você estiver offline | Nuvem gerenciada pela Anthropic, continua após você se desconectar |

22| Mobile | Iniciar e monitorar tarefas enquanto estiver longe de seu computador | Sessões em nuvem do aplicativo Claude para iOS e Android, [Remote Control](/pt/remote-control) para sessões locais, [Dispatch](/pt/desktop#sessions-from-dispatch) para Desktop em Pro e Max |

22 23

23A CLI é a superfície mais completa para trabalho nativo de terminal: scripts, provedores de terceiros e o Agent SDK são apenas CLI. Desktop e as extensões IDE trocam alguns recursos apenas CLI por revisão visual e integração mais estreita do editor. A web é executada na nuvem da Anthropic, portanto as tarefas continuam após você se desconectar.24A CLI é a superfície mais completa para trabalho nativo de terminal: scripts e o Agent SDK são apenas CLI. Provedores de terceiros também funcionam em [VS Code](/pt/vs-code#use-third-party-providers). Implantações [Desktop](/pt/desktop) corporativas suportam Vertex AI e provedores de gateway; para Bedrock ou Foundry, use a CLI ou VS Code em vez de Desktop. Desktop e as extensões IDE trocam alguns recursos apenas CLI por revisão visual e integração mais estreita do editor. A web é executada na nuvem da Anthropic, portanto as tarefas continuam após você se desconectar. Mobile é um cliente fino nessas mesmas sessões em nuvem ou em uma sessão local via Remote Control, e pode enviar tarefas para Desktop com Dispatch.

24 25

25Você pode misturar superfícies no mesmo projeto. Configuração, memória do projeto e servidores MCP são compartilhados entre as superfícies locais.26Você pode misturar superfícies no mesmo projeto. Configuração, memória do projeto e servidores MCP são compartilhados entre as superfícies locais.

26 27

61* [VS Code](/pt/vs-code): a extensão Claude Code dentro de seu editor62* [VS Code](/pt/vs-code): a extensão Claude Code dentro de seu editor

62* [JetBrains](/pt/jetbrains): a extensão para IntelliJ, PyCharm e outros IDEs JetBrains63* [JetBrains](/pt/jetbrains): a extensão para IntelliJ, PyCharm e outros IDEs JetBrains

63* [Claude Code na web](/pt/claude-code-on-the-web): sessões em nuvem que continuam sendo executadas quando você se desconecta64* [Claude Code na web](/pt/claude-code-on-the-web): sessões em nuvem que continuam sendo executadas quando você se desconecta

65* Mobile: o aplicativo Claude para [iOS](https://apps.apple.com/us/app/claude-by-anthropic/id6473753684) e [Android](https://play.google.com/store/apps/details?id=com.anthropic.claude) para iniciar e monitorar tarefas enquanto estiver longe de seu computador

64 66

65### Integrações67### Integrações

66 68

67* [Chrome](/pt/chrome): automatize tarefas do navegador com suas sessões conectadas69* [Chrome](/pt/chrome): automatize tarefas do navegador com suas sessões conectadas

70* [Computer use](/pt/computer-use): deixe Claude abrir aplicativos e controlar sua tela em macOS

68* [GitHub Actions](/pt/github-actions): execute Claude em seu pipeline CI71* [GitHub Actions](/pt/github-actions): execute Claude em seu pipeline CI

69* [GitLab CI/CD](/pt/gitlab-ci-cd): o mesmo para GitLab72* [GitLab CI/CD](/pt/gitlab-ci-cd): o mesmo para GitLab

70* [Code Review](/pt/code-review): revisão automática em cada pull request73* [Code Review](/pt/code-review): revisão automática em cada pull request

plugin-marketplaces.md +8 −6

Details

23 23

24## Passo a passo: criar um marketplace local24## Passo a passo: criar um marketplace local

25 25

26Este exemplo cria um marketplace com um plugin: uma skill `/quality-review` para revisões de código. Você criará a estrutura de diretórios, adicionará uma skill, criará o manifesto do plugin e o catálogo do marketplace, depois instalará e testará.26Este exemplo cria um marketplace com um plugin: uma skill `quality-review` para revisões de código. Você criará a estrutura de diretórios, adicionará uma skill, criará o manifesto do plugin e o catálogo do marketplace, depois instalará e testará.

27 27

28<Steps>28<Steps>

29 <Step title="Criar a estrutura de diretórios">29 <Step title="Criar a estrutura de diretórios">

35 </Step>35 </Step>

36 36

37 <Step title="Criar a skill">37 <Step title="Criar a skill">

~~38 Crie um arquivo `SKILL.md` que define o que a skill `/quality-review` faz.~~38 Crie um arquivo `SKILL.md` que define o que a skill `quality-review` faz.

39 39

40 ```markdown my-marketplace/plugins/quality-review-plugin/skills/quality-review/SKILL.md theme={null}40 ```markdown my-marketplace/plugins/quality-review-plugin/skills/quality-review/SKILL.md theme={null}

41 ---41 ---

59 ```json my-marketplace/plugins/quality-review-plugin/.claude-plugin/plugin.json theme={null}59 ```json my-marketplace/plugins/quality-review-plugin/.claude-plugin/plugin.json theme={null}

60 {60 {

61 "name": "quality-review-plugin",61 "name": "quality-review-plugin",

~~62 "description": "Adiciona uma skill /quality-review para revisões rápidas de código",~~62 "description": "Adiciona uma skill quality-review para revisões rápidas de código",

63 "version": "1.0.0"63 "version": "1.0.0"

64 }64 }

65 ```65 ```

82 {82 {

83 "name": "quality-review-plugin",83 "name": "quality-review-plugin",

84 "source": "./plugins/quality-review-plugin",84 "source": "./plugins/quality-review-plugin",

~~85 "description": "Adiciona uma skill /quality-review para revisões rápidas de código"~~85 "description": "Adiciona uma skill quality-review para revisões rápidas de código"

86 }86 }

87 ]87 ]

88 }88 }

99 </Step>99 </Step>

100 100

101 <Step title="Experimentar">101 <Step title="Experimentar">

102 Selecione algum código em seu editor e execute sua nova skill.102 Selecione algum código em seu editor e execute sua nova skill. As skills do plugin são nomeadas com o nome do plugin.

103 103

104 ```shell theme={null}104 ```shell theme={null}

105 /quality-review105 /quality-review-plugin:quality-review

106 ```106 ```

107 </Step>107 </Step>

108</Steps>108</Steps>

693* Para fontes `hostPattern`: o host do marketplace é correspondido contra o padrão regex693* Para fontes `hostPattern`: o host do marketplace é correspondido contra o padrão regex

694* Para fontes `pathPattern`: o caminho do sistema de arquivos do marketplace é correspondido contra o padrão regex694* Para fontes `pathPattern`: o caminho do sistema de arquivos do marketplace é correspondido contra o padrão regex

695 695

696A correspondência exata não normaliza URLs: uma barra à direita, sufixo `.git` ou forma `ssh://` versus `https://` são tratados como valores diferentes. Se o marketplace da sua organização pode ser clonado por mais de uma forma de URL, prefira uma entrada `hostPattern` em vez de uma URL literal para que todas as formas correspondam.

697

696Como `strictKnownMarketplaces` é definido em [configurações gerenciadas](/pt/settings#settings-files), configurações individuais de usuários e projetos não podem substituir essas restrições.698Como `strictKnownMarketplaces` é definido em [configurações gerenciadas](/pt/settings#settings-files), configurações individuais de usuários e projetos não podem substituir essas restrições.

697 699

698Para detalhes de configuração completos incluindo todos os tipos de fonte suportados e comparação com `extraKnownMarketplaces`, veja a [referência strictKnownMarketplaces](/pt/settings#strictknownmarketplaces).700Para detalhes de configuração completos incluindo todos os tipos de fonte suportados e comparação com `extraKnownMarketplaces`, veja a [referência strictKnownMarketplaces](/pt/settings#strictknownmarketplaces).

plugins-reference.md +7 −3

Details

262**Plugins LSP disponíveis:**262**Plugins LSP disponíveis:**

263 263

265| :--------------- | :------------------------- | :------------------------------------------------------------------------------------------- |265| :------------------ | :------------------------- | :------------------------------------------------------------------------------------------- |

269 269

270Instale o servidor de linguagem primeiro, depois instale o plugin do marketplace.270Instale o servidor de linguagem primeiro, depois instale o plugin do marketplace.

271 271

531 531

532Claude Code fornece duas variáveis para referenciar caminhos de plugin. Ambas são substituídas inline em qualquer lugar que apareçam em conteúdo de skill, conteúdo de agent, comandos de hook, comandos de monitor e configurações de servidor MCP ou LSP. Ambas também são exportadas como variáveis de ambiente para processos de hook e subprocessos de servidor MCP ou LSP.532Claude Code fornece duas variáveis para referenciar caminhos de plugin. Ambas são substituídas inline em qualquer lugar que apareçam em conteúdo de skill, conteúdo de agent, comandos de hook, comandos de monitor e configurações de servidor MCP ou LSP. Ambas também são exportadas como variáveis de ambiente para processos de hook e subprocessos de servidor MCP ou LSP.

533 533

534**`${CLAUDE_PLUGIN_ROOT}`**: o caminho absoluto para o diretório de instalação do seu plugin. Use isso para referenciar scripts, binários e arquivos de configuração agrupados com o plugin. Este caminho muda quando o plugin é atualizado, então arquivos que você escreve aqui não sobrevivem a uma atualização.534**`${CLAUDE_PLUGIN_ROOT}`**: o caminho absoluto para o diretório de instalação do seu plugin. Use isso para referenciar scripts, binários e arquivos de configuração agrupados com o plugin. Este caminho muda quando o plugin é atualizado. O diretório da versão anterior permanece no disco por aproximadamente sete dias após uma atualização antes da limpeza, mas trate-o como efêmero e não escreva estado aqui.

535

536Quando um plugin é atualizado no meio de uma sessão, comandos de hook, monitors, servidores MCP e servidores LSP continuam usando o caminho da versão anterior. Execute `/reload-plugins` para alternar hooks, servidores MCP e servidores LSP para o novo caminho; monitors requerem uma reinicialização de sessão.

535 537

536**`${CLAUDE_PLUGIN_DATA}`**: um diretório persistente para estado do plugin que sobrevive a atualizações. Use isso para dependências instaladas como `node_modules` ou ambientes virtuais Python, código gerado, caches e quaisquer outros arquivos que devem persistir entre versões de plugin. O diretório é criado automaticamente na primeira vez que esta variável é referenciada.538**`${CLAUDE_PLUGIN_DATA}`**: um diretório persistente para estado do plugin que sobrevive a atualizações. Use isso para dependências instaladas como `node_modules` ou ambientes virtuais Python, código gerado, caches e quaisquer outros arquivos que devem persistir entre versões de plugin. O diretório é criado automaticamente na primeira vez que esta variável é referenciada.

537 539

677 O diretório `.claude-plugin/` contém o arquivo `plugin.json`. Todos os outros diretórios (commands/, agents/, skills/, output-styles/, themes/, monitors/, hooks/) devem estar na raiz do plugin, não dentro de `.claude-plugin/`.679 O diretório `.claude-plugin/` contém o arquivo `plugin.json`. Todos os outros diretórios (commands/, agents/, skills/, output-styles/, themes/, monitors/, hooks/) devem estar na raiz do plugin, não dentro de `.claude-plugin/`.

678</Warning>680</Warning>

679 681

682Um arquivo `CLAUDE.md` na raiz do plugin não é carregado como contexto do projeto. Os plugins contribuem contexto através de skills, agents e hooks em vez de CLAUDE.md. Para enviar instruções que sejam carregadas no contexto do Claude, coloque-as em uma [skill](#skills).

683

680### Referência de localizações de arquivo684### Referência de localizações de arquivo

681 685

security.md +1 −1

Details

27* **Ferramenta bash em sandbox**: [Sandbox](/pt/sandboxing) comandos bash com isolamento de sistema de arquivos e rede, reduzindo prompts de permissão enquanto mantém a segurança. Ative com `/sandbox` para definir limites onde Claude Code pode trabalhar autonomamente27* **Ferramenta bash em sandbox**: [Sandbox](/pt/sandboxing) comandos bash com isolamento de sistema de arquivos e rede, reduzindo prompts de permissão enquanto mantém a segurança. Ative com `/sandbox` para definir limites onde Claude Code pode trabalhar autonomamente

28* **Restrição de acesso de escrita**: Claude Code pode escrever apenas na pasta onde foi iniciado e suas subpastas—não pode modificar arquivos em diretórios pai sem permissão explícita. Embora Claude Code possa ler arquivos fora do diretório de trabalho (útil para acessar bibliotecas do sistema e dependências), operações de escrita são estritamente confinadas ao escopo do projeto, criando um limite de segurança claro28* **Restrição de acesso de escrita**: Claude Code pode escrever apenas na pasta onde foi iniciado e suas subpastas—não pode modificar arquivos em diretórios pai sem permissão explícita. Embora Claude Code possa ler arquivos fora do diretório de trabalho (útil para acessar bibliotecas do sistema e dependências), operações de escrita são estritamente confinadas ao escopo do projeto, criando um limite de segurança claro

29* **Mitigação de fadiga de prompt**: Suporte para lista de permissões de comandos seguros frequentemente usados por usuário, por base de código ou por organização29* **Mitigação de fadiga de prompt**: Suporte para lista de permissões de comandos seguros frequentemente usados por usuário, por base de código ou por organização

~~30* **Modo Accept Edits**: Aceitar em lote múltiplas edições enquanto mantém prompts de permissão para comandos com efeitos colaterais~~30* **Modo Accept Edits**: Aprova automaticamente edições de arquivo e um conjunto fixo de comandos Bash do sistema de arquivos como `mkdir`, `touch`, `rm`, `mv`, `cp` e `sed` para caminhos no diretório de trabalho. Outros comandos Bash e caminhos fora do escopo ainda solicitam aprovação

31 31

32### Responsabilidade do usuário32### Responsabilidade do usuário

33 33

settings.md +27 −4

Details

37 37

38O escopo **Project** é melhor para:38O escopo **Project** é melhor para:

39 39

~~40* Configurações compartilhadas pela equipe (permissões, hooks, MCP servers)~~40* Configurações compartilhadas pela equipe (permissões, hooks, servidores MCP)

41* Plugins que toda a equipe deve ter41* Plugins que toda a equipe deve ter

42* Padronização de ferramentas entre colaboradores42* Padronização de ferramentas entre colaboradores

43 43

73 73

74No Windows, os caminhos mostrados como `~/.claude` são resolvidos para `%USERPROFILE%\.claude`.

74***76***

75 77

76## Arquivos de configuração78## Arquivos de configuração

166| `apiKeyHelper` | Script personalizado, a ser executado em `/bin/sh`, para gerar um valor de autenticação. Este valor será enviado como cabeçalhos `X-Api-Key` e `Authorization: Bearer` para solicitações de modelo | `/bin/generate_temp_api_key.sh` |168| `apiKeyHelper` | Script personalizado, a ser executado em `/bin/sh`, para gerar um valor de autenticação. Este valor será enviado como cabeçalhos `X-Api-Key` e `Authorization: Bearer` para solicitações de modelo | `/bin/generate_temp_api_key.sh` |

167| `attribution` | Personalizar atribuição para commits git e pull requests. Veja [Configurações de atribuição](#attribution-settings) | `{"commit": "🤖 Generated with Claude Code", "pr": ""}` |169| `attribution` | Personalizar atribuição para commits git e pull requests. Veja [Configurações de atribuição](#attribution-settings) | `{"commit": "🤖 Generated with Claude Code", "pr": ""}` |

168| `autoMemoryDirectory` | Diretório personalizado para armazenamento de [memória automática](/pt/memory#storage-location). Aceita um caminho absoluto ou um caminho com prefixo `~/`. Aceito de configurações de política e usuário, e da flag `--settings`. Não aceito de configurações de projeto ou local, já que um repositório clonado poderia fornecer qualquer arquivo para redirecionar escritas de memória para locais sensíveis | `"~/my-memory-dir"` |170| `autoMemoryDirectory` | Diretório personalizado para armazenamento de [memória automática](/pt/memory#storage-location). Aceita um caminho absoluto ou um caminho com prefixo `~/`. Aceito de configurações de política e usuário, e da flag `--settings`. Não aceito de configurações de projeto ou local, já que um repositório clonado poderia fornecer qualquer arquivo para redirecionar escritas de memória para locais sensíveis | `"~/my-memory-dir"` |

171| `autoMemoryEnabled` | Ativar [memória automática](/pt/memory#enable-or-disable-auto-memory). Quando `false`, Claude não lê ou escreve no diretório de memória automática. Padrão: `true`. Você também pode alternar isto com `/memory` durante uma sessão | `false` |

169| `autoMode` | Personalizar o que o classificador de [modo automático](/pt/permission-modes#eliminate-prompts-with-auto-mode) bloqueia e permite. Contém arrays `environment`, `allow`, e `soft_deny` de regras em prosa. Inclua a string literal `"$defaults"` em um array para herdar as regras integradas nessa posição. Veja [Configurar modo automático](/pt/auto-mode-config). Não lido de configurações de projeto compartilhadas | `{"soft_deny": ["$defaults", "Never run terraform apply"]}` |172| `autoMode` | Personalizar o que o classificador de [modo automático](/pt/permission-modes#eliminate-prompts-with-auto-mode) bloqueia e permite. Contém arrays `environment`, `allow`, e `soft_deny` de regras em prosa. Inclua a string literal `"$defaults"` em um array para herdar as regras integradas nessa posição. Veja [Configurar modo automático](/pt/auto-mode-config). Não lido de configurações de projeto compartilhadas | `{"soft_deny": ["$defaults", "Never run terraform apply"]}` |

170| `autoScrollEnabled` | Em [renderização fullscreen](/pt/fullscreen), seguir nova saída até o fundo da conversa. Padrão: `true`. Aparece em `/config` como **Auto-scroll**. Prompts de permissão ainda rolam para a vista quando isto está desligado | `false` |173| `autoScrollEnabled` | Em [renderização fullscreen](/pt/fullscreen), seguir nova saída até o fundo da conversa. Padrão: `true`. Aparece em `/config` como **Auto-scroll**. Prompts de permissão ainda rolam para a vista quando isto está desligado | `false` |

171| `autoUpdatesChannel` | Canal de lançamento a seguir para atualizações. Use `"stable"` para uma versão que é tipicamente cerca de uma semana antiga e pula versões com regressões maiores, ou `"latest"` (padrão) para o lançamento mais recente | `"stable"` |174| `autoUpdatesChannel` | Canal de lançamento a seguir para atualizações. Use `"stable"` para uma versão que é tipicamente cerca de uma semana antiga e pula versões com regressões maiores, ou `"latest"` (padrão) para o lançamento mais recente | `"stable"` |

174| `awsAuthRefresh` | Script personalizado que modifica o diretório `.aws` (veja [configuração avançada de credenciais](/pt/amazon-bedrock#advanced-credential-configuration)) | `aws sso login --profile myprofile` |177| `awsAuthRefresh` | Script personalizado que modifica o diretório `.aws` (veja [configuração avançada de credenciais](/pt/amazon-bedrock#advanced-credential-configuration)) | `aws sso login --profile myprofile` |

175| `awsCredentialExport` | Script personalizado que produz JSON com credenciais AWS (veja [configuração avançada de credenciais](/pt/amazon-bedrock#advanced-credential-configuration)) | `/bin/generate_aws_grant.sh` |178| `awsCredentialExport` | Script personalizado que produz JSON com credenciais AWS (veja [configuração avançada de credenciais](/pt/amazon-bedrock#advanced-credential-configuration)) | `/bin/generate_aws_grant.sh` |

176| `blockedMarketplaces` | (Apenas configurações gerenciadas) Lista de negação de fontes de marketplace. Aplicado em adição de marketplace e em instalação, atualização, atualização e auto-atualização de plugin, então um marketplace adicionado antes da política ser definida não pode ser usado para buscar plugins. Fontes bloqueadas são verificadas antes do download, então nunca tocam o sistema de arquivos. Veja [Restrições de marketplace gerenciado](/pt/plugin-marketplaces#managed-marketplace-restrictions) | `[{ "source": "github", "repo": "untrusted/plugins" }]` |179| `blockedMarketplaces` | (Apenas configurações gerenciadas) Lista de negação de fontes de marketplace. Aplicado em adição de marketplace e em instalação, atualização, atualização e auto-atualização de plugin, então um marketplace adicionado antes da política ser definida não pode ser usado para buscar plugins. Fontes bloqueadas são verificadas antes do download, então nunca tocam o sistema de arquivos. Veja [Restrições de marketplace gerenciado](/pt/plugin-marketplaces#managed-marketplace-restrictions) | `[{ "source": "github", "repo": "untrusted/plugins" }]` |

177| `channelsEnabled` | (Apenas configurações gerenciadas) Permitir [channels](/pt/channels) para usuários de Team e Enterprise. Indefinido ou `false` bloqueia entrega de mensagens de canal independentemente do que os usuários passam para `--channels` | `true` |180| `channelsEnabled` | (Apenas configurações gerenciadas) Permitir [channels](/pt/channels) para a organização. Em planos Claude.ai Team e Enterprise, channels são bloqueados quando isto está indefinido ou `false`. Para contas [Anthropic Console](/pt/authentication#claude-console-authentication) usando autenticação de chave de API, channels são permitidos por padrão a menos que sua organização implante configurações gerenciadas, nesse caso esta chave deve ser definida como `true` | `true` |

178| `cleanupPeriodDays` | Arquivos de sessão mais antigos que este período são deletados na inicialização (padrão: 30 dias, mínimo 1). Definir como `0` é rejeitado com um erro de validação. Também controla o corte de idade para remoção automática de [worktrees de subagent órfãos](/pt/worktrees#clean-up-worktrees) na inicialização. Para desabilitar escritas de transcrição completamente, defina a variável de ambiente [`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](/pt/env-vars), ou em modo não interativo (`-p`) use a flag `--no-session-persistence` ou a opção SDK `persistSession: false`. | `20` |181| `cleanupPeriodDays` | Arquivos de sessão mais antigos que este período são deletados na inicialização (padrão: 30 dias, mínimo 1). Definir como `0` é rejeitado com um erro de validação. Também controla o corte de idade para remoção automática de [worktrees de subagent órfãos](/pt/worktrees#clean-up-worktrees) na inicialização. Para desabilitar escritas de transcrição completamente, defina a variável de ambiente [`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](/pt/env-vars), ou em modo não interativo (`-p`) use a flag `--no-session-persistence` ou a opção SDK `persistSession: false`. | `20` |

179| `companyAnnouncements` | Anúncio a ser exibido aos usuários na inicialização. Se múltiplos anúncios forem fornecidos, eles serão alternados aleatoriamente. | `["Welcome to Acme Corp! Review our code guidelines at docs.acme.com"]` |182| `companyAnnouncements` | Anúncio a ser exibido aos usuários na inicialização. Se múltiplos anúncios forem fornecidos, eles serão alternados aleatoriamente. | `["Welcome to Acme Corp! Review our code guidelines at docs.acme.com"]` |

180| `defaultShell` | Shell padrão para comandos `!` da caixa de entrada. Aceita `"bash"` (padrão) ou `"powershell"`. Definir `"powershell"` roteia comandos `!` interativos através do PowerShell no Windows. Requer `CLAUDE_CODE_USE_POWERSHELL_TOOL=1`. Veja [Ferramenta PowerShell](/pt/tools-reference#powershell-tool) | `"powershell"` |183| `defaultShell` | Shell padrão para comandos `!` da caixa de entrada. Aceita `"bash"` (padrão) ou `"powershell"`. Definir `"powershell"` roteia comandos `!` interativos através do PowerShell no Windows. Requer `CLAUDE_CODE_USE_POWERSHELL_TOOL=1`. Veja [Ferramenta PowerShell](/pt/tools-reference#powershell-tool) | `"powershell"` |

183| `disableAutoMode` | Defina como `"disable"` para impedir que o [modo automático](/pt/permission-modes#eliminate-prompts-with-auto-mode) seja ativado. Remove `auto` do ciclo `Shift+Tab` e rejeita `--permission-mode auto` na inicialização. Mais útil em [configurações gerenciadas](/pt/permissions#managed-settings) onde os usuários não podem substituir | `"disable"` |186| `disableAutoMode` | Defina como `"disable"` para impedir que o [modo automático](/pt/permission-modes#eliminate-prompts-with-auto-mode) seja ativado. Remove `auto` do ciclo `Shift+Tab` e rejeita `--permission-mode auto` na inicialização. Mais útil em [configurações gerenciadas](/pt/permissions#managed-settings) onde os usuários não podem substituir | `"disable"` |

184| `disableDeepLinkRegistration` | Defina como `"disable"` para impedir que o Claude Code registre o manipulador de protocolo `claude-cli://` com o sistema operacional na inicialização. [Deep links](/pt/deep-links) permitem que ferramentas externas abram uma sessão do Claude Code com um prompt pré-preenchido. Útil em ambientes onde o registro de manipulador de protocolo é restrito ou gerenciado separadamente | `"disable"` |187| `disableDeepLinkRegistration` | Defina como `"disable"` para impedir que o Claude Code registre o manipulador de protocolo `claude-cli://` com o sistema operacional na inicialização. [Deep links](/pt/deep-links) permitem que ferramentas externas abram uma sessão do Claude Code com um prompt pré-preenchido. Útil em ambientes onde o registro de manipulador de protocolo é restrito ou gerenciado separadamente | `"disable"` |

189| `disableRemoteControl` | {/* min-version: 2.1.128 */}Desabilitar [Controle Remoto](/pt/remote-control): bloqueia `claude remote-control`, a flag `--remote-control`, auto-start, e o toggle em sessão. Tipicamente colocado em [configurações gerenciadas](/pt/permissions#managed-settings) para aplicação de MDM por dispositivo, mas funciona de qualquer escopo. Requer Claude Code v2.1.128 ou posterior | `true` |

186| `disableSkillShellExecution` | Desabilitar execução de shell inline para blocos `` !`...` `` e ` ```! ` em [skills](/pt/skills) e comandos personalizados de fontes de usuário, projeto, plugin ou diretório adicional. Comandos são substituídos por `[shell command execution disabled by policy]` em vez de serem executados. Skills agrupadas e gerenciadas não são afetadas. Mais útil em [configurações gerenciadas](/pt/permissions#managed-settings) onde os usuários não podem substituir | `true` |190| `disableSkillShellExecution` | Desabilitar execução de shell inline para blocos `` !`...` `` e ` ```! ` em [skills](/pt/skills) e comandos personalizados de fontes de usuário, projeto, plugin ou diretório adicional. Comandos são substituídos por `[shell command execution disabled by policy]` em vez de serem executados. Skills agrupadas e gerenciadas não são afetadas. Mais útil em [configurações gerenciadas](/pt/permissions#managed-settings) onde os usuários não podem substituir | `true` |

187| `editorMode` | Modo de atalho de teclado para o prompt de entrada: `"normal"` ou `"vim"`. Padrão: `"normal"`. Aparece em `/config` como **Editor mode** | `"vim"` |191| `editorMode` | Modo de atalho de teclado para o prompt de entrada: `"normal"` ou `"vim"`. Padrão: `"normal"`. Aparece em `/config` como **Editor mode** | `"vim"` |

188| `effortLevel` | Persistir o [nível de esforço](/pt/model-config#adjust-effort-level) entre sessões. Aceita `"low"`, `"medium"`, `"high"`, ou `"xhigh"`. Escrito automaticamente quando você executa `/effort` com um desses valores. Veja [Ajustar nível de esforço](/pt/model-config#adjust-effort-level) para modelos suportados | `"xhigh"` |192| `effortLevel` | Persistir o [nível de esforço](/pt/model-config#adjust-effort-level) entre sessões. Aceita `"low"`, `"medium"`, `"high"`, ou `"xhigh"`. Escrito automaticamente quando você executa `/effort` com um desses valores. Veja [Ajustar nível de esforço](/pt/model-config#adjust-effort-level) para modelos suportados | `"xhigh"` |

550 },554 },

551 "extraKnownMarketplaces": {555 "extraKnownMarketplaces": {

552 "acme-tools": {556 "acme-tools": {

557 "source": {

553 "source": "github",558 "source": "github",

554 "repo": "acme-corp/claude-plugins"559 "repo": "acme-corp/claude-plugins"

555 }560 }

556 }561 }

562 }

557}563}

558```564```

559 565

568* **Configurações locais** (`.claude/settings.local.json`): Substituições por máquina (não confirmadas)574* **Configurações locais** (`.claude/settings.local.json`): Substituições por máquina (não confirmadas)

569* **Configurações gerenciadas** (`managed-settings.json`): Substituições de política em toda a organização que bloqueiam instalação em todos os escopos e ocultam o plugin do marketplace575* **Configurações gerenciadas** (`managed-settings.json`): Substituições de política em toda a organização que bloqueiam instalação em todos os escopos e ocultam o plugin do marketplace

570 576

577<Note>

578 As configurações de projeto têm precedência sobre as configurações de usuário, portanto, definir um plugin como `false` em `~/.claude/settings.json` não desabilita um plugin que o `.claude/settings.json` do projeto habilita. Para optar por não usar um plugin habilitado pelo projeto em sua máquina, defina-o como `false` em `.claude/settings.local.json` em vez disso.

579

580 Plugins forçadamente habilitados por configurações gerenciadas não podem ser desabilitados desta forma, pois as configurações gerenciadas substituem as configurações locais.

581</Note>

582

571**Exemplo**:583**Exemplo**:

572 584

573```json theme={null}585```json theme={null}

659* Apenas disponível em configurações gerenciadas (`managed-settings.json`)671* Apenas disponível em configurações gerenciadas (`managed-settings.json`)

660* Não pode ser substituída por configurações de usuário ou projeto (precedência mais alta)672* Não pode ser substituída por configurações de usuário ou projeto (precedência mais alta)

661* Aplicada ANTES de operações de rede/sistema de arquivos (fontes bloqueadas nunca executam)673* Aplicada ANTES de operações de rede/sistema de arquivos (fontes bloqueadas nunca executam)

662* Usa correspondência exata para especificações de fonte (incluindo `ref`, `path` para fontes git), exceto `hostPattern`, que usa correspondência regex674* Usa correspondência exata para especificações de fonte (incluindo `ref`, `path` para fontes git), exceto `hostPattern` e `pathPattern`, que usam correspondência regex

663 675

664**Comportamento de lista de permissões**:676**Comportamento de lista de permissões**:

665 677

669 681

670**Todos os tipos de fonte suportados**:682**Todos os tipos de fonte suportados**:

671 683

672A lista de permissões suporta múltiplos tipos de fonte de marketplace. A maioria das fontes usa correspondência exata, enquanto `hostPattern` usa correspondência regex contra o host do marketplace.684A lista de permissões suporta múltiplos tipos de fonte de marketplace. A maioria das fontes usa correspondência exata, enquanto `hostPattern` e `pathPattern` usam correspondência regex contra o host do marketplace e caminho do sistema de arquivos respectivamente.

673 685

6741. **Repositórios GitHub**:6861. **Repositórios GitHub**:

675 687

749* `url`: extrai nome de host da URL761* `url`: extrai nome de host da URL

750* `npm`, `file`, `directory`: não suportado para correspondência de padrão de host762* `npm`, `file`, `directory`: não suportado para correspondência de padrão de host

751 763

7648. **Correspondência de padrão de caminho**:

765

766```json theme={null}

767{ "source": "pathPattern", "pathPattern": "^/opt/approved/" }

768{ "source": "pathPattern", "pathPattern": ".*" }

769```

770

771Campos: `pathPattern` (obrigatório: padrão regex correspondido contra o campo `path` de fontes `file` e `directory`)

772

773Use correspondência de padrão de caminho para permitir marketplaces baseados em sistema de arquivos junto com restrições `hostPattern` para fontes de rede. Defina `".*"` para permitir todos os caminhos locais, ou um padrão mais estreito para restringir a diretórios específicos.

774

752**Exemplos de configuração**:775**Exemplos de configuração**:

753 776

754Exemplo: permitir apenas marketplaces específicos:777Exemplo: permitir apenas marketplaces específicos:

sub-agents.md +35 −10

Details

51 </Tab>51 </Tab>

52 52

53 <Tab title="Plan">53 <Tab title="Plan">

~~54 Um agente de pesquisa usado durante [plan mode](/pt/common-workflows#use-plan-mode-for-safe-code-analysis) para reunir contexto antes de apresentar um plano.~~54 Um agente de pesquisa usado durante [plan mode](/pt/permission-modes#analyze-before-you-edit-with-plan-mode) para reunir contexto antes de apresentar um plano.

55 55

56 * **Model**: Herda da conversa principal56 * **Model**: Herda da conversa principal

57 * **Tools**: Ferramentas somente leitura (acesso negado a ferramentas Write e Edit)57 * **Tools**: Ferramentas somente leitura (acesso negado a ferramentas Write e Edit)

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

80 </Tab>80 </Tab>

81</Tabs>81</Tabs>

82 82

180 180

181**Subagentes definidos por CLI** são passados como JSON ao iniciar Claude Code. Eles existem apenas para essa sessão e não são salvos em disco, tornando-os úteis para testes rápidos ou scripts de automação. Você pode definir múltiplos subagentes em uma única chamada `--agents`:181**Subagentes definidos por CLI** são passados como JSON ao iniciar Claude Code. Eles existem apenas para essa sessão e não são salvos em disco, tornando-os úteis para testes rápidos ou scripts de automação. Você pode definir múltiplos subagentes em uma única chamada `--agents`:

182 182

183```bash theme={null}183<Tabs>

184claude --agents '{184 <Tab title="macOS, Linux, WSL">

185 ```bash theme={null}

186 claude --agents '{

185 "code-reviewer": {187 "code-reviewer": {

186 "description": "Expert code reviewer. Use proactively after code changes.",188 "description": "Expert code reviewer. Use proactively after code changes.",

187 "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",189 "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",

192 "description": "Debugging specialist for errors and test failures.",194 "description": "Debugging specialist for errors and test failures.",

193 "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."195 "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."

194 }196 }

195}'197 }'

196```198 ```

199 </Tab>

200

201 <Tab title="Windows PowerShell">

202 ```powershell theme={null}

203 claude --agents @'

204 {

205 "code-reviewer": {

206 "description": "Expert code reviewer. Use proactively after code changes.",

207 "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",

208 "tools": ["Read", "Grep", "Glob", "Bash"],

209 "model": "sonnet"

210 },

211 "debugger": {

212 "description": "Debugging specialist for errors and test failures.",

213 "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."

214 }

215 }

216 '@

217 ```

218 </Tab>

219</Tabs>

197 220

198O flag `--agents` aceita JSON com os mesmos campos de [frontmatter](#supported-frontmatter-fields) que subagentes baseados em arquivo: `description`, `prompt`, `tools`, `disallowedTools`, `model`, `permissionMode`, `mcpServers`, `hooks`, `maxTurns`, `skills`, `initialPrompt`, `memory`, `effort`, `background`, `isolation` e `color`. Use `prompt` para o prompt de sistema, equivalente ao corpo markdown em subagentes baseados em arquivo.221O flag `--agents` aceita JSON com os mesmos campos de [frontmatter](#supported-frontmatter-fields) que subagentes baseados em arquivo: `description`, `prompt`, `tools`, `disallowedTools`, `model`, `permissionMode`, `mcpServers`, `hooks`, `maxTurns`, `skills`, `initialPrompt`, `memory`, `effort`, `background`, `isolation` e `color`. Use `prompt` para o prompt de sistema, equivalente ao corpo markdown em subagentes baseados em arquivo.

199 222

212Arquivos de subagente usam frontmatter YAML para configuração, seguido pelo prompt de sistema em Markdown:235Arquivos de subagente usam frontmatter YAML para configuração, seguido pelo prompt de sistema em Markdown:

213 236

214<Note>237<Note>

215 Subagentes são carregados no início da sessão. Se você criar um subagente adicionando manualmente um arquivo, reinicie sua sessão ou use `/agents` para carregá-lo imediatamente.238 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.

216</Note>239</Note>

217 240

218```markdown theme={null}241```markdown theme={null}

250| `memory` | No | [Escopo de memória persistente](#enable-persistent-memory): `user`, `project`, ou `local`. Habilita aprendizado entre sessões |273| `memory` | No | [Escopo de memória persistente](#enable-persistent-memory): `user`, `project`, ou `local`. Habilita aprendizado entre sessões |

251| `background` | No | Defina como `true` para sempre executar este subagente como uma [tarefa em background](#run-subagents-in-foreground-or-background). Padrão: `false` |274| `background` | No | Defina como `true` para sempre executar este subagente como uma [tarefa em background](#run-subagents-in-foreground-or-background). Padrão: `false` |

252| `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 |275| `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 |

253| `isolation` | No | Defina como `worktree` para executar o subagente em um [git worktree](/pt/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees) temporário, dando-lhe uma cópia isolada do repositório. O worktree é automaticamente limpo se o subagente não fizer alterações |276| `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. O worktree é automaticamente limpo se o subagente não fizer alterações |

254| `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` |277| `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` |

255| `initialPrompt` | No | Auto-enviado como o primeiro turno do usuário quando este agente é executado como o agente da sessão principal (via `--agent` ou a configuração `agent`). [Comandos](/pt/commands) e [skills](/pt/skills) são processados. Preposto a qualquer prompt fornecido pelo usuário |278| `initialPrompt` | No | Auto-enviado como o primeiro turno do usuário quando este agente é executado como o agente da sessão principal (via `--agent` ou a configuração `agent`). [Comandos](/pt/commands) e [skills](/pt/skills) são processados. Preposto a qualquer prompt fornecido pelo usuário |

256 279

484exit 0507exit 0

485```508```

486 509

487Veja [Hook input](/pt/hooks#pretooluse-input) para o schema de entrada completo e [exit codes](/pt/hooks#exit-code-output) para como códigos de saída afetam o comportamento.510Veja [Hook input](/pt/hooks#pretooluse-input) para o schema de entrada completo e [exit codes](/pt/hooks#exit-code-output) para como códigos de saída afetam o comportamento. No Windows, escreva scripts de hook em PowerShell e adicione `shell: powershell` à entrada de hook conforme mostrado em [executando hooks em PowerShell](/pt/hooks#windows-powershell-tool).

488 511

489#### Desabilitar subagentes específicos512#### Desabilitar subagentes específicos

490 513

994exit 01017exit 0

995```1018```

996 1019

997Torne o script executável:1020No macOS e Linux, torne o script executável:

998 1021

999```bash theme={null}1022```bash theme={null}

1000chmod +x ./scripts/validate-readonly-query.sh1023chmod +x ./scripts/validate-readonly-query.sh

1001```1024```

1002 1025

1026No Windows, escreva o script de validação em PowerShell e adicione `shell: powershell` à entrada de hook. Veja [executando hooks em PowerShell](/pt/hooks#windows-powershell-tool).

1027

1003O hook recebe JSON via stdin com o comando Bash em `tool_input.command`. Código de saída 2 bloqueia a operação e alimenta a mensagem de erro de volta para Claude. Veja [Hooks](/pt/hooks#exit-code-output) para detalhes sobre códigos de saída e [Hook input](/pt/hooks#pretooluse-input) para o schema de entrada completo.1028O hook recebe JSON via stdin com o comando Bash em `tool_input.command`. Código de saída 2 bloqueia a operação e alimenta a mensagem de erro de volta para Claude. Veja [Hooks](/pt/hooks#exit-code-output) para detalhes sobre códigos de saída e [Hook input](/pt/hooks#pretooluse-input) para o schema de entrada completo.

1004 1029

1005## Próximos passos1030## Próximos passos

vs-code.md +17 −7

Details

95* **Permission modes**: clique no indicador de modo na parte inferior da caixa de prompt para alternar modos. No modo normal, Claude pede permissão antes de cada ação. Em Plan Mode, Claude descreve o que fará e aguarda aprovação antes de fazer alterações. VS Code abre automaticamente o plano como um documento markdown completo onde você pode adicionar comentários inline para fornecer feedback antes de Claude começar. Em modo auto-accept, Claude faz edições sem perguntar. Defina o padrão nas configurações do VS Code em `claudeCode.initialPermissionMode`.95* **Permission modes**: clique no indicador de modo na parte inferior da caixa de prompt para alternar modos. No modo normal, Claude pede permissão antes de cada ação. Em Plan Mode, Claude descreve o que fará e aguarda aprovação antes de fazer alterações. VS Code abre automaticamente o plano como um documento markdown completo onde você pode adicionar comentários inline para fornecer feedback antes de Claude começar. Em modo auto-accept, Claude faz edições sem perguntar. Defina o padrão nas configurações do VS Code em `claudeCode.initialPermissionMode`.

96* **Command menu**: clique em `/` ou digite `/` para abrir o menu de comandos. As opções incluem anexar arquivos, alternar modelos, alternar pensamento estendido, visualizar uso de plano (`/usage`) e iniciar uma sessão de [Remote Control](/pt/remote-control) (`/remote-control`). A seção Customize fornece acesso a MCP servers, hooks, memory, permissions e plugins. Itens com um ícone de terminal abrem no terminal integrado.96* **Command menu**: clique em `/` ou digite `/` para abrir o menu de comandos. As opções incluem anexar arquivos, alternar modelos, alternar pensamento estendido, visualizar uso de plano (`/usage`) e iniciar uma sessão de [Remote Control](/pt/remote-control) (`/remote-control`). A seção Customize fornece acesso a MCP servers, hooks, memory, permissions e plugins. Itens com um ícone de terminal abrem no terminal integrado.

97* **Context indicator**: a caixa de prompt mostra quanto da context window do Claude você está usando. Claude compacta automaticamente quando necessário, ou você pode executar `/compact` manualmente.97* **Context indicator**: a caixa de prompt mostra quanto da context window do Claude você está usando. Claude compacta automaticamente quando necessário, ou você pode executar `/compact` manualmente.

98* **Extended thinking**: permite que Claude gaste mais tempo raciocinando sobre problemas complexos. Alterne-o via menu de comandos (`/`). O raciocínio do Claude aparece na conversa como blocos recolhidos: clique em um bloco para lê-lo, ou pressione `Ctrl+O` para expandir ou recolher cada bloco de pensamento na sessão. Consulte [Extended thinking](/pt/common-workflows#use-extended-thinking-thinking-mode) para detalhes.98* **Extended thinking**: permite que Claude gaste mais tempo raciocinando sobre problemas complexos. Alterne-o via menu de comandos (`/`). O raciocínio do Claude aparece na conversa como blocos recolhidos: clique em um bloco para lê-lo, ou pressione `Ctrl+O` para expandir ou recolher cada bloco de pensamento na sessão. Consulte [Extended thinking](/pt/model-config#extended-thinking) para detalhes.

99* **Multi-line input**: pressione `Shift+Enter` para adicionar uma nova linha sem enviar. Isso também funciona na entrada de texto livre "Other" de diálogos de pergunta.99* **Multi-line input**: pressione `Shift+Enter` para adicionar uma nova linha sem enviar. Isso também funciona na entrada de texto livre "Other" de diálogos de pergunta.

100 100

101### Reference files and folders101### Reference files and folders

115 115

116### Resume past conversations116### Resume past conversations

117 117

118Clique no botão **Session history** na parte superior do painel Claude Code para acessar seu histórico de conversas. Você pode pesquisar por palavra-chave ou navegar por tempo (Today, Yesterday, Last 7 days, etc.). Clique em qualquer conversa para retomá-la com o histórico completo de mensagens. Novas sessões recebem títulos gerados por IA com base em sua primeira mensagem. Passe o mouse sobre uma sessão para revelar ações de renomear e remover: renomeie para dar um título descritivo, ou remova para deletá-la da lista. Para mais sobre retomar sessões, consulte [Common workflows](/pt/common-workflows#resume-previous-conversations).118Clique no botão **Session history** na parte superior do painel Claude Code para acessar seu histórico de conversas. Você pode pesquisar por palavra-chave ou navegar por tempo (Today, Yesterday, Last 7 days, etc.). Clique em qualquer conversa para retomá-la com o histórico completo de mensagens. Novas sessões recebem títulos gerados por IA com base em sua primeira mensagem. Passe o mouse sobre uma sessão para revelar ações de renomear e remover: renomeie para dar um título descritivo, ou remova para deletá-la da lista. Para mais sobre retomar sessões, consulte [Manage sessions](/pt/sessions).

119 119

120### Resume remote sessions from Claude.ai120### Resume remote sessions from Claude.ai

121 121

375 375

376Para gerenciar MCP servers sem sair do VS Code, digite `/mcp` no painel de chat. O diálogo de gerenciamento de MCP permite que você habilite ou desabilite servidores, reconecte a um servidor e gerencie autenticação OAuth. Consulte a [MCP documentation](/pt/mcp) para servidores disponíveis.376Para gerenciar MCP servers sem sair do VS Code, digite `/mcp` no painel de chat. O diálogo de gerenciamento de MCP permite que você habilite ou desabilite servidores, reconecte a um servidor e gerencie autenticação OAuth. Consulte a [MCP documentation](/pt/mcp) para servidores disponíveis.

377 377

378## Work with git378## Trabalhar com git

379 379

380Claude Code se integra com git para ajudar com fluxos de trabalho de controle de versão diretamente no VS Code. Peça ao Claude para fazer commit de alterações, criar pull requests ou trabalhar em branches.380Claude Code se integra com git para ajudar com fluxos de trabalho de controle de versão diretamente no VS Code. Peça ao Claude para fazer commit de alterações, criar pull requests ou trabalhar em branches.

381 381

382### Create commits and pull requests382### Criar commits e pull requests

383 383

384Claude pode preparar alterações, escrever mensagens de commit e criar pull requests com base em seu trabalho:384Claude pode preparar alterações, escrever mensagens de commit e criar pull requests com base em seu trabalho:

385 385

391 391

392Ao criar pull requests, Claude gera descrições com base nas alterações de código reais e pode adicionar contexto sobre testes ou decisões de implementação.392Ao criar pull requests, Claude gera descrições com base nas alterações de código reais e pode adicionar contexto sobre testes ou decisões de implementação.

393 393

394### Use git worktrees for parallel tasks394### Usar git worktrees para tarefas paralelas

395 395

396Use a flag `--worktree` (`-w`) para iniciar Claude em um worktree isolado com seus próprios arquivos e branch:396Use a flag `--worktree` (`-w`) para iniciar Claude em um worktree isolado com seus próprios arquivos e branch:

397 397

399claude --worktree feature-auth399claude --worktree feature-auth

400```400```

401 401

402Cada worktree mantém estado de arquivo independente enquanto compartilha histórico git. Isso evita que instâncias do Claude interfiram uma com a outra ao trabalhar em diferentes tarefas. Para mais detalhes, consulte [Run parallel sessions with Git worktrees](/pt/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees).402Cada worktree mantém estado de arquivo independente enquanto compartilha histórico git. Isso evita que instâncias do Claude interfiram uma com a outra ao trabalhar em diferentes tarefas. Para mais detalhes, consulte [Run parallel sessions with Git worktrees](/pt/worktrees).

403 403

404## Use third-party providers404## Use third-party providers

405 405

456 456

457<a id="troubleshooting" />457<a id="troubleshooting" />

458 458

459## Fix common issues459## Corrigir problemas comuns

460 460

461### Extension won't install461### Extension won't install

462 462

476 476

477Alternativamente, clique em "✱ Claude Code" na **Status Bar** (canto inferior direito). Isso funciona mesmo sem um arquivo aberto. Você também pode usar a **Command Palette** (`Cmd+Shift+P` / `Ctrl+Shift+P`) e digitar "Claude Code".477Alternativamente, clique em "✱ Claude Code" na **Status Bar** (canto inferior direito). Isso funciona mesmo sem um arquivo aberto. Você também pode usar a **Command Palette** (`Cmd+Shift+P` / `Ctrl+Shift+P`) e digitar "Claude Code".

478 478

479### Cmd+Esc does nothing on macOS

480

481No macOS Tahoe e posterior, o atalho do sistema Game Overlay está vinculado a `Cmd+Esc` por padrão e intercepta a tecla antes que chegue ao VS Code. Para liberar o atalho:

482

4831. Abra System Settings

4842. Vá para Keyboard, depois Keyboard Shortcuts, depois Game Controllers

4853. Desmarque a caixa de seleção Game Overlay

486

487Alternativamente, reassine a extensão para uma chave diferente: abra o editor de [Keyboard Shortcuts](https://code.visualstudio.com/docs/configure/keybindings) do VS Code (`Cmd+K Cmd+S`), procure por `Claude Code: Focus input`, e atribua uma nova vinculação.

488

479### Claude Code never responds489### Claude Code never responds

480 490

481Se Claude Code não está respondendo aos seus prompts:491Se Claude Code não está respondendo aos seus prompts:

Documentation 2026-05-04 22:58 UTC to 2026-05-05 23:00 UTC