Documentation — Spybara

agent-sdk/file-checkpointing.md +22 −11

Details

14 14

15## Como o checkpointing funciona15## Como o checkpointing funciona

16 16

17Quando você ativa o checkpointing de arquivo, o SDK cria backups de arquivos antes de modificá-los através das ferramentas Write, Edit ou NotebookEdit. As mensagens do usuário no fluxo de resposta incluem um UUID de checkpoint que você pode usar como ponto de restauração.17Quando você ativa o checkpointing de arquivo, o SDK cria backups de arquivos antes de modificá-los através das ferramentas Write, Edit ou NotebookEdit. Cada prompt que inicia um turno é um checkpoint, e o UUID da mensagem do usuário correspondente é o ponto de restauração.

18 18

19> [!NOTE]19> [!NOTE]

20>20>

147 147

148**2. Capturar UUID de checkpoint e ID de sessão**148**2. Capturar UUID de checkpoint e ID de sessão**

149 149

150Com a opção `replay-user-messages` definida, cada mensagem do usuário no fluxo de resposta tem um UUID que serve como um checkpoint.150Com a opção `replay-user-messages` definida, a mensagem do usuário de cada prompt que inicia um turno tem um UUID que serve como um checkpoint. Mensagens do usuário que carregam resultados de ferramentas também têm um UUID, mas ele não é um checkpoint.

151 151

152Para a maioria dos casos de uso, capture o UUID da primeira mensagem do usuário (`message.uuid`); reverter para ele restaura os arquivos rastreados para seu estado original. Para armazenar múltiplos checkpoints e reverter para estados intermediários, veja [Múltiplos pontos de restauração](#multiple-restore-points).152Para a maioria dos casos de uso, capture o UUID da primeira mensagem do usuário (`message.uuid`); reverter para ele restaura os arquivos rastreados para seu estado original. Para armazenar múltiplos checkpoints e reverter para estados intermediários, veja [Múltiplos pontos de restauração](#multiple-restore-points).

153 153

171 171

172### Checkpoint antes de operações arriscadas172### Checkpoint antes de operações arriscadas

173 173

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

175 175

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

177 177

193 await client.query("Refactor the authentication module")193 await client.query("Refactor the authentication module")

194 194

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

196 # Update checkpoint before each agent turn starts196 # Update checkpoint at each prompt you send; a tool result isn't one

197 # This overwrites the previous checkpoint. Only keep the latest197 # This overwrites the previous checkpoint. Only keep the latest

198 if isinstance(message, UserMessage) and message.uuid:198 if (

199 isinstance(message, UserMessage)

200 and message.uuid

201 and message.tool_use_result is None

202 and message.parent_tool_use_id is None

203 ):

199 safe_checkpoint = message.uuid204 safe_checkpoint = message.uuid

200 205

201 # Decide when to revert based on your own logic206 # Decide when to revert based on your own logic

225 let safeCheckpoint: string | undefined;230 let safeCheckpoint: string | undefined;

226 231

227 for await (const message of response) {232 for await (const message of response) {

228 // Update checkpoint before each agent turn starts233 // Update checkpoint at each prompt you send; a tool result isn't one

229 // This overwrites the previous checkpoint. Only keep the latest234 // This overwrites the previous checkpoint. Only keep the latest

230 if (message.type === "user" && message.uuid) {235 if (message.type === "user" && "isReplay" in message && message.isReplay && message.uuid) {

231 safeCheckpoint = message.uuid;236 safeCheckpoint = message.uuid;

232 }237 }

233 238

246 251

247### Múltiplos pontos de restauração252### Múltiplos pontos de restauração

248 253

249Se Claude fizer alterações em múltiplos turnos, você pode querer reverter para um ponto específico em vez de voltar completamente. Por exemplo, se Claude refatorar um arquivo no turno um e adicionar testes no turno dois, você pode querer manter a refatoração mas desfazer os testes.254Se Claude fizer alterações ao longo de vários prompts, você pode querer reverter para um ponto específico em vez de voltar completamente. Por exemplo, se o seu primeiro prompt refatorar um arquivo e o segundo adicionar testes, reverta para o checkpoint do seu segundo prompt para manter a refatoração e desfazer os testes.

250 255

251Este padrão armazena todos os UUIDs de checkpoint em um array com metadados. Após a sessão ser concluída, você pode reverter para qualquer checkpoint anterior:256Este padrão armazena cada UUID de checkpoint em um array com metadados. Após a sessão ser concluída, você pode reverter para qualquer checkpoint anterior:

252 257

253```python Python theme={null}258```python Python theme={null}

254import asyncio259import asyncio

284 await client.query("Refactor the authentication module")289 await client.query("Refactor the authentication module")

285 290

286 async for message in client.receive_response():291 async for message in client.receive_response():

287 if isinstance(message, UserMessage) and message.uuid:292 if (

293 isinstance(message, UserMessage)

294 and message.uuid

295 and message.tool_use_result is None

296 and message.parent_tool_use_id is None

297 ):

288 checkpoints.append(298 checkpoints.append(

289 Checkpoint(299 Checkpoint(

290 id=message.uuid,300 id=message.uuid,

338 348

339 try {349 try {

340 for await (const message of response) {350 for await (const message of response) {

341 if (message.type === "user" && message.uuid) {351 if (message.type === "user" && "isReplay" in message && message.isReplay && message.uuid) {

342 checkpoints.push({352 checkpoints.push({

343 id: message.uuid,353 id: message.uuid,

344 description: `After turn ${checkpoints.length + 1}`,354 description: `After turn ${checkpoints.length + 1}`,

638 648

639* O checkpointing de arquivo não foi ativado na sessão original (`enable_file_checkpointing` ou `enableFileCheckpointing` não foi definido como `true`)649* O checkpointing de arquivo não foi ativado na sessão original (`enable_file_checkpointing` ou `enableFileCheckpointing` não foi definido como `true`)

640* A sessão não foi concluída adequadamente antes de tentar retomar e reverter650* A sessão não foi concluída adequadamente antes de tentar retomar e reverter

651* O UUID veio de uma mensagem do usuário que carrega um resultado de ferramenta, o que não é um checkpoint

641 652

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

643 654

agent-sdk/modifying-system-prompts.md +1 −1

Details

agent-sdk/python.md +1 −1

Details

875| `allowed_tools` | `list[str]` | `[]` | Ferramentas para aprovar automaticamente sem solicitar, exceto leituras de [caminhos de rede](https://code.claude.com/docs/pt/permissions.md#network-paths). Isto não restringe Claude apenas a estas ferramentas. Se você nomear uma das [ferramentas de rastreamento de tarefas](https://code.claude.com/docs/pt/agent-sdk/todo-tracking.md#model-availability) aqui, Claude Code também as habilita na sessão. Outras ferramentas não listadas caem em `permission_mode` e `can_use_tool`. Use `disallowed_tools` para bloquear ferramentas. Veja [Permissões](https://code.claude.com/docs/pt/agent-sdk/permissions.md#allow-and-deny-rules) |875| `allowed_tools` | `list[str]` | `[]` | Ferramentas para aprovar automaticamente sem solicitar, exceto leituras de [caminhos de rede](https://code.claude.com/docs/pt/permissions.md#network-paths). Isto não restringe Claude apenas a estas ferramentas. Se você nomear uma das [ferramentas de rastreamento de tarefas](https://code.claude.com/docs/pt/agent-sdk/todo-tracking.md#model-availability) aqui, Claude Code também as habilita na sessão. Outras ferramentas não listadas caem em `permission_mode` e `can_use_tool`. Use `disallowed_tools` para bloquear ferramentas. Veja [Permissões](https://code.claude.com/docs/pt/agent-sdk/permissions.md#allow-and-deny-rules) |

876| `system_prompt` | `str \| SystemPromptPreset \| SystemPromptCustom \| SystemPromptFile \| None` | `None` | Configuração de prompt do sistema. Passe uma string para um prompt personalizado, `{"type": "preset", "preset": "claude_code"}` para o prompt do sistema do Claude Code com `"append"` opcional, `{"type": "custom", "prompt": "..."}` para um prompt personalizado que também pode definir `"snapshot"`, ou `{"type": "file", "path": "..."}` para carregar um prompt grande do disco. Veja [`SystemPromptPreset`](#systempromptpreset), [`SystemPromptCustom`](#systempromptcustom), e [`SystemPromptFile`](#systempromptfile) |876| `system_prompt` | `str \| SystemPromptPreset \| SystemPromptCustom \| SystemPromptFile \| None` | `None` | Configuração de prompt do sistema. Passe uma string para um prompt personalizado, `{"type": "preset", "preset": "claude_code"}` para o prompt do sistema do Claude Code com `"append"` opcional, `{"type": "custom", "prompt": "..."}` para um prompt personalizado que também pode definir `"snapshot"`, ou `{"type": "file", "path": "..."}` para carregar um prompt grande do disco. Veja [`SystemPromptPreset`](#systempromptpreset), [`SystemPromptCustom`](#systempromptcustom), e [`SystemPromptFile`](#systempromptfile) |

877| `mcp_servers` | `dict[str, McpServerConfig] \| str \| Path` | `{}` | Configurações de servidor MCP ou caminho para arquivo de configuração |877| `mcp_servers` | `dict[str, McpServerConfig] \| str \| Path` | `{}` | Configurações de servidor MCP ou caminho para arquivo de configuração |

878| `strict_mcp_config` | `bool` | `False` | Quando `True`, use apenas os servidores passados em `mcp_servers` e ignore o projeto `.mcp.json`, configurações do usuário, servidores MCP fornecidos por plugins, e [conectores claude.ai](https://code.claude.com/docs/pt/mcp.md#use-mcp-servers-from-claude-ai). Mapeia para a flag CLI `--strict-mcp-config` |878| `strict_mcp_config` | `bool` | `False` | Quando `True`, use os servidores passados em `mcp_servers` e ignore o projeto `.mcp.json`, configurações do usuário, servidores MCP fornecidos por plugins, e [conectores claude.ai](https://code.claude.com/docs/pt/mcp.md#use-mcp-servers-from-claude-ai). Mapeia para a flag CLI `--strict-mcp-config` |

agent-sdk/quickstart.md +2 −0

Details

342 342

343Para limitar as ferramentas integradas do agente a um desses conjuntos, passe-o como `tools`. Se, em vez disso, você listar um conjunto em `allowedTools`, você [pré-aprova essas ferramentas](https://code.claude.com/docs/pt/agent-sdk/custom-tools.md#configure-allowed-tools), e o agente ainda pode chamar as outras, sujeito ao seu modo de permissão.

344

343**Modos de permissão** controlam quanto de supervisão humana você deseja. O SDK avalia o modo ativo junto com suas regras de permissão e negação em uma ordem fixa, descrita em [Como as permissões são avaliadas](https://code.claude.com/docs/pt/agent-sdk/permissions.md#how-permissions-are-evaluated). Para a lista completa de modos, seu comportamento e quando usar cada um, veja [Modo de permissão em Como o loop do agente funciona](https://code.claude.com/docs/pt/agent-sdk/agent-loop.md#permission-mode).345**Modos de permissão** controlam quanto de supervisão humana você deseja. O SDK avalia o modo ativo junto com suas regras de permissão e negação em uma ordem fixa, descrita em [Como as permissões são avaliadas](https://code.claude.com/docs/pt/agent-sdk/permissions.md#how-permissions-are-evaluated). Para a lista completa de modos, seu comportamento e quando usar cada um, veja [Modo de permissão em Como o loop do agente funciona](https://code.claude.com/docs/pt/agent-sdk/agent-loop.md#permission-mode).

344 346

345## Próximos passos347## Próximos passos

agent-sdk/subagents.md +1 −1

Details

148| `disallowedTools` | `string[]` | Não | Array de nomes de ferramentas a remover do conjunto de ferramentas do agente. Padrões de nível de servidor MCP também são aceitos: `mcp__server` ou `mcp__server__*` remove todas as ferramentas desse servidor, e `mcp__*` remove todas as ferramentas MCP de qualquer servidor |148| `disallowedTools` | `string[]` | Não | Array de nomes de ferramentas a remover do conjunto de ferramentas do agente. Padrões de nível de servidor MCP também são aceitos: `mcp__server` ou `mcp__server__*` remove todas as ferramentas desse servidor, e `mcp__*` remove todas as ferramentas MCP de qualquer servidor |

149| `model` | `string` | Não | Substituição de modelo para este agente. Aceita um alias como `'fable'`, `'opus'`, `'sonnet'`, `'haiku'`, `'inherit'`, ou um ID de modelo completo. `'inherit'` usa o modelo principal. Quando você o omite, Claude Code escolhe o modelo na [ordem de modelo de subagente](https://code.claude.com/docs/pt/sub-agents.md#choose-a-model) |149| `model` | `string` | Não | Substituição de modelo para este agente. Aceita um alias como `'fable'`, `'opus'`, `'sonnet'`, `'haiku'`, `'inherit'`, ou um ID de modelo completo. `'inherit'` usa o modelo do agente que gerou este. Quando você omite `model`, Claude Code escolhe o modelo na [ordem de modelo de subagente](https://code.claude.com/docs/pt/sub-agents.md#choose-a-model) |

150| `skills` | `string[]` | Não | Lista de nomes de skills a pré-carregar no contexto do agente na inicialização. No máximo os [primeiros 32 nomes distintos](https://code.claude.com/docs/pt/sub-agents.md#preload-skills-into-subagents) da lista são pré-carregados. Skills não listadas permanecem invocáveis através da ferramenta Skill |150| `skills` | `string[]` | Não | Lista de nomes de skills a pré-carregar no contexto do agente na inicialização. No máximo os [primeiros 32 nomes distintos](https://code.claude.com/docs/pt/sub-agents.md#preload-skills-into-subagents) da lista são pré-carregados. Skills não listadas permanecem invocáveis através da ferramenta Skill |

agent-sdk/typescript.md +2 −2

Details

589| `skills` | `string[] \| 'all'` | `undefined` | Skills disponíveis para a sessão. Passe `'all'` para habilitar todas as skills descobertas, ou uma lista de nomes de skills. Passe apenas nomes exatos. No Agent SDK v0.3.221 ou posterior, o SDK rejeita nomes malformados e em formato curinga com um erro antes de iniciar o processo do Claude Code. Quando definido, o SDK adiciona a ferramenta Skill a `allowedTools` automaticamente. Se você também passar `tools`, inclua `'Skill'` nessa lista. Consulte [Skills](https://code.claude.com/docs/pt/agent-sdk/skills.md) |589| `skills` | `string[] \| 'all'` | `undefined` | Skills disponíveis para a sessão. Passe `'all'` para habilitar todas as skills descobertas, ou uma lista de nomes de skills. Passe apenas nomes exatos. No Agent SDK v0.3.221 ou posterior, o SDK rejeita nomes malformados e em formato curinga com um erro antes de iniciar o processo do Claude Code. Quando definido, o SDK adiciona a ferramenta Skill a `allowedTools` automaticamente. Se você também passar `tools`, inclua `'Skill'` nessa lista. Consulte [Skills](https://code.claude.com/docs/pt/agent-sdk/skills.md) |

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

592| `strictMcpConfig` | `boolean` | `false` | Usa apenas os servidores passados em `mcpServers` e ignora o `.mcp.json` do projeto, as configurações de usuário, os servidores MCP fornecidos por plugins e os [conectores do claude.ai](https://code.claude.com/docs/pt/mcp.md#use-mcp-servers-from-claude-ai) |592| `strictMcpConfig` | `boolean` | `false` | Usa os servidores passados em `mcpServers` e ignora o `.mcp.json` do projeto, as configurações de usuário, os servidores MCP fornecidos por plugins e os [conectores do claude.ai](https://code.claude.com/docs/pt/mcp.md#use-mcp-servers-from-claude-ai) |

593| `systemPrompt` | `string \| string[] \| { type: 'custom'; prompt: string \| string[]; snapshot?: boolean } \| { type: 'preset'; preset: 'claude_code'; append?: string; excludeDynamicSections?: boolean; snapshot?: boolean }` | `undefined` (prompt mínimo) | Configuração do system prompt. Passe uma string para um prompt personalizado, ou `{ type: 'preset', preset: 'claude_code' }` para usar o system prompt do Claude Code. Passe um array de strings com a constante exportada `SYSTEM_PROMPT_DYNAMIC_BOUNDARY` entre as partes estática e por requisição para [armazenar em cache a parte estática de um prompt personalizado](https://code.claude.com/docs/pt/agent-sdk/modifying-system-prompts.md#cache-the-static-part-of-a-custom-prompt). Ao usar a forma de objeto preset, adicione `append` para estendê-lo com instruções adicionais e defina `excludeDynamicSections: true` para mover o contexto por sessão para a primeira mensagem do usuário, obtendo [melhor reutilização do cache de prompt entre máquinas](https://code.claude.com/docs/pt/agent-sdk/modifying-system-prompts.md#improve-prompt-caching-across-users-and-machines). Defina `snapshot: false` para reconstruir o prompt a cada requisição em vez de [reutilizar o prompt que a sessão registrou em sua primeira requisição](https://code.claude.com/docs/pt/agent-sdk/modifying-system-prompts.md#change-the-prompt-of-an-existing-session). Para definir `snapshot` em um prompt personalizado, passe a forma `{ type: 'custom', prompt }`. A forma `{ type: 'custom' }` e o campo `snapshot` exigem o TypeScript Agent SDK v0.3.257 ou posterior |593| `systemPrompt` | `string \| string[] \| { type: 'custom'; prompt: string \| string[]; snapshot?: boolean } \| { type: 'preset'; preset: 'claude_code'; append?: string; excludeDynamicSections?: boolean; snapshot?: boolean }` | `undefined` (prompt mínimo) | Configuração do system prompt. Passe uma string para um prompt personalizado, ou `{ type: 'preset', preset: 'claude_code' }` para usar o system prompt do Claude Code. Passe um array de strings com a constante exportada `SYSTEM_PROMPT_DYNAMIC_BOUNDARY` entre as partes estática e por requisição para [armazenar em cache a parte estática de um prompt personalizado](https://code.claude.com/docs/pt/agent-sdk/modifying-system-prompts.md#cache-the-static-part-of-a-custom-prompt). Ao usar a forma de objeto preset, adicione `append` para estendê-lo com instruções adicionais e defina `excludeDynamicSections: true` para mover o contexto por sessão para a primeira mensagem do usuário, obtendo [melhor reutilização do cache de prompt entre máquinas](https://code.claude.com/docs/pt/agent-sdk/modifying-system-prompts.md#improve-prompt-caching-across-users-and-machines). Defina `snapshot: false` para reconstruir o prompt a cada requisição em vez de [reutilizar o prompt que a sessão registrou em sua primeira requisição](https://code.claude.com/docs/pt/agent-sdk/modifying-system-prompts.md#change-the-prompt-of-an-existing-session). Para definir `snapshot` em um prompt personalizado, passe a forma `{ type: 'custom', prompt }`. A forma `{ type: 'custom' }` e o campo `snapshot` exigem o TypeScript Agent SDK v0.3.257 ou posterior |

594| `taskBudget` | `{ total: number }` | `undefined` | *Alpha.* Orçamento de tarefa do lado da API em tokens. Quando definido, o modelo é informado de seu orçamento de tokens restante para que possa dosar o uso de ferramentas e concluir antes do limite |594| `taskBudget` | `{ total: number }` | `undefined` | *Alpha.* Orçamento de tarefa do lado da API em tokens. Quando definido, o modelo é informado de seu orçamento de tokens restante para que possa dosar o uso de ferramentas e concluir antes do limite |

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

1285| `tools` | Não | Array de nomes de ferramentas permitidas. Se omitido, herda todas as [ferramentas disponíveis para subagentes](https://code.claude.com/docs/pt/sub-agents.md#available-tools). Para pré-carregar Skills no contexto do agente, use o campo `skills` em vez de listar `'Skill'` aqui |1285| `tools` | Não | Array de nomes de ferramentas permitidas. Se omitido, herda todas as [ferramentas disponíveis para subagentes](https://code.claude.com/docs/pt/sub-agents.md#available-tools). Para pré-carregar Skills no contexto do agente, use o campo `skills` em vez de listar `'Skill'` aqui |

1286| `disallowedTools` | Não | Array de nomes de ferramentas a proibir explicitamente para este agente. Padrões no nível de servidor MCP também são aceitos: `mcp__server` ou `mcp__server__*` remove todas as ferramentas desse servidor, e `mcp__*` remove todas as ferramentas MCP de qualquer servidor |1286| `disallowedTools` | Não | Array de nomes de ferramentas a proibir explicitamente para este agente. Padrões no nível de servidor MCP também são aceitos: `mcp__server` ou `mcp__server__*` remove todas as ferramentas desse servidor, e `mcp__*` remove todas as ferramentas MCP de qualquer servidor |

1287| `prompt` | Sim | O system prompt do agente |1287| `prompt` | Sim | O system prompt do agente |

1288| `model` | Não | Modelo que sobrescreve o padrão para este agente. Aceita um alias como `'fable'`, `'opus'`, `'sonnet'`, `'haiku'`, `'inherit'` ou um ID de modelo completo. `'inherit'` usa o modelo principal. Quando você o omite, o Claude Code escolhe o modelo na [ordem de modelos de subagentes](https://code.claude.com/docs/pt/sub-agents.md#choose-a-model) |1288| `model` | Não | Sobrescrita de modelo para este agente. Aceita um alias como `'fable'`, `'opus'`, `'sonnet'`, `'haiku'`, `'inherit'` ou um ID de modelo completo. `'inherit'` usa o modelo do agente que criou este. Quando você omite `model`, o Claude Code escolhe o modelo na [ordem de modelos de subagentes](https://code.claude.com/docs/pt/sub-agents.md#choose-a-model) |

1289| `mcpServers` | Não | Especificações de servidores MCP para este agente |1289| `mcpServers` | Não | Especificações de servidores MCP para este agente |

1290| `skills` | Não | Array de nomes de skills a pré-carregar no contexto do agente |1290| `skills` | Não | Array de nomes de skills a pré-carregar no contexto do agente |

1291| `initialPrompt` | Não | Enviado automaticamente como o primeiro turno do usuário quando este agente é executado como o agente da thread principal |1291| `initialPrompt` | Não | Enviado automaticamente como o primeiro turno do usuário quando este agente é executado como o agente da thread principal |

agent-teams.md +26 −9

Details

102>102>

103> `tmux` tem limitações conhecidas em certos sistemas operacionais e tradicionalmente funciona melhor no macOS. Usar `tmux -CC` no iTerm2 é o ponto de entrada sugerido para `tmux`.103> `tmux` tem limitações conhecidas em certos sistemas operacionais e tradicionalmente funciona melhor no macOS. Usar `tmux -CC` no iTerm2 é o ponto de entrada sugerido para `tmux`.

104 104

105O padrão é `"in-process"`. Defina `"auto"` para ativar split panes quando você já estiver executando dentro de uma sessão tmux, ou quando seu terminal for iTerm2 com o CLI `it2` instalado, voltando para in-process caso contrário. A configuração `"tmux"` ativa o modo split-pane e detecta automaticamente se deve usar tmux ou iTerm2 com base no seu terminal.105Com as equipes de agentes [ativadas](#enable-agent-teams), siga estas etapas para dar a cada companheiro de equipe seu próprio painel:

106 106

107Defina `"iterm2"` para usar explicitamente split panes nativos do iTerm2. Este modo requer o [CLI `it2`](https://github.com/mkusaka/it2) e mostra um erro com o comando de instalação se `it2` estiver faltando. O prompt de configuração que oferece instalar `it2` ou mudar para tmux aparece em `"auto"` ou `"tmux"` quando seu terminal é iTerm2 e tmux está disponível como fallback.107**1. Instale o tmux ou configure o iTerm2**

108 108

109Para substituir o padrão, defina [`teammateMode`](https://code.claude.com/docs/pt/settings-reference#teammatemode) em `~/.claude/settings.json`:109O modo split-pane requer [tmux](https://github.com/tmux/tmux/wiki) ou iTerm2 com o [CLI `it2`](https://github.com/mkusaka/it2). Configure aquele em que você executará o Claude Code:

110

111* **tmux**: instale através do gerenciador de pacotes do seu sistema. Veja o [wiki tmux](https://github.com/tmux/tmux/wiki/Installing) para instruções específicas da plataforma.

112* **iTerm2**: instale o [CLI `it2`](https://github.com/mkusaka/it2), depois ative a API Python em **iTerm2 > Settings > General > Magic > Enable Python API**.

113

114**2. Ative os split panes**

115

116Os companheiros de equipe são executados in-process até que você altere a configuração [`teammateMode`](https://code.claude.com/docs/pt/settings-reference#teammatemode).

117

118Defina-a como `"auto"` em `~/.claude/settings.json`:

110 119

111```json theme={null}120```json theme={null}

112{121{

114}123}

115```124```

116 125

126Com `"auto"`, os companheiros de equipe abrem em split panes quando você executa o Claude Code dentro do tmux ou do iTerm2, e são executados in-process em outros terminais.

127

128**3. Inicie o Claude Code e gere companheiros de equipe**

129

130Execute `claude` dentro do tmux ou no iTerm2 e, em seguida, peça ao Claude para gerar companheiros de equipe.

131

132Se um prompt de configuração para `it2` aparecer no iTerm2, selecione **Install it2 now** para abrir os painéis na sua janela do iTerm2.

133

134Se você executar o Claude Code fora do tmux e do iTerm2, ou se os painéis não abrirem na sua janela do iTerm2, altere `teammateMode` novamente:

135

136* **Fora do tmux e do iTerm2**: com o tmux instalado, defina `teammateMode` como `"tmux"`. Os painéis abrem em uma sessão tmux separada. Para acompanhá-los, copie o comando da linha `View teammates` no prompt do Claude Code e execute esse comando em um segundo terminal.

137* **Os painéis não abrem na sua janela do iTerm2**: defina `teammateMode` como `"iterm2"` para usar os painéis próprios do iTerm2. Os companheiros de equipe então só são iniciados quando você executa o Claude Code no iTerm2 com o `it2` configurado.

138

117Para definir o modo para uma única sessão, passe como um sinalizador:139Para definir o modo para uma única sessão, passe como um sinalizador:

118 140

119```bash theme={null}141```bash theme={null}

122 144

123O sinalizador `--teammate-mode` é experimental e não aparece em `claude --help`.145O sinalizador `--teammate-mode` é experimental e não aparece em `claude --help`.

124 146

125O modo split-pane requer [tmux](https://github.com/tmux/tmux/wiki) ou iTerm2 com o CLI [`it2`](https://github.com/mkusaka/it2). Para instalar manualmente:

~~126~~

127* **tmux**: instale através do gerenciador de pacotes do seu sistema. Veja o [wiki tmux](https://github.com/tmux/tmux/wiki/Installing) para instruções específicas da plataforma.

128* **iTerm2**: instale o CLI [`it2`](https://github.com/mkusaka/it2), depois ative a API Python em **iTerm2 → Settings → General → Magic → Enable Python API**.

~~129~~

130### Especifique companheiros de equipe e modelos147### Especifique companheiros de equipe e modelos

131 148

132Claude decide o número de companheiros de equipe a gerar com base em sua tarefa, ou você pode especificar exatamente o que deseja:149Claude decide o número de companheiros de equipe a gerar com base em sua tarefa, ou você pode especificar exatamente o que deseja:

497* **Sem subagentes em segundo plano de companheiros de equipe in-process**: os próprios subagentes de um companheiro de equipe in-process são executados em primeiro plano, porque o trabalho em segundo plano de um companheiro de equipe não pode sobreviver ao processo do líder. Claude Code retorna um erro quando um companheiro de equipe gera um subagente cuja definição define `background: true`. Uma requisição `run_in_background: true` de um companheiro de equipe também falha, seja com um erro ou executando silenciosamente em primeiro plano. Subagentes lançados da conversa principal seguem o [padrão de segundo plano](https://code.claude.com/docs/pt/sub-agents.md#run-subagents-in-foreground-or-background).514* **Sem subagentes em segundo plano de companheiros de equipe in-process**: os próprios subagentes de um companheiro de equipe in-process são executados em primeiro plano, porque o trabalho em segundo plano de um companheiro de equipe não pode sobreviver ao processo do líder. Claude Code retorna um erro quando um companheiro de equipe gera um subagente cuja definição define `background: true`. Uma requisição `run_in_background: true` de um companheiro de equipe também falha, seja com um erro ou executando silenciosamente em primeiro plano. Subagentes lançados da conversa principal seguem o [padrão de segundo plano](https://code.claude.com/docs/pt/sub-agents.md#run-subagents-in-foreground-or-background).

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

499* **Sem modos de permissão por companheiro de equipe no tempo de geração**: os companheiros de equipe começam com o modo de permissão descrito em [Permissões](#permissions).516* **Sem modos de permissão por companheiro de equipe no tempo de geração**: os companheiros de equipe começam com o modo de permissão descrito em [Permissões](#permissions).

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

501 518

502## Próximos passos519## Próximos passos

503 520

agent-view.md +30 −39

Details

144| Forma | O que significa |144| Forma | O que significa |

145| :- | :- |145| :- | :- |

147| `∙` | O processo saiu. Você ainda pode espreitar a linha, e quando você responde ou anexa, Claude a reinicia a partir de sua conversa salva |147| `∙` | O processo saiu. Você ainda pode espreitar a linha, e quando você responde ou pressiona `Enter`, Claude o reinicia a partir de sua conversa salva |

148| `✢` | Uma sessão [`/loop`](https://code.claude.com/docs/pt/scheduled-tasks) dormindo entre iterações. A linha mostra sua contagem de execução e uma contagem regressiva |148| `✢` | Uma sessão [`/loop`](https://code.claude.com/docs/pt/scheduled-tasks) dormindo entre iterações. A linha mostra sua contagem de execução e uma contagem regressiva |

149 149

150O rótulo `#N` ou `!N` que pode aparecer na borda direita de uma linha é um link para o [pull request ou merge request](#pull-request-status) da sessão, não parte do ícone de estado.150O rótulo `#N` ou `!N` que pode aparecer na borda direita de uma linha é um link para o [pull request ou merge request](#pull-request-status) da sessão, não parte do ícone de estado.

316* Pressione `Enter` em um cabeçalho de grupo para recolhê-lo, exceto enquanto um [filtro](#filter-sessions) está ativo, quando todos os grupos permanecem expandidos316* Pressione `Enter` em um cabeçalho de grupo para recolhê-lo, exceto enquanto um [filtro](#filter-sessions) está ativo, quando todos os grupos permanecem expandidos

317* Pressione `Ctrl+X` para interromper uma sessão e `Ctrl+X` novamente dentro de dois segundos para deletá-la da lista, ou `Esc` para descartar a confirmação sem deletar. O segundo pressionamento deleta a sessão mesmo quando a tentativa de parada falha, por exemplo porque o [serviço em background não está respondendo](#agent-view-says-the-background-service-did-not-respond). Nesse caso, a confirmação permanece ativa por mais dois segundos, e a exclusão encerra o processo da sessão em si317* Pressione `Ctrl+X` para interromper uma sessão e `Ctrl+X` novamente dentro de dois segundos para deletá-la da lista, ou `Esc` para descartar a confirmação sem deletar. O segundo pressionamento deleta a sessão mesmo quando a tentativa de parada falha, por exemplo porque o [serviço em background não está respondendo](#agent-view-says-the-background-service-did-not-respond). Nesse caso, a confirmação permanece ativa por mais dois segundos, e a exclusão encerra o processo da sessão em si

318 318

319Pressionar `Ctrl+X` em um cabeçalho de grupo deleta cada sessão naquele grupo após confirmação. Exceto nos casos mantidos cobertos em [What deleting a session removes](#what-deleting-a-session-removes), deletar remove a sessão da lista. Um worktree que Claude criou para ela é removido, mantido ou deixado no lugar dependendo de como você deleta e o que o worktree contém. A transcrição da conversa fica em sua máquina local, disponível através de `claude --resume`.319Pressione `Ctrl+X` em um cabeçalho de grupo para deletar cada sessão naquele grupo após confirmação, exceto aquelas que o Claude Code [se recusa a deletar](#delete-a-session-after-claude-code-refuses). Veja [What deleting a session removes](#what-deleting-a-session-removes) para saber o que acontece com o worktree de cada sessão. A transcrição da conversa fica em sua máquina local, disponível através de `claude --resume`.

320 320

321Sessões concluídas que não cabem na tela se dobram em uma linha `… N more`. O grupo `Completed` preenche o espaço vertical deixado após os grupos ativos. Em um terminal curto, o cabeçalho se compacta para uma única linha de resumo para que sessões que estão funcionando ou precisam de entrada permaneçam visíveis.321Sessões concluídas que não cabem na tela se dobram em uma linha `… N more`. O grupo `Completed` preenche o espaço vertical deixado após os grupos ativos. Em um terminal curto, o cabeçalho se compacta para uma única linha de resumo para que sessões que estão funcionando ou precisam de entrada permaneçam visíveis.

322 322

622 622

623#### O que deletar uma sessão remove623#### O que deletar uma sessão remove

624 624

625Delete uma sessão com `Ctrl+X` duas vezes na [visualização de agentes](#organize-the-list) ou com [`claude rm`](#manage-sessions-from-the-shell). Exceto nos casos mantidos abaixo, a sessão sai da lista. Sua transcrição permanece em sua máquina através de `claude --resume`, e a remoção sobrevive a reinicializações do supervisor.625Delete uma sessão com `Ctrl+X` duas vezes na [visualização de agentes](#organize-the-list) ou com [`claude rm`](#manage-sessions-from-the-shell). A sessão desaparece da lista, a menos que Claude Code [se recuse a deletá-la](#delete-a-session-after-claude-code-refuses). Sua transcrição permanece em sua máquina, disponível através de `claude --resume`.

626 626

627O que acontece com um worktree que Claude criou para a sessão:627O que acontece com um worktree que Claude criou para a sessão:

628 628

629* A visualização de agentes o remove, incluindo alterações não confirmadas, portanto faça commit do que você quer manter primeiro.629* A visualização de agentes o remove, incluindo alterações não confirmadas, portanto faça commit do que você quer manter primeiro.

630* `claude rm` o mantém, junto com a linha da sessão, quando tem alterações não confirmadas.630* `claude rm` o mantém, junto com a linha da sessão, quando tem alterações não confirmadas.

631* Nem a visualização de agentes nem `claude rm` remove um worktree que outra sessão em execução está usando ou bloqueou, e deletar novamente não muda isso. Claude Code mantém o worktree e a sessão, e nomeia o diretório mantido e o motivo; na visualização de agentes, a linha da sessão mostra `not removed`. Feche a outra sessão, depois delete novamente.

632* Quando você deleta uma sessão cujo worktree tem commits que Claude Code não pode confirmar que estão salvos em outro lugar, Claude Code mantém o worktree e a sessão, e a mensagem nomeia o branch do worktree e quantos commits não foram feitos push. A mensagem também oferece os dois caminhos adiante: fazer push dos commits, ou deletar novamente para descartá-los.

633 631

634 Commits em um remote não bloqueiam a deleção. Nem commits na cópia local do branch padrão do seu remote `origin`, desde que esse branch esteja em checkout no seu checkout principal, o diretório do repositório em si em vez de um worktree.632Um dos motivos pelos quais Claude Code se recusa a deletar uma sessão são [commits sem push em seu worktree](https://code.claude.com/docs/pt/errors.md#worktree-has-commits-that-are-not-pushed-anywhere). Para manter esses commits, faça push deles antes de deletar a sessão.

635 633

636 Após essa recusa, você escolhe:634Alguns worktrees permanecem em disco, quer você use a visualização de agentes ou `claude rm`:

637 635

638 * Para manter os commits, faça push deles, ou mescle-os nesse branch padrão, depois delete a sessão novamente.636* Se você criou um worktree você mesmo e iniciou a sessão de dentro dele, o worktree permanece em disco para você manter ou remover.

639 * Para descartá-los, delete a sessão novamente sem fazer push: pressione `Ctrl+X` duas vezes em sua linha na visualização de agentes, ou execute o comando `claude rm <id> --discard-unpushed` que a recusa imprimiu. Isso remove a sessão e o worktree junto com seu branch, descartando os commits não feitos push e quaisquer alterações não confirmadas.637* Se um diretório de worktree que Claude criou dentro do seu repositório não tiver mais seu arquivo `.git`, o diretório permanece em disco para você remover. O branch do worktree permanece no repositório, portanto você mantém os commits nesse branch.

640 638

641 Quando você deleta novamente, Claude Code descarta apenas o que a recusa mostrou: se o worktree ganhou um commit desde então, Claude Code o mantém novamente e mostra o estado atualizado.639##### Deletar uma sessão depois que Claude Code se recusa

642 640

643 Quando o registro de outra sessão concluída também nomeia o worktree, ele permanece quando você deleta novamente; faça push dos commits, depois delete novamente.641Quando Claude Code se recusa a deletar uma sessão por causa de seu worktree, siga a mensagem que ele mostra. Se a mensagem mencionar commits sem push, veja [Worktree has commits that are not pushed anywhere](https://code.claude.com/docs/pt/errors.md#worktree-has-commits-that-are-not-pushed-anywhere).

644* Um worktree que git não reconhece mais, por exemplo após `git worktree prune`, não bloqueia a deleção. Claude Code deleta a sessão e deixa o diretório em disco.

645* Quando git ou seu [`WorktreeRemove` hook](https://code.claude.com/docs/pt/hooks#worktreeremove) falha em remover o worktree, Claude Code mantém o worktree e a sessão, e a mensagem nomeia a causa. Para um hook, a mensagem diz como terminou, como `exited 1`, e cita o início de seu stderr. A mensagem também diz qual destes fazer a seguir:

646 642

647 * Delete a sessão novamente para remover o diretório mesmo assim, pressionando `Ctrl+X` duas vezes em sua linha na visualização de agentes ou executando o comando `claude rm <id> --force-remove-worktree <worktree-id>` que a recusa de `claude rm` imprimiu. O branch do worktree permanece no repositório.643##### Resolver uma mensagem `Worktree not removed`

648 644

649 Claude Code oferece isso apenas quando pode confirmar todos os seguintes:645Uma mensagem `Worktree not removed` significa que Claude Code ou seu [`WorktreeRemove` hook](https://code.claude.com/docs/pt/hooks#worktreeremove) não terminou de remover o worktree da sessão. Faça push de quaisquer commits e copie quaisquer arquivos que você queira manter, depois siga a mensagem.

650 646

651 * O diretório é um dos worktrees vinculados do repositório sob `.claude/worktrees/`647##### Resolver uma mensagem `files that weren't checked against a repository`

652 * Nem o worktree nem um submódulo em checkout tem alterações não confirmadas em arquivos rastreados

653 * Nenhum registro de outra sessão o nomeia

654 648

655 Quando Claude Code não pode verificar o estado de um checkout de submódulo, como um substituído por um repositório git separado, ele também não oferece isso.649Esta mensagem de `claude rm` significa que restam arquivos em um diretório de worktree que não está dentro de nenhum repositório git ou que um [`WorktreeCreate` hook](https://code.claude.com/docs/pt/hooks#worktreecreate) gerencia. Copie quaisquer arquivos que você queira manter, depois siga a etapa para o seu caso:

656 * Corrija o que está no caminho, como fazer commit ou stash das alterações não confirmadas, mover um repositório git separado para fora do worktree, fechar o que quer que esteja usando o diretório, ou corrigir o hook, depois delete a sessão novamente.

657 * Remova o diretório você mesmo, depois delete a sessão novamente.

658 650

659Um worktree que você criou você mesmo e iniciou a sessão dentro é deixado no lugar de qualquer forma.651| Seu caso | O que fazer |

~~660~~ 652| :- | :- |

661Uma sessão cujo diretório de worktree não pertence a nenhum repositório git, porque o repositório foi deletado ou um [`WorktreeCreate` hook](https://code.claude.com/docs/pt/hooks#worktreecreate) criou o diretório em outro lugar, ainda pode ser deletada. Enquanto arquivos permanecem no diretório:653| Nenhum `WorktreeCreate` hook gerencia o diretório | Para descartar os arquivos, pressione `Ctrl+X` duas vezes na linha da sessão na visualização de agentes. Ou remova o diretório você mesmo, depois execute `claude rm <id>` novamente |

~~662~~ 654| Um `WorktreeCreate` hook gerencia o diretório, e você tem um [`WorktreeRemove` hook](https://code.claude.com/docs/pt/hooks#worktreeremove) | Para tentar remover o diretório com seu hook, pressione `Ctrl+X` duas vezes na linha da sessão na visualização de agentes. Ou remova o diretório você mesmo, depois execute `claude rm <id>` novamente |

663* A visualização de agentes pede o mesmo duplo `Ctrl+X` antes de descartá-los. Para um diretório criado por hook, ele executa seu [`WorktreeRemove` hook](https://code.claude.com/docs/pt/hooks#worktreeremove) em vez disso, e sem um ele recusa a deleção e mantém a sessão.655| Um `WorktreeCreate` hook gerencia o diretório, e você não tem um `WorktreeRemove` hook | Remova o diretório você mesmo, depois execute `claude rm <id>` novamente |

664* `claude rm` mantém a sessão e o worktree, e nomeia o motivo.

~~665~~

666Qualquer caminho mantém um diretório que o registro de outra sessão concluída nomeia.

667 656

668### Definir o modelo, o esforço e o modo rápido657### Definir o modelo, o esforço e o modo rápido

669 658

774| [`--add-dir <path>`](https://code.claude.com/docs/pt/permissions#additional-directories-grant-file-access-not-configuration) | Conceder acesso a arquivo para um diretório adicional |763| [`--add-dir <path>`](https://code.claude.com/docs/pt/permissions#additional-directories-grant-file-access-not-configuration) | Conceder acesso a arquivo para um diretório adicional |

775| [`--plugin-dir <path>`](https://code.claude.com/docs/pt/plugins/create#load-a-directory-or-archive-for-one-session) | Carregar um plugin de um diretório local |764| [`--plugin-dir <path>`](https://code.claude.com/docs/pt/plugins/create#load-a-directory-or-archive-for-one-session) | Carregar um plugin de um diretório local |

776| [`--mcp-config <file-or-json>`](https://code.claude.com/docs/pt/mcp) | Carregar servidores MCP de um arquivo de configuração ou string JSON |765| [`--mcp-config <file-or-json>`](https://code.claude.com/docs/pt/mcp) | Carregar servidores MCP de um arquivo de configuração ou string JSON |

777| `--strict-mcp-config` | Use apenas os servidores MCP de `--mcp-config`, ignorando outra configuração MCP. Veja [Controle exclusivo com managed-mcp.json](https://code.claude.com/docs/pt/managed-mcp.md#exclusive-control-with-managed-mcp-json) para o que a flag faz sob um arquivo MCP gerenciado |766| `--strict-mcp-config` | Ignorar os servidores MCP configurados em locais como `.mcp.json` e carregar os que você passa com `--mcp-config`. Veja [Controle exclusivo com managed-mcp.json](https://code.claude.com/docs/pt/managed-mcp.md#exclusive-control-with-managed-mcp-json) para o que a flag faz sob um arquivo MCP gerenciado |

778 767

779Repita `--add-dir`, `--plugin-dir` ou `--mcp-config` uma vez por valor. `claude agents` não suporta a forma separada por espaço, como `--add-dir a b c`.768Repita `--add-dir`, `--plugin-dir` ou `--mcp-config` uma vez por valor. `claude agents` não suporta a forma separada por espaço, como `--add-dir a b c`.

780 769

803| `claude respawn <id>` | Reiniciar uma sessão, em execução ou interrompida, por exemplo, para usar um binário Claude Code atualizado. Uma sessão que tem uma conversa salva a retoma |792| `claude respawn <id>` | Reiniciar uma sessão, em execução ou interrompida, por exemplo, para usar um binário Claude Code atualizado. Uma sessão que tem uma conversa salva a retoma |

804| `claude respawn --all` | Reiniciar cada sessão em execução, por exemplo, para mover todas as sessões para um binário Claude Code atualizado de uma vez |793| `claude respawn --all` | Reiniciar cada sessão em execução, por exemplo, para mover todas as sessões para um binário Claude Code atualizado de uma vez |

805| `claude rm <id>` | Remover uma sessão da lista, junto com um worktree que Claude criou para ela quando é seguro deletar; veja [O que deletar uma sessão remove](#what-deleting-a-session-removes). A transcrição da conversa permanece em sua máquina local e continua disponível através de `claude --resume` |794| `claude rm <id>` | Remover uma sessão da lista, junto com um worktree que Claude criou para ela quando é seguro deletá-lo. Se o Claude Code se recusar a deletar a sessão por causa do seu worktree, veja [Deletar uma sessão depois que o Claude Code recusar](#delete-a-session-after-claude-code-refuses). A transcrição da conversa permanece em sua máquina local e continua disponível através de `claude --resume` |

806| `claude rm <id> --discard-unpushed <commit>@<worktree-id>` | Deletar uma sessão cuja exclusão foi recusada sobre commits não enviados, descartando o worktree junto com seu branch e commits. Passe o valor exato que a recusa imprimiu; veja [O que deletar uma sessão remove](#what-deleting-a-session-removes). Requer v2.1.260 ou posterior |795| `claude rm <id> --discard-unpushed <commit>@<worktree-id>` | Tentar novamente deletar uma sessão e descartar seu worktree, depois que o Claude Code recusou por causa de commits não enviados. Copie o comando da mensagem do `claude rm` que o oferece; veja [Worktree has commits that are not pushed anywhere](https://code.claude.com/docs/pt/errors.md#worktree-has-commits-that-are-not-pushed-anywhere). Requer v2.1.260 ou posterior |

807| `claude rm <id> --force-remove-worktree <worktree-id>` | Deletar uma sessão cuja exclusão foi recusada porque git ou o hook `WorktreeRemove` não conseguiu remover seu worktree, deletando o diretório worktree mesmo assim e deixando seu branch no repositório. Passe o valor exato que a recusa imprimiu; veja [O que deletar uma sessão remove](#what-deleting-a-session-removes). Requer v2.1.268 ou posterior |796| `claude rm <id> --force-remove-worktree <worktree-id>` | Tentar novamente deletar uma sessão e remover o diretório do seu worktree mesmo assim, depois que o Claude Code recusou porque não conseguiu remover o worktree. Copie o comando da mensagem do `claude rm` que o oferece; veja [Resolver uma mensagem `Worktree not removed`](#resolve-a-worktree-not-removed-message). Requer v2.1.268 ou posterior |

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

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

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

939 928

940 Pressione `Enter` na linha e o rodapé mostra `Press enter again to resume this session (it ended while the background service was off), or ctrl+x to remove it.` Pressione `Enter` na mesma linha novamente para retomar sua conversa salva. Uma resposta, ou `claude attach <id>`, a retoma sem esse prompt de rodapé.929 Pressione `Enter` na linha e o rodapé mostra `Press enter again to resume this session (it ended while the background service was off), or ctrl+x to remove it.` Pressione `Enter` na mesma linha novamente para retomar sua conversa salva. Uma resposta, ou `claude attach <id>`, a retoma sem esse prompt de rodapé.

941 930

942Quando [transcript cleanup](https://code.claude.com/docs/pt/settings-reference.md#cleanupperioddays) removeu a conversa salva de uma sessão parada, Claude Code recusa abrir a linha: a mensagem diz que não há nada para retomar. `claude rm <id>` deleta a linha, exceto nos [casos mantidos](#what-deleting-a-session-removes) descritos acima, e `claude respawn <id>` executa seu prompt original novamente. Veja [This session's saved conversation is no longer on disk](https://code.claude.com/docs/pt/errors.md#this-sessions-saved-conversation-is-no-longer-on-disk).931Quando [transcript cleanup](https://code.claude.com/docs/pt/settings-reference.md#cleanupperioddays) removeu a conversa salva de uma sessão parada, Claude Code recusa abrir a linha: a mensagem diz que não há nada para retomar. `claude rm <id>` deleta a linha, a menos que [Claude Code recuse](#what-deleting-a-session-removes), e `claude respawn <id>` executa seu prompt original novamente. Veja [This session's saved conversation is no longer on disk](https://code.claude.com/docs/pt/errors.md#this-sessions-saved-conversation-is-no-longer-on-disk).

943 932

944Sleep sozinho não interrompe as sessões. Sessões são preservadas durante o sleep e o supervisor se reconecta a elas ao acordar.933Sleep sozinho não interrompe as sessões. Sessões são preservadas durante o sleep e o supervisor se reconecta a elas ao acordar.

945 934

973 962

974Quando o processo de uma sessão em background sai antes de terminar de iniciar e o host está com pouca memória, o status da linha nomeia a saída e adiciona `possibly low memory — free some up and retry`.963Quando o processo de uma sessão em background sai antes de terminar de iniciar e o host está com pouca memória, o status da linha nomeia a saída e adiciona `possibly low memory — free some up and retry`.

975 964

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

966>

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

977 968

978Libere memória na máquina, depois anexe ou responda à linha e o supervisor inicia um novo processo para a sessão. Quando a memória permanece baixa, o supervisor também [interrompe sessões ociosas](#the-supervisor-process) para liberar recursos por conta própria, e interrompe sessões fixadas ociosas também se interromper as outras não liberou nada.969Libere memória na máquina, depois pressione `Enter` na linha, e pressione-o novamente se [o rodapé pedir](#opening-a-session-says-it-has-no-saved-transcript). O [supervisor](#the-supervisor-process) inicia um novo processo para a sessão. Quando a memória permanece baixa, o supervisor também [interrompe sessões ociosas](#the-supervisor-process) para liberar recursos por conta própria, e interrompe sessões fixadas ociosas também se interromper as outras não liberou nada.

979 970

980### Agent view says the background service did not respond971### Agent view says the background service did not respond

981 972

1036 1027

1037### `.claude/worktrees/` is filling up1028### `.claude/worktrees/` is filling up

1038 1029

1039Deletar uma sessão em agent view remove o worktree que Claude criou para ela, mas [alguns deletes mantêm o worktree ou deixam seu diretório no disco](#what-deleting-a-session-removes), então diretórios restantes podem se acumular. Diretórios que git não reconhece mais não aparecem em `git worktree list`, então remova aqueles à mão.1030Deletar uma sessão em agent view remove o worktree que Claude criou para ela, mas [alguns diretórios de worktree permanecem no disco](#what-deleting-a-session-removes). Diretórios que git não reconhece mais não aparecem em `git worktree list`, então remova esses você mesmo.

1040 1031

1041Liste entradas restantes com `git worktree list` no diretório do projeto e remova cada uma com `git worktree remove <path>`. Veja [Clean up worktrees](https://code.claude.com/docs/pt/worktrees.md#clean-up-worktrees).1032Liste entradas restantes com `git worktree list` no diretório do projeto e remova cada uma com `git worktree remove <path>`. Se o git recusar, veja [Clean up subagent and background-session worktrees](https://code.claude.com/docs/pt/worktrees.md#clean-up-subagent-and-background-session-worktrees).

1042 1033

1043## Limitações1034## Limitações

1044 1035

1046 1037

1047* **Limites de taxa se aplicam**: sessões em background consomem o uso de sua assinatura da mesma forma que sessões interativas, então executar dez agentes em paralelo usa cota aproximadamente dez vezes mais rápido do que executar um.1038* **Limites de taxa se aplicam**: sessões em background consomem o uso de sua assinatura da mesma forma que sessões interativas, então executar dez agentes em paralelo usa cota aproximadamente dez vezes mais rápido do que executar um.

1048* **Sessões são locais**: sessões em background são executadas em sua máquina. Elas são preservadas durante o sleep, mas param se a máquina desligar.1039* **Sessões são locais**: sessões em background são executadas em sua máquina. Elas são preservadas durante o sleep, mas param se a máquina desligar.

1049* **Worktrees criadas pelo Claude são deletadas com a sessão em agent view**: confirme as alterações antes de deletar uma sessão que editou arquivos em seu próprio worktree. [Algumas exclusões mantêm o worktree em vez disso](#what-deleting-a-session-removes).1040* **Worktrees criados pelo Claude são deletados com a sessão em agent view**: faça commit das alterações antes de deletar uma sessão que editou arquivos em seu próprio worktree. [Alguns worktrees permanecem no disco](#what-deleting-a-session-removes).

1050 1041

1051## Recursos relacionados1042## Recursos relacionados

1052 1043

artifacts.md +2 −2

Details

432 432

433Para definir quanto tempo os artefatos são mantidos antes da exclusão automática, vá para [**Organization settings > Data and privacy**](https://claude.ai/admin-settings/data-privacy-controls). Você pode definir períodos de retenção separados para artefatos que ainda são privados para seu autor e artefatos que foram compartilhados.433Para definir quanto tempo os artefatos são mantidos antes da exclusão automática, vá para [**Organization settings > Data and privacy**](https://claude.ai/admin-settings/data-privacy-controls). Você pode definir períodos de retenção separados para artefatos que ainda são privados para seu autor e artefatos que foram compartilhados.

434 434

435### Revisar o log de auditoria435### Auditar a atividade de artefatos com a API de Conformidade

436 436

437Publicar, compartilhar e excluir um artefato aparecem cada um no log de auditoria de sua organização sob os tipos de evento `claude_artifact_*`, a mesma família usada para artefatos criados em conversas do claude.ai.437Em planos Enterprise, consulte o [Activity Feed](https://platform.claude.com/docs/en/manage-claude/compliance-activity-feed) da API de Conformidade para ver quem publicou, compartilhou ou excluiu um artefato. Para encontrar os tipos de atividade pelos quais filtrar, expanda `activity_types` na [referência do Activity Feed](https://platform.claude.com/docs/en/api/compliance/activities/list) e procure nomes que contenham `artifact`.

438 438

439### Adicionar o domínio do visualizador à lista de permissões439### Adicionar o domínio do visualizador à lista de permissões

440 440

claude-projects.md +3 −9

Details

163Claude decide para onde cada mensagem que você envia na conversa vai:163Claude decide para onde cada mensagem que você envia na conversa vai:

164 164

165* Uma pergunta rápida geralmente recebe uma resposta na conversa.165* Uma pergunta rápida geralmente recebe uma resposta na conversa.

166* Novo trabalho vai para uma nova thread ou para uma thread já trabalhando nessa área, e Claude diz qual. Cada nova thread aparece sob sua mensagem como um cartão: uma caixa com o título e status da thread, que você clica para abrir a thread.166* Novo trabalho vai para uma nova thread ou para uma thread já trabalhando nessa área, e Claude diz qual. Cada nova thread aparece na conversa, e você clica nela para abrir a thread.

167* Várias tarefas não relacionadas em uma mensagem se tornam threads separadas.167* Várias tarefas não relacionadas em uma mensagem se tornam threads separadas.

168 168

169Se Claude rotear algo diferente do que você queria, diga. [Ajustar como Claude executa um projeto](#tune-how-claude-runs-a-project) lista coisas que você pode dizer a ele, como reutilizar uma thread existente para acompanhamentos ou responder no local em vez de iniciar uma thread.169Se Claude rotear algo diferente do que você queria, diga. [Ajustar como Claude executa um projeto](#tune-how-claude-runs-a-project) lista coisas que você pode dizer a ele, como reutilizar uma thread existente para acompanhamentos ou responder no local em vez de iniciar uma thread.

170 170

171Os resultados completos de uma thread permanecem na thread, e você abre seu cartão na conversa para lê-los. Os arquivos que uma thread produziu também estão na [**Library**](#see-what-needs-you-in-overview) do projeto.171Os resultados completos de uma thread permanecem na thread, então abra a thread para lê-los. Os arquivos que uma thread produziu também estão na [**Library**](#see-what-needs-you-in-overview) do projeto.

172 172

173Às vezes Claude propõe threads em vez de iniciá-las, em uma lista **Suggested threads**. Clique na seta em uma sugestão para iniciar essa thread. Quando várias estão listadas, um botão sob a lista inicia todas elas.173Às vezes Claude propõe threads em vez de iniciá-las, em uma lista **Suggested threads**. Clique na seta em uma sugestão para iniciar essa thread. Quando várias estão listadas, um botão sob a lista inicia todas elas.

174 174

180* **Pull request**: abre um quando você pede, e pode abrir um por conta própria para uma correção de bug ou outra mudança concreta.180* **Pull request**: abre um quando você pede, e pode abrir um por conta própria para uma correção de bug ou outra mudança concreta.

181* **Depois que abre**: observa o pull request com [auto-fix](https://code.claude.com/docs/pt/claude-code-on-the-web.md#auto-fix-pull-requests) ligado, independentemente de auto-fix estar ligado para suas outras sessões em nuvem. Ele empurra correções quando CI falha, aborda comentários de revisão e responde na thread quando as verificações passam e o pull request está pronto para você.181* **Depois que abre**: observa o pull request com [auto-fix](https://code.claude.com/docs/pt/claude-code-on-the-web.md#auto-fix-pull-requests) ligado, independentemente de auto-fix estar ligado para suas outras sessões em nuvem. Ele empurra correções quando CI falha, aborda comentários de revisão e responde na thread quando as verificações passam e o pull request está pronto para você.

182 182

183Quando uma thread empurrou um branch ou abriu um pull request, seu cartão na conversa pode mostrar um botão para o próximo passo:

~~184~~

185* **Resolve conflicts**, **Fix CI**, **Address comments** e **Merge it** enviam essa instrução para a thread como uma mensagem sua, então você pode solicitar a thread você mesmo em vez de esperar que ela reaja ao pull request.

186* **Review PR** abre o pull request no GitHub.

187* **Create PR** aparece quando uma thread ociosa empurrou um branch mas não abriu um pull request. Clicar nele cria o pull request desse branch diretamente em vez de enviar à thread uma instrução para abrir um.

~~188~~

189Para mudar quando as threads abrem pull requests, por exemplo apenas quando você pede, ou a partir de qual branch elas começam, diga na tarefa ou em [instruções do projeto](#write-project-instructions).183Para mudar quando as threads abrem pull requests, por exemplo apenas quando você pede, ou a partir de qual branch elas começam, diga na tarefa ou em [instruções do projeto](#write-project-instructions).

190 184

191### Ver o que precisa de você em Overview185### Ver o que precisa de você em Overview

212 206

213### Abrir uma thread quando você precisa de controle207### Abrir uma thread quando você precisa de controle

214 208

215Clique no cartão de uma thread na conversa ou sua linha em Overview para abrir sua transcrição no painel Overview. De lá você pode:209Clique em uma thread na conversa ou em sua linha em Overview para abrir a thread no painel Overview. De lá você pode:

216 210

217* Ler o que Claude fez, passo a passo.211* Ler o que Claude fez, passo a passo.

218* Direcionar a tarefa escrevendo na caixa de mensagem própria da thread. Uma mensagem lá vai direto para essa thread, enquanto um acompanhamento na conversa do projeto a alcança apenas quando Claude corresponde o acompanhamento a essa thread.212* Direcionar a tarefa escrevendo na caixa de mensagem própria da thread. Uma mensagem lá vai direto para essa thread, enquanto um acompanhamento na conversa do projeto a alcança apenas quando Claude corresponde o acompanhamento a essa thread.

cli-reference.md +1 −1

Details

129| `--setting-sources` | Lista separada por vírgula de fontes de configuração a carregar (`user`, `project`, `local`). Veja [agent view](https://code.claude.com/docs/pt/agent-view.md#what-carries-over-when-you-background) e [equipes de agentes](https://code.claude.com/docs/pt/agent-teams.md#context-and-communication) para as sessões que você inicia a partir desta que herdam a lista | `claude --setting-sources user,project` |129| `--setting-sources` | Lista separada por vírgula de fontes de configuração a carregar (`user`, `project`, `local`). Veja [agent view](https://code.claude.com/docs/pt/agent-view.md#what-carries-over-when-you-background) e [equipes de agentes](https://code.claude.com/docs/pt/agent-teams.md#context-and-communication) para as sessões que você inicia a partir desta que herdam a lista | `claude --setting-sources user,project` |

130| `--settings` | Caminho para um arquivo JSON de configurações ou uma string JSON para carregar configurações adicionais. Os valores que você define aqui substituem as mesmas chaves em seus arquivos `settings.json` para esta sessão. As chaves que você omite mantêm seus valores baseados em arquivo. O arquivo deve ser um arquivo regular com no máximo 2 MiB. Veja [precedência de configurações](https://code.claude.com/docs/pt/settings.md#settings-precedence) | `claude --settings ./settings.json` |130| `--settings` | Caminho para um arquivo JSON de configurações ou uma string JSON para carregar configurações adicionais. Os valores que você define aqui substituem as mesmas chaves em seus arquivos `settings.json` para esta sessão. As chaves que você omite mantêm seus valores baseados em arquivo. O arquivo deve ser um arquivo regular com no máximo 2 MiB. Veja [precedência de configurações](https://code.claude.com/docs/pt/settings.md#settings-precedence) | `claude --settings ./settings.json` |

131| `--strict-mcp-config` | Usar apenas servidores MCP de `--mcp-config`, ignorando todas as outras configurações de MCP. Veja [Controle exclusivo com managed-mcp.json](https://code.claude.com/docs/pt/managed-mcp.md#exclusive-control-with-managed-mcp-json) para o que o sinalizador faz sob um arquivo MCP gerenciado | `claude --strict-mcp-config --mcp-config ./mcp.json` |131| `--strict-mcp-config` | Ignorar os servidores MCP configurados em locais como `.mcp.json`, `~/.claude.json` ou um plugin, e carregar os que você passa com `--mcp-config`. Veja [Controle exclusivo com managed-mcp.json](https://code.claude.com/docs/pt/managed-mcp.md#exclusive-control-with-managed-mcp-json) para o que o sinalizador faz sob um arquivo MCP gerenciado | `claude --strict-mcp-config --mcp-config ./mcp.json` |

134| `--system-prompt-snapshot` | Passar `off` para reconstruir o prompt do sistema em cada solicitação em vez de reutilizar o prompt [registrado na primeira solicitação da conversa](#system-prompt-flags-in-resumed-conversations), por exemplo enquanto você itera no texto `--append-system-prompt` em execuções `--continue`. Requer Claude Code v2.1.257 ou posterior | `claude --system-prompt-snapshot off` |134| `--system-prompt-snapshot` | Passar `off` para reconstruir o prompt do sistema em cada solicitação em vez de reutilizar o prompt [registrado na primeira solicitação da conversa](#system-prompt-flags-in-resumed-conversations), por exemplo enquanto você itera no texto `--append-system-prompt` em execuções `--continue`. Requer Claude Code v2.1.257 ou posterior | `claude --system-prompt-snapshot off` |

desktop.md +2 −1

Details

2127 2127

2128Para impedir isso, implante também `forceLoginOrgUUID` na política do Claude Desktop (em `HKLM` no Windows), com o ID da sua organização claude.ai. A menos que a própria política [selecione a Claude API](https://claude.com/docs/third-party/claude-desktop/claude-api#choose-an-authentication-approach), o Claude Desktop deixa de usar a chave de API ou a conta do Console da própria pessoa na próxima inicialização do aplicativo.2128Para impedir isso, implante também `forceLoginOrgUUID` na política do Claude Desktop (em `HKLM` no Windows), com o ID da sua organização claude.ai. A menos que a própria política [selecione a Claude API](https://claude.com/docs/third-party/claude-desktop/claude-api#choose-an-authentication-approach), o Claude Desktop deixa de usar a chave de API ou a conta do Console da própria pessoa na próxima inicialização do aplicativo.

2129 2129

2130Verifique dois casos antes de implantá-la:2130Verifique três casos antes de implantá-la:

2131 2131

2132* **Organizações do Claude Console**: não implante `forceLoginOrgUUID` sozinho com o ID de uma organização do Claude Console, ou você bloqueará o acesso das pessoas da sua organização ao Claude Desktop. Em vez disso, veja [Which devices offer the Claude API account sign-in](https://claude.com/docs/third-party/claude-desktop/claude-api#which-devices-offer-the-claude-api-account-sign-in).2132* **Organizações do Claude Console**: não implante `forceLoginOrgUUID` sozinho com o ID de uma organização do Claude Console, ou você bloqueará o acesso das pessoas da sua organização ao Claude Desktop. Em vez disso, veja [Which devices offer the Claude API account sign-in](https://claude.com/docs/third-party/claude-desktop/claude-api#which-devices-offer-the-claude-api-account-sign-in).

2133* **Enterprise Admin Console**: se ele entrega a configuração do Claude Desktop dos seus computadores, atualize-os primeiro para o Claude Desktop v2.37337.0 ou posterior, porque versões anteriores o ignoram depois que essa chave é definida. Veja [Keep a device on its managed profile](https://claude.com/docs/third-party/claude-desktop/admin-console#keep-a-device-on-its-managed-profile).2133* **Enterprise Admin Console**: se ele entrega a configuração do Claude Desktop dos seus computadores, atualize-os primeiro para o Claude Desktop v2.37337.0 ou posterior, porque versões anteriores o ignoram depois que essa chave é definida. Veja [Keep a device on its managed profile](https://claude.com/docs/third-party/claude-desktop/admin-console#keep-a-device-on-its-managed-profile).

2134* **Provedores terceirizados**: se as pessoas configurarem sua própria [configuração de inferência de terceiros](https://claude.com/docs/third-party/claude-desktop/in-app-configuration) no aplicativo, o Claude Desktop ignora essa configuração a partir da próxima inicialização depois que você implantar essa chave. Para manter as pessoas no Amazon Bedrock, no Agent Platform do Google Cloud, no Microsoft Foundry ou em um gateway de LLM, [implante uma configuração](https://claude.com/docs/third-party/claude-desktop/configuration) nos computadores delas na mesma política do Claude Desktop.

2134 2135

2135### Requisitos de acesso à rede2136### Requisitos de acesso à rede

2136 2137

desktop-scheduled-tasks.md +4 −4

Details

182* **Review allowed permissions**: veja e revogue aprovações de ferramentas salvas para esta tarefa no painel **Always allowed**182* **Review allowed permissions**: veja e revogue aprovações de ferramentas salvas para esta tarefa no painel **Always allowed**

183* **Delete**: remova a tarefa. As sessões que a tarefa criou são [arquivadas](https://code.claude.com/docs/pt/desktop.md#organize-and-find-sessions), não deletadas. A pasta que contém o arquivo `SKILL.md` da tarefa permanece no disco em `~/.claude/scheduled-tasks/<task-name>/`, ou em `scheduled-tasks/<task-name>/` dentro de [`CLAUDE_CONFIG_DIR`](https://code.claude.com/docs/pt/env-vars) se você definir essa variável. Para remover essa pasta, delete-a você mesmo.183* **Delete**: remova a tarefa. As sessões que a tarefa criou são [arquivadas](https://code.claude.com/docs/pt/desktop.md#organize-and-find-sessions), não deletadas. A pasta que contém o arquivo `SKILL.md` da tarefa permanece no disco em `~/.claude/scheduled-tasks/<task-name>/`, ou em `scheduled-tasks/<task-name>/` dentro de [`CLAUDE_CONFIG_DIR`](https://code.claude.com/docs/pt/env-vars) se você definir essa variável. Para remover essa pasta, delete-a você mesmo.

184 184

185Você também pode listar, criar, editar e pausar tarefas pedindo ao Claude em qualquer sessão do Desktop. Por exemplo, "pause my dependency-audit task" ou "show me my scheduled tasks." Para deletar uma tarefa, use o botão **Delete** em sua página de detalhes.185Você também pode gerenciar tarefas pedindo ao Claude, permitindo que uma tarefa se atualize ou editando o prompt de uma tarefa no disco:

186 186

187Para permitir que uma tarefa altere seu próprio agendamento ou prompt com a ferramenta MCP `update_scheduled_task`, clique em **Run now** e aprove a chamada a cada vez.187* **Pedir ao Claude**: liste, crie, edite e pause tarefas pedindo ao Claude em qualquer sessão do Desktop. Por exemplo, "pause my dependency-audit task" ou "show me my scheduled tasks." Para deletar uma tarefa, use o botão **Delete** em sua página de detalhes.

~~188~~ 188* **Permitir que uma tarefa se atualize**: para que uma tarefa altere seu próprio agendamento ou prompt com a ferramenta MCP `update_scheduled_task`, clique em **Run now** e aprove a chamada a cada vez

189Para editar o prompt de uma tarefa no disco, abra `~/.claude/scheduled-tasks/<task-name>/SKILL.md` (ou em [`CLAUDE_CONFIG_DIR`](https://code.claude.com/docs/pt/env-vars) se definido). O arquivo usa frontmatter YAML para `name` e `description`, com o prompt como corpo. As alterações entram em vigor na próxima execução. Agendamento, pasta e estado habilitado não estão neste arquivo: altere-os através do formulário Edit ou peça ao Claude.189* **Editar o prompt no disco**: abra `~/.claude/scheduled-tasks/<task-name>/SKILL.md`, ou `scheduled-tasks/<task-name>/SKILL.md` dentro de [`CLAUDE_CONFIG_DIR`](https://code.claude.com/docs/pt/env-vars) se você definir essa variável. O arquivo usa frontmatter YAML para `name` e `description`, com o prompt como corpo. As alterações entram em vigor na próxima execução. Agendamento, pasta e estado habilitado não estão neste arquivo: altere-os através do formulário Edit ou peça ao Claude.

190 190

191## Recursos relacionados191## Recursos relacionados

192 192

env-vars.md +1 −1

Details

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

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

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

359| `CLAUDE_CODE_PLUGIN_DIR_WATCH` | Controla se o Claude Code recarrega um [mod](https://code.claude.com/docs/pt/plugins/mods/overview.md) quando os arquivos do mod mudam. O recarregamento se aplica a um mod que você carrega de um diretório com `--plugin-dir` e é ativado por padrão em sessões interativas. Defina como `1` para ativá-lo também em sessões não interativas, ou `0` para desativá-lo em todas as sessões. Requer Claude Code v2.1.287 ou posterior. Consulte [configurações e variáveis de ambiente de mods](https://code.claude.com/docs/pt/plugins/mods/reference.md#settings-and-environment-variables) |359| `CLAUDE_CODE_PLUGIN_DIR_WATCH` | Controla se um [mod](https://code.claude.com/docs/pt/plugins/mods/overview.md) é recarregado quando seus arquivos mudam. Por padrão, mods em [diretórios de skills](https://code.claude.com/docs/pt/plugins/org.md#keep-skills-directory-plugins-loading) são recarregados em qualquer sessão que leve mais de um prompt, incluindo as [não interativas](https://code.claude.com/docs/pt/headless.md). Mods em diretórios `--plugin-dir` são recarregados apenas em sessões interativas de terminal. Defina como `1` para recarregá-los como os mods de diretórios de skills, ou `0` para desativar o recarregamento em todos os lugares. Requer Claude Code v2.1.287 ou posterior |

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

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

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

errors.md +4 −8

Details

5556 5556

5557### Worktree tem commits que não foram enviados para lugar nenhum5557### Worktree tem commits que não foram enviados para lugar nenhum

5558 5558

5559Você tentou deletar uma [sessão em background](https://code.claude.com/docs/pt/agent-view.md#what-deleting-a-session-removes) cujo worktree contém commits que Claude Code não consegue confirmar que estão salvos em outro lugar. Claude Code mantém o worktree e a linha de sessão em vez de destruir os commits sem vê-los. `claude rm` nomeia o branch e os commits não enviados, e diz como proceder:5559Você tentou deletar uma [sessão em background](https://code.claude.com/docs/pt/agent-view.md#what-deleting-a-session-removes) cujo worktree contém commits que Claude Code não consegue confirmar que estão salvos em outro lugar. `claude rm` diz como proceder:

5560 5560

5561```text theme={null}5561```text theme={null}

5562kept 7c5dcf5d — its worktree is still at “/home/you/project/.claude/worktrees/fix-login”5562kept 7c5dcf5d — its worktree is still at “/home/you/project/.claude/worktrees/fix-login”

5566 5566

5567Quando Claude Code não consegue resumir os commits, a linha de detalhe lê `The worktree has unpushed commits` em vez disso. Na [agent view](https://code.claude.com/docs/pt/agent-view.md), a linha da sessão mostra `not removed` com a mesma razão.5567Quando Claude Code não consegue resumir os commits, a linha de detalhe lê `The worktree has unpushed commits` em vez disso. Na [agent view](https://code.claude.com/docs/pt/agent-view.md), a linha da sessão mostra `not removed` com a mesma razão.

5568 5568

5569Commits em um remote não bloqueiam o delete. Nem commits na cópia local do branch padrão do seu remote `origin`, desde que esse branch esteja em checkout no seu checkout principal, o diretório do repositório em si em vez de um worktree.

~~5570~~

5571**O que fazer:**5569**O que fazer:**

5572 5570

5573* Para manter os commits, envie o branch do worktree, ou mescle-o no branch padrão em checkout no seu checkout principal, depois delete a sessão novamente5571* Para manter os commits, envie-os. Depois que o push os colocar em um branch de rastreamento remoto, como `origin/claude/fix-login`, tente deletar a sessão novamente.

5574* Para descartar os commits, execute o comando `claude rm <id> --discard-unpushed` que a mensagem imprimiu, ou pressione `Ctrl+X` duas vezes na linha da sessão na agent view novamente. Isso remove a sessão e o worktree junto com seu branch, os commits não enviados, e quaisquer mudanças sem commit. Se o delete for recusado novamente, siga a nova mensagem.5572* Se a mensagem oferecer descartar os commits, primeiro certifique-se de que você não precisa do worktree, dos commits nem de quaisquer mudanças sem commit. Depois siga o passo que a mensagem indica: pressione `Ctrl+X` duas vezes na linha da sessão na agent view, ou execute o comando `claude rm <id> --discard-unpushed <commit>@<worktree-id>` que `claude rm` imprimiu. Se Claude Code recusar novamente, siga a nova mensagem.

5575* Quando a mensagem diz que o worktree também é registrado por outra sessão terminada, deletar novamente não o descarta: envie os commits, depois delete a sessão novamente5573* Quando a mensagem diz que o worktree também é registrado por outra sessão terminada, deletar novamente não o descarta: envie os commits, depois tente deletar a sessão novamente

5576 5574

5577Antes da v2.1.268, `claude rm` colocava o resumo de commit na linha `kept` em si. Quando `claude rm` não conseguia resumir os commits, a linha `kept` lia `worktree has commits that are not pushed anywhere` no lugar do resumo.5575Antes da v2.1.268, `claude rm` colocava o resumo de commit na linha `kept` em si. Quando `claude rm` não conseguia resumir os commits, a linha `kept` lia `worktree has commits that are not pushed anywhere` no lugar do resumo.

5578 5576

5579Antes da v2.1.260, a mensagem não nomeava o branch ou os commits, e não havia uma forma de descartá-los. Você ainda pode deletar a sessão, perdendo as mudanças sem commit mas mantendo o branch e os commits. Execute `git worktree remove --force --force <path>` com o caminho que a recusa imprimiu, depois `claude rm <id>`. O Git precisa de `--force` duas vezes para um worktree bloqueado.5577Antes da v2.1.260, a mensagem não nomeava o branch ou os commits, e não havia uma forma de descartá-los. Você ainda pode deletar a sessão, perdendo as mudanças sem commit mas mantendo o branch e os commits. Execute `git worktree remove --force --force <path>` com o caminho que a recusa imprimiu, depois `claude rm <id>`. O Git precisa de `--force` duas vezes para um worktree bloqueado.

5580 5578

5581Antes da v2.1.248, o branch padrão em checkout no seu checkout principal não contava: um branch que você já tinha mesclado lá ainda acionava essa recusa até seus commits chegarem a um remote.

~~5582~~

5583### Processo host do terminal morreu5579### Processo host do terminal morreu

5584 5580

5585Cada terminal de [sessão em background](https://code.claude.com/docs/pt/agent-view.md) é executado em um processo host sob o serviço em background, e esse processo morreu enquanto o serviço ainda mantinha sua conexão, portanto a sessão não pôde ser alcançada.5581Cada terminal de [sessão em background](https://code.claude.com/docs/pt/agent-view.md) é executado em um processo host sob o serviço em background, e esse processo morreu enquanto o serviço ainda mantinha sua conexão, portanto a sessão não pôde ser alcançada.

feature-availability.md +1 −1

Details

35Estes têm diferenças específicas do provedor:35Estes têm diferenças específicas do provedor:

36 36

37* **Servidores MCP**: [conectores do claude.ai](https://code.claude.com/docs/pt/mcp.md#use-mcp-servers-from-claude-ai) carregam apenas quando sua assinatura claude.ai é o método de autenticação ativo. [Busca de ferramentas](https://code.claude.com/docs/pt/mcp.md#configure-tool-search) não é suportada em [implantações hospedadas no Azure](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options) do Microsoft Foundry. No Google Cloud's Agent Platform, a busca de ferramentas não é suportada em modelos anteriores a Claude Opus 4.5, Claude Sonnet 4.5 e Claude Haiku 4.537* **Servidores MCP**: [conectores do claude.ai](https://code.claude.com/docs/pt/mcp.md#use-mcp-servers-from-claude-ai) carregam apenas quando sua assinatura claude.ai é o método de autenticação ativo. [Busca de ferramentas](https://code.claude.com/docs/pt/mcp.md#configure-tool-search) não é suportada em [implantações hospedadas no Azure](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options) do Microsoft Foundry. No Google Cloud's Agent Platform, a busca de ferramentas não é suportada em modelos anteriores a Claude Opus 4.5, Claude Sonnet 4.5 e Claude Haiku 4.5

38* **Subagents**: quando a conversa principal executa Fable, o [Explore subagent](https://code.claude.com/docs/pt/sub-agents.md#built-in-subagents) integrado é executado no Opus com uma assinatura Claude, uma conta Anthropic Console ou um [LLM gateway](https://code.claude.com/docs/pt/llm-gateway) acessado através de `ANTHROPIC_BASE_URL`. Em outros provedores, incluindo Claude Platform on AWS, ele é executado no Fable38* **Subagentes**: quando a conversa principal executa Fable, o [subagente Explore](https://code.claude.com/docs/pt/sub-agents.md#built-in-subagents) integrado é executado no Opus com uma assinatura do Claude, uma conta do Anthropic Console ou um [gateway de LLM](https://code.claude.com/docs/pt/llm-gateway) acessado por meio de `ANTHROPIC_BASE_URL`. Em outros provedores, incluindo o Claude Platform on AWS, ele é executado no Fable

39* **[Commands](https://code.claude.com/docs/pt/commands.md#all-commands)**:39* **[Commands](https://code.claude.com/docs/pt/commands.md#all-commands)**:

40 * `/design-sync` e `/import` com sua forma de subcomando `claude import` não estão disponíveis no Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry e Claude Platform on AWS, e através de um [gateway de aplicativos Claude](https://code.claude.com/docs/pt/claude-apps-gateway#availability-and-limitations)40 * `/design-sync` e `/import` com sua forma de subcomando `claude import` não estão disponíveis no Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry e Claude Platform on AWS, e através de um [gateway de aplicativos Claude](https://code.claude.com/docs/pt/claude-apps-gateway#availability-and-limitations)

41 * `/voice` requer uma conta claude.ai41 * `/voice` requer uma conta claude.ai

features-overview.md +2 −2

Details

186>186>

187> **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.187> **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.

188>188>

189> **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.189> **Coloque as proteções em hooks.** Uma instrução como "nunca edite `.env`" no CLAUDE.md ou em uma skill é um pedido, não uma garantia. Um hook `PreToolUse` que bloqueia a edição é imposição garantida da regra. Se uma regra precisa valer todas as vezes, transforme-a em um hook em vez de uma instrução no prompt.

190>190>

191> **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.191> **Combine um hook com uma skill.** Use um hook `PostToolUse` para executar seu linter e [enviar os erros para Claude](https://code.claude.com/docs/pt/hooks.md#exit-code-2-behavior-per-event). Para dar a Claude suas próprias regras para corrigir os erros, escreva uma skill como `/fix-lint`.

192 192

193### Entender como os recursos se sobrepõem193### Entender como os recursos se sobrepõem

194 194

glossary.md +1 −1

Details

283 283

284### Sandboxing284### Sandboxing

285 285

286Isolamento de sistema de arquivos e rede em nível de SO para a ferramenta Bash. Os comandos são executados dentro de um limite que você define antecipadamente, para que Claude possa trabalhar livremente dentro dele sem prompts de aprovação por comando. O sandboxing é uma camada separada das [regras de permissão](#permission-rule).286Isolamento de sistema de arquivos e rede em nível de SO para a ferramenta Bash. Os comandos são executados dentro de um limite que você define antecipadamente. O sandboxing é uma camada separada das [regras de permissão](#permission-rule).

287 287

288Saiba mais: [Sandboxing](https://code.claude.com/docs/pt/sandboxing.md)288Saiba mais: [Sandboxing](https://code.claude.com/docs/pt/sandboxing.md)

289 289

hooks-guide.md +5 −1

Details

242 242

243### Bloquear edições em arquivos protegidos243### Bloquear edições em arquivos protegidos

244 244

245Impeça que Claude modifique arquivos sensíveis como `.env`, `package-lock.json` ou qualquer coisa em `.git/`. Claude recebe feedback explicando por que a edição foi bloqueada, para que possa ajustar sua abordagem.245Impeça que as ferramentas `Edit` e `Write` do Claude modifiquem arquivos sensíveis como `.env`, `package-lock.json` ou qualquer coisa em `.git/`. Claude recebe feedback explicando por que a edição foi bloqueada, para que possa ajustar sua abordagem.

246 246

247Este exemplo usa um arquivo de script separado que o hook chama. O script verifica o caminho do arquivo de destino contra uma lista de padrões protegidos e sai com código 2 para bloquear a edição.247Este exemplo usa um arquivo de script separado que o hook chama. O script verifica o caminho do arquivo de destino contra uma lista de padrões protegidos e sai com código 2 para bloquear a edição.

248 248

306 306

307Peça ao Claude para adicionar um comentário ao seu arquivo `.env`. Claude Code bloqueia a edição antes de executá-la e passa a mensagem `Blocked:` do script para Claude como feedback.307Peça ao Claude para adicionar um comentário ao seu arquivo `.env`. Claude Code bloqueia a edição antes de executá-la e passa a mensagem `Blocked:` do script para Claude como feedback.

308 308

309Claude ainda pode alterar os arquivos protegidos com comandos shell. Para bloquear alguns desses comandos, adicione uma [regra de negação `Edit`](https://code.claude.com/docs/pt/permissions#what-read-and-edit-rules-cover) por caminho em `permissions.deny` no `.claude/settings.json`, como `Edit(/.env)` para o `.env` da raiz do projeto.

310

311Mesmo com essas regras, Claude pode alterar o `.env` de outras formas. Para limitar em quais arquivos os comandos podem escrever, consulte [Configurar sandboxing](https://code.claude.com/docs/pt/sandboxing.md#configure-sandboxing).

312

309### Re-injetar contexto após compactação313### Re-injetar contexto após compactação

310 314

311Quando a janela de contexto do Claude fica cheia, a compactação resume a conversa para liberar espaço. Isto pode perder detalhes importantes. Use um hook `SessionStart` com um matcher `compact` para re-injetar contexto crítico após cada compactação.315Quando a janela de contexto do Claude fica cheia, a compactação resume a conversa para liberar espaço. Isto pode perder detalhes importantes. Use um hook `SessionStart` com um matcher `compact` para re-injetar contexto crítico após cada compactação.

llm-gateway-protocol.md +1 −0

Details

296* O campo `output_config.effort` de nível superior. [Retry automático e encaminhamento de erro](#automatic-retry-and-error-forwarding) cobre um upstream que o rejeita296* O campo `output_config.effort` de nível superior. [Retry automático e encaminhamento de erro](#automatic-retry-and-error-forwarding) cobre um upstream que o rejeita

297* O campo `thinking` do raciocínio adaptativo, que não tem header beta297* O campo `thinking` do raciocínio adaptativo, que não tem header beta

298* As entradas `role: "system"` que carregam [mensagens de sistema no meio da conversa](#feature-pass-through)298* As entradas `role: "system"` que carregam [mensagens de sistema no meio da conversa](#feature-pass-through)

299* O valor `anthropic-beta` e o campo `safeguards` da [revisão do classificador no lado do servidor](https://code.claude.com/docs/pt/permission-modes.md#server-side-classifier-review) do modo auto, em sessões em que essa revisão permanece ativada, como quando `/status` mostra **Auto mode server** como `Enabled`. Para desativar a revisão, defina `CLAUDE_CODE_AUTO_MODE_SERVER=0` antes de iniciar a sessão. No terminal, `/status` então mostra **Auto mode server** como `Disabled`.

299* O valor `anthropic-beta` de OAuth que a autenticação de assinatura requer300* O valor `anthropic-beta` de OAuth que a autenticação de assinatura requer

300* Valores de header e campos de corpo que os próprios desenvolvedores adicionam por meio de [`ANTHROPIC_BETAS`](https://code.claude.com/docs/pt/env-vars) ou [`CLAUDE_CODE_EXTRA_BODY`](https://code.claude.com/docs/pt/env-vars)301* Valores de header e campos de corpo que os próprios desenvolvedores adicionam por meio de [`ANTHROPIC_BETAS`](https://code.claude.com/docs/pt/env-vars) ou [`CLAUDE_CODE_EXTRA_BODY`](https://code.claude.com/docs/pt/env-vars)

301 302

managed-mcp.md +3 −2

Details

31| :- | :- | :- |31| :- | :- | :- |

32| **Desabilitar MCP** | Nenhum servidor é carregado, exceto os poucos que [carregam sob controle exclusivo](#exclusive-control-with-managed-mcp-json) | `managed-mcp.json` com um mapa de servidor vazio |32| **Desabilitar MCP** | Nenhum servidor é carregado, exceto os poucos que [carregam sob controle exclusivo](#exclusive-control-with-managed-mcp-json) | `managed-mcp.json` com um mapa de servidor vazio |

35| **Catálogo aprovado** | Publique uma lista de servidores aprovados; os usuários adicionam os que desejam, qualquer outra coisa é bloqueada | `allowedMcpServers` + `allowManagedMcpServersOnly: true` |35| **Catálogo aprovado** | Publique uma lista de servidores aprovados; os usuários adicionam os que desejam, qualquer outra coisa é bloqueada | `allowedMcpServers` + `allowManagedMcpServersOnly: true` |

36| **Apenas servidores de plugin** | Os usuários não podem adicionar servidores através de `~/.claude.json` ou `.mcp.json`; [plugins de diretório de skills](https://code.claude.com/docs/pt/plugins/loading.md#skills-directory-plugins-blocked-by-managed-settings) deixam de ser carregados como plugins, e os servidores de outros plugins ainda são carregados | [`strictPluginOnlyCustomization`](https://code.claude.com/docs/pt/settings-reference#strictpluginonlycustomization) com `mcp` na lista |36| **Apenas servidores de plugin** | Os usuários não podem adicionar servidores através de `~/.claude.json` ou `.mcp.json`; [plugins de diretório de skills](https://code.claude.com/docs/pt/plugins/loading.md#skills-directory-plugins-blocked-by-managed-settings) deixam de ser carregados como plugins, e os servidores de outros plugins ainda são carregados | [`strictPluginOnlyCustomization`](https://code.claude.com/docs/pt/settings-reference#strictpluginonlycustomization) com `mcp` na lista |

49* Os servidores que o arquivo define49* Os servidores que o arquivo define

50* Servidores que você [fornece através de `managedMcpServers`](#provide-servers-through-managed-settings)50* Servidores que você [fornece através de `managedMcpServers`](#provide-servers-through-managed-settings)

51* Servidores em processo que o aplicativo que iniciou a sessão registra, como o servidor próprio da extensão VS Code ou os [conectores que o aplicativo desktop fornece](https://code.claude.com/docs/pt/mcp.md#how-connectors-reach-claude-code)51* Servidores em processo que o aplicativo que iniciou a sessão registra, como o servidor próprio da extensão VS Code ou os [conectores que o aplicativo desktop fornece](https://code.claude.com/docs/pt/mcp.md#how-connectors-reach-claude-code)

52* O servidor que Claude Code cria quando um [mod](https://code.claude.com/docs/pt/plugins/mods/overview.md) [adiciona ferramentas](https://code.claude.com/docs/pt/plugins/mods/api.md#add-a-tool). Para bloquear as ferramentas que os mods de seus usuários adicionam, [impeça que mods instalados pelo usuário sejam carregados](https://code.claude.com/docs/pt/plugins/mods/admin.md#stop-user-installed-mods-from-loading).

52* O servidor integrado [Claude in Chrome](https://code.claude.com/docs/pt/chrome.md), se você [permitir junto com o conjunto gerenciado](#allow-claude-in-chrome-alongside-the-managed-set)53* O servidor integrado [Claude in Chrome](https://code.claude.com/docs/pt/chrome.md), se você [permitir junto com o conjunto gerenciado](#allow-claude-in-chrome-alongside-the-managed-set)

53 54

54Os usuários não podem adicionar, modificar ou usar nenhum outro servidor MCP, incluindo servidores fornecidos por plugins e servidores passados com a [flag CLI `--mcp-config`](https://code.claude.com/docs/pt/cli-reference#cli-flags). O arquivo também suprime os conectores claude.ai que Claude Code busca por si mesmo, a menos que você [permita-os junto com o conjunto gerenciado](#allow-claude-ai-connectors-alongside-the-managed-set).55Os usuários não podem adicionar, modificar ou usar nenhum outro servidor MCP, incluindo servidores fornecidos por plugins e servidores passados com a [flag CLI `--mcp-config`](https://code.claude.com/docs/pt/cli-reference#cli-flags). O arquivo também suprime os conectores claude.ai que Claude Code busca por si mesmo, a menos que você [permita-os junto com o conjunto gerenciado](#allow-claude-ai-connectors-alongside-the-managed-set).

137}138}

138```139```

139 140

140`claude mcp add` falha com o erro de política empresarial acima. Os servidores que os usuários configuraram anteriormente param de ser carregados na próxima vez que iniciam uma sessão, sem aviso de que a política é o motivo. Os servidores que você fornece através de `managedMcpServers`, e qualquer outra coisa que você permita junto com o conjunto gerenciado, ainda carregam sob um mapa vazio, portanto deixe essas chaves não definidas para desabilitar MCP completamente.141`claude mcp add` falha com o erro de política empresarial acima. Os servidores que os usuários configuraram anteriormente param de ser carregados na próxima vez que iniciam uma sessão, sem aviso de que a política é o motivo. Os servidores que você fornece através de `managedMcpServers`, e qualquer outra coisa que você permita junto com o conjunto gerenciado, [ainda carregam](#exclusive-control-with-managed-mcp-json) sob um mapa vazio, portanto deixe essas chaves não definidas.

141 142

142### Permitir conectores claude.ai junto com o conjunto gerenciado143### Permitir conectores claude.ai junto com o conjunto gerenciado

143 144

mcp.md +1 −1

Details

806 806

807* Adicione-o a [`disabledMcpjsonServers`](https://code.claude.com/docs/pt/settings-reference#disabledmcpjsonservers), que o bloqueia em todos os modos de permissão.807* Adicione-o a [`disabledMcpjsonServers`](https://code.claude.com/docs/pt/settings-reference#disabledmcpjsonservers), que o bloqueia em todos os modos de permissão.

808* Exclua as configurações do projeto inteiramente com [`--setting-sources`](https://code.claude.com/docs/pt/cli-reference#cli-flags) ou a opção `settingSources` do SDK.808* Exclua as configurações do projeto inteiramente com [`--setting-sources`](https://code.claude.com/docs/pt/cli-reference#cli-flags) ou a opção `settingSources` do SDK.

809* Inicie a sessão com [`--strict-mcp-config`](https://code.claude.com/docs/pt/cli-reference#cli-flags). Claude Code então usa apenas os servidores MCP que você passa com `--mcp-config`. Ignorar o prompt de aprovação para os servidores com escopo de projeto que Claude Code não está carregando requer Claude Code v2.1.246 ou posterior; antes de v2.1.246, uma sessão estrita ainda aguardava aprovação para eles, o que deixava sessões em segundo plano aguardando na inicialização. Veja [Controle exclusivo com managed-mcp.json](https://code.claude.com/docs/pt/managed-mcp.md#exclusive-control-with-managed-mcp-json) para o que o sinalizador faz sob um arquivo MCP gerenciado.809* Inicie a sessão com [`--strict-mcp-config`](https://code.claude.com/docs/pt/cli-reference#cli-flags). Claude Code então carrega os servidores que você passa com `--mcp-config` e ignora os configurados em locais como `.mcp.json`. Ignorar o prompt de aprovação para os servidores com escopo de projeto que Claude Code não está carregando requer Claude Code v2.1.246 ou posterior. Veja [Controle exclusivo com managed-mcp.json](https://code.claude.com/docs/pt/managed-mcp.md#exclusive-control-with-managed-mcp-json) para o que a flag faz sob um arquivo MCP gerenciado.

810 810

811[Aprovações de servidor de projeto e confiança do espaço de trabalho](#project-server-approvals-and-workspace-trust) aborda como as aprovações confirmadas no repositório interagem com a confiança do espaço de trabalho.811[Aprovações de servidor de projeto e confiança do espaço de trabalho](#project-server-approvals-and-workspace-trust) aborda como as aprovações confirmadas no repositório interagem com a confiança do espaço de trabalho.

812 812

model-config.md +2 −2

Details

273* **`/model`**: Claude Code rejeita a mudança com um erro273* **`/model`**: Claude Code rejeita a mudança com um erro

274* **Flag `--model`, `ANTHROPIC_MODEL` ou a configuração `model`**: Claude Code substitui o valor na inicialização com um aviso nomeando os modelos solicitado e substituído, e a sessão inicia no modelo padrão274* **Flag `--model`, `ANTHROPIC_MODEL` ou a configuração `model`**: Claude Code substitui o valor na inicialização com um aviso nomeando os modelos solicitado e substituído, e a sessão inicia no modelo padrão

275* **[`ANTHROPIC_DEFAULT_MODEL`](#set-a-default-model-for-new-sessions)**: Claude Code ignora a variável275* **[`ANTHROPIC_DEFAULT_MODEL`](#set-a-default-model-for-new-sessions)**: Claude Code ignora a variável

276* **Substituição de subagente ou colega**: Claude Code executa o subagente ou colega em um modelo de fallback em vez de falhar na solicitação. Veja [Escolher um modelo](https://code.claude.com/docs/pt/sub-agents.md#choose-a-model) para o fallback do subagente e [Especificar colegas e modelos](https://code.claude.com/docs/pt/agent-teams.md#specify-teammates-and-models) para o fallback do colega.276* **Substituição de subagente ou colega**: Claude Code executa o subagente ou colega em um modelo de fallback em vez de falhar na requisição. Veja [Quando uma allowlist bloqueia um modelo de subagente](https://code.claude.com/docs/pt/sub-agents.md#when-an-allowlist-blocks-a-subagent-model) para o fallback do subagente e [Especificar colegas e modelos](https://code.claude.com/docs/pt/agent-teams.md#specify-teammates-and-models) para o fallback do colega.

277 277

278 Em sessões interativas, Claude Code avisa quando substitui o modelo de um subagente, por este fallback ou pela substituição de versão mais recente permitida acima, nomeando os modelos solicitado e substituído; não relata um fallback de colega.278 Em sessões interativas, Claude Code avisa você quando substitui o modelo de um subagente de nível superior. Ele não relata o fallback de um colega.

279 279

280 Onde a substituição de versão mais recente permitida acima opera, um alias de família bloqueado a segue. Antes da v2.1.222, um alias caía de volta como qualquer outro valor bloqueado em cada provedor280 Onde a substituição de versão mais recente permitida acima opera, um alias de família bloqueado a segue. Antes da v2.1.222, um alias caía de volta como qualquer outro valor bloqueado em cada provedor

281* **Substituição de skill ou comando**: Claude Code ignora a substituição, incluindo um alias de família bloqueado, e o skill ou comando é executado no modelo de sessão. Um skill ou comando que [é executado em um subagente](https://code.claude.com/docs/pt/skills.md#run-skills-in-a-subagent) segue o comportamento do subagente acima281* **Substituição de skill ou comando**: Claude Code ignora a substituição, incluindo um alias de família bloqueado, e o skill ou comando é executado no modelo de sessão. Um skill ou comando que [é executado em um subagente](https://code.claude.com/docs/pt/skills.md#run-skills-in-a-subagent) segue o comportamento do subagente acima

permission-modes.md +1 −1

Details

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

53| Iterar localmente com menos prompts, sem um classificador | Modo Manual mais o sandbox Bash em [modo auto-allow](https://code.claude.com/docs/pt/sandboxing.md#sandbox-modes): `claude --permission-mode default`, depois execute `/sandbox` e selecione auto-allow | O sandbox Bash integrado, em macOS, Linux e WSL2 | Regras de negação ainda se aplicam, e regras de solicitação que nomeiam um comando, como `Bash(git push *)`, ainda solicitam. O [modo auto-allow](https://code.claude.com/docs/pt/sandboxing.md#auto-allow-mode) abrange outros comandos que podem solicitar confirmação. Para ativar o sandbox a partir de um arquivo de configurações em vez disso, defina [`sandbox.enabled`](https://code.claude.com/docs/pt/settings-reference#sandbox-enabled) como `true` |53| Iterar localmente com menos prompts, sem um classificador | Modo Manual mais o sandbox Bash em [modo auto-allow](https://code.claude.com/docs/pt/sandboxing.md#sandbox-modes): `claude --permission-mode default`, depois execute `/sandbox` e selecione auto-allow | O sandbox Bash integrado, em macOS, Linux e WSL2 | Regras de negação ainda se aplicam, e regras de solicitação que nomeiam um comando, como `Bash(git push *)`, ainda solicitam. O [modo auto-allow](https://code.claude.com/docs/pt/sandboxing.md#auto-allow-mode) abrange outros comandos que podem solicitar confirmação. Para ativar o sandbox a partir de um arquivo de configurações em vez disso, defina [`sandbox.enabled`](https://code.claude.com/docs/pt/settings-reference#sandbox-enabled) e [`sandbox.autoAllowBashIfSandboxed`](https://code.claude.com/docs/pt/settings-reference#sandbox-autoallowbashifsandboxed) como `true` |

55| Trabalhar sem supervisão em modo automático | `claude --permission-mode auto`, o [modo de permissão inicial integrado](#which-mode-a-session-starts-in) com v2.1.283 ou posterior | Nenhum; um sandbox ou contêiner adiciona defesa em profundidade | Requer um [modelo suportado](#eliminate-prompts-with-auto-mode), e sua organização pode [desativar o modo automático](#eliminate-prompts-with-auto-mode) |55| Trabalhar sem supervisão em modo automático | `claude --permission-mode auto`, o [modo de permissão inicial integrado](#which-mode-a-session-starts-in) com v2.1.283 ou posterior | Nenhum; um sandbox ou contêiner adiciona defesa em profundidade | Requer um [modelo suportado](#eliminate-prompts-with-auto-mode), e sua organização pode [desativar o modo automático](#eliminate-prompts-with-auto-mode) |

56| Executar em CI com uma lista de permissões exata | `claude -p "run the test suite" --permission-mode dontAsk --allowedTools "Bash(npm test)" "Read"` | Nenhum além do que seu executor de CI fornece | [Cloud sessions](https://code.claude.com/docs/pt/claude-code-on-the-web.md) ignora `dontAsk` de arquivos de configurações |56| Executar em CI com uma lista de permissões exata | `claude -p "run the test suite" --permission-mode dontAsk --allowedTools "Bash(npm test)" "Read"` | Nenhum além do que seu executor de CI fornece | [Cloud sessions](https://code.claude.com/docs/pt/claude-code-on-the-web.md) ignora `dontAsk` de arquivos de configurações |

permissions.md +1 −1

Details

743 743

744Use ambos para defesa em profundidade, já que as restrições de sandbox ainda se aplicam mesmo se uma injeção de prompt contornar a tomada de decisão do Claude. Caminhos e domínios tanto das configurações de sandbox quanto das regras de permissão são [mesclados na configuração final de sandbox](https://code.claude.com/docs/pt/sandboxing.md#permission-rules).744Use ambos para defesa em profundidade, já que as restrições de sandbox ainda se aplicam mesmo se uma injeção de prompt contornar a tomada de decisão do Claude. Caminhos e domínios tanto das configurações de sandbox quanto das regras de permissão são [mesclados na configuração final de sandbox](https://code.claude.com/docs/pt/sandboxing.md#permission-rules).

745 745

746Quando você ativa sandboxing e deixa `autoAllowBashIfSandboxed` em seu padrão de `true`, comandos Bash em sandbox são executados sem solicitação mesmo se suas permissões incluem uma regra de pergunta simples `Bash`, ou a [forma equivalente `Bash(*)`](#match-all-uses-of-a-tool): o limite de sandbox substitui esse prompt de ferramenta inteira.746Quando você ativa sandboxing e define [`sandbox.autoAllowBashIfSandboxed`](https://code.claude.com/docs/pt/settings-reference#sandbox-autoallowbashifsandboxed) como `true`, comandos Bash em sandbox são executados sem solicitação. Isso vale mesmo com uma regra de pergunta simples `Bash` ou a [forma equivalente `Bash(*)`](#match-all-uses-of-a-tool): o limite de sandbox substitui esse prompt de ferramenta inteira.

747 747

748Em [modo de planejamento](https://code.claude.com/docs/pt/permission-modes.md#analyze-before-you-edit-with-plan-mode), o Claude Code pula essa substituição. Sem uma regra de pergunta, os [comandos somente leitura integrados](#read-only-commands) ainda são executados sem solicitação, e qualquer outro comando shell passa pelo fluxo de permissão regular enquanto você ainda está planejando; veja [modo de planejamento](https://code.claude.com/docs/pt/permission-modes.md#analyze-before-you-edit-with-plan-mode) para como o Claude Code controla comandos lá. Com uma regra de pergunta simples `Bash`, cada comando Bash solicita, incluindo comandos somente leitura em sandbox, o mesmo que fora do sandboxing.748Em [modo de planejamento](https://code.claude.com/docs/pt/permission-modes.md#analyze-before-you-edit-with-plan-mode), o Claude Code pula essa substituição. Sem uma regra de pergunta, os [comandos somente leitura integrados](#read-only-commands) ainda são executados sem solicitação, e qualquer outro comando shell passa pelo fluxo de permissão regular enquanto você ainda está planejando; veja [modo de planejamento](https://code.claude.com/docs/pt/permission-modes.md#analyze-before-you-edit-with-plan-mode) para como o Claude Code controla comandos lá. Com uma regra de pergunta simples `Bash`, cada comando Bash solicita, incluindo comandos somente leitura em sandbox, o mesmo que fora do sandboxing.

749 749

plugins/mods/interface.md +91 −2

Details

438 438

439* **Os campos de `backdrop`**: `scene` é um [nome](https://code.claude.com/docs/pt/plugins/mods/reference.md#limits) que você escolhe para um plano de fundo que seu hook desenha. Para os outros campos e `overrideColorScheme`, consulte [os tipos para o seu build](https://code.claude.com/docs/pt/plugins/mods/create.md#get-the-types-for-your-build).439* **Os campos de `backdrop`**: `scene` é um [nome](https://code.claude.com/docs/pt/plugins/mods/reference.md#limits) que você escolhe para um plano de fundo que seu hook desenha. Para os outros campos e `overrideColorScheme`, consulte [os tipos para o seu build](https://code.claude.com/docs/pt/plugins/mods/create.md#get-the-types-for-your-build).

440* **Se o plano de fundo é desenhado**: `$.theme.set` resolve com `isDrawn: true` quando um app Desktop ou móvel conectado à sessão informa que desenha planos de fundo. Caso contrário, `isDrawn` é `false` e `reason` diz por quê.440* **Se o plano de fundo é desenhado**: `$.theme.set` resolve com `isDrawn: true` quando um app Desktop ou móvel conectado à sessão informa que desenha planos de fundo. Caso contrário, `isDrawn` é `false` e `reason` diz por quê.

441* **Um plano de fundo para cada sessão**: uma chamada `$.theme.set` substitui o plano de fundo da sessão e `$.theme.clear()` remove esse plano de fundo, independentemente de qual mod o definiu. Chame `$.theme.clear()` apenas quando o usuário pedir.441* **Um tema para cada sessão**: um mod que chama `$.theme.set` substitui o plano de fundo e as [cores](#change-the-colors-of-the-desktop-app) da sessão, e um mod que chama `$.theme.clear()` os remove, independentemente de qual mod os definiu. Chame `$.theme.clear()` apenas quando o usuário pedir.

442

443### Alterar as cores do app Desktop

444

445Para alterar as cores da aba Code do app Desktop com um mod, [peça um ao Claude](#ask-claude-for-a-colors-mod) ou [escreva um você mesmo](#write-a-colors-mod-yourself). As duas formas requerem o Claude Code v2.1.324 ou posterior na aba Code, então [verifique a versão ali](https://code.claude.com/docs/pt/desktop.md#claude-code-version-in-the-code-tab) primeiro. O Claude Code no terminal mantém suas próprias cores.

446

447#### Pedir ao Claude um mod de cores

448

449**1. Descrever as cores**

450

451Inicie uma sessão local na aba Code e diga ao Claude quais cores você deseja. Por exemplo, digite `make a mod that makes the app cream in light mode and dark brown in dark mode`. O Claude escreve os arquivos do mod.

452

453**2. Aprovar o mod**

454

455Responda às perguntas que o Claude Code faz sobre os arquivos do mod e o hot reloading. Para saber o que cada resposta faz, consulte [Pedir um mod ao Claude](https://code.claude.com/docs/pt/plugins/mods/create.md#ask-claude-for-a-mod).

456

457**3. Verificar as cores**

458

459A aba Code muda de cor quando o mod é carregado. Para ajustar uma cor, diga ao Claude o que alterar. Se nada mudar, consulte [Corrigir cores de mod ausentes](#fix-missing-mod-colors-in-the-desktop-app).

460

461#### Escrever um mod de cores você mesmo

462

463`makeColors` é uma função que constrói um tema a partir de algumas cores hex. Estas etapas criam um mod chamado `paper` que a utiliza.

464

465**1. Pedir ao Claude para copiar makeColors**

466

467Inicie uma sessão local na aba Code e digite `copy make-colors.js and make-colors.d.ts from your plugin-authoring skill into ~/.claude/skills/paper/hooks/`. Verifique se os dois arquivos estão nesse diretório.

468

469**2. Salvar o manifesto e o hooks.json**

470

471A partir de [Escrever um mod você mesmo](https://code.claude.com/docs/pt/plugins/mods/create.md#write-a-mod-yourself), salve `.claude-plugin/plugin.json` e `hooks/hooks.json` em `~/.claude/skills/paper/` e altere `first-mod` para `paper` nos dois arquivos. Um mod [em `~/.claude/skills/`](https://code.claude.com/docs/pt/plugins/create#scaffold-a-plugin-that-loads-every-session) é carregado quando você inicia uma sessão.

472

473**3. Escrever o código**

474

475Salve este arquivo como `~/.claude/skills/paper/hooks/register.js`. Quando uma sessão começa, o código chama `$.theme.set` com as cores para o modo claro e o modo escuro:

476

477```javascript theme={null}

478import { makeColors } from './make-colors.js'

479

480const { theme } = makeColors({

481 label: 'Paper',

482 // surface-0 is the background, text-primary is the main text, and text-muted is the faint text

483 light: {

484 gray: { anchors: { 'surface-0': '#efe6d3', 'text-primary': '#2a241d', 'text-muted': '#6a5f50' } },

485 },

486 dark: {

487 gray: { anchors: { 'surface-0': '#1f1a15', 'text-primary': '#f0e7d7', 'text-muted': '#aca08d' } },

488 },

489})

490

491export function register(on) {

492 on('session.start', async ($, e, next) => {

493 await $.theme.set({ colors: theme })

494 return next(e)

495 })

496}

497```

498

499Para usar suas próprias cores, substitua os valores hex por outras cores hex de seis dígitos.

500

501**4. Verificar as cores**

502

503Inicie uma nova sessão local na aba Code. Com os valores do exemplo, o plano de fundo fica creme no modo claro e marrom-escuro no modo escuro. Se nada mudar, consulte [Corrigir cores de mod ausentes](#fix-missing-mod-colors-in-the-desktop-app).

504

505### Corrigir cores de mod ausentes no app Desktop

506

507Se você usa um [provedor terceirizado](https://code.claude.com/docs/pt/third-party-integrations.md) em vez de uma conta Claude no [Claude Desktop v5.11492.5 ou anterior](https://code.claude.com/docs/pt/desktop.md#check-your-version), a aba Code mantém suas próprias cores, então ignore estas verificações. Caso contrário, se as cores de um mod não aparecerem na aba Code, ou se desaparecerem, verifique estas causas:

508

509* **Versão antiga**: [atualize o app Desktop](https://code.claude.com/docs/pt/desktop.md#claude-code-version-in-the-code-tab), reinicie-o e inicie uma nova sessão local na aba Code. Se o Claude escreveu o mod, peça-o novamente ali.

510* **Mod não carregado**: se o Claude escreveu o mod, veja quando ele é carregado em [Pedir um mod ao Claude](https://code.claude.com/docs/pt/plugins/mods/create.md#ask-claude-for-a-mod). Se você o escreveu, compare seus arquivos e os caminhos deles com [Escrever um mod de cores você mesmo](#write-a-colors-mod-yourself).

511* **Tema recusado**: peça ao Claude para executar a chamada [`makeColors`](#write-a-colors-mod-yourself) do mod. Se a chamada lançar um erro, ou se a lista `problems` dela tiver uma entrada que comece com `Desktop won't paint this theme`, peça ao Claude para corrigir o tema. Se você instalou o mod, envie o que o Claude encontrar para o autor dele.

512* **Outra chamada `$.theme`**: quando qualquer mod na sessão chama `$.theme.set` ou `$.theme.clear()`, as cores e o [plano de fundo](#put-a-backdrop-behind-the-conversation) de uma chamada anterior desaparecem. No seu próprio mod, passe `colors` e `backdrop` na mesma chamada `$.theme.set`. Use um mod de cada vez que defina um tema.

513

514### Remover cores de mod do app Desktop

515

516Para remover as cores de um mod da aba Code, desative o mod primeiro. Um mod que ainda está ativado pode definir suas cores novamente.

517

518**1. Desativar o mod**

519

520* **O Claude escreveu o mod**: mova o diretório dele para fora da [pasta de mods](https://code.claude.com/docs/pt/plugins/mods/create.md#ask-claude-for-a-mod) da sessão em que o Claude o escreveu.

521* **Você colocou o mod em `~/.claude/skills/`**: mova o diretório dele, como `~/.claude/skills/paper/`, para um local fora de `~/.claude/skills/`.

522* **Você instalou o mod**: no app Desktop, [desative ou desinstale o plugin dele](https://code.claude.com/docs/pt/desktop.md#install-plugins) em **Manage plugins**. Se você não vê **Manage plugins** e tem [a CLI](https://code.claude.com/docs/pt/quickstart.md), pode [desativar ou desinstalar um plugin de marketplace a partir do seu shell](https://code.claude.com/docs/pt/plugins/install.md#manage-plugins-from-your-shell).

523

524**2. Iniciar uma nova sessão**

525

526Inicie uma nova sessão local na aba Code.

527

528**3. Remover cores que permanecem**

529

530Se as cores ainda estiverem lá, abra **Settings** a partir da aba Code e pesquise ali por `code appearance`. Abra o resultado e selecione **Remove colors**.

442 531

443## Construir uma árvore a partir de elementos532## Construir uma árvore a partir de elementos

444 533

677 766

678As mesmas teclas, ou na renderização em tela cheia um clique na linha, expandem a faixa novamente. Até lá, nada pressiona um botão nela: nenhum atalho de teclado, nenhum dígito digitado em um prompt vazio e nenhum atalho de teclado para a [`action`](https://code.claude.com/docs/pt/plugins/mods/reference#elements) de um botão. Se a faixa tiver foco do teclado quando o usuário a recolher, o foco retorna para o prompt, e Ctrl+X depois Tab pula a faixa enquanto ela está recolhida.767As mesmas teclas, ou na renderização em tela cheia um clique na linha, expandem a faixa novamente. Até lá, nada pressiona um botão nela: nenhum atalho de teclado, nenhum dígito digitado em um prompt vazio e nenhum atalho de teclado para a [`action`](https://code.claude.com/docs/pt/plugins/mods/reference#elements) de um botão. Se a faixa tiver foco do teclado quando o usuário a recolher, o foco retorna para o prompt, e Ctrl+X depois Tab pula a faixa enquanto ela está recolhida.

679 768

680A faixa permanece recolhida até que o usuário a expanda, mesmo após `/clear`, e é expandida novamente na próxima vez que o Claude Code iniciar. Seu mod não pode expandi-la nem saber que ela está recolhida: o hook `ui.render` continua sendo executado, e nada em `e.props` indica isso. Não faça da faixa o único lugar em que seu mod mostra algo que o usuário precisa responder.769A faixa permanece recolhida até que o usuário a expanda, mesmo após `/clear`, e é expandida novamente na próxima vez que o Claude Code iniciar. Seu mod não pode expandi-la. Não faça da faixa o único lugar em que seu mod mostra algo que o usuário precisa responder. Para mostrar isso em outro lugar apenas enquanto a faixa está recolhida, leia `e.props.isCollapsed` em seu hook `ui.render`, que continua sendo executado. `isCollapsed` requer o Claude Code v2.1.321 ou posterior.

681 770

682### Tomar entrada digitada e desenhar uma linha para cada item771### Tomar entrada digitada e desenhar uma linha para cada item

683 772

plugins/mods/reference.md +16 −3

Details

212 212

213Alguns desses eventos também são disparados para as ações do próprio Claude Code, então verifique se `next.origin.plugin` é `engine` antes de recusar um deles.213Alguns desses eventos também são disparados para as ações do próprio Claude Code, então verifique se `next.origin.plugin` é `engine` antes de recusar um deles.

214 214

215#### Campos nas requisições `http.fetch` do próprio Claude Code

216

217Em um hook `http.fetch`, um [`next.origin`](#the-hook-function) de `{ plugin: 'engine', tier: 'core' }` marca uma das requisições do próprio Claude Code, como uma requisição ao modelo, e não uma chamada `$.http.fetch` de um mod. Onde a [guarda integrada](https://code.claude.com/docs/pt/plugins/mods/admin.md#know-what-happens-by-default) está carregada, seu hook não recebe esses eventos, exceto se o seu mod [contar como um mod da sua organização](https://code.claude.com/docs/pt/plugins/mods/admin.md#install-your-organizations-mods).

218

219Nesses eventos, `e.init` e o `value` para o qual `next(e)` resolve podem conter estes campos, entre outros:

220

221| Campo | O que significa |

222| :- | :- |

223| `e.init.compress` | Definido quando o Claude Code comprime o corpo depois do seu hook. `e.init.body` contém o corpo não comprimido. Para enviar o corpo sem compressão, chame `next({ ...e, init: { ...e.init, compress: undefined } })`. |

224| `value.isStreaming` | Definido como `true` porque o próprio Claude Code lê o corpo da resposta, então `value.text` fica vazio. Em vez disso, leia `value.status` e `value.headers`. Para responder com o seu próprio `text`, retorne um `value` sem `isStreaming`. |

225

226Esses eventos e campos exigem o Claude Code v2.1.321 ou posterior.

227

215## Métodos da API de mods228## Métodos da API de mods

216 229

217A API de mods é o argumento `$` que todo hook recebe. Seus métodos estão agrupados em namespaces, como `$.ui`. Esta tabela lista os métodos de cada namespace pelo nome, então `open` na linha de `$.ui` é a chamada `$.ui.open(...)`. Os guias mostram os mais comuns em uso, e [os tipos para o seu build](https://code.claude.com/docs/pt/plugins/mods/create.md#get-the-types-for-your-build) documentam cada método com um exemplo.230A API de mods é o argumento `$` que todo hook recebe. Seus métodos estão agrupados em namespaces, como `$.ui`. Esta tabela lista os métodos de cada namespace pelo nome, então `open` na linha de `$.ui` é a chamada `$.ui.open(...)`. Os guias mostram os mais comuns em uso, e [os tipos para o seu build](https://code.claude.com/docs/pt/plugins/mods/create.md#get-the-types-for-your-build) documentam cada método com um exemplo.

222| [`$.ui`](https://code.claude.com/docs/pt/plugins/mods/interface#pick-where-to-draw) | `resolve`, `invalidate`, `open`, `close`, `panes`, [`place`](https://code.claude.com/docs/pt/plugins/mods/interface#place-a-row-in-the-transcript), `focus`, `scroll`, `toast`, `notify`, `status`, `log`, `notice`, `ask`, `copy`, `selection`, `blit`, `view`. `view` exige o Claude Code v2.1.300 ou posterior e `place`, a v2.1.314 ou posterior. |235| [`$.ui`](https://code.claude.com/docs/pt/plugins/mods/interface#pick-where-to-draw) | `resolve`, `invalidate`, `open`, `close`, `panes`, [`place`](https://code.claude.com/docs/pt/plugins/mods/interface#place-a-row-in-the-transcript), `focus`, `scroll`, `toast`, `notify`, `status`, `log`, `notice`, `ask`, `copy`, `selection`, `blit`, `view`. `view` exige o Claude Code v2.1.300 ou posterior e `place`, a v2.1.314 ou posterior. |

223| [`$.theme`](https://code.claude.com/docs/pt/plugins/mods/interface#put-a-backdrop-behind-the-conversation) | `set`, `clear`: define um plano de fundo para o aplicativo Desktop ou móvel desenhar e remove o plano de fundo. Exige o Claude Code v2.1.319 ou posterior. |236| [`$.theme`](https://code.claude.com/docs/pt/plugins/mods/interface#put-a-backdrop-behind-the-conversation) | `set`, `clear`: define um plano de fundo para o aplicativo Desktop ou móvel desenhar e remove o plano de fundo. Exige o Claude Code v2.1.319 ou posterior. |

225| [`$.tool`](https://code.claude.com/docs/pt/plugins/mods/api#add-a-tool) | `register`, `call`, `check`, `list` |238| [`$.tool`](https://code.claude.com/docs/pt/plugins/mods/api#add-a-tool) | `register`, `call`, `check`, `list`. Quando uma `call` precisa da aprovação de uma pessoa, como uma que um hook ou a sua organização responde com `ask`, ela é resolvida com `{ deny: "<tool> wasn't run: this call needs a person's approval, and a mod's own call can't ask for it." }`, em que `<tool>` é o nome da ferramenta. |

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

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

251| :- | :- | :- | :- |264| :- | :- | :- | :- |

253| [`AbovePrompt`](https://code.claude.com/docs/pt/plugins/mods/interface#pick-where-to-draw) | `hasSurvey`, `isWorking`, `maxRows`, `bodyColumns`, `scroll`, `view` | Uma instância | Terminal, Desktop |266| [`AbovePrompt`](https://code.claude.com/docs/pt/plugins/mods/interface#pick-where-to-draw) | `hasSurvey`, [`isCollapsed`](https://code.claude.com/docs/pt/plugins/mods/interface#when-the-user-collapses-the-band), `isWorking`, `maxRows`, `bodyColumns`, `scroll`, `view` | Uma instância | Terminal, Desktop |

254| `AbovePromptList`, a pilha de linhas `AbovePrompt` | `rows`, uma lista com um `{ plugin, tree }` para a linha de cada mod, mais as props de `AbovePrompt` | Uma instância | Terminal, Desktop. Requer Claude Code v2.1.323 ou posterior. |267| `AbovePromptList`, a pilha de linhas `AbovePrompt` | `rows`, uma lista com um `{ plugin, tree }` para a linha de cada mod, mais as props de `AbovePrompt` | Uma instância | Terminal, Desktop. Requer Claude Code v2.1.323 ou posterior. |

256| [`Backdrop`](https://code.claude.com/docs/pt/plugins/mods/interface#put-a-backdrop-behind-the-conversation) | `scene`, `plugin`, `glass`, `overrideColorScheme`. Antes da v2.1.323, `scene` era `id` e `overrideColorScheme` era `colorScheme`. | `backdrop` | Superfícies `desktop` e `mobile`. Seu hook é executado quando o aplicativo Desktop ou mobile solicita desenhar um plano de fundo. |269| [`Backdrop`](https://code.claude.com/docs/pt/plugins/mods/interface#put-a-backdrop-behind-the-conversation) | `scene`, `plugin`, `glass`, `overrideColorScheme`. Antes da v2.1.323, `scene` era `id` e `overrideColorScheme` era `colorScheme`. | `backdrop` | Superfícies `desktop` e `mobile`. Seu hook é executado quando o aplicativo Desktop ou mobile solicita desenhar um plano de fundo. |

427| :- | :- | :- |440| :- | :- | :- |

428| `CLAUDE_CODE_PLUGIN_DIRS` | Ambiente, ou `env` em `~/.claude/settings.json` | Diretórios de plugin a carregar como `--plugin-dir` faz, para aplicativos aos quais você não pode passar uma flag. Caminhos absolutos separados por `:`, ou `;` no Windows. |441| `CLAUDE_CODE_PLUGIN_DIRS` | Ambiente, ou `env` em `~/.claude/settings.json` | Diretórios de plugin a carregar como `--plugin-dir` faz, para aplicativos aos quais você não pode passar uma flag. Caminhos absolutos separados por `:`, ou `;` no Windows. |

429| `CLAUDE_CODE_PLUGIN_DIR_WATCH` | Ambiente | `1` faz com que uma sessão não interativa de longa duração recarregue os mods de `--plugin-dir` ao salvar |442| `CLAUDE_CODE_PLUGIN_DIR_WATCH` | Ambiente | Se os mods são recarregados ao salvar. Consulte a [referência de variáveis de ambiente](https://code.claude.com/docs/pt/env-vars.md) para os padrões e valores |

430| `prependPlugins`, `appendPlugins` | Configurações gerenciadas. Configurações do usuário somente em uma máquina sem configurações gerenciadas nem arquivo [`managed-mcp.json`](https://code.claude.com/docs/pt/managed-mcp#deploy-managed-mcp-json), em uma sessão cuja credencial não é um `/login` Team ou Enterprise. | Listas de ids de plugin, como `acme-guard@acme-tools`. Mods em `prependPlugins` são executados antes de todo mod que um usuário instala, e mods em `appendPlugins` são executados depois, na ordem listada. Consulte [A ordem em que os mods são executados](https://code.claude.com/docs/pt/plugins/mods/events.md#the-order-mods-run-in). |443| `prependPlugins`, `appendPlugins` | Configurações gerenciadas. Configurações do usuário somente em uma máquina sem configurações gerenciadas nem arquivo [`managed-mcp.json`](https://code.claude.com/docs/pt/managed-mcp#deploy-managed-mcp-json), em uma sessão cuja credencial não é um `/login` Team ou Enterprise. | Listas de ids de plugin, como `acme-guard@acme-tools`. Mods em `prependPlugins` são executados antes de todo mod que um usuário instala, e mods em `appendPlugins` são executados depois, na ordem listada. Consulte [A ordem em que os mods são executados](https://code.claude.com/docs/pt/plugins/mods/events.md#the-order-mods-run-in). |

431| `allowManagedModsOnly` | Configurações gerenciadas, como uma [opção da guarda integrada](https://code.claude.com/docs/pt/plugins/mods/admin.md#set-options-on-the-built-in-guard) | Somente mods que [contam como da sua organização](https://code.claude.com/docs/pt/plugins/mods/admin.md#install-your-organizations-mods), e mods integrados ao Claude Code, executam seus hooks. Os hooks de configuração dos usuários continuam em execução. |444| `allowManagedModsOnly` | Configurações gerenciadas, como uma [opção da guarda integrada](https://code.claude.com/docs/pt/plugins/mods/admin.md#set-options-on-the-built-in-guard) | Somente mods que [contam como da sua organização](https://code.claude.com/docs/pt/plugins/mods/admin.md#install-your-organizations-mods), e mods integrados ao Claude Code, executam seus hooks. Os hooks de configuração dos usuários continuam em execução. |

432| `allowModsToOverrideDenyRules` | Configurações gerenciadas, como uma [opção da guarda integrada](https://code.claude.com/docs/pt/plugins/mods/admin.md#set-options-on-the-built-in-guard) | Permite que um mod instalado por um usuário aprove uma chamada de ferramenta passando por cima da maioria dos [resultados que permanecem em vigor por padrão](https://code.claude.com/docs/pt/permissions.md#precedence-among-rules-hooks-and-mods), incluindo uma regra `deny` |445| `allowModsToOverrideDenyRules` | Configurações gerenciadas, como uma [opção da guarda integrada](https://code.claude.com/docs/pt/plugins/mods/admin.md#set-options-on-the-built-in-guard) | Permite que um mod instalado por um usuário aprove uma chamada de ferramenta passando por cima da maioria dos [resultados que permanecem em vigor por padrão](https://code.claude.com/docs/pt/permissions.md#precedence-among-rules-hooks-and-mods), incluindo uma regra `deny` |

plugins/mods/test.md +3 −4

Details

115 115

116### Seguir as regras do test kit116### Seguir as regras do test kit

117 117

118O test kit tem algumas regras próprias, e quebrar uma produz os erros que novos autores de testes encontram primeiro:

~~119~~

120* **Registre cada stub antes da primeira chamada do teste em `$`.** Chamar `on` depois disso lança um erro como `on("ui.render") after the test first called $`.118* **Registre cada stub antes da primeira chamada do teste em `$`.** Chamar `on` depois disso lança um erro como `on("ui.render") after the test first called $`.

121 119

122* **[`session.start`](https://code.claude.com/docs/pt/plugins/mods/reference#session) não é executado por si só.** Cada teste começa com seu módulo carregado recentemente e nenhum de seus hooks chamado, então variáveis de nível de módulo mantêm seus valores iniciais. Se um hook depende do que `session.start` configura, dispare-o primeiro:120* **[`session.start`](https://code.claude.com/docs/pt/plugins/mods/reference#session) não é executado por si só.** Cada teste começa com seu módulo carregado recentemente e nenhum de seus hooks chamado, então variáveis de nível de módulo mantêm seus valores iniciais. Se um hook depende do que `session.start` configura, dispare-o primeiro:

132 130

133 O segundo stub responde a chamada `$.command.register` que um hook `session.start` como o do [tutorial](https://code.claude.com/docs/pt/plugins/mods/create.md#write-a-mod-yourself) faz. Sem ele, essa chamada rejeita com `no implementation for command.register` e o kit pula seu hook, então nada depois da chamada no hook é executado. O teste não falha nesse ponto. O hook pulado é listado sob `the engine reported:` apenas se uma verificação posterior falhar.131 O segundo stub responde a chamada `$.command.register` que um hook `session.start` como o do [tutorial](https://code.claude.com/docs/pt/plugins/mods/create.md#write-a-mod-yourself) faz. Sem ele, essa chamada rejeita com `no implementation for command.register` e o kit pula seu hook, então nada depois da chamada no hook é executado. O teste não falha nesse ponto. O hook pulado é listado sob `the engine reported:` apenas se uma verificação posterior falhar.

134 132

135* **Um hook que retorna `next(e)` precisa de um stub para responder.** Quando seu hook [`ui.render`](https://code.claude.com/docs/pt/plugins/mods/reference#interface) retorna `next(e)`, por exemplo para não desenhar nada enquanto Claude está ocioso, [montá-lo](#test-a-drawing) falha com `no implementation for ui.render`. Registre um stub que retorna um elemento como dados simples:133* **Registre um stub `ui.render` para escolher o que `next(e)` retorna.** Quando seu hook [`ui.render`](https://code.claude.com/docs/pt/plugins/mods/reference#interface) retorna `next(e)`, por exemplo para não desenhar nada enquanto Claude está ocioso, a [montagem](#test-a-drawing) é bem-sucedida sem nenhum stub. Para fazer `next(e)` retornar um elemento que você escolher, registre um stub que o retorna como dados simples:

136 134

137 ```typescript theme={null}135 ```typescript theme={null}

138 // Stands for what Claude Code would draw at the site136 // Stands for what Claude Code would draw at the site

139 on('ui.render', () => ({ type: 'Text', props: {}, children: ['drawn by Claude Code'] }))137 on('ui.render', () => ({ type: 'Text', props: {}, children: ['drawn by Claude Code'] }))

140 ```138 ```

141 139

142 Com o stub registrado, a montagem é bem-sucedida, e `ui.find({ type: 'Text' })` retorna esse elemento sempre que seu hook retornou `next(e)`. Na v2.1.323 ou posterior, para a faixa, passe o nome do seu mod como segundo argumento para `on`, como em `{ plugin: 'my-mod' }`. Sem ele, o stub não responde ao seu `next(e)`.140 Onde o local [pode desenhar esse elemento](https://code.claude.com/docs/pt/plugins/mods/interface.md#change-what-claude-code-already-draws), `ui.find({ type: 'Text' })` o retorna quando seu hook retornou `next(e)`. Na v2.1.323 ou posterior, para a faixa, passe o nome do seu mod como segundo argumento para `on`, como em `{ plugin: 'my-mod' }`. Sem ele, o stub não responde ao seu `next(e)`. Antes da v2.1.321, a montagem falha com `no implementation for ui.render`, a menos que você registre o stub.

143 141

144* **Um stub para `turn.step` é um gerador assíncrono**, e o teste lê o fluxo até o final para obter o resultado:142* **Um stub para `turn.step` é um gerador assíncrono**, e o teste lê o fluxo até o final para obter o resultado:

145 143

316| `press({ key: 'more' })` | Pressiona o `Button` com essa chave |314| `press({ key: 'more' })` | Pressiona o `Button` com essa chave |

317| `input({ key: 'new-note', text: 'buy milk' })` | Digita o texto no `Input` com essa chave e pressiona Enter. Adicione `kind: 'change'` para digitar sem enviar. Para um campo com `rows`, o texto pode conter `\n`. |315| `input({ key: 'new-note', text: 'buy milk' })` | Digita o texto no `Input` com essa chave e pressiona Enter. Adicione `kind: 'change'` para digitar sem enviar. Para um campo com `rows`, o texto pode conter `\n`. |

318| `select({ key: 'size', value: 'large' })` | Escolhe a opção com esse valor no `Select` com essa chave |316| `select({ key: 'size', value: 'large' })` | Escolhe a opção com esse valor no `Select` com essa chave |

317| `keepsBeneath()` | Em um teste sem stub de `ui.render`, resolve para `true` quando o desenho inclui o que `next(e)` retornou, e `false` quando seu hook o deixou de fora. Em um teste que registra um, use `find` para procurar o que o stub desenhou. Requer Claude Code v2.1.321 ou posterior. |

319| `find({ key: 'more' })` ou `find({ type: 'Text', text: 'Count: 2' })` | Retorna o primeiro elemento correspondente como `{ type, props, children }`, ou `undefined`. `text` pode ser uma string ou uma expressão regular. |318| `find({ key: 'more' })` ou `find({ type: 'Text', text: 'Count: 2' })` | Retorna o primeiro elemento correspondente como `{ type, props, children }`, ou `undefined`. `text` pode ser uma string ou uma expressão regular. |

321 320

sandbox-environments.md +1 −1

Details

41 41

42| You want to | Start with |42| You want to | Start with |

43| :- | :- |43| :- | :- |

~~44| Reduzir prompts de permissão durante o trabalho diário em sua própria máquina | A [sandboxed Bash tool](https://code.claude.com/docs/pt/sandboxing.md), configurada com `/sandbox` |~~44| Reduzir prompts de permissão durante o trabalho diário em sua própria máquina | A [sandboxed Bash tool](https://code.claude.com/docs/pt/sandboxing.md) no modo auto-allow, configurada com `/sandbox` |

45| Deixar o Claude trabalhar sem supervisão com `--dangerously-skip-permissions` ou modo automático | O [dev container](https://code.claude.com/docs/pt/devcontainer.md) pré-configurado, qualquer container ou VM, ou o [sandbox runtime](#sandbox-runtime) |45| Deixar o Claude trabalhar sem supervisão com `--dangerously-skip-permissions` ou modo automático | O [dev container](https://code.claude.com/docs/pt/devcontainer.md) pré-configurado, qualquer container ou VM, ou o [sandbox runtime](#sandbox-runtime) |

46| Isolar servidores MCP e hooks bem como Bash, sem Docker | O sandbox runtime |46| Isolar servidores MCP e hooks bem como Bash, sem Docker | O sandbox runtime |

47| Padronizar um ambiente sandbox em toda uma equipe | O [dev container](https://code.claude.com/docs/pt/devcontainer.md) pré-configurado, copiado para seu repositório |47| Padronizar um ambiente sandbox em toda uma equipe | O [dev container](https://code.claude.com/docs/pt/devcontainer.md) pré-configurado, copiado para seu repositório |

sandboxing.md +4 −7

Details

6 6

7> Restrinja os arquivos e hosts de rede que os comandos de shell do Claude Code podem acessar com o sandbox integrado. Ative-o, defina o limite e corrija o que ele quebra.7> Restrinja os arquivos e hosts de rede que os comandos de shell do Claude Code podem acessar com o sandbox integrado. Ative-o, defina o limite e corrija o que ele quebra.

8 8

9O sandbox do Bash é um limite que o sistema operacional impõe em torno dos comandos de shell que o Claude executa na sua máquina. Você define quais arquivos e domínios de rede esses comandos podem acessar, e os limites se aplicam aos comandos Bash, PowerShell e Monitor e aos processos que eles iniciam. Como o sistema operacional aplica os limites enquanto um comando é executado, o Claude Code pode [executar comandos em sandbox sem pedir a você](#sandbox-modes) que aprove cada um deles.9O sandbox do Bash é um limite que o sistema operacional impõe em torno dos comandos de shell que o Claude executa na sua máquina. Você define quais arquivos e domínios de rede esses comandos podem acessar, e os limites se aplicam aos comandos Bash, PowerShell e Monitor e aos processos que eles iniciam. Os comandos em sandbox ainda passam pelo fluxo de permissão normal, a menos que você escolha o [modo de permissão automática](#sandbox-modes), que pode executá-los sem pedir a você.

10 10

11O sandbox abrange apenas comandos de shell. As ferramentas de arquivo do Claude, os servidores MCP e os hooks [são executados fora dele](#what-runs-outside-the-sandbox).11O sandbox abrange apenas comandos de shell. As ferramentas de arquivo do Claude, os servidores MCP e os hooks [são executados fora dele](#what-runs-outside-the-sandbox).

12 12

394| Entradas `deny` e `mask` de `credentials.envVars` | Aplicadas. A limpeza de variáveis de ambiente é independente da camada de sistema de arquivos |394| Entradas `deny` e `mask` de `credentials.envVars` | Aplicadas. A limpeza de variáveis de ambiente é independente da camada de sistema de arquivos |

395| [Entradas `mask` de `credentials.files`](#mask-credential-files) aplicadas como máscaras | Aplicadas: o mascaramento é independente da camada de sistema de arquivos. Uma entrada que [recorreu ao fallback `deny`](#mask-credential-files) não é aplicada, como qualquer entrada `deny` |395| [Entradas `mask` de `credentials.files`](#mask-credential-files) aplicadas como máscaras | Aplicadas: o mascaramento é independente da camada de sistema de arquivos. Uma entrada que [recorreu ao fallback `deny`](#mask-credential-files) não é aplicada, como qualquer entrada `deny` |

396 396

397Duas outras coisas mudam:397Os comandos em sandbox também herdam o `$TMPDIR` do seu shell em vez do diretório temporário por usuário, pois todo diretório temporário é gravável e o Claude Code não redireciona mais os comandos para o diretório por usuário.

398 398

399* Os comandos em sandbox herdam o `$TMPDIR` do seu shell em vez do diretório temporário por usuário, pois todo diretório temporário é gravável e o Claude Code não redireciona mais os comandos para o diretório por usuário.399No Linux, a variável muitas vezes não está definida no shell pai. A orientação da ferramenta Bash instrui o Claude a criar diretórios de rascunho com `mktemp -d` em vez de depender de `$TMPDIR`.

~~400~~

401 No Linux, a variável muitas vezes não está definida no shell pai. A orientação da ferramenta Bash instrui o Claude a criar diretórios de rascunho com `mktemp -d` em vez de depender de `$TMPDIR`.

402* [`autoAllowBashIfSandboxed`](https://code.claude.com/docs/pt/settings-reference#sandbox-autoallowbashifsandboxed) ainda tem `true` como padrão, de modo que os comandos em sandbox continuam sendo executados sem prompts. Defina-o como `false` para solicitar confirmação para comandos em sandbox.

403 400

404### Proteger credenciais401### Proteger credenciais

405 402

1095}1092}

1096```1093```

1097 1094

1098Isso ativa o [modo de permissão automática](#sandbox-modes). Para o modo de permissões regular, defina também [`sandbox.autoAllowBashIfSandboxed`](https://code.claude.com/docs/pt/settings-reference#sandbox-autoallowbashifsandboxed) como `false`. A alteração entra em vigor na sua sessão em execução no próximo comando de shell que o Claude executar, e a aba **Mode** do `/sandbox` então marca o modo em vigor.1095Isso ativa o [modo de permissões regular](#sandbox-modes). Para o modo de permissão automática, defina também [`sandbox.autoAllowBashIfSandboxed`](https://code.claude.com/docs/pt/settings-reference#sandbox-autoallowbashifsandboxed) como `true`. A alteração entra em vigor na sua sessão em execução no próximo comando de shell que o Claude executar, e a aba **Mode** do `/sandbox` então marca o modo em vigor.

1099 1096

1100## Limitações1097## Limitações

1101 1098

security.md +2 −2

Details

25 25

26Para mitigar riscos em sistemas agentic:26Para mitigar riscos em sistemas agentic:

27 27

28* **Ferramenta bash em sandbox**: [Sandbox](https://code.claude.com/docs/pt/sandboxing.md) comandos bash com isolamento de sistema de arquivos e rede, reduzindo prompts de permissão enquanto mantém a segurança. Configure com `/sandbox` para definir limites onde Claude Code pode trabalhar autonomamente28* **Ferramenta Bash em sandbox**: Execute comandos Bash em [sandbox](https://code.claude.com/docs/pt/sandboxing.md) com isolamento de sistema de arquivos e rede. Configure com `/sandbox`

29* **Limite de diretório de trabalho**: No modo Manual, Claude Code pergunta a você antes que suas ferramentas de arquivo leiam ou escrevam fora da pasta onde foi iniciado e de suas subpastas. O limite é um prompt de permissão, então um comando Bash que você aprova ainda pode escrever em qualquer lugar onde sua conta de usuário possa escrever29* **Limite de diretório de trabalho**: No modo Manual, Claude Code pergunta a você antes que suas ferramentas de arquivo leiam ou escrevam fora da pasta onde foi iniciado e de suas subpastas. O limite é um prompt de permissão, então um comando Bash que você aprova ainda pode escrever em qualquer lugar onde sua conta de usuário possa escrever

30 * Para ler uma pasta sem o prompt, adicione-a como um [diretório adicional](https://code.claude.com/docs/pt/permissions.md#working-directories)30 * Para ler uma pasta sem o prompt, adicione-a como um [diretório adicional](https://code.claude.com/docs/pt/permissions.md#working-directories)

31 * Para restringir comandos Bash no nível do sistema operacional, ative o [sandboxing](https://code.claude.com/docs/pt/sandboxing.md#filesystem-isolation)31 * Para restringir comandos Bash no nível do sistema operacional, ative o [sandboxing](https://code.claude.com/docs/pt/sandboxing.md#filesystem-isolation)

62* **Verificação de confiança**: Em uma sessão interativa, Claude Code mostra o diálogo de confiança do workspace quando você o inicia em uma pasta na qual ainda não confiou. Servidores no `.mcp.json` de um projeto têm seu próprio prompt de aprovação, e [Escopo de projeto](https://code.claude.com/docs/pt/mcp.md#project-scope) lista as sessões que o ignoram62* **Verificação de confiança**: Em uma sessão interativa, Claude Code mostra o diálogo de confiança do workspace quando você o inicia em uma pasta na qual ainda não confiou. Servidores no `.mcp.json` de um projeto têm seu próprio prompt de aprovação, e [Escopo de projeto](https://code.claude.com/docs/pt/mcp.md#project-scope) lista as sessões que o ignoram

63 * Nota: Uma sessão `-p` não mostra nenhum dos dois prompts. [O que é executado antes de você confiar em uma pasta](https://code.claude.com/docs/pt/permissions.md#what-runs-before-you-trust-a-folder) lista o que os arquivos de um repositório podem executar nesse caso63 * Nota: Uma sessão `-p` não mostra nenhum dos dois prompts. [O que é executado antes de você confiar em uma pasta](https://code.claude.com/docs/pt/permissions.md#what-runs-before-you-trust-a-folder) lista o que os arquivos de um repositório podem executar nesse caso

64 * Nota: Quando você inicia Claude Code diretamente no seu diretório pessoal, a aceitação de confiança é mantida apenas para a sessão atual e não é gravada em disco, portanto o prompt reaparece a cada inicialização. Não há configuração para persistir isso. Inicie Claude Code a partir de um subdiretório do projeto, onde a aceitação de confiança é salva por diretório64 * Nota: Quando você inicia Claude Code diretamente no seu diretório pessoal, a aceitação de confiança é mantida apenas para a sessão atual e não é gravada em disco, portanto o prompt reaparece a cada inicialização. Não há configuração para persistir isso. Inicie Claude Code a partir de um subdiretório do projeto, onde a aceitação de confiança é salva por diretório

65* **Detecção de injeção de comando**: No modo Manual, Claude Code pergunta antes de executar um comando Bash que não consegue analisar completamente. Uma regra de permissão para parte de um comando, como `Bash(git *)`, não ignora esse prompt. [Comandos em sandbox](https://code.claude.com/docs/pt/permissions.md#how-permissions-interact-with-sandboxing) podem ser executados sem ele65* **Detecção de injeção de comando**: No modo Manual, Claude Code pergunta antes de executar um comando Bash que não consegue analisar completamente. Uma regra de permissão para parte de um comando, como `Bash(git *)`, não ignora esse prompt. [Comandos em sandbox](https://code.claude.com/docs/pt/permissions.md#how-permissions-interact-with-sandboxing) no [modo de permissão automática](https://code.claude.com/docs/pt/sandboxing.md#auto-allow-mode) podem ser executados sem ele

66* **Correspondência fail-closed**: No modo Manual, comandos não correspondidos requerem aprovação por padrão66* **Correspondência fail-closed**: No modo Manual, comandos não correspondidos requerem aprovação por padrão

67* **Armazenamento seguro de credenciais**: Chaves de API e tokens são armazenados no Keychain do macOS quando disponível. No Linux, eles são armazenados em um arquivo com modo `0600`, e no Windows em um arquivo que herda os controles de acesso do diretório do seu perfil de usuário. Consulte [Credential Management](https://code.claude.com/docs/pt/authentication.md#credential-management)67* **Armazenamento seguro de credenciais**: Chaves de API e tokens são armazenados no Keychain do macOS quando disponível. No Linux, eles são armazenados em um arquivo com modo `0600`, e no Windows em um arquivo que herda os controles de acesso do diretório do seu perfil de usuário. Consulte [Credential Management](https://code.claude.com/docs/pt/authentication.md#credential-management)

68 68

settings-reference.md +14 −14

Details

1355 1355

1356### `sandbox.autoAllowBashIfSandboxed`1356### `sandbox.autoAllowBashIfSandboxed`

1357 1357

1358Permite que o Claude Code execute comandos Bash em sandbox sem um prompt de permissão. Comandos que não podem ser executados no sandbox ainda passam pelo fluxo normal de permissões, e as regras `deny` e as regras `ask` com escopo de conteúdo, como `Bash(git push *)`, continuam valendo; uma regra ask `Bash` simples é ignorada para comandos em sandbox. Defina como `false` para que os comandos em sandbox também passem pelo fluxo normal de permissões, o que a aba **Mode** do `/sandbox` chama de modo de permissões normais.1358Permite que o Claude Code execute comandos Bash em sandbox sem um prompt de permissão. Comandos que não podem ser executados no sandbox ainda passam pelo fluxo normal de permissões. Regras `deny` e regras `ask` com escopo de conteúdo, como `Bash(git push *)`, continuam valendo, mas uma regra ask `Bash` simples é ignorada para comandos em sandbox. Para defini-la como `true` nas configurações gerenciadas, adicione-a ao bloco `sandbox` da sua [fonte gerenciada de maior prioridade](https://code.claude.com/docs/pt/managed-settings.md#how-claude-code-combines-managed-sources).

1359 1359

1360* **Scope**: [`Any file`](#scopes)1360* **Scope**: [`Any file`](#scopes)

1361* **Type**: Boolean1361* **Type**: Boolean

1362 * `true`: Claude Code executa comandos Bash em sandbox sem um prompt de permissão, exceto nos casos que [Auto-allow mode](https://code.claude.com/docs/pt/sandboxing.md#auto-allow-mode) descreve; `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` desativa a auto-autorização1362 * `true`: Claude Code executa comandos Bash em sandbox sem um prompt de permissão, exceto nos casos que [Auto-allow mode](https://code.claude.com/docs/pt/sandboxing.md#auto-allow-mode) descreve; `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` desativa a auto-autorização

1363 * `false`: comandos em sandbox passam pelo fluxo de permissão regular, então suas regras de autorização e modo de permissão decidem. A aba **Mode** do `/sandbox` chama isso modo de permissões regular1363 * `false`: comandos em sandbox passam pelo fluxo de permissão regular, então suas regras de autorização e modo de permissão decidem. A aba **Mode** do `/sandbox` chama isso modo de permissões regular

1364* **Default**: `true`1364* **Padrão**: `false`. Antes da v2.1.324, o padrão era `true`

1365 1365

1366Isso mantém o sandbox ativado e envia comandos em sandbox pelo fluxo de permissão regular:1366Para manter o sandbox ativado e executar comandos em sandbox sem um prompt de permissão, defina ambas as chaves no seu bloco `sandbox`:

1367 1367

1368```json settings.json theme={null}1368```json settings.json theme={null}

1369{1369{

1370 "sandbox": {1370 "sandbox": {

1371 "enabled": true,1371 "enabled": true,

1372 "autoAllowBashIfSandboxed": false1372 "autoAllowBashIfSandboxed": true

1373 }1373 }

1374}1374}

1375```1375```

1653}1653}

1654```1654```

1655 1655

1656Com a camada desativada, o Claude Code não impõe as entradas de `denyRead` nem as entradas `deny` de `credentials.files`, enquanto as entradas de `credentials.envVars` e as entradas `mask` aplicadas continuam funcionando. [`autoAllowBashIfSandboxed`](#sandbox-autoallowbashifsandboxed) continua com padrão `true`, então defina-a como `false` para continuar recebendo prompts. Consulte [Desativar o isolamento do sistema de arquivos](https://code.claude.com/docs/pt/sandboxing.md#disable-filesystem-isolation) para ver a lista completa de fontes que podem defini-la e o que muda quando o isolamento está desativado.1656Com a camada desativada, o Claude Code não impõe as entradas de `denyRead` nem as entradas `deny` de `credentials.files`, enquanto as entradas de `credentials.envVars` e as entradas `mask` aplicadas continuam funcionando. Consulte [Desativar o isolamento do sistema de arquivos](https://code.claude.com/docs/pt/sandboxing.md#disable-filesystem-isolation) para a lista completa de fontes que podem defini-la e o que muda quando o isolamento está desativado.

1657 1657

1658### `sandbox.ignoreViolations`1658### `sandbox.ignoreViolations`

1659 1659

4870 4870

4871### `agentPushNotifEnabled`4871### `agentPushNotifEnabled`

4872 4872

4873Permita que o Claude envie uma notificação por push para seu telefone quando decidir que vale a pena enviar uma, por exemplo, quando uma tarefa longa termina. Em uma sessão local, o Claude pode enviar uma enquanto o [Remote Control](https://code.claude.com/docs/pt/remote-control.md) está conectado. Aparece em `/config` como **Push when Claude decides**. Quando você a altera lá, o Claude Code também salva o valor em sua conta.4873Permita que o Claude envie uma notificação por push para seu telefone quando decidir que vale a pena enviar uma, por exemplo, quando uma tarefa longa termina. Em uma sessão local, o Claude pode enviar uma enquanto o [Remote Control](https://code.claude.com/docs/pt/remote-control.md) está conectado. Aparece em `/config` como **Push when Claude decides**.

4874 4874

4875* **Escopo**: [`Qualquer arquivo`](#scopes). O Claude Code também lê um valor deixado em `~/.claude.json` por versões antigas.4875* **Escopo**: [`Qualquer arquivo`](#scopes). O Claude Code também lê um valor deixado em `~/.claude.json` por versões antigas.

4876* **Tipo**: Boolean4876* **Tipo**: Boolean

4884}4884}

4885```4885```

4886 4886

4887Se você executa sessões em um servidor [`claude remote-control`](https://code.claude.com/docs/pt/remote-control#start-a-remote-control-session), elas seguem o valor salvo em sua conta em vez dessa chave. Para alterar esse valor, execute `/config` em uma sessão do Claude Code em seu terminal e ative ou desative **Push when Claude decides**. Se o alternador já mostrar o valor que você deseja, altere-o e volte-o ao valor anterior para que o Claude Code salve esse valor em sua conta.4887Você não recebe notificações apenas com essa chave. Para configurá-las, siga as etapas em [Notificações por push móvel](https://code.claude.com/docs/pt/remote-control.md#mobile-push-notifications).

4888 4888

4889Veja [Notificações por push móvel](https://code.claude.com/docs/pt/remote-control.md#mobile-push-notifications).4889Se você executa sessões em um servidor [`claude remote-control`](https://code.claude.com/docs/pt/remote-control#start-a-remote-control-session), elas seguem o valor salvo em sua conta em vez dessa chave. Para alterar esse valor, execute `/config` em uma sessão do Claude Code em seu terminal e ative ou desative **Push when Claude decides**. Se o alternador já mostrar o valor que você deseja, altere-o e volte-o ao valor anterior para que o Claude Code salve esse valor em sua conta.

4890 4890

4891### `awaySummaryEnabled`4891### `awaySummaryEnabled`

4892 4892

5043}5043}

5044```5044```

5045 5045

5046Veja [Notificações por push móvel](https://code.claude.com/docs/pt/remote-control.md#mobile-push-notifications).5046Você não recebe notificações apenas com essa chave. Para configurá-las, siga as etapas em [Notificações por push móvel](https://code.claude.com/docs/pt/remote-control.md#mobile-push-notifications).

5047 5047

5048### `preferredNotifChannel`5048### `preferredNotifChannel`

5049 5049

5421 5421

5422### `minimumVersion`5422### `minimumVersion`

5423 5423

5424Impeça que atualizações automáticas em segundo plano e `claude update` instalem qualquer versão abaixo desta, para que mudar para o canal `"stable"` não o faça fazer downgrade de um build `"latest"` mais recente. Claude Code escreve esta chave para você quando você escolhe permanecer em sua versão atual ao mudar de canais em `/config`, e a limpa quando você volta para `"latest"`.5424Impeça que atualizações automáticas em segundo plano e `claude update` instalem qualquer versão abaixo da que você definir. Claude Code escreve esta chave para você quando você escolhe permanecer em sua versão atual ao mudar de canais em `/config`. Claude Code limpa a chave quando você volta para `"latest"` em `/config`.

5425 5425

5426* **Escopo**: [`Any file`](#scopes). Defina-o em configurações gerenciadas para fixar um mínimo em toda a organização que as configurações de usuário e projeto não possam reduzir.5426* **Escopo**: [`Any file`](#scopes). Defina esta chave em configurações gerenciadas para fixar um mínimo em toda a organização que as configurações de usuário e projeto não possam sobrescrever.

5427* **Tipo**: string, um número de versão como `"2.1.100"`; um valor que não é uma versão válida é ignorado5427* **Tipo**: string, um número de versão como `"2.1.323"`; um valor que não é uma versão válida é ignorado

5428* **Padrão**: não definido, então as atualizações podem instalar qualquer versão que o canal oferece5428* **Padrão**: não definido, então as atualizações podem instalar qualquer versão que o canal oferece

5429 5429

5430Este exemplo segue o canal stable e recusa instalar qualquer versão abaixo de 2.1.100:5430Este exemplo segue o canal stable e recusa instalar qualquer versão abaixo de 2.1.323:

5431 5431

5432```json settings.json theme={null}5432```json settings.json theme={null}

5433{5433{

5434 "autoUpdatesChannel": "stable",5434 "autoUpdatesChannel": "stable",

5435 "minimumVersion": "2.1.100"5435 "minimumVersion": "2.1.323"

5436}5436}

5437```5437```

5438 5438

setup.md +19 −10

Details

40>40>

41> **macOS, Linux, WSL:**41> **macOS, Linux, WSL:**

42>42>

~~43> ```bash theme={null}~~43> ```bash theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}

44> curl -fsSL https://claude.ai/install.sh | bash44> curl -fsSL https://claude.ai/install.sh | bash

45> ```45> ```

46>46>

48>48>

49> **Windows PowerShell:**49> **Windows PowerShell:**

50>50>

~~51> ```powershell theme={null}~~51> ```powershell theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}

52> irm https://claude.ai/install.ps1 | iex52> irm https://claude.ai/install.ps1 | iex

53> ```53> ```

54>54>

55> **Windows CMD:**55> **Windows CMD:**

56>56>

~~57> ```batch theme={null}~~57> ```batch theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}

58> curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd58> curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

59> ```59> ```

60>60>

72 72

73> [tab] Homebrew73> [tab] Homebrew

74>74>

~~75> ```bash theme={null}~~75> ```bash theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}

76> brew install --cask claude-code76> brew install --cask claude-code

77> ```77> ```

78>78>

84 84

85> [tab] WinGet85> [tab] WinGet

86>86>

~~87> ```powershell theme={null}~~87> ```powershell theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}

88> winget install Anthropic.ClaudeCode88> winget install Anthropic.ClaudeCode

89> ```89> ```

90>90>

220}220}

221```221```

222 222

223Com essa configuração, uma instalação nativa é atualizada para a versão estável mesmo quando essa versão é mais antiga que a sua. Para evitar o downgrade, também [fixe uma versão mínima](#pin-a-minimum-version).

224

223Um modelo recém-lançado pode exigir uma versão do Claude Code mais recente do que a fornecida pelo canal estável. Para executar o modelo agora, mude para o canal mais recente.225Um modelo recém-lançado pode exigir uma versão do Claude Code mais recente do que a fornecida pelo canal estável. Para executar o modelo agora, mude para o canal mais recente.

224 226

225Para implantações empresariais, você pode impor um canal de lançamento consistente em toda a sua organização usando [configurações gerenciadas](https://code.claude.com/docs/pt/managed-settings.md).227Para implantações empresariais, você pode impor um canal de lançamento consistente em toda a sua organização usando [configurações gerenciadas](https://code.claude.com/docs/pt/managed-settings.md).

230 232

231### Fixar uma versão mínima233### Fixar uma versão mínima

232 234

233A configuração `minimumVersion` estabelece um piso. As atualizações automáticas em segundo plano e `claude update` recusam instalar qualquer versão abaixo desse valor, portanto mudar para o canal `"stable"` não faz downgrade se você já estiver em um build `"latest"` mais recente.235Para mover uma instalação nativa para o [canal de lançamento](#configure-release-channel) `"stable"` sem downgrade, defina [`minimumVersion`](https://code.claude.com/docs/pt/settings-reference#minimumversion) como a versão que você está executando. As atualizações automáticas em segundo plano e `claude update` recusam instalar qualquer versão abaixo do mínimo.

236

237Defina o mínimo em `/config` para que Claude Code preencha sua versão atual, ou no seu arquivo de configurações para digitar o número você mesmo:

234 238

235Mudar de `"latest"` para `"stable"` via `/config` solicita que você escolha ficar na versão atual ou permitir o downgrade. Escolher ficar define `minimumVersion` para essa versão. Mudar de volta para `"latest"` limpa isso.239* **Em `/config`**: mude **Canal de atualização automática** para stable e, em seguida, selecione **Permanecer na versão atual**. Se você voltar para latest em `/config`, Claude Code limpa o mínimo.

240* **No seu [arquivo de configurações](https://code.claude.com/docs/pt/settings.md)**: execute `claude --version` no seu shell e defina `minimumVersion` como o número no início da saída. Na mesma edição, defina `autoUpdatesChannel` como `"stable"`.

236 241

237Adicione-o ao seu [arquivo settings.json](https://code.claude.com/docs/pt/settings.md) para fixar um piso explicitamente:242Este `~/.claude/settings.json` muda uma instalação na versão 2.1.323 para stable:

238 243

239```json theme={null}244```json theme={null}

240{245{

241 "autoUpdatesChannel": "stable",246 "autoUpdatesChannel": "stable",

242 "minimumVersion": "2.1.100"247 "minimumVersion": "2.1.323"

243}248}

244```249```

245 250

246Em [configurações gerenciadas](https://code.claude.com/docs/pt/managed-settings.md), isso impõe um mínimo em toda a organização que as configurações de usuário e projeto não podem substituir.251A instalação permanece na 2.1.323 até que o canal stable forneça uma versão mais recente.

252

253#### Definir limites de versão para sua organização

254

255Em [configurações gerenciadas](https://code.claude.com/docs/pt/managed-settings.md), `minimumVersion` impõe um mínimo em toda a organização que as configurações de usuário e projeto não podem sobrescrever.

247 256

248O pino `minimumVersion` apenas restringe atualizações. Para fazer Claude Code recusar iniciar fora de um intervalo de versão, use as configurações gerenciadas `requiredMinimumVersion` e `requiredMaximumVersion` em vez disso. As atualizações também respeitam o teto `requiredMaximumVersion`. Consulte [`requiredMinimumVersion`](https://code.claude.com/docs/pt/settings-reference#requiredminimumversion) e [`requiredMaximumVersion`](https://code.claude.com/docs/pt/settings-reference#requiredmaximumversion).257O pino `minimumVersion` apenas restringe atualizações. Para fazer Claude Code recusar iniciar fora de um intervalo de versão, use as configurações gerenciadas `requiredMinimumVersion` e `requiredMaximumVersion` em vez disso. As atualizações também respeitam o teto `requiredMaximumVersion`. Consulte [`requiredMinimumVersion`](https://code.claude.com/docs/pt/settings-reference#requiredminimumversion) e [`requiredMaximumVersion`](https://code.claude.com/docs/pt/settings-reference#requiredmaximumversion).

249 258

skills.md +4 −2

Details

22 22

23Claude Code inclui um conjunto de skills agrupadas, como `/doctor`, `/code-review`, `/batch`, `/debug`, `/loop` e `/claude-api`. Skills agrupadas são baseadas em prompt: elas fornecem ao Claude instruções detalhadas e permitem que ele orquestre o trabalho usando suas ferramentas. A maioria dos comandos integrados executa lógica fixa diretamente.23Claude Code inclui um conjunto de skills agrupadas, como `/doctor`, `/code-review`, `/batch`, `/debug`, `/loop` e `/claude-api`. Skills agrupadas são baseadas em prompt: elas fornecem ao Claude instruções detalhadas e permitem que ele orquestre o trabalho usando suas ferramentas. A maioria dos comandos integrados executa lógica fixa diretamente.

24 24

25Você invoca uma skill incluída digitando `/` seguido do nome da skill. Claude invoca algumas skills incluídas automaticamente quando relevante; outras, incluindo [`/verify`](#run-and-verify-your-app), são executadas apenas quando você as invoca.25Você invoca uma skill incluída digitando `/` seguido do nome da skill. Claude invoca algumas skills incluídas automaticamente quando relevante.

26 26

27A maioria das skills agrupadas está disponível em todas as sessões. Algumas dependem de um recurso específico: `/workflow-authoring`, por exemplo, está disponível apenas quando [fluxos de trabalho dinâmicos](https://code.claude.com/docs/pt/workflows.md) estão habilitados.27A maioria das skills agrupadas está disponível em todas as sessões. Algumas dependem de um recurso específico: `/workflow-authoring`, por exemplo, está disponível apenas quando [fluxos de trabalho dinâmicos](https://code.claude.com/docs/pt/workflows.md) estão habilitados.

28 28

320 320

321Se você criar um diretório de skills de nível superior que não existia quando a sessão iniciou, execute [`/reload-skills`](https://code.claude.com/docs/pt/commands#all-commands) para pegar as skills que você colocou lá. Claude Code não está observando aquele diretório ainda, então execute `/reload-skills` novamente após cada mudança posterior lá.321Se você criar um diretório de skills de nível superior que não existia quando a sessão iniciou, execute [`/reload-skills`](https://code.claude.com/docs/pt/commands#all-commands) para pegar as skills que você colocou lá. Claude Code não está observando aquele diretório ainda, então execute `/reload-skills` novamente após cada mudança posterior lá.

322 322

323A detecção de mudança ao vivo cobre apenas texto `SKILL.md`. Para uma pasta de skill que também é um [plugin](https://code.claude.com/docs/pt/plugins/loading.md#plugins-shared-through-a-repository), mudanças em `hooks/`, `.mcp.json`, `agents/` e `output-styles/` precisam de `/reload-plugins` para entrar em vigor.323> [!NOTE]

324>

325> A detecção de mudança ao vivo cobre o texto de `SKILL.md`. Para uma pasta de skill que também é um [plugin](https://code.claude.com/docs/pt/plugins/loading.md#plugins-shared-through-a-repository), mudanças em `.mcp.json`, `agents/` e `output-styles/` precisam de `/reload-plugins` para entrar em vigor. Mudanças em `hooks/` também precisam dele, exceto o arquivo de módulo de um [mod](https://code.claude.com/docs/pt/plugins/mods/overview.md) quando ele [recarrega por conta própria](https://code.claude.com/docs/pt/env-vars.md).

324 326

325### Remova uma skill327### Remova uma skill

326 328

sub-agents.md +59 −42

Details

36>36>

37> Um agente rápido e somente leitura otimizado para pesquisar e analisar bases de código.37> Um agente rápido e somente leitura otimizado para pesquisar e analisar bases de código.

38>38>

~~39> * **Model**: o modelo da conversa principal. Quando a conversa principal executa Fable, o modelo do Explore depende de como você se conecta:~~39> * **Model**: o modelo da [conversa principal](#which-model-a-nested-subagent-runs-on). Quando a conversa principal executa Fable, Explore é executado no Opus ou permanece no Fable, dependendo de como você se conecta.

40> * Com uma assinatura Claude, uma conta do Anthropic Console ou um [gateway de LLM](https://code.claude.com/docs/pt/llm-gateway) acessado por meio de `ANTHROPIC_BASE_URL`, Explore é executado no modelo Opus para o qual o [alias `opus`](https://code.claude.com/docs/pt/model-config#model-aliases) é resolvido.40> * Com uma assinatura Claude, uma conta do Anthropic Console ou um [gateway de LLM](https://code.claude.com/docs/pt/llm-gateway) acessado por meio de `ANTHROPIC_BASE_URL`, Explore é executado no modelo Opus para o qual o [alias `opus`](https://code.claude.com/docs/pt/model-config#model-aliases) é resolvido.

41> * No Amazon Bedrock, no Google Cloud's Agent Platform, no Microsoft Foundry, na [Claude Platform on AWS](https://code.claude.com/docs/pt/claude-platform-on-aws.md) ou em um [gateway de Claude apps](https://code.claude.com/docs/pt/claude-apps-gateway), Explore permanece no modelo da conversa principal.41> * No Amazon Bedrock, no Google Cloud's Agent Platform, no Microsoft Foundry, na [Claude Platform on AWS](https://code.claude.com/docs/pt/claude-platform-on-aws.md) ou em um [gateway de Claude apps](https://code.claude.com/docs/pt/claude-apps-gateway), Explore permanece no Fable.

42> * **Tools**: ferramentas somente leitura; Write e Edit são negados42> * **Tools**: ferramentas somente leitura; Write e Edit são negados

43> * **Purpose**: descoberta de arquivos, pesquisa de código, exploração de base de código43> * **Purpose**: descoberta de arquivos, pesquisa de código, exploração de base de código

44>44>

52>52>

53> Um agente de pesquisa usado durante [plan mode](https://code.claude.com/docs/pt/permission-modes.md#analyze-before-you-edit-with-plan-mode) para reunir contexto antes de apresentar um plano.53> Um agente de pesquisa usado durante [plan mode](https://code.claude.com/docs/pt/permission-modes.md#analyze-before-you-edit-with-plan-mode) para reunir contexto antes de apresentar um plano.

54>54>

~~55> * **Model**: herda da conversa principal, a menos que você defina `CLAUDE_CODE_SUBAGENT_MODEL` e [force-o em cada subagente](#run-every-subagent-on-one-model)~~55> * **Model**: herda da [conversa principal](#which-model-a-nested-subagent-runs-on), a menos que você defina `CLAUDE_CODE_SUBAGENT_MODEL` e [force-o em cada subagente](#run-every-subagent-on-one-model)

56> * **Tools**: ferramentas somente leitura; Write e Edit são negados56> * **Tools**: ferramentas somente leitura; Write e Edit são negados

57> * **Purpose**: pesquisa de base de código para planejamento57> * **Purpose**: pesquisa de base de código para planejamento

58>58>

62>62>

63> Um agente capaz para tarefas complexas e multi-etapas que requerem exploração e ação.63> Um agente capaz para tarefas complexas e multi-etapas que requerem exploração e ação.

64>64>

65> * **Model**: o modelo [`CLAUDE_CODE_SUBAGENT_MODEL`](#choose-a-model) se você definir um e nada atribuir um modelo de outra forma, caso contrário o modelo da conversa principal; [Escolha um modelo](#choose-a-model) declara a ordem completa, e [Execute cada subagente em um modelo](#run-every-subagent-on-one-model) mostra como fazer a variável substituir essas fontes65> * **Model**: o modelo da conversa principal por padrão, seguindo a [ordem de modelo](#choose-a-model)

66> * **Tools**: todas as ferramentas [disponíveis para subagentes](#available-tools)66> * **Tools**: todas as ferramentas [disponíveis para subagentes](#available-tools)

67> * **Purpose**: pesquisa complexa, operações multi-etapas, modificações de código67> * **Purpose**: pesquisa complexa, operações multi-etapas, modificações de código

68>68>

346 346

347### Escolher um modelo347### Escolher um modelo

348 348

349O campo `model` controla qual modelo o subagente usa:349Por padrão, um subagente que você define é executado no mesmo modelo da conversa que o inicia. Para escolher você mesmo o modelo dele, defina o campo [`model`](#supported-frontmatter-fields) na definição dele como um destes valores:

350 350

351* **Alias de modelo**: use um dos aliases disponíveis: `sonnet`, `opus`, `haiku` ou `fable`351* **Alias de modelo**: `sonnet`, `opus`, `haiku` ou `fable`

352* **ID de modelo completo**: use um ID de modelo completo como `claude-opus-5-5` ou `claude-sonnet-5`. Aceita os mesmos valores que a flag `--model`352* **ID de modelo completo**: um valor que a flag [`--model`](https://code.claude.com/docs/pt/cli-reference#cli-flags) aceita, como `claude-opus-5-5` ou `claude-sonnet-5`

353* **inherit**: use o mesmo modelo da conversa principal353* **`inherit`**: o modelo da conversa principal ou, no caso de um [subagente aninhado](#which-model-a-nested-subagent-runs-on), o modelo do subagente que o criou

354 354

355Quando o Claude invoca um subagente, ele também pode passar um parâmetro `model` para aquela invocação específica. Em uma chamada da ferramenta Agent, esse parâmetro aceita um alias de modelo: `sonnet`, `opus`, `haiku` ou `fable`. O Claude não pode passar um ID de modelo completo nem `inherit` nessa chamada. O Claude Code resolve o modelo do subagente nesta ordem:355Quando mais de uma fonte define um modelo, o Claude Code usa a primeira nesta ordem:

356 356

3571. O parâmetro `model` por invocação3571. O parâmetro `model` por invocação, que o Claude pode passar ao iniciar o subagente. Em uma chamada da ferramenta Agent, o parâmetro aceita um alias de modelo, e não um ID de modelo completo nem `inherit`.

3582. O frontmatter `model` da definição do subagente, em que `inherit` seleciona o modelo da conversa principal3582. O campo `model` na definição do subagente, incluindo `inherit`

3593. A variável de ambiente [`CLAUDE_CODE_SUBAGENT_MODEL`](https://code.claude.com/docs/pt/model-config#environment-variables), quando você a define como um alias de modelo ou ID de modelo3593. A variável de ambiente [`CLAUDE_CODE_SUBAGENT_MODEL`](https://code.claude.com/docs/pt/model-config#environment-variables)

3604. O modelo da conversa principal3604. O modelo da conversa principal ou, no caso de um subagente aninhado, o modelo do subagente que o criou

361 361

362Se um [mod](https://code.claude.com/docs/pt/plugins/mods/overview.md) instalado definir um modelo no seu hook [`agent.spawn`](https://code.claude.com/docs/pt/plugins/mods/reference#subagents), o Claude Code usa esse modelo no lugar do parâmetro por invocação.362Se o Claude passou um alias, o subagente mantém esse alias quando é [retomado ou recebe uma mensagem de acompanhamento](#resume-subagents). Se um [mod](https://code.claude.com/docs/pt/plugins/mods/overview.md) instalado definir um modelo no seu hook [`agent.spawn`](https://code.claude.com/docs/pt/plugins/mods/reference#subagents), o Claude Code usa esse modelo no lugar do parâmetro por invocação.

~~363~~

364Em dois casos, um alias de família como `opus` no parâmetro por invocação ou no frontmatter resolve para o modelo da conversa principal em vez da [versão para a qual o alias aponta](https://code.claude.com/docs/pt/model-config.md#model-aliases):

~~365~~

366* **O modelo da conversa principal pertence a essa família**: o subagente é executado no modelo exato da conversa principal, incluindo qualquer sufixo `[1m]`, de modo que recebe a mesma janela de [contexto estendido](https://code.claude.com/docs/pt/model-config.md#extended-context) da conversa principal.

367* **O Claude Code não consegue identificar a família do modelo da conversa principal, em [um provedor diferente da API da Anthropic](https://code.claude.com/docs/pt/third-party-integrations.md)**: isso pode acontecer com um [ARN de perfil de inferência de aplicação](https://code.claude.com/docs/pt/amazon-bedrock.md#iam-configuration) no Amazon Bedrock que o Claude Code não resolveu para um modelo subjacente. Este caso abrange apenas o alias `opus` e não se aplica quando você define [`ANTHROPIC_DEFAULT_OPUS_MODEL`](https://code.claude.com/docs/pt/model-config#environment-variables), pois `opus` então resolve para o modelo que você definiu.

~~368~~

369Um alias em `CLAUDE_CODE_SUBAGENT_MODEL` sempre resolve para a versão para a qual o alias aponta, mesmo quando nomeia a família da conversa principal. Definir a variável como `inherit` é o mesmo que deixá-la sem definição.

370 363

371Definir `CLAUDE_CODE_SUBAGENT_MODEL` sozinha não altera o modelo em que os subagentes integrados Explore e Plan são executados. Para alterá-lo, consulte [Executar todos os subagentes em um único modelo](#run-every-subagent-on-one-model).364Definir `CLAUDE_CODE_SUBAGENT_MODEL` sozinha não altera o modelo em que os subagentes integrados Explore e Plan são executados. Para alterá-lo, consulte [Executar todos os subagentes em um único modelo](#run-every-subagent-on-one-model).

372 365

373Antes da v2.1.251, `CLAUDE_CODE_SUBAGENT_MODEL` vinha primeiro nesta ordem e sobrescrevia tanto o parâmetro por invocação quanto o frontmatter, incluindo `model: inherit`.366#### Em qual modelo um subagente aninhado é executado

374 367

375O Claude Code verifica os valores do parâmetro por invocação, do frontmatter e da variável de ambiente em relação à allowlist [`availableModels`](https://code.claude.com/docs/pt/model-config#restrict-model-selection) da sua organização. Para um valor bloqueado, ele substitui por outro modelo:368Por padrão, um [subagente aninhado](#let-subagents-spawn-their-own-subagents) que você define é executado no modelo do seu pai, o subagente que o criou. Para executar o subagente aninhado em outro modelo, defina o campo `model` dele como esse modelo.

376 369

377* Quando o valor bloqueado é um alias de família como `opus`, o Claude Code executa o subagente na versão mais recente dessa família que a allowlist permite, seguindo as mesmas [regras de substituição e escopo de provedor](https://code.claude.com/docs/pt/model-config.md#restrict-model-selection) que o `/model`. Antes da v2.1.222, o Claude Code também executava o subagente no modelo herdado para um alias de família bloqueado.370Por exemplo, suponha que sua conversa principal seja executada no Opus e inicie um subagente revisor no Haiku. Por padrão, estes subagentes são executados no Haiku, e não no Opus, quando o revisor os cria:

378* Para qualquer outro valor bloqueado, em provedores onde essa substituição não opera, ou quando a allowlist não permite nenhuma versão da família, o Claude Code executa o subagente no modelo herdado. Se você definir `CLAUDE_CODE_SUBAGENT_MODEL`, o Claude Code tenta esse modelo primeiro, sob essas mesmas regras.

379 371

380Em sessões interativas, o Claude Code mostra um aviso nomeando o modelo solicitado e o modelo em que o subagente é executado, para qualquer uma das substituições.372* Um subagente com `model: inherit` ou sem campo `model`

373* Os subagentes integrados Explore, Plan e general-purpose

374* Um [fork](#fork-the-current-conversation)

381 375

382Para verificar em qual modelo um subagente está sendo executado, execute [`/tasks`](https://code.claude.com/docs/pt/commands). O Claude Code nomeia o modelo na linha do subagente e adiciona o [nível de esforço](https://code.claude.com/docs/pt/model-config.md#adjust-effort-level) definido para esse subagente, se houver. Requer o Claude Code v2.1.242 ou posterior.376No modo de planejamento, esses subagentes são executados no Opus se você definir o modelo da sua sessão como [`opusplan`](https://code.claude.com/docs/pt/model-config#opusplan-model-setting), ou no Sonnet se você o definir como `haiku`.

383 377

384Um parâmetro `model` por invocação também se aplica quando o subagente é [retomado ou recebe uma mensagem de acompanhamento](#resume-subagents), de modo que o subagente permanece nesse modelo.378#### Verificar o modelo de um subagente

385 379

386A partir da v2.1.198, os subagentes também herdam a configuração de [pensamento estendido](https://code.claude.com/docs/pt/model-config.md#extended-thinking) da conversa principal: se o pensamento estiver ativado na sua sessão, ele estará ativado para o subagente e, se estiver desativado, permanecerá desativado. Não há configuração de pensamento por subagente. Antes da v2.1.198, os subagentes eram executados com o pensamento estendido desativado, independentemente da configuração da conversa principal.380Para verificar em qual modelo um subagente está sendo executado, execute [`/tasks`](https://code.claude.com/docs/pt/commands). O Claude Code nomeia o modelo na linha do subagente e adiciona o [nível de esforço](https://code.claude.com/docs/pt/model-config.md#adjust-effort-level) definido para esse subagente, se houver. Requer o Claude Code v2.1.242 ou posterior.

387 381

388#### Executar todos os subagentes em um único modelo382#### Executar todos os subagentes em um único modelo

389 383

390`CLAUDE_CODE_SUBAGENT_MODEL` é um padrão, então a definição de um subagente ou um modelo que o Claude passa ainda tem precedência sobre ela. Para aplicar um único modelo a todos os subagentes, [colegas](https://code.claude.com/docs/pt/agent-teams.md#specify-teammates-and-models) e [agentes de workflow](https://code.claude.com/docs/pt/workflows.md), defina também `CLAUDE_CODE_SUBAGENT_MODEL_FORCE` como `1`. Requer o Claude Code v2.1.257 ou posterior.384Para aplicar um único modelo a todos os subagentes, [colegas](https://code.claude.com/docs/pt/agent-teams.md#specify-teammates-and-models) e [agentes de workflow](https://code.claude.com/docs/pt/workflows.md), defina `CLAUDE_CODE_SUBAGENT_MODEL` como esse modelo e `CLAUDE_CODE_SUBAGENT_MODEL_FORCE` como `1`. Requer o Claude Code v2.1.257 ou posterior.

~~391~~

392* Se você definir ambas as variáveis, os subagentes são executados no modelo em `CLAUDE_CODE_SUBAGENT_MODEL`.

393* Se você definir apenas `CLAUDE_CODE_SUBAGENT_MODEL_FORCE`, os subagentes são executados no modelo da conversa principal, exceto que o subagente integrado Explore é executado no [modelo listado para ele em Subagentes integrados](#built-in-subagents).

394 385

395Por exemplo, para executar todos os subagentes no Haiku, defina ambas as variáveis no bloco `env` de um [arquivo de configurações](https://code.claude.com/docs/pt/settings.md):386Por exemplo, para executar todos os subagentes no Haiku, defina ambas as variáveis no bloco `env` de um [arquivo de configurações](https://code.claude.com/docs/pt/settings.md):

396 387

405 396

406Para verificar se a configuração entrou em vigor, execute [`/tasks`](https://code.claude.com/docs/pt/commands) enquanto um subagente estiver em execução. A linha do subagente mostra o modelo em que ele é executado.397Para verificar se a configuração entrou em vigor, execute [`/tasks`](https://code.claude.com/docs/pt/commands) enquanto um subagente estiver em execução. A linha do subagente mostra o modelo em que ele é executado.

407 398

408Enquanto `CLAUDE_CODE_SUBAGENT_MODEL_FORCE` estiver [ativada](https://code.claude.com/docs/pt/env-vars.md), o Claude Code ignora o campo `model` nas definições de subagentes, e o Claude não pode passar um modelo ao iniciar um subagente. Estes subagentes ainda são executados no modelo da conversa principal:399Enquanto `CLAUDE_CODE_SUBAGENT_MODEL_FORCE` estiver [ativada](https://code.claude.com/docs/pt/env-vars.md), o Claude Code ignora o campo `model` nas definições de subagentes, e o Claude não pode passar um modelo ao iniciar um subagente. Os seguintes subagentes ainda são executados no modelo da conversa pai:

409 400

410* Um [fork](#fork-the-current-conversation)401* Um [fork](#fork-the-current-conversation)

411* Uma [skill executada em um subagente](https://code.claude.com/docs/pt/skills.md#run-skills-in-a-subagent) com `model: inherit`402* Uma [skill executada em um subagente](https://code.claude.com/docs/pt/skills.md#run-skills-in-a-subagent) com `model: inherit`

412 403

404Se você definir apenas `CLAUDE_CODE_SUBAGENT_MODEL_FORCE`, os subagentes são executados no modelo da conversa principal, exceto que o subagente integrado Explore é executado no [modelo listado para ele em Subagentes integrados](#built-in-subagents).

405

406#### Qual versão um alias de modelo seleciona

407

408Por padrão, um subagente com um alias de modelo é executado na [versão para a qual o alias aponta](https://code.claude.com/docs/pt/model-config.md#model-aliases). Com um alias de família como `opus` no campo `model` ou no parâmetro por invocação, o subagente é executado no modelo da conversa pai em dois casos:

409

410* **Mesma família**: por exemplo, se sua conversa principal é executada em `claude-opus-4-7`, um subagente com `model: opus` também é executado nessa versão. Para executar outra versão, defina um ID de modelo completo no campo `model`.

411* **Família desconhecida**: o Claude Code não consegue identificar a família do modelo pai, como com um ARN do Amazon Bedrock que ele [não consegue consultar](https://code.claude.com/docs/pt/amazon-bedrock.md#iam-configuration). Este caso se aplica apenas ao alias `opus` em [um provedor diferente da API da Anthropic](https://code.claude.com/docs/pt/third-party-integrations.md). Para escolher a versão do Opus, defina [`ANTHROPIC_DEFAULT_OPUS_MODEL`](https://code.claude.com/docs/pt/model-config#environment-variables).

412

413#### Quando uma allowlist bloqueia um modelo de subagente

414

415Se a allowlist [`availableModels`](https://code.claude.com/docs/pt/model-config#restrict-model-selection) da sua organização bloquear o modelo definido para um subagente, o subagente é executado no primeiro destes que se aplicar:

416

4171. Para um alias de família bloqueado, a versão permitida mais recente dessa família, em [provedores que suportam essa substituição](https://code.claude.com/docs/pt/model-config.md#restrict-model-selection)

4182. O modelo em `CLAUDE_CODE_SUBAGENT_MODEL`, se você o definir, sob essas mesmas regras

4193. O modelo da conversa principal ou, no caso de um subagente aninhado, o modelo do subagente que o criou

420

421Para um subagente de nível superior em uma sessão interativa, um aviso nomeia o modelo solicitado e o seu substituto. Para executar um modelo específico, altere o valor bloqueado para um que a allowlist permita.

422

423### Pensamento estendido em subagentes

424

425Os subagentes herdam a configuração de [pensamento estendido](https://code.claude.com/docs/pt/model-config.md#extended-thinking) da conversa principal. Não há configuração de pensamento por subagente.

426

413### Escolher um nível de esforço427### Escolher um nível de esforço

414 428

415Para executar um subagente em seu próprio [nível de esforço](https://code.claude.com/docs/pt/model-config.md#adjust-effort-level), defina o campo [`effort`](#supported-frontmatter-fields) na sua definição.429Para executar um subagente em seu próprio [nível de esforço](https://code.claude.com/docs/pt/model-config.md#adjust-effort-level), defina o campo [`effort`](#supported-frontmatter-fields) na sua definição.

426 440

427#### Ferramentas disponíveis441#### Ferramentas disponíveis

428 442

429Os subagentes herdam as [ferramentas integradas](https://code.claude.com/docs/pt/tools-reference.md) e as ferramentas MCP disponíveis na conversa principal, reduzidas por dois filtros: o primeiro remove uma pequena lista de ferramentas de todos os subagentes, e o segundo reduz o conjunto de ferramentas integradas para subagentes executados em [segundo plano](#run-subagents-in-foreground-or-background), que é o padrão. No macOS, Linux e WSL, um subagente também pode receber as ferramentas Glob e Grep quando a conversa principal não as tem, conforme descrito em [Comportamento da ferramenta Glob](https://code.claude.com/docs/pt/tools-reference.md#glob-tool-behavior). Os [forks](#fork-the-current-conversation) ignoram ambos os filtros e recebem exatamente o conjunto de ferramentas da conversa principal. O primeiro filtro remove estas ferramentas, mesmo quando listadas no campo `tools`:443Os subagentes herdam as [ferramentas integradas](https://code.claude.com/docs/pt/tools-reference.md) e as ferramentas MCP disponíveis na conversa principal, reduzidas por dois filtros. O primeiro remove uma pequena lista de ferramentas de todos os subagentes. O segundo reduz o conjunto de ferramentas integradas para subagentes executados em [segundo plano](#run-subagents-in-foreground-or-background), que é o padrão.

444

445No macOS, Linux e WSL, um subagente também pode receber as ferramentas Glob e Grep quando a conversa principal não as tem, conforme descrito em [Comportamento da ferramenta Glob](https://code.claude.com/docs/pt/tools-reference.md#glob-tool-behavior). Os [forks](#fork-the-current-conversation) ignoram ambos os filtros e recebem exatamente o conjunto de ferramentas da conversa pai. O primeiro filtro remove estas ferramentas, mesmo quando listadas no campo `tools`:

430 446

431* `Agent`, quando o subagente está no [limite de profundidade](#let-subagents-spawn-their-own-subagents); em um [fork](#fork-the-current-conversation), a ferramenta permanece listada, mas retorna um erro em vez de criar um subagente447* `Agent`, quando o subagente está no [limite de profundidade](#let-subagents-spawn-their-own-subagents); em um [fork](#fork-the-current-conversation), a ferramenta permanece listada, mas retorna um erro em vez de criar um subagente

432* `AskUserQuestion`448* `AskUserQuestion`

1077 1093

1078Com este valor, seus subagentes podem delegar a uma segunda camada de seus próprios, e essa segunda camada não pode delegar mais. Defina `1` para desativar o aninhamento.1094Com este valor, seus subagentes podem delegar a uma segunda camada de seus próprios, e essa segunda camada não pode delegar mais. Defina `1` para desativar o aninhamento.

1079 1095

1080Um subagente aninhado é configurado da mesma forma que um de nível superior e é resolvido dos mesmos [escopos](#choose-the-subagent-scope). Para manter um subagente de gerar enquanto o aninhamento está ativado, como um revisor que deve permanecer somente leitura, omita `Agent` de sua lista [`tools`](#available-tools) ou adicione-o a `disallowedTools`.1096Defina um subagente aninhado nos mesmos [escopos](#choose-the-subagent-scope) que um de nível superior. Por padrão, um subagente aninhado que você define é executado no [modelo do subagente que o gera](#which-model-a-nested-subagent-runs-on). Para manter um subagente de gerar enquanto o aninhamento está ativado, como um revisor que deve permanecer somente leitura, omita `Agent` de sua lista [`tools`](#available-tools) ou adicione-o a `disallowedTools`.

1081 1097

1082No terminal, Claude Code mostra subagentes aninhados como uma árvore no painel de subagentes abaixo da entrada de prompt e marca cada linha que ainda tem descendentes no painel com uma contagem `(+N)` deles. Abra uma linha para ver os irmãos e filhos diretos desse subagente com um caminho de volta para `main`.1098No terminal, Claude Code mostra subagentes aninhados como uma árvore no painel de subagentes abaixo da entrada de prompt e marca cada linha que ainda tem descendentes no painel com uma contagem `(+N)` deles. Abra uma linha para ver os irmãos e filhos diretos desse subagente com um caminho de volta para `main`.

1083 1099

1221>1237>

1222> Quando [a visualização de agente está desativada](https://code.claude.com/docs/pt/agent-view.md#turn-off-agent-view), `/subtask` não está disponível e `/fork` inicia o subagente bifurcado; caso contrário, `/fork` copia toda a sessão para uma nova [sessão em background](https://code.claude.com/docs/pt/agent-view.md#from-inside-a-session).1238> Quando [a visualização de agente está desativada](https://code.claude.com/docs/pt/agent-view.md#turn-off-agent-view), `/subtask` não está disponível e `/fork` inicia o subagente bifurcado; caso contrário, `/fork` copia toda a sessão para uma nova [sessão em background](https://code.claude.com/docs/pt/agent-view.md#from-inside-a-session).

1223 1239

1224Uma bifurcação é um subagente que herda toda a conversa até agora em vez de começar do zero. Isso remove o isolamento de entrada que subagentes de outra forma fornecem: uma bifurcação vê o mesmo prompt de sistema, ferramentas, modelo e histórico de mensagens que a sessão principal, para que você possa entregar uma tarefa secundária sem re-explicar a situação. As chamadas de ferramentas da bifurcação ainda ficam fora de sua conversa e apenas seu resultado final volta, para que sua janela de contexto principal permaneça limpa. Use uma bifurcação quando qualquer outro subagente precisaria de muito contexto para ser útil, ou quando você quer tentar várias abordagens em paralelo a partir do mesmo ponto de partida.1240Uma bifurcação é um subagente que herda toda a conversa até agora em vez de começar do zero. Use uma bifurcação quando qualquer outro subagente precisaria de muito contexto para ser útil, ou quando você quer tentar várias abordagens em paralelo a partir do mesmo ponto de partida.

1241

1242* **Entrada**: uma bifurcação vê o mesmo system prompt, ferramentas, [modelo](#which-model-a-nested-subagent-runs-on) e histórico de mensagens que sua conversa pai

1243* **Saída**: as próprias chamadas de ferramenta da bifurcação ficam fora de sua conversa pai e apenas seu resultado final volta

1225 1244

1226Claude pode iniciar uma bifurcação por conta própria enquanto o modo de bifurcação está ativado, como está por padrão. Para impedir bifurcações, consulte [Desativar o modo de bifurcação](#turn-fork-mode-on-or-off).1245Claude pode iniciar uma bifurcação por conta própria enquanto o modo de bifurcação está ativado, como está por padrão. Para impedir bifurcações, consulte [Desativar o modo de bifurcação](#turn-fork-mode-on-or-off).

1227 1246

1257 1276

1258### Como bifurcações diferem de outros subagentes1277### Como bifurcações diferem de outros subagentes

1259 1278

1260Uma bifurcação herda tudo que a sessão principal tem no momento em que é gerada. Qualquer outro subagente começa do zero a partir de sua definição.

~~1261~~

1262| | Bifurcação | Subagente não-bifurcado |1279| | Bifurcação | Subagente não-bifurcado |

1263| :- | :- | :- |1280| :- | :- | :- |

1268 1285

1269Porque o system prompt de uma bifurcação e as definições de ferramentas são idênticos aos do pai, sua primeira requisição reutiliza o [cache de prompt](https://code.claude.com/docs/pt/prompt-caching.md#subagents-and-the-cache) do pai. Por causa dessa reutilização, uma bifurcação custa menos do que um subagente fresco para tarefas que precisam do mesmo contexto.1286Porque o system prompt de uma bifurcação e as definições de ferramentas são idênticos aos do pai, sua primeira requisição reutiliza o [cache de prompt](https://code.claude.com/docs/pt/prompt-caching.md#subagents-and-the-cache) do pai. Por causa dessa reutilização, uma bifurcação custa menos do que um subagente fresco para tarefas que precisam do mesmo contexto.

1270 1287

workflows.md +1 −1

Details

454* Verifique `/model` antes de uma execução grande se você geralmente muda para um modelo menor para trabalho de rotina454* Verifique `/model` antes de uma execução grande se você geralmente muda para um modelo menor para trabalho de rotina

455* Peça a Claude para usar um modelo menor para estágios que não precisam do mais forte quando você descreve a tarefa455* Peça a Claude para usar um modelo menor para estágios que não precisam do mais forte quando você descreve a tarefa

456 456

457Quando a [`availableModels` allowlist](https://code.claude.com/docs/pt/model-config#restrict-model-selection) da sua organização bloqueia um modelo que o script solicita para um agente, esse agente é executado em um modelo substituído em vez disso, seguindo as mesmas [regras de substituição que subagentes](https://code.claude.com/docs/pt/sub-agents.md#choose-a-model).457Quando a [`availableModels` allowlist](https://code.claude.com/docs/pt/model-config#restrict-model-selection) da sua organização bloqueia um modelo que o script solicita para um agente, esse agente é executado em um modelo substituído em vez disso, seguindo as mesmas [regras de substituição que subagentes](https://code.claude.com/docs/pt/sub-agents.md#when-an-allowlist-blocks-a-subagent-model).

458 458

459### Defina uma diretriz de tamanho459### Defina uma diretriz de tamanho

460 460

worktrees.md +5 −2

Details

232 232

233Com a [base](#choose-the-base-branch) padrão `"fresh"`, um worktree reaberto é redefinido para o branch padrão do repositório em vez de continuar em sua ponta antiga quando todas as seguintes condições se aplicam:233Com a [base](#choose-the-base-branch) padrão `"fresh"`, um worktree reaberto é redefinido para o branch padrão do repositório em vez de continuar em sua ponta antiga quando todas as seguintes condições se aplicam:

234 234

235* Não tem alterações não confirmadas ou arquivos não rastreados.235* O [sandbox](https://code.claude.com/docs/pt/sandboxing.md#filesystem-isolation) não está restringindo gravações de arquivos na sua sessão, e nem os arquivos de configuração `.claude` do worktree nem os do checkout principal habilitam o sandbox.

236* O worktree não tem alterações sem commit nem arquivos não rastreados.

236* Ainda está na branch que Claude Code criou para ela.237* Ainda está na branch que Claude Code criou para ela.

237* Não tem commits próprios, ou seu pull request ou merge request foi mesclado e sua branch remota foi deletada.238* Não tem commits próprios, ou seu pull request ou merge request foi mesclado e sua branch remota foi deletada.

238 239

240 241

241Em todos os outros casos, Claude Code reabre a worktree em sua ponta antiga:242Em todos os outros casos, Claude Code reabre a worktree em sua ponta antiga:

242 243

243* A worktree falha em qualquer uma das condições.244* O worktree ou a sessão não atende a alguma das condições.

244* Claude Code não pode verificar o estado da worktree.245* Claude Code não pode verificar o estado da worktree.

245* `worktree.baseRef` é `"head"`.246* `worktree.baseRef` é `"head"`.

246* O nome é uma referência de pull request ou merge request.247* O nome é uma referência de pull request ou merge request.

247 248

249Se você usa o sandbox com a base `"fresh"`, execute `git fetch origin` e, em seguida, passe um novo nome para `--worktree` para começar a partir do branch padrão mais recente.

250

248### Substitua a criação de worktree com um hook251### Substitua a criação de worktree com um hook

249 252

250Configure um hook [`WorktreeCreate`](https://code.claude.com/docs/pt/hooks#worktreecreate) para substituir completamente a lógica padrão de `git worktree`, incluindo colocar worktrees em outro lugar que não `.claude/worktrees/`. Para um exemplo completo, consulte [Controle de versão não-git](#non-git-version-control).253Configure um hook [`WorktreeCreate`](https://code.claude.com/docs/pt/hooks#worktreecreate) para substituir completamente a lógica padrão de `git worktree`, incluindo colocar worktrees em outro lugar que não `.claude/worktrees/`. Para um exemplo completo, consulte [Controle de versão não-git](#non-git-version-control).

Documentation 2026-11-13 23:02 UTC to 2026-11-14 03:01 UTC