Documentation — Spybara

agent-sdk/agent-loop.md +2 −2

Details

187 187

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

189 189

190* **`allowed_tools` / `allowedTools`** aprova automaticamente ferramentas listadas. Um agente somente leitura com `["Read", "Glob", "Grep"]` em sua lista de ferramentas permitidas executa essas ferramentas sem avisar. Ferramentas não listadas ainda estão disponíveis, e chamadas para elas que precisam de aprovação caem através do modo de permissão e `canUseTool`.190* **`allowed_tools` / `allowedTools`** aprova automaticamente ferramentas listadas. Um agente somente leitura com `["Read", "Glob", "Grep"]` em sua lista de ferramentas permitidas executa essas ferramentas sem avisar, exceto leituras de [caminhos de rede](/docs/pt/permissions#network-paths). Ferramentas não listadas ainda estão disponíveis, e chamadas para elas que precisam de aprovação caem através do modo de permissão e `canUseTool`.

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

192* **`permission_mode` / `permissionMode`** controla 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](/docs/pt/agent-sdk/permissions#how-permissions-are-evaluated). Veja [Modo de permissão](#permission-mode) para os modos disponíveis.192* **`permission_mode` / `permissionMode`** controla 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](/docs/pt/agent-sdk/permissions#how-permissions-are-evaluated). Veja [Modo de permissão](#permission-mode) para os modos disponíveis.

193 193

263| `"default"` | Chamadas de ferramentas que precisam de aprovação e não são cobertas por regras de permissão acionam seu callback `canUseTool`; nenhum callback significa negar | Aplicações interativas com um callback de aprovação personalizado |263| `"default"` | Chamadas de ferramentas que precisam de aprovação e não são cobertas por regras de permissão acionam seu callback `canUseTool`; nenhum callback significa negar | Aplicações interativas com um callback de aprovação personalizado |

264| `"acceptEdits"` | Aprova automaticamente edições de arquivo e comandos comuns do sistema de arquivos (`mkdir`, `touch`, `mv`, `cp`, etc.); outros comandos Bash seguem as regras padrão | Você confia nas edições do Claude e quer iteração mais rápida, como durante prototipagem ou ao trabalhar em um diretório isolado |264| `"acceptEdits"` | Aprova automaticamente edições de arquivo e comandos comuns do sistema de arquivos (`mkdir`, `touch`, `mv`, `cp`, etc.); outros comandos Bash seguem as regras padrão | Você confia nas edições do Claude e quer iteração mais rápida, como durante prototipagem ou ao trabalhar em um diretório isolado |

265| `"plan"` | Claude explora e planeja sem editar seus arquivos de origem; edições de arquivo nunca são aprovadas automaticamente e solicitam através de seu callback `canUseTool` | Você quer que Claude proponha mudanças sem executá-las, como durante revisão de código ou quando você precisa aprovar mudanças antes de serem feitas |265| `"plan"` | Claude explora e planeja sem editar seus arquivos de origem; edições de arquivo nunca são aprovadas automaticamente e solicitam através de seu callback `canUseTool` | Você quer que Claude proponha mudanças sem executá-las, como durante revisão de código ou quando você precisa aprovar mudanças antes de serem feitas |

266| `"dontAsk"` | Nunca solicita. Ferramentas pré-aprovadas por [regras de permissão](/docs/pt/settings-reference#permission-settings) são executadas, assim como chamadas que não precisam de aprovação no modo `default`, como leituras de arquivo dentro de seus diretórios de trabalho; toda chamada que de outra forma solicitaria é negada. `AskUserQuestion`, ferramentas de conector [que sua organização definiu como `ask`](/docs/pt/mcp#organization-controls-on-connector-tools) e ferramentas MCP marcadas [`requiresUserInteraction`](/docs/pt/mcp#require-approval-for-a-specific-tool) são negadas mesmo que você as tenha permitido | Você quer uma superfície de ferramenta fixa e explícita para um agente sem cabeça e prefere uma negação rígida sobre confiança silenciosa em `canUseTool` estar ausente |266| `"dontAsk"` | Nunca solicita. Ferramentas pré-aprovadas por [regras de permissão](/docs/pt/settings-reference#permission-settings) são executadas, assim como chamadas que não precisam de aprovação no modo `default`, como leituras de arquivo dentro de seus diretórios de trabalho; toda chamada que de outra forma solicitaria é negada. `AskUserQuestion`, ferramentas de conector [que sua organização definiu como `ask`](/docs/pt/mcp#organization-controls-on-connector-tools), ferramentas MCP marcadas [`requiresUserInteraction`](/docs/pt/mcp#require-approval-for-a-specific-tool) e [leituras de caminhos de rede](/docs/pt/permissions#network-paths) são negadas mesmo que você as tenha permitido | Você quer uma superfície de ferramenta fixa e explícita para um agente sem cabeça e prefere uma negação rígida sobre confiança silenciosa em `canUseTool` estar ausente |

267| `"auto"` | Usa um classificador de modelo para revisar ações como comandos shell e solicitações de rede, permitindo ou bloqueando cada uma que revisa. Veja [Auto mode](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode) para disponibilidade e a ordem de decisão | Agentes autônomos que ainda querem proteções de segurança no uso de ferramentas |267| `"auto"` | Usa um classificador de modelo para revisar ações como comandos shell e solicitações de rede, permitindo ou bloqueando cada uma que revisa. Veja [Auto mode](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode) para disponibilidade e a ordem de decisão | Agentes autônomos que ainda querem proteções de segurança no uso de ferramentas |

268| `"bypassPermissions"` | Executa todas as ferramentas permitidas sem perguntar, exceto ferramentas correspondidas por uma regra [`ask`](/docs/pt/settings-reference#permission-settings) explícita, ferramentas de conector [que sua organização definiu como `ask`](/docs/pt/mcp#organization-controls-on-connector-tools) e ferramentas que exigem interação do usuário. As [proteções de mensagens entre sessões](/docs/pt/permission-modes#skip-all-checks-with-bypasspermissions-mode) ainda se aplicam. Veja [How permissions are evaluated](/docs/pt/agent-sdk/permissions#how-permissions-are-evaluated) para a ordem de precedência. No SDK TypeScript, também requer `allowDangerouslySkipPermissions: true` em `options`. Não pode ser usado ao executar como root no Unix. Use apenas em ambientes isolados onde as ações do agente não podem afetar sistemas que você se importa | CI, contêineres ou outros ambientes isolados |268| `"bypassPermissions"` | Executa todas as ferramentas permitidas sem perguntar, exceto ferramentas correspondidas por uma regra [`ask`](/docs/pt/settings-reference#permission-settings) explícita, ferramentas de conector [que sua organização definiu como `ask`](/docs/pt/mcp#organization-controls-on-connector-tools) e ferramentas que exigem interação do usuário. As [proteções de mensagens entre sessões](/docs/pt/permission-modes#skip-all-checks-with-bypasspermissions-mode) ainda se aplicam. Veja [How permissions are evaluated](/docs/pt/agent-sdk/permissions#how-permissions-are-evaluated) para a ordem de precedência. No SDK TypeScript, também requer `allowDangerouslySkipPermissions: true` em `options`. Não pode ser usado ao executar como root no Unix. Use apenas em ambientes isolados onde as ações do agente não podem afetar sistemas que você se importa | CI, contêineres ou outros ambientes isolados |

269 269

agent-sdk/hooks.md +1 −1

Details

424 Aprovar automaticamente ferramentas específicas424 Aprovar automaticamente ferramentas específicas

425</h3>425</h3>

426 426

427Por padrão, o agente pode solicitar permissão antes de usar certas ferramentas. Este exemplo aprova automaticamente ferramentas de sistema de arquivos somente leitura (Read, Glob, Grep) retornando `permissionDecision: 'allow'`, permitindo que sejam executadas sem confirmação do usuário enquanto deixa todas as outras ferramentas sujeitas a verificações de permissão normais:427Por padrão, o agente pode solicitar permissão antes de usar certas ferramentas. Este exemplo aprova automaticamente ferramentas de sistema de arquivos somente leitura (Read, Glob, Grep) retornando `permissionDecision: 'allow'`, permitindo que sejam executadas sem confirmação do usuário, exceto leituras de [caminhos de rede](/docs/pt/permissions#network-paths), enquanto deixa todas as outras ferramentas sujeitas a verificações de permissão normais:

428 428

429<CodeGroup>429<CodeGroup>

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

agent-sdk/permissions.md +8 −6

Details

44 Verifique as regras `allow` (de `allowed_tools` e settings.json). Se uma regra corresponder, a ferramenta é aprovada. Uma chamada que a ferramenta aprova por conta própria é resolvida nesta etapa também, sem necessidade de regra: por exemplo uma leitura de arquivo dentro de seus diretórios de trabalho ou um [comando Bash somente leitura](/docs/pt/permissions#read-only-commands).44 Verifique as regras `allow` (de `allowed_tools` e settings.json). Se uma regra corresponder, a ferramenta é aprovada. Uma chamada que a ferramenta aprova por conta própria é resolvida nesta etapa também, sem necessidade de regra: por exemplo uma leitura de arquivo dentro de seus diretórios de trabalho ou um [comando Bash somente leitura](/docs/pt/permissions#read-only-commands).

45 45

46 Remoções `rm` e `rmdir` direcionadas a um [caminho crítico](/docs/pt/permission-modes#critical-paths) nunca são aprovadas por uma regra de permissão. Se elas então chegarem ao seu callback depende do modo de permissão: em uma sessão do Agent SDK no modo `auto`, por exemplo, Claude Code as nega por padrão sem chamá-lo. A tabela [Caminhos críticos](/docs/pt/permission-modes#critical-paths) do modo lista o que cada modo faz com elas.46 Remoções `rm` e `rmdir` direcionadas a um [caminho crítico](/docs/pt/permission-modes#critical-paths) nunca são aprovadas por uma regra de permissão. Se elas então chegarem ao seu callback depende do modo de permissão: em uma sessão do Agent SDK no modo `auto`, por exemplo, Claude Code as nega por padrão sem chamá-lo. A tabela [Caminhos críticos](/docs/pt/permission-modes#critical-paths) do modo lista o que cada modo faz com elas.

48 Uma regra de permissão não aprova uma leitura de um [caminho de rede](/docs/pt/permissions#network-paths).

47 </Step>49 </Step>

48 50

49 <Step title="Callback canUseTool">51 <Step title="Callback canUseTool">

60Se você passar um callback `canUseTool` em uma configuração onde o SDK TypeScript espera que a ordem de avaliação aprove automaticamente as chamadas antes do callback ser consultado, o SDK emite um aviso de processo Node.js uma vez quando a consulta é construída. O código do aviso é `CLAUDE_SDK_CAN_USE_TOOL_SHADOWED`. Duas configurações o acionam:62Se você passar um callback `canUseTool` em uma configuração onde o SDK TypeScript espera que a ordem de avaliação aprove automaticamente as chamadas antes do callback ser consultado, o SDK emite um aviso de processo Node.js uma vez quando a consulta é construída. O código do aviso é `CLAUDE_SDK_CAN_USE_TOOL_SHADOWED`. Duas configurações o acionam:

61 63

62* `permissionMode: 'bypassPermissions'`, que aprova automaticamente cada chamada que chega à etapa do modo de permissão, exceto pelas [ações que nenhum modo aprova automaticamente](/docs/pt/permission-modes#actions-no-mode-auto-approves)64* `permissionMode: 'bypassPermissions'`, que aprova automaticamente cada chamada que chega à etapa do modo de permissão, exceto pelas [ações que nenhum modo aprova automaticamente](/docs/pt/permission-modes#actions-no-mode-auto-approves)

63* Cada entrada `allowedTools` simples como `"Read"`, que aprova automaticamente essa ferramenta inteira antes do callback ser consultado, exceto pelas [ações que nenhum modo aprova automaticamente](/docs/pt/permission-modes#actions-no-mode-auto-approves)65* Cada entrada `allowedTools` simples como `"Read"`, que aprova automaticamente essa ferramenta inteira antes do callback ser consultado, exceto pelas [ações que nenhum modo aprova automaticamente](/docs/pt/permission-modes#actions-no-mode-auto-approves) e pelas [leituras de caminhos de rede](/docs/pt/permissions#network-paths)

64 66

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

66 68

79 81

80| Opção | Efeito |82| Opção | Efeito |

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

82| `allowed_tools=["Read", "Grep"]` | `Read` e `Grep` são aprovadas automaticamente. Outras ferramentas não listadas aqui ainda existem, e chamadas a elas que precisam de aprovação passam para o modo de permissão e `canUseTool`. |84| `allowed_tools=["Read", "Grep"]` | `Read` e `Grep` são aprovadas automaticamente, exceto por [leituras de caminhos de rede](/docs/pt/permissions#network-paths). Outras ferramentas não listadas aqui ainda existem, e chamadas a elas que precisam de aprovação passam para o modo de permissão e `canUseTool`. |

83| `disallowed_tools=["Bash"]` | A definição da ferramenta `Bash` é removida da solicitação. Claude não vê a ferramenta e não pode tentar usá-la. |85| `disallowed_tools=["Bash"]` | A definição da ferramenta `Bash` é removida da solicitação. Claude não vê a ferramenta e não pode tentar usá-la. |

84| `disallowed_tools=["Bash(rm *)"]` | `Bash` permanece disponível. Chamadas correspondentes a `rm *` [conforme escrito](/docs/pt/permissions#bash-rule-limits) são negadas em todos os modos de permissão, incluindo `bypassPermissions`. Outras chamadas `Bash`, incluindo `/bin/rm`, passam para o modo de permissão. |86| `disallowed_tools=["Bash(rm *)"]` | `Bash` permanece disponível. Chamadas correspondentes a `rm *` [conforme escrito](/docs/pt/permissions#bash-rule-limits) são negadas em todos os modos de permissão, incluindo `bypassPermissions`. Outras chamadas `Bash`, incluindo `/bin/rm`, passam para o modo de permissão. |

85| `disallowed_tools=["*"]` | Toda definição de ferramenta é removida da solicitação. Globs de nome de ferramenta são suportados em regras de negação: `"*"` corresponde a todas as ferramentas e `"mcp__*"` corresponde a todas as ferramentas MCP em todos os servidores. |87| `disallowed_tools=["*"]` | Toda definição de ferramenta é removida da solicitação. Globs de nome de ferramenta são suportados em regras de negação: `"*"` corresponde a todas as ferramentas e `"mcp__*"` corresponde a todas as ferramentas MCP em todos os servidores. |

95 97

96 Uma regra de permissão nunca aprova automaticamente `AskUserQuestion`, ferramentas MCP marcadas [`_meta["anthropic/requiresUserInteraction"]`](/docs/pt/mcp#require-approval-for-a-specific-tool), ferramentas de conector [que sua organização definiu como `ask`](/docs/pt/mcp#organization-controls-on-connector-tools), ou remoções `rm` e `rmdir` direcionadas a um [caminho crítico](/docs/pt/permission-modes#critical-paths). No modo `dontAsk` Claude Code nega essas chamadas sem invocar o callback. Em outros modos os três primeiros chegam ao callback. Dependendo do [modo de permissão](/docs/pt/permission-modes#critical-paths), uma remoção de caminho crítico chega ao callback também ou Claude Code a nega sem chamá-lo, como faz por padrão para uma sessão do Agent SDK no modo `auto`.98 Uma regra de permissão nunca aprova automaticamente `AskUserQuestion`, ferramentas MCP marcadas [`_meta["anthropic/requiresUserInteraction"]`](/docs/pt/mcp#require-approval-for-a-specific-tool), ferramentas de conector [que sua organização definiu como `ask`](/docs/pt/mcp#organization-controls-on-connector-tools), ou remoções `rm` e `rmdir` direcionadas a um [caminho crítico](/docs/pt/permission-modes#critical-paths). No modo `dontAsk` Claude Code nega essas chamadas sem invocar o callback. Em outros modos os três primeiros chegam ao callback. Dependendo do [modo de permissão](/docs/pt/permission-modes#critical-paths), uma remoção de caminho crítico chega ao callback também ou Claude Code a nega sem chamá-lo, como faz por padrão para uma sessão do Agent SDK no modo `auto`.

97 99

98 A cobertura depende da forma da entrada: um nome simples como `Read` ou `mcp__github__get_issue` aprova automaticamente todas as chamadas a essa ferramenta, exceto as exceções acima, enquanto uma regra com escopo como `Bash(npm test *)` aprova automaticamente apenas chamadas correspondentes, e outras chamadas `Bash` que precisam de aprovação ainda passam para o callback. Para verificações que devem ser executadas em todas as chamadas de ferramenta, use um [hook `PreToolUse`](/docs/pt/agent-sdk/hooks): hooks são executados antes de qualquer outra etapa, e uma negação de hook se aplica mesmo no modo `bypassPermissions`.100 A cobertura depende da forma da entrada: um nome simples como `Read` ou `mcp__github__get_issue` aprova automaticamente todas as chamadas a essa ferramenta, exceto essas exceções e [leituras de caminhos de rede](/docs/pt/permissions#network-paths), enquanto uma regra com escopo como `Bash(npm test *)` aprova automaticamente apenas chamadas correspondentes, e outras chamadas `Bash` que precisam de aprovação ainda passam para o callback. Para verificações que devem ser executadas em todas as chamadas de ferramenta, use um [hook `PreToolUse`](/docs/pt/agent-sdk/hooks): hooks são executados antes de qualquer outra etapa, e uma negação de hook se aplica mesmo no modo `bypassPermissions`.

99</Warning>101</Warning>

100 102

101Para um agente bloqueado, combine `allowedTools` com `permissionMode: "dontAsk"`:103Para um agente bloqueado, combine `allowedTools` com `permissionMode: "dontAsk"`:

107};109};

108```110```

109 111

110As ferramentas listadas são aprovadas, exceto pelas [ações que nenhum modo aprova automaticamente](/docs/pt/permission-modes#actions-no-mode-auto-approves), e todas as outras chamadas que solicitariam aprovação são negadas. Chamadas que não precisam de aprovação no modo `default` são executadas independentemente de você listá-las, como [comandos Bash somente leitura](/docs/pt/permissions#read-only-commands), ferramentas como `Agent` que não solicitam antes de executar, e leituras de arquivo dentro de seus diretórios de trabalho. Para colocar uma ferramenta completamente fora do alcance de Claude, adicione seu nome simples a `disallowedTools`.112As ferramentas listadas são aprovadas, exceto pelas [ações que nenhum modo aprova automaticamente](/docs/pt/permission-modes#actions-no-mode-auto-approves) e pelas [leituras de caminhos de rede](/docs/pt/permissions#network-paths), e todas as outras chamadas que solicitariam aprovação são negadas. Chamadas que não precisam de aprovação no modo `default` são executadas independentemente de você listá-las, como [comandos Bash somente leitura](/docs/pt/permissions#read-only-commands), ferramentas como `Agent` que não solicitam antes de executar, e leituras de arquivo dentro de seus diretórios de trabalho. Para remover uma ferramenta completamente da requisição, adicione seu nome simples a `disallowedTools`.

111 113

112<Warning>114<Warning>

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

140| :- | :- | :- |142| :- | :- | :- |

141| `default` | Comportamento de permissão padrão | Sem aprovações automáticas baseadas em modo; chamadas que precisam de aprovação e não correspondem a nenhuma regra de permissão acionam seu callback `canUseTool` |143| `default` | Comportamento de permissão padrão | Sem aprovações automáticas baseadas em modo; chamadas que precisam de aprovação e não correspondem a nenhuma regra de permissão acionam seu callback `canUseTool` |

142| `dontAsk` | Negar em vez de solicitar | Qualquer chamada que de outra forma solicitaria é negada. Chamadas aprovadas por `allowed_tools` ou regras são executadas, assim como chamadas que não precisam de aprovação no modo `default`, como leituras de arquivo dentro de seus diretórios de trabalho e chamadas para `Agent`. Ferramentas de conector [que sua organização definiu como `ask`](/docs/pt/mcp#organization-controls-on-connector-tools) e ferramentas que exigem interação do usuário são negadas mesmo que você as tenha pré-aprovado, assim como remoções `rm` e `rmdir` direcionadas a um [caminho crítico](/docs/pt/permission-modes#critical-paths). `canUseTool` nunca é chamado |144| `dontAsk` | Negar em vez de solicitar | Qualquer chamada que de outra forma solicitaria é negada. Chamadas aprovadas por `allowed_tools` ou regras são executadas, assim como chamadas que não precisam de aprovação no modo `default`; ferramentas de conector [que sua organização definiu como `ask`](/docs/pt/mcp#organization-controls-on-connector-tools) e ferramentas que exigem interação do usuário são negadas mesmo que você as tenha pré-aprovado, assim como [leituras de caminhos de rede](/docs/pt/permissions#network-paths) e remoções `rm` e `rmdir` direcionadas a um [caminho crítico](/docs/pt/permission-modes#critical-paths). `canUseTool` nunca é chamado |

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

144| `bypassPermissions` | Contornar verificações de permissão | As ferramentas são executadas sem prompts de permissão, exceto pelas [ações que nenhum modo aprova automaticamente](/docs/pt/permission-modes#actions-no-mode-auto-approves). Use com cuidado |146| `bypassPermissions` | Contornar verificações de permissão | As ferramentas são executadas sem prompts de permissão, exceto pelas [ações que nenhum modo aprova automaticamente](/docs/pt/permission-modes#actions-no-mode-auto-approves). Use com cuidado |

145| `plan` | Modo de planejamento | Claude explora e planeja sem editar seus arquivos de origem; edições de arquivo nunca são aprovadas automaticamente e solicitam através de seu callback `canUseTool` |147| `plan` | Modo de planejamento | Claude explora e planeja sem editar seus arquivos de origem; edições de arquivo nunca são aprovadas automaticamente e solicitam através de seu callback `canUseTool` |

286 Modo não perguntar (`dontAsk`)288 Modo não perguntar (`dontAsk`)

287</h4>289</h4>

288 290

289Converte qualquer prompt de permissão em uma negação, sem chamar `canUseTool`. Ferramentas pré-aprovadas por `allowed_tools`, regras de permissão em `settings.json` ou um hook são executadas normalmente, assim como chamadas que não precisam de aprovação no modo `default`, como leituras de arquivo dentro de seus diretórios de trabalho e chamadas para `Agent`. Ferramentas de conector [que sua organização definiu como `ask`](/docs/pt/mcp#organization-controls-on-connector-tools), ferramentas que exigem interação do usuário e remoções `rm` e `rmdir` direcionadas a um [caminho crítico](/docs/pt/permission-modes#critical-paths) são negadas mesmo quando uma regra de permissão corresponde. Uma permissão de hook `PreToolUse` também não limpa uma remoção de caminho crítico.291Converte qualquer prompt de permissão em uma negação, sem chamar `canUseTool`. Ferramentas pré-aprovadas por `allowed_tools`, regras de permissão em `settings.json` ou um hook são executadas normalmente, assim como chamadas que não precisam de aprovação no modo `default`, como leituras de arquivo dentro de seus diretórios de trabalho e chamadas para `Agent`. Ferramentas de conector [que sua organização definiu como `ask`](/docs/pt/mcp#organization-controls-on-connector-tools), ferramentas que exigem interação do usuário, [leituras de caminhos de rede](/docs/pt/permissions#network-paths) e remoções `rm` e `rmdir` direcionadas a um [caminho crítico](/docs/pt/permission-modes#critical-paths) são negadas mesmo quando uma regra de permissão corresponde. Uma permissão de hook `PreToolUse` também não libera uma remoção de caminho crítico nem uma leitura de um caminho de rede.

290 292

291**Use quando:** você deseja uma superfície de ferramenta fixa e explícita para um agente sem interface e prefere uma negação definitiva em vez de depender silenciosamente de `canUseTool` estar ausente.293**Use quando:** você deseja uma superfície de ferramenta fixa e explícita para um agente sem interface e prefere uma negação definitiva em vez de depender silenciosamente de `canUseTool` estar ausente.

292 294

agent-sdk/python.md +52 −1

Details

518 print(session.summary)518 print(session.summary)

519```519```

520 520

521<h3 id="fork_session">

522 `fork_session()`

523</h3>

524

525Copia a transcrição de uma sessão para uma nova sessão, para que você possa levar a conversa em outra direção enquanto a original permanece inalterada. Para ramificar a partir de um ponto anterior da conversa, passe `up_to_message_id`. Síncrono.

526

527```python theme={null}

528def fork_session(

529 session_id: str,

530 directory: str | None = None,

531 up_to_message_id: str | None = None,

532 title: str | None = None,

533) -> ForkSessionResult

534```

535

536<h4 id="parameters-9">

537 Parâmetros

538</h4>

539

541| :- | :- | :- | :- |

546

547Retorna um `ForkSessionResult` cujo `session_id` é o UUID da nova sessão. Passe-o como [`resume`](#claudeagentoptions) para continuar o fork. O fork não inclui os [checkpoints de arquivo](/docs/pt/agent-sdk/file-checkpointing) da sessão original, portanto você não pode retrocedê-lo para um checkpoint capturado antes do fork.

548

549`fork_session()` lança:

550

551* `ValueError`: `session_id` ou `up_to_message_id` não é um UUID válido

552* `ValueError`: a sessão não tem mensagens, ou `up_to_message_id` não corresponde a nenhuma mensagem na transcrição

553* `FileNotFoundError`: a sessão não pode ser encontrada

554

555<h4 id="example-8">

556 Exemplo

557</h4>

558

559Crie um fork da sessão mais recente com um novo título e depois retome o fork. A sessão original mantém seu próprio histórico.

560

561```python theme={null}

562from claude_agent_sdk import fork_session, list_sessions

563

564sessions = list_sessions(directory="/path/to/project", limit=1)

565if sessions:

566 forked = fork_session(sessions[0].session_id, title="Try the OAuth approach")

567 print(forked.session_id) # pass as ClaudeAgentOptions(resume=...) to continue the fork

568```

569

521<h2 id="classes">570<h2 id="classes">

522 Classes571 Classes

523</h2>572</h2>

920| :- | :- | :- | :- |969| :- | :- | :- | :- |

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

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

923| `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) |972| `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) |

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

925| `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](/docs/pt/mcp#use-mcp-servers-from-claude-ai). Mapeia para a flag CLI `--strict-mcp-config` |974| `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](/docs/pt/mcp#use-mcp-servers-from-claude-ai). Mapeia para a flag CLI `--strict-mcp-config` |

1849* `terminal_reason`: por que o loop de consulta terminou, como `"completed"`, `"max_turns"`, `"api_error"`, `"aborted_streaming"` ou `"aborted_tools"`. Um valor de `"aborted_streaming"` ou `"aborted_tools"` significa que o turno foi abortado antes de ser concluído. As causas comuns são [`interrupt()`](#claudesdkclient) e um callback de permissão retornando [`PermissionResultDeny`](#permissionresultdeny) com `interrupt=True`. `None` em versões da CLI que antecedem o campo, em resultados de comandos locais como `/voice` ou `/usage`, que contornam o loop de consulta, ou em resultados de erro sintetizados emitidos quando a sessão falha fatalmente. Espelha o [`SDKResultMessage.terminal_reason`](/docs/pt/agent-sdk/typescript#sdkresultmessage) do SDK TypeScript, que lista o conjunto completo de valores.1898* `terminal_reason`: por que o loop de consulta terminou, como `"completed"`, `"max_turns"`, `"api_error"`, `"aborted_streaming"` ou `"aborted_tools"`. Um valor de `"aborted_streaming"` ou `"aborted_tools"` significa que o turno foi abortado antes de ser concluído. As causas comuns são [`interrupt()`](#claudesdkclient) e um callback de permissão retornando [`PermissionResultDeny`](#permissionresultdeny) com `interrupt=True`. `None` em versões da CLI que antecedem o campo, em resultados de comandos locais como `/voice` ou `/usage`, que contornam o loop de consulta, ou em resultados de erro sintetizados emitidos quando a sessão falha fatalmente. Espelha o [`SDKResultMessage.terminal_reason`](/docs/pt/agent-sdk/typescript#sdkresultmessage) do SDK TypeScript, que lista o conjunto completo de valores.

1850* `origin`: origem da mensagem do usuário que acionou este turno. Em [modo de entrada de streaming](/docs/pt/agent-sdk/streaming-vs-single-mode), verifique isso para distinguir o resultado do seu próprio prompt, onde `origin` é `None` ou `{"kind": "human"}`, do resultado de um turno injetado, como uma notificação de tarefa em segundo plano. Requer Python Agent SDK 0.2.137 ou posterior.1899* `origin`: origem da mensagem do usuário que acionou este turno. Em [modo de entrada de streaming](/docs/pt/agent-sdk/streaming-vs-single-mode), verifique isso para distinguir o resultado do seu próprio prompt, onde `origin` é `None` ou `{"kind": "human"}`, do resultado de um turno injetado, como uma notificação de tarefa em segundo plano. Requer Python Agent SDK 0.2.137 ou posterior.

1851 1900

1901Quando várias tarefas em segundo plano terminam em momentos próximos, o Claude Code pode responder às notificações delas em um único turno, em vez de um turno para cada. Você ainda recebe um `ResultMessage` por notificação, em ordem, cada um com um `origin` cujo `kind` é `"task-notification"`. Todos, exceto o último, têm `num_turns` definido como `0` e um `result` vazio, e o último carrega o turno que responde a todas elas.

1902

1852O dict `usage` cobre apenas o loop do agente principal e exclui subagentes e outras chamadas de modelo aninhadas ou auxiliares. Em [modo de entrada de streaming](/docs/pt/agent-sdk/streaming-vs-single-mode), os valores são por turno. Prefira `model_usage` para contabilidade de token e custo. O dict `usage` contém as seguintes chaves quando presentes:1903O dict `usage` cobre apenas o loop do agente principal e exclui subagentes e outras chamadas de modelo aninhadas ou auxiliares. Em [modo de entrada de streaming](/docs/pt/agent-sdk/streaming-vs-single-mode), os valores são por turno. Prefira `model_usage` para contabilidade de token e custo. O dict `usage` contém as seguintes chaves quando presentes:

1853 1904

agent-sdk/session-storage.md +1 −1

Details

360* [`renameSession()`](/docs/pt/agent-sdk/typescript#renamesession)360* [`renameSession()`](/docs/pt/agent-sdk/typescript#renamesession)

361* [`tagSession()`](/docs/pt/agent-sdk/typescript#tagsession)361* [`tagSession()`](/docs/pt/agent-sdk/typescript#tagsession)

362* [`deleteSession()`](/docs/pt/agent-sdk/typescript)362* [`deleteSession()`](/docs/pt/agent-sdk/typescript)

363* [`forkSession()`](/docs/pt/agent-sdk/typescript)363* [`forkSession()`](/docs/pt/agent-sdk/typescript#forksession)

364* [`listSubagents()`](/docs/pt/agent-sdk/typescript)364* [`listSubagents()`](/docs/pt/agent-sdk/typescript)

365* [`getSubagentMessages()`](/docs/pt/agent-sdk/typescript)365* [`getSubagentMessages()`](/docs/pt/agent-sdk/typescript)

366 366

agent-sdk/sessions.md +2 −2

Details

293 293

294 Você pode retomar de qualquer diretório de trabalho:294 Você pode retomar de qualquer diretório de trabalho:

295 295

296 * **Busca entre diretórios**: Claude Code procura além do diretório do projeto atual para encontrar o ID; veja [Resume a session](/docs/pt/sessions#resume-a-session) para a ordem exata de busca e como cópias duplicadas são tratadas.296 * **Busca entre diretórios**: Claude Code procura além do diretório do projeto atual para encontrar o ID; veja [Resume a session](/docs/pt/sessions#where-the-session-picker-looks) para a ordem exata de busca e como cópias duplicadas são tratadas.

297 * **Mesma máquina apenas**: o arquivo de sessão ainda precisa existir na máquina atual.297 * **Mesma máquina apenas**: o arquivo de sessão ainda precisa existir na máquina atual.

298 298

299 Antes da v2.1.223, a busca era limitada ao diretório do projeto atual e seus git worktrees; versões do SDK que agrupam uma CLI mais antiga ainda se comportam dessa forma.299 Antes da v2.1.223, a busca era limitada ao diretório do projeto atual e seus git worktrees; versões do SDK que agrupam uma CLI mais antiga ainda se comportam dessa forma.

423 423

424* **Mova o arquivo de sessão.** Persista `~/.claude/projects/<encoded-cwd>/<session-id>.jsonl` da primeira execução e restaure-o dentro de qualquer diretório em `~/.claude/projects/` no novo host antes de chamar `resume`.424* **Mova o arquivo de sessão.** Persista `~/.claude/projects/<encoded-cwd>/<session-id>.jsonl` da primeira execução e restaure-o dentro de qualquer diretório em `~/.claude/projects/` no novo host antes de chamar `resume`.

425 425

426 Claude Code procura além do diretório do projeto atual para encontrar o ID; consulte [Retomar uma sessão](/docs/pt/sessions#resume-a-session) para a ordem exata de busca e como cópias duplicadas são tratadas. Antes da v2.1.223, a busca era limitada ao diretório do projeto atual e seus git worktrees; versões do SDK que agrupam uma CLI mais antiga ainda se comportam dessa forma.426 Claude Code procura além do diretório do projeto atual para encontrar o ID; consulte [Retomar uma sessão](/docs/pt/sessions#where-the-session-picker-looks) para a ordem exata de busca e como cópias duplicadas são tratadas. Antes da v2.1.223, a busca era limitada ao diretório do projeto atual e seus git worktrees; versões do SDK que agrupam uma CLI mais antiga ainda se comportam dessa forma.

427 427

428* **Não confie em retomada de sessão.** Capture os resultados que você precisa (saída de análise, decisões, diffs de arquivo) como estado do aplicativo e passe-os para o prompt de uma sessão nova. Isso geralmente é mais robusto do que enviar arquivos de transcrição.428* **Não confie em retomada de sessão.** Capture os resultados que você precisa (saída de análise, decisões, diffs de arquivo) como estado do aplicativo e passe-os para o prompt de uma sessão nova. Isso geralmente é mais robusto do que enviar arquivos de transcrição.

429 429

agent-sdk/streaming-output.md +8 −0

Details

124 124

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

126 126

127<h3 id="handle-a-stream-that’s-cut-off">

128 Lidar com um stream interrompido

129</h3>

130

131Se um stream for interrompido no meio de uma mensagem, como quando você interrompe o turno ou a conexão cai, você ainda recebe o `message_stop` dessa mensagem antes que o turno termine. Um bloco de texto ou de pensamento interrompido também recebe seu `content_block_stop`. Uma chamada de ferramenta interrompida não recebe, portanto, se `message_stop` chegar enquanto o bloco de uma chamada de ferramenta ainda estiver aberto, trate a entrada dessa chamada como incompleta.

132

133Antes do Claude Code v2.1.290, um stream interrompido podia encerrar o turno sem `message_stop`, de modo que uma resposta que você renderiza a partir de eventos de stream podia continuar sendo exibida como em andamento. O Agent SDK para TypeScript inclui o Claude Code v2.1.290 ou posterior a partir da v0.3.290, e o Agent SDK para Python a partir da v0.2.164. Se uma resposta continuar sendo exibida como em andamento após o término do turno, atualize o SDK.

134

127<h2 id="stream-tool-calls">135<h2 id="stream-tool-calls">

128 Transmitir chamadas de ferramentas136 Transmitir chamadas de ferramentas

129</h2>137</h2>

agent-sdk/typescript.md +51 −12

Details

466 466

467<h3 id="forksession">

468 `forkSession()`

469</h3>

470

471Copia a transcrição de uma sessão para uma nova sessão, para que você possa levar a conversa em outra direção enquanto a original permanece inalterada. Para criar uma ramificação a partir de um ponto anterior da conversa, passe `upToMessageId`.

472

473```typescript theme={null}

474function forkSession(

475 sessionId: string,

476 options?: ForkSessionOptions

477): Promise<ForkSessionResult>;

478```

479

480<h4 id="parameters-10">

481 Parâmetros

482</h4>

483

485| :- | :- | :- | :- |

488| `options.upToMessageId` | `string` | `undefined` | Copia a transcrição até a mensagem com este `uuid`, inclusive: um valor de [`getSessionMessages()`](#getsessionmessages), ou um `uuid` que você define em uma [`SDKUserMessage`](#sdkusermessage) enviada por streaming. Quando omitido, copia a transcrição inteira |

490

491Retorna `{ sessionId }`, o UUID da nova sessão. Passe-o como [`resume`](#options) para continuar o fork. O fork não inclui os [checkpoints de arquivo](/docs/pt/agent-sdk/file-checkpointing) da sessão original, então você não pode retrocedê-lo para um checkpoint capturado antes do fork.

492

493`forkSession()` lança uma exceção quando:

494

495* `sessionId` não é um UUID

496* a sessão não pode ser encontrada ou não tem mensagens

497* `upToMessageId` não corresponde a nenhuma mensagem na transcrição

498

467<h3 id="resolvesettings">499<h3 id="resolvesettings">

468 `resolveSettings()`500 `resolveSettings()`

469</h3>501</h3>

486): Promise<ResolvedSettings>;518): Promise<ResolvedSettings>;

487```519```

488 520

489<h4 id="parameters-10">521<h4 id="parameters-11">

490 Parâmetros522 Parâmetros

491</h4>523</h4>

492 524

548| `agentProgressSummaries` | `boolean` | `false` | Quando `true`, gera resumos de progresso de uma linha para subagentes e os encaminha em eventos [`task_progress`](#sdktaskprogressmessage) por meio do campo `summary`. Aplica-se a subagentes em primeiro plano e em segundo plano |580| `agentProgressSummaries` | `boolean` | `false` | Quando `true`, gera resumos de progresso de uma linha para subagentes e os encaminha em eventos [`task_progress`](#sdktaskprogressmessage) por meio do campo `summary`. Aplica-se a subagentes em primeiro plano e em segundo plano |

549| `allowDangerouslySkipPermissions` | `boolean` | `false` | Habilita o bypass de permissões. Obrigatório ao usar `permissionMode: 'bypassPermissions'`, na inicialização ou posteriormente por meio de `setPermissionMode()`. Consulte [modo de planejamento](/docs/pt/agent-sdk/permissions#plan-mode-plan) para ver como isso interage com `permissionMode: 'plan'` |581| `allowDangerouslySkipPermissions` | `boolean` | `false` | Habilita o bypass de permissões. Obrigatório ao usar `permissionMode: 'bypassPermissions'`, na inicialização ou posteriormente por meio de `setPermissionMode()`. Consulte [modo de planejamento](/docs/pt/agent-sdk/permissions#plan-mode-plan) para ver como isso interage com `permissionMode: 'plan'` |

550| `allowedTools` | `string[]` | `[]` | Ferramentas a aprovar automaticamente sem pedir confirmação. Isso não restringe o Claude apenas a essas ferramentas. Se você nomear aqui uma das [ferramentas de acompanhamento de tarefas](/docs/pt/agent-sdk/todo-tracking#model-availability), o Claude Code também as habilita para a sessão. Outras ferramentas não listadas seguem para `permissionMode` e `canUseTool`. Use `disallowedTools` para bloquear ferramentas. Consulte [Permissões](/docs/pt/agent-sdk/permissions#allow-and-deny-rules) |582| `allowedTools` | `string[]` | `[]` | Ferramentas a aprovar automaticamente sem solicitar confirmação, exceto leituras de [caminhos de rede](/docs/pt/permissions#network-paths). Isso não restringe Claude apenas a essas ferramentas. Se você nomear aqui uma das [ferramentas de acompanhamento de tarefas](/docs/pt/agent-sdk/todo-tracking#model-availability), o Claude Code também as habilita na sessão. Outras ferramentas não listadas seguem para `permissionMode` e `canUseTool`. Use `disallowedTools` para bloquear ferramentas. Consulte [Permissões](/docs/pt/agent-sdk/permissions#allow-and-deny-rules) |

552| `canUseTool` | [`CanUseTool`](#canusetool) | `undefined` | Função de permissão personalizada, invocada somente quando o [fluxo de permissões](/docs/pt/agent-sdk/permissions#how-permissions-are-evaluated) chega a um prompt. Não é invocada para chamadas aprovadas automaticamente por `allowedTools`, regras de permissão ou `permissionMode`. Uma regra de permissão não pré-aprova as [ações que nenhum modo aprova automaticamente](/docs/pt/permission-modes#actions-no-mode-auto-approves). Consulte [`CanUseTool`](#canusetool) para obter detalhes |584| `canUseTool` | [`CanUseTool`](#canusetool) | `undefined` | Função de permissão personalizada, invocada somente quando o [fluxo de permissões](/docs/pt/agent-sdk/permissions#how-permissions-are-evaluated) chega a um prompt. Não é invocada para chamadas aprovadas automaticamente por `allowedTools`, regras de permissão ou `permissionMode`. Uma regra de permissão não pré-aprova as [ações que nenhum modo aprova automaticamente](/docs/pt/permission-modes#actions-no-mode-auto-approves). Consulte [`CanUseTool`](#canusetool) para obter detalhes |

1588 1620

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

1590 1622

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

1592 1624

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

1594 1626

1631 1663

1632Defina `inline_pastes` para informar ao Claude Code quais partes de `message.content` o usuário colou em vez de digitar, uma string por colagem. O texto do prompt permanece onde o usuário o colocou. O Claude Code pode envolver cada colagem listada em tags `<pasted_content>` no local em que ela está, para que o Claude consiga distinguir o material colado das palavras do próprio usuário. Apenas colagens no último bloco de texto do prompt são envolvidas. Requer o TypeScript Agent SDK v0.3.280 ou posterior.1664Defina `inline_pastes` para informar ao Claude Code quais partes de `message.content` o usuário colou em vez de digitar, uma string por colagem. O texto do prompt permanece onde o usuário o colocou. O Claude Code pode envolver cada colagem listada em tags `<pasted_content>` no local em que ela está, para que o Claude consiga distinguir o material colado das palavras do próprio usuário. Apenas colagens no último bloco de texto do prompt são envolvidas. Requer o TypeScript Agent SDK v0.3.280 ou posterior.

1633 1665

1666Cada campo de colagem tem um limite de tamanho:

1667

1668* `pasted_content`: se as entradas mais os blocos de conteúdo dentro delas somarem mais de 1.000, o Claude Code ignora o campo inteiro.

1669* `inline_pastes`: o Claude Code usa as primeiras 100 entradas que não estão em branco e ignora o restante.

1670

1634Defina `shouldQuery`, `client_composed` ou `priority` para alterar como o Claude Code trata uma mensagem que você envia:1671Defina `shouldQuery`, `client_composed` ou `priority` para alterar como o Claude Code trata uma mensagem que você envia:

1635 1672

1636* `shouldQuery`: defina como `false` para anexar a mensagem à transcrição sem disparar um turno do assistente. A mensagem é mantida e mesclada na próxima mensagem do usuário que dispara um turno. Use isso para injetar contexto, como a saída de um comando que você executou fora de banda, sem gastar uma chamada de modelo.1673* `shouldQuery`: defina como `false` para anexar a mensagem à transcrição sem disparar um turno do assistente. A mensagem é mantida e mesclada na próxima mensagem do usuário que dispara um turno. Use isso para injetar contexto, como a saída de um comando que você executou fora de banda, sem gastar uma chamada de modelo.

1661* Uma chamada de WebFetch ou WebSearch que o Claude Code moveu para segundo plano para entregar uma mensagem `'now'`: a mensagem do usuário que carrega o `tool_result` dessa chamada tem `tool_use_result` definido como `{ detachedToolCall: true }`. A chamada ainda está em execução, e o Claude recebe seu resultado quando ela terminar. Nenhum segundo `tool_result` para esse `tool_use_id` virá a seguir; portanto, se sua aplicação desenha uma linha para cada chamada de ferramenta, marque essa linha como movida para segundo plano quando essa mensagem chegar. Requer o Claude Code v2.1.287 ou posterior.1698* Uma chamada de WebFetch ou WebSearch que o Claude Code moveu para segundo plano para entregar uma mensagem `'now'`: a mensagem do usuário que carrega o `tool_result` dessa chamada tem `tool_use_result` definido como `{ detachedToolCall: true }`. A chamada ainda está em execução, e o Claude recebe seu resultado quando ela terminar. Nenhum segundo `tool_result` para esse `tool_use_id` virá a seguir; portanto, se sua aplicação desenha uma linha para cada chamada de ferramenta, marque essa linha como movida para segundo plano quando essa mensagem chegar. Requer o Claude Code v2.1.287 ou posterior.

1662* Uma ferramenta MCP cujo resultado contém blocos `resource_link`: `tool_use_result` é um objeto com um array `resourceLinks` de entradas [`SDKMcpResourceLink`](#sdkmcpresourcelink). O Claude recebe cada link como uma linha de texto no bloco `tool_result`, então leia `resourceLinks` para renderizar os arquivos que o servidor retornou em vez de analisar esse texto. O Claude Code omite `resourceLinks` quando o resultado não tem links e em resultados de subagentes, mantém no máximo 50 links por resultado e para de adicionar links quando o array atinge 64 KiB de JSON serializado. `resourceLinks` requer o Agent SDK v0.3.257 ou posterior.1699* Uma ferramenta MCP cujo resultado contém blocos `resource_link`: `tool_use_result` é um objeto com um array `resourceLinks` de entradas [`SDKMcpResourceLink`](#sdkmcpresourcelink). O Claude recebe cada link como uma linha de texto no bloco `tool_result`, então leia `resourceLinks` para renderizar os arquivos que o servidor retornou em vez de analisar esse texto. O Claude Code omite `resourceLinks` quando o resultado não tem links e em resultados de subagentes, mantém no máximo 50 links por resultado e para de adicionar links quando o array atinge 64 KiB de JSON serializado. `resourceLinks` requer o Agent SDK v0.3.257 ou posterior.

1663* Uma ferramenta MCP que retorna [`structuredContent`](#calltoolresult): `tool_use_result` é um objeto cujo membro `structuredContent` contém o que o servidor enviou e cujo membro `content` contém o valor [`McpOutput`](#mcpoutput). Resultados de subagentes não carregam `structuredContent`.1700* Uma ferramenta MCP que retorna [`structuredContent`](#calltoolresult): `tool_use_result` é um objeto cujo membro `structuredContent` contém o que o servidor enviou e cujo membro `content` contém o valor [`McpOutput`](#mcpoutput). Resultados de subagentes não carregam `structuredContent`.

1664* Uma ferramenta MCP cujo `structuredContent` serializa para mais de 1.048.576 caracteres de JSON: o Claude Code deixa `structuredContent` fora de `tool_use_result` e define `structuredContentOmitted: true` em seu lugar, para que sua aplicação consiga distinguir um objeto descartado de uma ferramenta que não enviou nenhum. Os outros membros, como `content` e `resourceLinks`, permanecem, e o que o Claude recebe não muda. Ferramentas de [servidores SDK em processo](/docs/pt/agent-sdk/custom-tools) e ferramentas cuja entrada em `tools/list` declara um [recurso `_meta.ui` do MCP Apps](#mcpserverstatus) estão isentas e entregam o objeto inteiro. O Claude Code v2.1.287 ou posterior aplica esse limite.1701* Uma ferramenta MCP cujo `structuredContent` serializa para mais de 1.048.576 caracteres de JSON: o Claude Code deixa `structuredContent` fora de `tool_use_result` e define `structuredContentOmitted: true` no lugar dele, para que seu aplicativo possa distinguir um objeto descartado de uma ferramenta que não enviou nenhum. Os outros membros, como `content` e `resourceLinks`, permanecem, e o que Claude recebe não muda. O Claude Code v2.1.287 ou posterior aplica esse limite. Dois tipos de ferramenta diferem:

1702 * Ferramentas de [servidores SDK em processo](/docs/pt/agent-sdk/custom-tools) estão isentas e entregam o objeto inteiro.

1703 * Uma ferramenta cuja entrada `tools/list` declara um [recurso `ui://` do MCP Apps](#mcpserverstatus) tem um limite de 8.388.608 caracteres no Claude Code v2.1.295 ou posterior, e versões anteriores à v2.1.295 a isentam.

1665 1704

1666<h3 id="sdkusermessagereplay">1705<h3 id="sdkusermessagereplay">

1667 `SDKUserMessageReplay`1706 `SDKUserMessageReplay`

1775* `ttft_stream_ms`: tempo em milissegundos até o primeiro evento de stream `message_start`, quando o stream de resposta abre. Menor que `ttft_ms`; a diferença entre os dois é o tempo gasto transmitindo a primeira mensagem. Presente apenas no braço de sucesso.1814* `ttft_stream_ms`: tempo em milissegundos até o primeiro evento de stream `message_start`, quando o stream de resposta abre. Menor que `ttft_ms`; a diferença entre os dois é o tempo gasto transmitindo a primeira mensagem. Presente apenas no braço de sucesso.

1776* `user_message_uuid`: o `uuid` da mensagem que você enviou que este turno respondeu. Consulte [`user_message_uuid`](#user_message_uuid) para saber quais resultados o carregam.1815* `user_message_uuid`: o `uuid` da mensagem que você enviou que este turno respondeu. Consulte [`user_message_uuid`](#user_message_uuid) para saber quais resultados o carregam.

1777* `user_message_uuids`: os `uuid`s de cada mensagem que você enviou que Claude Code respondeu neste turno. Consulte [`user_message_uuids`](#user_message_uuids).1816* `user_message_uuids`: os `uuid`s de cada mensagem que você enviou que Claude Code respondeu neste turno. Consulte [`user_message_uuids`](#user_message_uuids).

1778* `resume_reason`: por que o Claude Code executou novamente este turno depois que uma reinicialização o interrompeu. Presente em ambos os ramos. Consulte [`resume_reason`](#resume_reason).1817* `resume_reason`: por que este turno continua um que uma reinicialização interrompeu. Presente em ambos os ramos. Consulte [`resume_reason`](#resume_reason).

1779* `local_command`: o nome do comando que o turno despachou, no resultado de sucesso de um turno que um comando completou sem entrar no loop do agente, como `/compact`. O nome é convertido para letras minúsculas e underscores, portanto `/reload-plugins` relata `reload_plugins`. Um comando que um servidor MCP fornece, e o `/mcp` integrado, relatam `mcp`. Um comando que você mesmo definiu relata `custom`. Os argumentos nunca são incluídos. Ausente em cada turno que entrou no loop do agente e em envios que não executaram nenhum comando. Requer Agent SDK v0.3.268 ou posterior.1818* `local_command`: o nome do comando que o turno despachou, no resultado de sucesso de um turno que um comando completou sem entrar no loop do agente, como `/compact`. O nome é convertido para letras minúsculas e underscores, portanto `/reload-plugins` relata `reload_plugins`. Um comando que um servidor MCP fornece, e o `/mcp` integrado, relatam `mcp`. Um comando que você mesmo definiu relata `custom`. Os argumentos nunca são incluídos. Ausente em cada turno que entrou no loop do agente e em envios que não executaram nenhum comando. Requer Agent SDK v0.3.268 ou posterior.

1780* `request_sent_wall_ms`: milissegundos de época em que Claude Code despachou a requisição de API, para junções com timestamps do lado do servidor. Presente apenas junto com [`user_message_uuid`](#user_message_uuid), em um resultado de sucesso com `is_error` false cujo turno enviou uma requisição de API.1819* `request_sent_wall_ms`: milissegundos de época em que Claude Code despachou a requisição de API, para junções com timestamps do lado do servidor. Presente apenas junto com [`user_message_uuid`](#user_message_uuid), em um resultado de sucesso com `is_error` false cujo turno enviou uma requisição de API.

1781* `first_content_frame_ms`: tempo em milissegundos até o primeiro evento de stream `content_block_start` ou `content_block_delta`, contando blocos de pensamento como conteúdo. Presente apenas no braço de sucesso, quando `is_error` é false. Requer Agent SDK v0.3.260 ou posterior.1820* `first_content_frame_ms`: tempo em milissegundos até o primeiro evento de stream `content_block_start` ou `content_block_delta`, contando blocos de pensamento como conteúdo. Presente apenas no braço de sucesso, quando `is_error` é false. Requer Agent SDK v0.3.260 ou posterior.

1825 1864

1826* **Uma mensagem regular que você enviou**, ou seja, uma sem `isSynthetic: true`: o turno responde a essa mensagem durante toda a sua execução. Quando você envia várias mensagens próximas, Claude Code pode mesclá-las em um turno, e o campo então carrega apenas o `uuid` da última mensagem. Para corresponder a resposta a qualquer uma das mensagens mescladas, use [`user_message_uuids`](#user_message_uuids).1865* **Uma mensagem regular que você enviou**, ou seja, uma sem `isSynthetic: true`: o turno responde a essa mensagem durante toda a sua execução. Quando você envia várias mensagens próximas, Claude Code pode mesclá-las em um turno, e o campo então carrega apenas o `uuid` da última mensagem. Para corresponder a resposta a qualquer uma das mensagens mescladas, use [`user_message_uuids`](#user_message_uuids).

1827* **Uma mensagem que você enviou com `isSynthetic: true`**: o turno responde a essa mensagem no início. Se Claude Code captar uma mensagem regular sua entre chamadas de ferramenta, o turno responde à mensagem captada a partir de então. Ecoar o `uuid` de uma mensagem sintética requer Agent SDK v0.3.265 ou posterior; versões anteriores não ecoam nada em turnos sintéticos.1866* **Uma mensagem que você enviou com `isSynthetic: true`**: o turno responde a essa mensagem no início. Se Claude Code captar uma mensagem regular sua entre chamadas de ferramenta, o turno responde à mensagem captada a partir de então. Ecoar o `uuid` de uma mensagem sintética requer Agent SDK v0.3.265 ou posterior; versões anteriores não ecoam nada em turnos sintéticos.

1828* **O prompt que Claude Code gera para re-executar um turno interrompido sob [`CLAUDE_CODE_RESUME_INTERRUPTED_TURN`](/docs/pt/env-vars)**: quando o último prompt do turno interrompido é uma mensagem regular que você enviou, independentemente de ela ter aberto o turno ou de Claude Code tê-la captado durante o turno, a re-execução responde a essa mensagem no início. [`resume_reason`](#resume_reason) distingue os quadros da re-execução dos da tentativa interrompida. Quando o último prompt não é uma mensagem regular sua, a re-execução não responde a nenhuma mensagem sua no início. Se Claude Code captar uma mensagem regular sua entre chamadas de ferramenta, o turno responde à mensagem captada a partir de então. Ecoar o prompt do turno interrompido requer Agent SDK v0.3.268 ou posterior.1867* **O prompt que o Claude Code gera para continuar um turno interrompido sob [`CLAUDE_CODE_RESUME_INTERRUPTED_TURN`](/docs/pt/env-vars)**: quando o último prompt do turno interrompido é uma mensagem regular que você enviou, seja ela a que abriu o turno ou uma que o Claude Code captou durante o turno, o turno continuado responde a essa mensagem inicialmente. [`resume_reason`](#resume_reason) distingue os frames do turno continuado dos da tentativa interrompida. Quando o último prompt não é uma mensagem regular sua, o turno continuado inicialmente não responde a nenhuma mensagem sua. Se o Claude Code captar uma mensagem regular sua entre chamadas de ferramenta, o turno passa a responder à mensagem captada a partir de então. Ecoar o prompt do turno interrompido requer o Agent SDK v0.3.268 ou posterior.

1829* **Qualquer outro prompt que Claude Code gerou por conta própria**: o turno não responde a nenhuma mensagem sua no início e seus quadros não carregam nenhum eco. Se Claude Code captar uma mensagem regular sua entre chamadas de ferramenta, o turno responde a essa mensagem a partir de então. O eco de captação requer Agent SDK v0.3.265 ou posterior; versões anteriores não ecoam nada nesses turnos.1868* **Qualquer outro prompt que Claude Code gerou por conta própria**: o turno não responde a nenhuma mensagem sua no início e seus quadros não carregam nenhum eco. Se Claude Code captar uma mensagem regular sua entre chamadas de ferramenta, o turno responde a essa mensagem a partir de então. O eco de captação requer Agent SDK v0.3.265 ou posterior; versões anteriores não ecoam nada nesses turnos.

1830 1869

1831Claude Code ecoa o `uuid` da mensagem respondida em três tipos de quadro:1870Claude Code ecoa o `uuid` da mensagem respondida em três tipos de quadro:

1857 `resume_reason`1896 `resume_reason`

1858</h4>1897</h4>

1859 1898

1860Por que Claude Code re-executou este turno após uma reinicialização. Claude Code define este campo em um turno que re-executou sob [`CLAUDE_CODE_RESUME_INTERRUPTED_TURN`](/docs/pt/env-vars), para que você possa distinguir a resposta e o resultado da re-execução dos da tentativa interrompida. Requer Agent SDK v0.3.268 ou posterior.1899Por que este turno continua um que uma reinicialização interrompeu. O Claude Code define este campo em um turno que continua um turno interrompido sob [`CLAUDE_CODE_RESUME_INTERRUPTED_TURN`](/docs/pt/env-vars), para que você possa distinguir a resposta e o resultado do turno continuado dos da tentativa interrompida. Requer o Agent SDK v0.3.268 ou posterior.

1861 1900

1862Claude Code define o campo em dois tipos de quadro:1901Claude Code define o campo em dois tipos de quadro:

1863 1902

1864* **O resultado da re-execução**: tanto no braço de sucesso quanto no de erro, independentemente de o resultado carregar `user_message_uuid`.1903* **O resultado do turno continuado**: tanto no ramo de sucesso quanto no de erro, quer o resultado carregue ou não `user_message_uuid`.

1865* **Os quadros de resposta da re-execução**: aqueles que carregam [`user_message_uuid`](#user_message_uuid).1904* **Os frames de resposta do turno continuado**: aqueles que carregam [`user_message_uuid`](#user_message_uuid).

1866 1905

1867O valor é um token curto em minúsculas que nomeia por que o turno foi executado novamente, como `interrupted_turn`.1906O valor é um token curto em minúsculas, como `interrupted_turn`.

1868 1907

1869<h4 id="queued_turn_count">1908<h4 id="queued_turn_count">

1870 `queued_turn_count`1909 `queued_turn_count`

2029};2068};

2030```2069```

2031 2070

2032Claude Code define `user_message_uuid` e `user_message_uuids` no primeiro evento de stream não-ping do turno, e novamente quando a mensagem que o turno está respondendo muda, sob as condições em [`user_message_uuid`](#user_message_uuid). Quando Claude Code re-executa um turno que uma reinicialização interrompeu, os eventos de stream da re-execução que carregam esses campos também carregam [`resume_reason`](#resume_reason).2071O Claude Code define `user_message_uuid` e `user_message_uuids` no primeiro evento de stream do turno que não seja ping, e novamente quando a mensagem que o turno está respondendo muda, nas condições descritas em [`user_message_uuid`](#user_message_uuid). Quando o turno continua um que uma reinicialização interrompeu, os eventos de stream que carregam esses campos também carregam [`resume_reason`](#resume_reason).

2033 2072

2034<h3 id="sdkcompactboundarymessage">2073<h3 id="sdkcompactboundarymessage">

2035 `SDKCompactBoundaryMessage`2074 `SDKCompactBoundaryMessage`

3560| - | - | - |3599| - | - | - |

3561| `script` | `string` | Script de workflow inline. Deve começar com `export const meta = { name, description }` como um literal, seguido pelo corpo do script usando `agent()`, `parallel()`, `pipeline()` e `phase()`. Um array `phases` opcional em `meta` agrupa agentes sob estágios nomeados na visualização de progresso |3600| `script` | `string` | Script de workflow inline. Deve começar com `export const meta = { name, description }` como um literal, seguido pelo corpo do script usando `agent()`, `parallel()`, `pipeline()` e `phase()`. Um array `phases` opcional em `meta` agrupa agentes sob estágios nomeados na visualização de progresso |

3563| `scriptPath` | `string` | Caminho para um arquivo de script de workflow no disco. Tem precedência sobre `script` e `name`. Claude Code persiste cada invocação do script e retorna o caminho no resultado, para que você possa editar esse arquivo e reinvocar com o mesmo `scriptPath` para iterar |3602| `scriptPath` | `string` | Caminho para um arquivo de script de workflow no disco, como o `scriptPath` que uma execução anterior retornou. Tem precedência sobre `script` e `name`. Claude Code rejeita `scriptPath` com um erro quando as ferramentas da sessão não incluem `Read` |

3564| `args` | `unknown` | Valor de entrada exposto ao script como o `args` global, para workflows nomeados parametrizados, como uma pergunta de pesquisa ou uma lista de caminhos de arquivo. Passe arrays e objetos como valores JSON reais, não como uma string codificada em JSON |3603| `args` | `unknown` | Valor de entrada exposto ao script como o `args` global, para workflows nomeados parametrizados, como uma pergunta de pesquisa ou uma lista de caminhos de arquivo. Passe arrays e objetos como valores JSON reais, não como uma string codificada em JSON |

3565| `resumeFromRunId` | `string` | ID de execução de uma invocação anterior de `Workflow` para retomar. Chamadas `agent()` concluídas com entradas inalteradas geralmente retornam resultados em cache; o resto é executado ao vivo. [Retomar após uma pausa](/docs/pt/workflows#resume-after-a-pause) cobre quais chamadas concluídas são re-executadas. Apenas a mesma sessão |3604| `resumeFromRunId` | `string` | ID de execução de uma invocação anterior de `Workflow` para retomar. Chamadas `agent()` concluídas com entradas inalteradas geralmente retornam resultados em cache; o resto é executado ao vivo. [Retomar após uma pausa](/docs/pt/workflows#resume-after-a-pause) cobre quais chamadas concluídas são re-executadas. Apenas a mesma sessão |

agent-view.md +18 −14

Details

152| Forma | O que significa |152| Forma | O que significa |

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

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

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

157 157

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

256 256

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

258 258

259Uma sessão anexada não [informa seu status ao seu terminal](/docs/pt/terminal-config#see-session-status-in-your-terminal).

260

259Pressione `←` em um prompt vazio, ou execute `/exit`, para desanexar e retornar a agent view, independentemente de você ter aberto a sessão a partir de agent view ou com `claude attach <id>` a partir do seu shell.261Pressione `←` em um prompt vazio, ou execute `/exit`, para desanexar e retornar a agent view, independentemente de você ter aberto a sessão a partir de agent view ou com `claude attach <id>` a partir do seu shell.

260 262

261`←` também desanexa enquanto o [overlay `/btw`](/docs/pt/interactive-mode#side-questions-with-%2Fbtw) está aberto. Requer Claude Code v2.1.257 ou posterior. Uma pergunta lateral que ainda está respondendo continua em execução enquanto você está ausente. Na próxima vez que você anexar, o overlay reabre com ela, ou com sua resposta.263`←` também desanexa enquanto o [overlay `/btw`](/docs/pt/interactive-mode#side-questions-with-%2Fbtw) está aberto. Requer Claude Code v2.1.257 ou posterior. Uma pergunta lateral que ainda está respondendo continua em execução enquanto você está ausente. Na próxima vez que você anexar, o overlay reabre com ela, ou com sua resposta.

264 266

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

266 268

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

268 270

269Desanexar nunca interrompe uma sessão em background: `←`, `Ctrl+Z`, `/exit` e duplo `Ctrl+C` ou duplo `Ctrl+D` a deixam em execução. Para encerrar uma sessão de dentro dela, execute `/stop`.271Desanexar nunca interrompe uma sessão em background: `←`, `Ctrl+Z`, `/exit` e duplo `Ctrl+C` ou duplo `Ctrl+D` a deixam em execução. Se você desanexar enquanto um `/loop` está aguardando sua próxima iteração, o loop continua em execução e essa iteração começa no horário programado sem você. Para interromper o loop antes de desanexar, veja [Interromper um loop](/docs/pt/scheduled-tasks#stop-a-loop). Para encerrar uma sessão de dentro dela, execute `/stop`.

270 272

271<h4 id="switch-sessions-without-leaving-the-terminal">273<h4 id="switch-sessions-without-leaving-the-terminal">

272 Alternar sessões sem sair do terminal274 Alternar sessões sem sair do terminal

293Após cerca de dez segundos, Claude Code coloca a sessão em background sem aguardar mais, exceto em casos como estes:295Após cerca de dez segundos, Claude Code coloca a sessão em background sem aguardar mais, exceto em casos como estes:

294 296

295* **Subagentes em primeiro plano ainda estão em execução**: Claude Code continua aguardando para que o trabalho dos [subagentes em primeiro plano](/docs/pt/sub-agents#run-subagents-in-foreground-or-background) que Claude iniciou seja transferido, e mostra `Still backgrounding after the current tool`. Pressione `←` novamente para colocar em background sem aguardar, o que reinicia esses subagentes do início.297* **Subagentes em primeiro plano ainda estão em execução**: Claude Code continua aguardando para que o trabalho dos [subagentes em primeiro plano](/docs/pt/sub-agents#run-subagents-in-foreground-or-background) que Claude iniciou seja transferido, e mostra `Still backgrounding after the current tool`. Pressione `←` novamente para colocar em background sem aguardar, o que reinicia esses subagentes do início.

296* **Um prompt de permissão ou uma pergunta está aguardando sua resposta**: enquanto um prompt de permissão ou uma pergunta que Claude fez aguarda, Claude Code continua aguardando e mostra `Still backgrounding after the current tool — a question is waiting for your answer.`298* **Um prompt de permissão ou uma pergunta está aguardando sua resposta**: enquanto um prompt de permissão ou uma pergunta que Claude fez aguarda, Claude Code continua aguardando e mostra `Still backgrounding after the current tool — a question is waiting for your answer.` Se sua resposta permitir que o turno continue, como **Yes** em um prompt de permissão, Claude Code coloca a sessão em background quando a ferramenta atual terminar.

297* **Você digita na entrada do prompt**: Claude Code cancela a alternância, porque o texto não enviado fica na caixa de entrada do seu terminal e não se moveria para a sessão em background. Ele mostra `Backgrounding cancelled — you have unsent text in the input. Send it or clear it, then press ← again.`299* **Você digita na entrada do prompt**: Claude Code cancela a alternância, porque o texto não enviado fica na caixa de entrada do seu terminal e não se moveria para a sessão em background. Ele mostra `Backgrounding cancelled — you have unsent text in the input. Send it or clear it, then press ← again.`

300* **Você interrompe o turno**: Claude Code cancela a alternância e mostra `Backgrounding cancelled — the turn was stopped.` Por exemplo, o turno é interrompido quando você [interrompe Claude com `Esc`](/docs/pt/interactive-mode#general-controls) ou seleciona **No** [sem um comentário](/docs/pt/permissions#add-a-comment-when-you-answer-a-permission-prompt) em um prompt de permissão da conversa principal, ou pressiona `Esc` em uma pergunta que Claude faz ali. Pressione `←` novamente para colocar a sessão em background.

298* **Uma mensagem enfileirada não pode ser movida**: as mensagens que você [enfileirou enquanto Claude estava trabalhando](/docs/pt/interactive-mode#queue-messages-while-claude-works) se movem para a sessão em background com a conversa. Quando uma delas não pode ser movida, a sessão permanece em primeiro plano e Claude Code mostra um aviso como `Cannot open agents — 1 queued message can't move to the background. Press ← again once Claude has read it.`301* **Uma mensagem enfileirada não pode ser movida**: as mensagens que você [enfileirou enquanto Claude estava trabalhando](/docs/pt/interactive-mode#queue-messages-while-claude-works) se movem para a sessão em background com a conversa. Quando uma delas não pode ser movida, a sessão permanece em primeiro plano e Claude Code mostra um aviso como `Cannot open agents — 1 queued message can't move to the background. Press ← again once Claude has read it.`

299 302

300Pressionar `←` cria a linha da sessão mesmo quando a conversa não tem mensagens ainda, então `→` ainda retorna a ela.303Pressionar `←` cria a linha da sessão mesmo quando a conversa não tem mensagens ainda, então `→` ainda retorna a ela.

513* `--fallback-model`516* `--fallback-model`

514* `--allow-dangerously-skip-permissions`517* `--allow-dangerously-skip-permissions`

515 518

516Os diretórios que você adicionou durante a sessão com [`/add-dir`](/docs/pt/permissions#additional-directories-grant-file-access-not-configuration) também são transferidos. Transferir `--allow-dangerously-skip-permissions` mantém `bypassPermissions` acessível na sessão em segundo plano, mas não concede nada novo: o modo ainda requer a aceitação interativa única descrita em [Modo de permissão, modelo e esforço](#permission-mode-model-and-effort).519Os diretórios que você adicionou durante a sessão com [`/add-dir`](/docs/pt/permissions#additional-directories-grant-file-access-not-configuration) também são transferidos. Transferir `--allow-dangerously-skip-permissions` mantém `bypassPermissions` acessível na sessão em segundo plano, mas não concede nada novo: o modo ainda requer sua [aceitação do aviso de bypass](/docs/pt/permission-modes#skip-all-checks-with-bypasspermissions-mode) registrada.

517 520

518<span id="from-your-shell" />521<span id="from-your-shell" />

519 522

767 770

768Os padrões ativos aparecem no rodapé abaixo da entrada de despacho.771Os padrões ativos aparecem no rodapé abaixo da entrada de despacho.

769 772

770Claude Code recusa `claude --bg --permission-mode bypassPermissions` até que você tenha aceitado o aviso de bypass executando `claude --dangerously-skip-permissions` uma vez interativamente, já que esse modo permite que uma sessão que você não está observando aja sem aprovação. Passar `--dangerously-skip-permissions` ou `--permission-mode bypassPermissions` para `claude agents` mostra o mesmo aviso quando você não o aceitou antes, e aceitar aplica `bypassPermissions` às sessões que você inicia a partir da visualização. Passar `--allow-dangerously-skip-permissions` mostra o mesmo aviso também, e aceitar torna `bypassPermissions` disponível no ciclo `Shift+Tab` dessas sessões sem iniciá-las nele.773Uma sessão em segundo plano iniciada no modo `bypassPermissions` requer sua [aceitação do aviso de bypass](/docs/pt/permission-modes#skip-all-checks-with-bypasspermissions-mode) registrada, já que esse modo permite que uma sessão que você não está observando aja sem aprovação. Passar `--dangerously-skip-permissions` ou `--permission-mode bypassPermissions` para `claude agents` mostra o mesmo aviso quando você não o aceitou antes, e aceitar aplica `bypassPermissions` às sessões que você inicia a partir da visualização. Passar `--allow-dangerously-skip-permissions` mostra o mesmo aviso também, e aceitar torna `bypassPermissions` disponível no ciclo `Shift+Tab` dessas sessões sem iniciá-las nele.

771 774

772<h4 id="what-persists-across-restarts">775<h4 id="what-persists-across-restarts">

773 O que persiste entre reinicializações776 O que persiste entre reinicializações

774</h4>777</h4>

775 778

776O modo de permissão, modelo e esforço que você escolheu para uma sessão em segundo plano, junto com as [flags de configuração que ela carrega](#what-carries-over-when-you-background), tudo persiste quando o supervisor mais tarde [para e reinicia](#the-supervisor-process) seu processo. Uma sessão que você iniciou com `claude --bg --dangerously-skip-permissions` ou `claude --bg --permission-mode bypassPermissions` permanece em `bypassPermissions` após essa reinicialização. Um modelo ou esforço que você mudou no meio da sessão com `/model` ou `/effort` também é mantido.779O modo de permissão, modelo e esforço que você escolheu para uma sessão em segundo plano, junto com as [flags de configuração que ela carrega](#what-carries-over-when-you-background), tudo persiste quando o supervisor mais tarde [para e reinicia](#the-supervisor-process) seu processo. Um modelo ou esforço que você mudou no meio da sessão com `/model` ou `/effort` também é mantido.

777 780

778Se a sessão tomou seu esforço de suas configurações em vez de `--effort` ou `/effort`, Claude Code lê suas configurações novamente cada vez que inicia um processo para a sessão. Depois que você edita o esforço salvo em `settings.json`, a mudança alcança sessões que você coloca em segundo plano com `←` ou `/bg`, e suas reinicializações posteriores. O esforço salvo é a chave [`effortLevel`](/docs/pt/settings-reference#effortlevel) ou uma entrada [`modelSettings`](/docs/pt/settings-reference#modelsettings).781Se a sessão tomou seu esforço de suas configurações em vez de `--effort` ou `/effort`, Claude Code lê suas configurações novamente cada vez que inicia um processo para a sessão. Depois que você edita o esforço salvo em `settings.json`, a mudança alcança sessões que você coloca em segundo plano com `←` ou `/bg`, e suas reinicializações posteriores. O esforço salvo é a chave [`effortLevel`](/docs/pt/settings-reference#effortlevel) ou uma entrada [`modelSettings`](/docs/pt/settings-reference#modelsettings).

779 782

825| `claude respawn <id>` | Reiniciar uma sessão, em execução ou interrompida, por exemplo, para usar um binário Claude Code atualizado. A sessão reiniciada retoma sua conversa salva; quando nenhuma está no disco, ela executa seu prompt original novamente como uma nova conversa |828| `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 |

826| `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 |829| `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 |

827| `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` |830| `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` |

828| `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 |831| `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 |

829| `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 |832| `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 |

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

831| `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` |834| `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` |

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

833 836

834`claude attach` e `claude logs` podem receber parte do nome de uma sessão no lugar do ID, como em `claude logs "auth refactor"`. Passar um nome requer Claude Code v2.1.290 ou posterior.837`claude attach` e `claude logs` podem receber parte do nome de uma sessão no lugar do ID, como em `claude logs "auth refactor"`. `claude attach` abre uma sessão pelo nome apenas enquanto seu processo está em execução, então passe o ID para reiniciar uma sessão interrompida. Passar um nome requer Claude Code v2.1.290 ou posterior.

835 838

836<h3 id="list-sessions-as-json">839<h3 id="list-sessions-as-json">

837 Listar sessões como JSON840 Listar sessões como JSON

889* **Terminado ou aguardando sua próxima mensagem, e desanexado por cerca de uma hora**: o supervisor interrompe o processo para liberar recursos. Uma sessão que terminou seu turno fazendo uma pergunta a você conta como aguardando sua próxima mensagem. A conversa fica no disco, e na próxima vez que você anexar ou responder, a sessão retoma de onde parou. Fixe uma sessão com `Ctrl+T` para manter seu processo em execução.892* **Terminado ou aguardando sua próxima mensagem, e desanexado por cerca de uma hora**: o supervisor interrompe o processo para liberar recursos. Uma sessão que terminou seu turno fazendo uma pergunta a você conta como aguardando sua próxima mensagem. A conversa fica no disco, e na próxima vez que você anexar ou responder, a sessão retoma de onde parou. Fixe uma sessão com `Ctrl+T` para manter seu processo em execução.

890* **Saiu inesperadamente enquanto o supervisor está em execução**: o supervisor reinicia o processo. Terminar uma sessão que você colocou em background com `←` ou `/background`, por exemplo com `kill`, marca-a como parada em vez de reiniciá-la. Para sessões que terminaram com um desligamento, consulte [Sessões aparecem como falhadas ou paradas após desligamento](#sessions-show-as-failed-after-shutdown).893* **Saiu inesperadamente enquanto o supervisor está em execução**: o supervisor reinicia o processo. Terminar uma sessão que você colocou em background com `←` ou `/background`, por exemplo com `kill`, marca-a como parada em vez de reiniciá-la. Para sessões que terminaram com um desligamento, consulte [Sessões aparecem como falhadas ou paradas após desligamento](#sessions-show-as-failed-after-shutdown).

891* **Após uma atualização automática**: o supervisor reinicia a si mesmo para a nova versão e move sessões inativas em background. Sessões que estão funcionando, aguardando você ou anexadas não são interrompidas.894* **Após uma atualização automática**: o supervisor reinicia a si mesmo para a nova versão e move sessões inativas em background. Sessões que estão funcionando, aguardando você ou anexadas não são interrompidas.

895* **O próprio supervisor para**, por exemplo porque seu processo foi encerrado de fora do Claude Code: no macOS e no Linux, o processo de cada sessão aguarda cerca de um minuto para que um novo supervisor se reconecte a ele, e para se nenhum o fizer. Execute `claude agents` no seu shell dentro desse minuto para iniciar um novo supervisor e manter suas sessões em execução. Se o minuto passar antes, as sessões param, mas suas conversas salvas permanecem no disco: anexe-se a uma sessão ou responda a ela e ela reinicia a partir de sua conversa salva, conforme descrito em [Sessões aparecem como falhadas ou paradas após desligamento](#sessions-show-as-failed-after-shutdown).

892 896

893Quando o processo de uma sessão para ou reinicia, os comandos de shell em background, fluxos de trabalho dinâmicos e subagentes em background que Claude iniciou nela são transferidos para seu próximo processo; monitors em execução e comandos de shell que um subagente iniciou param com o processo. Deletar a sessão para tudo que ela transferiu. Para parar tudo com o processo em vez disso, defina [`CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF`](/docs/pt/env-vars#variables) como `1`.897Quando o processo de uma sessão para ou reinicia, os comandos de shell em background, fluxos de trabalho dinâmicos e subagentes em background que Claude iniciou nela são transferidos para seu próximo processo; monitors em execução e comandos de shell que um subagente iniciou param com o processo. Deletar a sessão para tudo que ela transferiu. Para parar tudo com o processo em vez disso, defina [`CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF`](/docs/pt/env-vars#variables) como `1`.

894 898

911 915

912Para inspecionar este estado sem ler os arquivos diretamente, execute `claude daemon status`. Ele relata se o supervisor está acessível, seu ID de processo e versão, o diretório do socket e quantas sessões em background estão ativas.916Para inspecionar este estado sem ler os arquivos diretamente, execute `claude daemon status`. Ele relata se o supervisor está acessível, seu ID de processo e versão, o diretório do socket e quantas sessões em background estão ativas.

913 917

914O comando também avisa quando o supervisor em execução está em uma versão diferente do `claude` que você invocou, o que acontece após uma atualização que o supervisor ainda não reiniciou. O aviso mostra ambas as versões e diz para você executar `claude daemon stop --any` para pegar a nova versão. Quando Claude Code é instalado como um serviço do SO, o comando sugerido é `claude daemon stop` sem a flag.918O comando também avisa quando o supervisor em execução está em uma versão diferente do `claude` que você invocou, o que acontece após uma atualização que o supervisor ainda não reiniciou. O aviso mostra ambas as versões e diz para você executar `claude daemon stop --any` para pegar a nova versão.

915 919

916Sessões sobrevivem a esse desajuste de versão intactas: uma versão mais antiga do Claude Code que atualiza o `state.json` de uma sessão preserva campos que não reconhece e mantém a sessão listada. A lista de sessões em `roster.json` segue a mesma regra, então sessões iniciadas pela versão mais nova permanecem acessíveis e continuam aceitando entrada após o supervisor reiniciar.920Sessões sobrevivem a esse desajuste de versão intactas: uma versão mais antiga do Claude Code que atualiza o `state.json` de uma sessão preserva campos que não reconhece e mantém a sessão listada. A lista de sessões em `roster.json` segue a mesma regra, então sessões iniciadas pela versão mais nova permanecem acessíveis e continuam aceitando entrada após o supervisor reiniciar.

917 921

963 967

964Desligar ou reiniciar sua máquina interrompe as sessões em execução em background. Uma sessão que estava aguardando sua entrada permanece sob `Needs input` quando você volta. Para qualquer outra sessão em execução, o que agent view mostra depende de quanto tempo atrás ela fez progresso pela última vez:968Desligar ou reiniciar sua máquina interrompe as sessões em execução em background. Uma sessão que estava aguardando sua entrada permanece sob `Needs input` quando você volta. Para qualquer outra sessão em execução, o que agent view mostra depende de quanto tempo atrás ela fez progresso pela última vez:

965 969

966* Dentro de 48 horas, a sessão mostra como falhada. Anexe ou responda a ela e ela reinicia de onde parou.970* Dentro de 48 horas, a sessão mostra como falhada. Anexe ou responda a ela e ela reinicia a partir de sua conversa salva. Para retomar o trabalho interrompido, envie a ela uma resposta pedindo que continue.

967* Passadas 48 horas, como após a máquina estar desligada por dias, a sessão mostra como parada com `ended while the background service was off`. 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 delete 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é.971* Passadas 48 horas, como após a máquina estar desligada por dias, a sessão mostra como parada com `ended while the background service was off`. 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 delete 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é.

968 972

969Quando [transcript cleanup](/docs/pt/settings-reference#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](/docs/pt/errors#this-sessions-saved-conversation-is-no-longer-on-disk).973Quando [transcript cleanup](/docs/pt/settings-reference#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](/docs/pt/errors#this-sessions-saved-conversation-is-no-longer-on-disk).

1022claude daemon stop --any --keep-workers1026claude daemon stop --any --keep-workers

1023```1027```

1024 1028

1025O novo supervisor se reconecta às sessões em execução. Sem `--keep-workers`, o comando também encerra as sessões em background. A flag `--any` confirma que você deseja interromper um supervisor que foi iniciado sob demanda em vez de como um serviço instalado, que é o padrão.1029Depois execute `claude agents` no seu shell para iniciar o novo supervisor. Se você fizer isso dentro de [cerca de um minuto](#the-supervisor-process) após a parada, ele se reconecta às sessões ainda em execução, e o trabalho delas continua sem interrupção. Se você demorar mais, no macOS e no Linux as sessões já terão parado por conta própria, e anexar ou responder a uma delas a reinicia a partir de sua conversa salva. Sem `--keep-workers`, o comando também encerra as sessões em background. A flag `--any` faz o comando interromper um supervisor que Claude Code iniciou sob demanda.

1026 1030

1027Um supervisor que inicia mas não consegue aceitar conexões sai e libera seu bloqueio por conta própria, portanto o próximo `claude agents` inicia um novo sem essa parada manual. Os passos acima se aplicam quando um supervisor em execução trava.1031Um supervisor que inicia mas não consegue aceitar conexões sai e libera seu bloqueio por conta própria, portanto o próximo `claude agents` inicia um novo sem essa parada manual. Os passos acima se aplicam quando um supervisor em execução trava.

1028 1032

1040claude daemon stop --any --keep-workers1044claude daemon stop --any --keep-workers

1041```1045```

1042 1046

1043O próximo `claude agents` ou `claude --bg` inicia um novo supervisor que lê suas credenciais armazenadas. Se você autenticar com uma variável de ambiente como `ANTHROPIC_API_KEY` em vez de `/login`, execute esse próximo comando a partir de um shell onde a variável está definida.1047Dentro de [cerca de um minuto](#the-supervisor-process), execute `claude agents` ou `claude --bg` no seu shell para iniciar um novo supervisor que lê suas credenciais armazenadas. Se você autenticar com uma variável de ambiente como `ANTHROPIC_API_KEY` em vez de `/login`, execute esse próximo comando a partir de um shell onde a variável está definida.

1044 1048

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

1046 1050

analytics.md +1 −1

Details

67* **"GitHub app required"**: instale o aplicativo GitHub para visualizar métricas de contribuição67* **"GitHub app required"**: instale o aplicativo GitHub para visualizar métricas de contribuição

68* **"Data processing in progress"**: verifique novamente em alguns dias e confirme se o aplicativo GitHub está instalado se os dados não aparecerem68* **"Data processing in progress"**: verifique novamente em alguns dias e confirme se o aplicativo GitHub está instalado se os dados não aparecerem

69 69

~~70As métricas de contribuição suportam GitHub Cloud e GitHub Enterprise Server.~~70As métricas de contribuição cobrem repositórios hospedados em github.com. Para repositórios no [GitHub Enterprise Server](/docs/pt/github-enterprise-server), o painel de análise mostra apenas métricas de uso.

71 71

72<h3 id="review-summary-metrics">72<h3 id="review-summary-metrics">

73 Revisar métricas de resumo73 Revisar métricas de resumo

authentication.md +3 −3

Details

96 <Step title="Adicione usuários">96 <Step title="Adicione usuários">

97 Você pode adicionar usuários através de qualquer um dos métodos:97 Você pode adicionar usuários através de qualquer um dos métodos:

98 98

~~99 * Convide usuários em massa de dentro do Console: Settings -> Members -> Invite~~99 * Convide usuários em massa a partir da página Members do Console em [platform.claude.com/settings/members](https://platform.claude.com/settings/members): clique em **Invite**

100 * [Configure SSO](https://support.claude.com/en/articles/13132885-setting-up-single-sign-on-sso)100 * [Configure SSO](https://support.claude.com/en/articles/13132885-setting-up-single-sign-on-sso)

101 </Step>101 </Step>

102 102

123 123

124Você pode fazer login em sua conta do Console sem criar uma chave de API, mesmo quando sua organização não permite que desenvolvedores as criem. Escolha a conta Anthropic Console no prompt `/login` e Claude Code pergunta como você deseja fazer login. Requer Claude Code v2.1.242 ou posterior. Ambas as rotas fazem login no Console no navegador e diferem no que Claude Code armazena depois:124Você pode fazer login em sua conta do Console sem criar uma chave de API, mesmo quando sua organização não permite que desenvolvedores as criem. Escolha a conta Anthropic Console no prompt `/login` e Claude Code pergunta como você deseja fazer login. Requer Claude Code v2.1.242 ou posterior. Ambas as rotas fazem login no Console no navegador e diferem no que Claude Code armazena depois:

125 125

126* **Faça login com sua conta do Console**, rotulado `(recomendado)`: Claude Code mantém o token OAuth desse login e o armazena como um [perfil Anthropic](#anthropic-profiles-and-federation-credentials). Não cria nenhuma chave de API126* **Faça login com sua conta do Console**, rotulado `(recommended)`: Claude Code mantém o token OAuth desse login e o armazena como um [perfil Anthropic](#anthropic-profiles-and-federation-credentials). Não cria nenhuma chave de API

127* **Crie uma chave de API**, rotulado `(legado)`: Claude Code cria uma chave de API do Console para você e a armazena com suas outras credenciais127* **Crie uma chave de API**, rotulado `(legacy)`: Claude Code cria uma chave de API do Console para você e a armazena com suas outras credenciais

128 128

129Na prática, o perfil armazena um login OAuth enquanto uma chave de API é uma credencial estática: Claude Code atualiza automaticamente o login do perfil, e quando a atualização falha, as solicitações falham com [login do perfil Anthropic expirado](/docs/pt/errors#anthropic-profile-login-expired) até que você faça login novamente.129Na prática, o perfil armazena um login OAuth enquanto uma chave de API é uma credencial estática: Claude Code atualiza automaticamente o login do perfil, e quando a atualização falha, as solicitações falham com [login do perfil Anthropic expirado](/docs/pt/errors#anthropic-profile-login-expired) até que você faça login novamente.

130 130

auto-mode-classifier-billing.md +67 −0 created

Details

1> ## Documentation Index

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

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

5# Cobranças de requisição do classificador do modo auto

7> Resolva o aviso do Claude Code dizendo que esta sessão não é elegível para requisições de classificador sem cobrança do modo auto: o que significa, por que aparece e o que fazer.

9No [modo automático](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode), um classificador verifica ações como comandos shell e solicitações de rede antes de serem executadas. Onde [as verificações do lado do servidor estão ativadas](/docs/pt/permission-modes#server-side-classifier-review), o servidor executa essas verificações como parte das próprias solicitações de modelo da sessão, sem cobrança. Este aviso significa que as verificações do servidor não estão alcançando sua sessão, portanto Claude Code está fazendo suas próprias solicitações de classificador, e em sua conta essas solicitações contam para seu uso de tokens:

11```text theme={null}

12We're changing auto mode to no longer charge for classifier requests in Claude Code. However, this session isn't eligible.

13```

15No prompt, Claude Code retém a primeira ação que verificaria dessa forma até você responder. Nada está quebrado: o modo automático continua funcionando, e suas solicitações de classificador são cobradas como eram antes. A causa mais comum é um gateway LLM ou proxy entre Claude Code e a API, e quando Claude Code consegue identificar um, o aviso o nomeia. Pressione **Enter** para continuar, ou veja [Tornar a sessão elegível](#make-the-session-eligible) para evitar que apareça em novas sessões.

17<h2 id="respond-to-the-notice">

18 Responder ao aviso

19</h2>

21O aviso mantém a ação em espera até que você responda:

23* **Enter** continua: a ação mantida em espera e o resto da sessão usam as próprias solicitações de classificador do Claude Code, faturadas como uso de tokens como antes, e o aviso não aparece novamente nessa sessão. Quando o aviso nomeou um gateway, reconhecê-lo impede que ele reapareça nesta máquina por 24 horas. Quando não nomeou, o aviso retorna na próxima vez que uma sessão retrocede.

24* **Esc** ou **Ctrl+C** cancela: a ação mantida em espera não é executada e o turno atual para, com a sessão ainda em modo automático. Nada é lembrado, então o aviso aparece novamente antes da próxima ação verificada.

26Para parar de usar o modo automático, alterne os modos de permissão com `Shift+Tab` depois de responder.

28Onde o aviso não pode esperar por uma resposta, Claude Code relata o mesmo texto e a sessão continua em modo automático, a menos que um reconhecimento de gateway nesta máquina nos últimos 24 horas o tenha descartado. Em [modo não interativo](/docs/pt/headless) com `-p`, ele imprime o texto em stderr, e na saída `stream-json`, ele emite uma mensagem de aviso `system`, que as aplicações do Agent SDK podem ler do fluxo de mensagens.

30<h2 id="make-the-session-eligible">

31 Tornar a sessão elegível

32</h2>

34Se um gateway for a causa, peça ao administrador da sua empresa ou ao provedor do seu gateway para passar solicitações e respostas inalteradas. Isso significa encaminhar cabeçalhos de solicitação e campos de corpo conforme estão, incluindo aqueles que o gateway não reconhece, como o campo de solicitação `safeguards`, e retornar respostas e eventos de streaming sem descartar chaves como o campo `safeguard_results` ou reescrever IDs de uso de ferramentas, conforme o [guia de compatibilidade de gateway](/docs/pt/llm-gateway-protocol#feature-pass-through) descreve. Um gateway que passa tráfego dessa forma continua funcionando com este recurso e com futuros. Novas sessões então usam as verificações do servidor novamente.

36Se você já sabe que seu gateway não pode fornecer as verificações do servidor, diga ao Claude Code para não pedir por elas lá definindo `CLAUDE_CODE_AUTO_MODE_SERVER` para `0` antes de iniciar a sessão, em seu shell ou na [chave de configurações `env`](/docs/pt/settings-reference#env):

38```bash theme={null}

39export CLAUDE_CODE_AUTO_MODE_SERVER=0

40```

42As solicitações do classificador são então sempre do próprio Claude Code, faturadas da mesma forma, e o aviso não aparece. Em uma conexão direta com a API Anthropic, a variável requer Claude Code v2.1.281 ou posterior. Definir `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1` enquanto `CLAUDE_CODE_AUTO_MODE_SERVER` não está definido desativa as verificações do servidor também, exceto conforme [Desabilitar capacidades de pré-lançamento](/docs/pt/llm-gateway-protocol#disable-pre-release-capabilities) descreve.

44`CLAUDE_CODE_AUTO_MODE_SERVER` é uma configuração temporária e pode ser removida em uma versão posterior.

46<h2 id="why-the-notice-appears">

47 Por que o aviso aparece

48</h2>

50[Revisão do classificador do lado do servidor](/docs/pt/permission-modes#server-side-classifier-review) lista quais sessões solicitam ao servidor as verificações do classificador. Os planos Pro, Max e Team nunca mostram o aviso. Quando aparece, as causas usuais são:

52* **Um gateway LLM ou proxy está no caminho**: um que remove ou reescreve cabeçalhos de solicitação, descarta campos de solicitação que não reconhece ou edita respostas. O servidor então nunca recebe a solicitação de verificações, ou Claude Code nunca recebe os resultados. Quando sua configuração ou as respostas identificam o gateway, o aviso o nomeia.

53* **As verificações do lado do servidor ainda não chegaram à sua plataforma, região ou credencial**: se uma plataforma ou região as realiza depende do lançamento dessa plataforma. Se você vir o aviso sem nenhum gateway ou proxy no caminho e ele continuar aparecendo, essa é a causa provável. Para confirmar, entre em contato com o suporte ou o administrador da sua empresa, ou relate com `/feedback`.

55Para verificar uma sessão que está em modo automático, execute `/status` no prompt do Claude Code: sua linha **Auto mode server** lê `Enabled` enquanto as verificações do servidor decidem as ações da sessão e `Disabled` uma vez que a sessão fez fallback.

57Quando um gateway corta respostas ou reescreve os resultados em uma forma que Claude Code não consegue ler, você recebe negações sem veredicto no lugar deste aviso; veja [Revisão do classificador do lado do servidor](/docs/pt/permission-modes#server-side-classifier-review).

59<h2 id="related-resources">

60 Recursos relacionados

61</h2>

63* [Modo automático](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode): o que é o modo automático e o que ele bloqueia por padrão

64* [Revisão do classificador do lado do servidor](/docs/pt/permission-modes#server-side-classifier-review): quais sessões solicitam ao servidor que verifique ações e a versão do Claude Code que cada uma requer

65* [Guia de compatibilidade de gateway](/docs/pt/llm-gateway-protocol#feature-pass-through): o que quebra quando um gateway remove cabeçalhos ou campos de corpo

66* [O servidor não retornou nenhum veredicto de segurança](/docs/pt/errors#the-server-returned-no-safety-verdict): a negação que você vê quando o servidor não fornece um veredicto para uma ação

67* [Gerencie custos efetivamente](/docs/pt/costs): rastreie o uso de tokens e reduza os custos do Claude Code

auto-mode-config.md +3 −1

Details

383 383

384Dois outros lugares na tela que relatam negações omitem o comando ou URL: o aviso perto da caixa de entrada, como `bash denied by auto mode · [Data Exfiltration] · /permissions`, fornece a ferramenta e o motivo, e a aba **Recently denied** lista um comando shell pela descrição que Claude escreveu para ele. Para capturar a entrada exata dessas negações programaticamente, adicione um [hook `PermissionDenied`](/docs/pt/hooks#permissiondenied), que a recebe como `tool_input`.384Dois outros lugares na tela que relatam negações omitem o comando ou URL: o aviso perto da caixa de entrada, como `bash denied by auto mode · [Data Exfiltration] · /permissions`, fornece a ferramenta e o motivo, e a aba **Recently denied** lista um comando shell pela descrição que Claude escreveu para ele. Para capturar a entrada exata dessas negações programaticamente, adicione um [hook `PermissionDenied`](/docs/pt/hooks#permissiondenied), que a recebe como `tool_input`.

385 385

386O texto sob a chamada informa se há algo a corrigir. Texto que relata um problema com o próprio classificador, como um modelo que `is temporarily unavailable` ou um erro do classificador, significa que Claude Code bloqueou a chamada sem um veredicto final do classificador; veja [Auto mode cannot determine the safety of an action](/docs/pt/errors#auto-mode-cannot-determine-the-safety-of-an-action) para saber o que fazer. Caso contrário, uma linha lendo `Denied by auto mode classifier` com um motivo como `[Production Deploy]` ou `Blocked by classifier` significa que o classificador julgou a chamada insegura, então escolha a correção do que a chamada estava tentando alcançar ou fazer:386O texto sob a chamada informa se há algo a corrigir. Uma linha esmaecida `Not run · auto mode's check had no usable answer`, ou texto que relata um problema com o próprio classificador, como `Auto mode could not evaluate this action`, significa que Claude Code bloqueou a chamada sem um veredicto do classificador. Para uma linha `Not run`, pressione `Ctrl+O` para ler a mensagem completa e, em seguida, veja [Auto mode cannot determine the safety of an action](/docs/pt/errors#auto-mode-cannot-determine-the-safety-of-an-action) ou [The server returned no safety verdict](/docs/pt/errors#the-server-returned-no-safety-verdict) para saber o que fazer.

387

388Caso contrário, uma linha lendo `Denied by auto mode classifier` com um motivo como `[Production Deploy]` ou `Blocked by classifier` significa que o classificador julgou a chamada insegura, então escolha a correção do que a chamada estava tentando alcançar ou fazer:

387 389

388* Um destino que Claude precisa durante toda a tarefa, como um registro de pacotes, um domínio interno ou um host de repositório: adicione-o a `autoMode.environment`.390* Um destino que Claude precisa durante toda a tarefa, como um registro de pacotes, um domínio interno ou um host de repositório: adicione-o a `autoMode.environment`.

389* Um comando que você deseja executar sem revisão a partir de agora: adicione uma regra `allow`.391* Um comando que você deseja executar sem revisão a partir de agora: adicione uma regra `allow`.

checkpointing.md +2 −2

Details

114 Mensagens enviadas no meio do turno não checkpointed114 Mensagens enviadas no meio do turno não checkpointed

115</h3>115</h3>

116 116

117Quando uma mensagem que você [enfileira enquanto Claude trabalha](/docs/pt/interactive-mode#queue-messages-while-claude-works) chega ao Claude dentro do turno em execução, ela se junta a esse turno em vez de iniciar um novo. A mensagem aparece na conversa, mas Claude Code não cria um checkpoint para ela. Uma mensagem enfileirada que Claude Code envia como parte de um novo turno recebe um checkpoint como de costume, incluindo quando várias mensagens enfileiradas [compartilham esse turno](/docs/pt/interactive-mode#when-claude-code-sends-what-you-queued).117No menu de rewind, uma mensagem que você [digitou enquanto Claude ainda estava trabalhando](/docs/pt/interactive-mode#queue-messages-while-claude-works) pode ser marcada como **No code restore**. Claude leu essa mensagem antes de seu turno terminar. [Checkpoints são criados para prompts que iniciam um turno](#how-checkpoints-work), então essa mensagem não tem um checkpoint próprio. As edições que Claude fez depois de lê-la contam para o prompt que iniciou o turno.

118 118

119Para desfazer as edições que Claude fez depois de tal mensagem, faça rewind para o prompt que iniciou o turno. Isso faz rewind de todo o turno, incluindo o trabalho que Claude fez antes de sua mensagem chegar.119Você não precisa fazer nada em relação à mensagem em si. Para desfazer as alterações de arquivo dessa parte da sessão, selecione o prompt que iniciou o turno e escolha **Restore code** ou **Restore code and conversation**. Isso reverte as edições de arquivo do Claude de todo o turno, incluindo as feitas antes de sua mensagem chegar. Selecionar a mensagem marcada ainda oferece **Restore conversation**, que faz rewind da conversa até ela e mantém seus arquivos como estão.

120 120

121<h3 id="symlinked-and-hard-linked-paths-not-restored">121<h3 id="symlinked-and-hard-linked-paths-not-restored">

122 Caminhos symlinked e hard-linked não restaurados122 Caminhos symlinked e hard-linked não restaurados

chrome.md +3 −4

Details

129 Prompts de permissão em sessões do VS Code129 Prompts de permissão em sessões do VS Code

130</h3>130</h3>

131 131

132Em uma sessão do VS Code, se Claude Code pergunta a você antes de uma ação do navegador depende de como a sessão se conectou ao seu navegador:132Em uma sessão do VS Code, quando Claude Code pergunta a você antes de uma ação do navegador, o prompt aparece como um cartão no painel de chat. Quando a ação tem como alvo um site que você não permitiu, o cartão também oferece a opção de permitir esse site.

133 133

134* **Você digitou `@browser`**: a extensão aprova cada ação do navegador sobre a qual Claude Code, de outra forma, perguntaria a você.134Em uma sessão que se conectou ao seu navegador ao iniciar porque [Enabled by default](#enable-chrome-by-default) está ativado, Claude Code pergunta a você antes de ações do navegador em um site que você não permitiu, nos modos de permissão Manual, Edit automatically, Auto e Bypass permissions. Nos modos de permissão Auto e Bypass permissions, isso se aplica até que você digite `@browser` nessa sessão.

135* **A configuração [Enabled by default](#enable-chrome-by-default) a conectou ao iniciar**: Claude Code pergunta a você antes de ações do navegador em um site que você não permitiu, nos modos de permissão Manual, Edit automatically, Auto e Bypass permissions, até que você digite `@browser` nessa sessão.

136 135

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

138 Ferramentas do navegador no modo de plano137 Ferramentas do navegador no modo de plano

139</h3>138</h3>

140 139

141No [modo de planejamento](/docs/pt/permission-modes#analyze-before-you-edit-with-plan-mode), um prompt de permissão aparece antes de Claude gravar um GIF, abrir uma nova aba ou executar um atalho, exceto em uma sessão do VS Code em que você digitou [`@browser`](#permission-prompts-in-vs-code-sessions). Em uma sessão interativa da CLI, se o [modo de bypass de permissões estiver disponível](/docs/pt/permission-modes#skip-all-checks-with-bypasspermissions-mode) e a [busca de sinalizador de recurso](/docs/pt/env-vars#features-that-need-feature-flag-fetching) estiver desativada, essas chamadas são executadas sem um prompt.140No [modo de planejamento](/docs/pt/permission-modes#analyze-before-you-edit-with-plan-mode), um prompt de permissão aparece antes de Claude gravar um GIF, abrir uma nova aba ou executar um atalho. Em uma sessão interativa da CLI, se o [modo de bypass de permissões estiver disponível](/docs/pt/permission-modes#skip-all-checks-with-bypasspermissions-mode) e a [busca de feature flags](/docs/pt/env-vars#features-that-need-feature-flag-fetching) estiver desativada, essas chamadas são executadas sem um prompt.

142 141

143Uma chamada `tabs_context_mcp` também solicita quando define `createIfEmpty`, e o mesmo ocorre com uma chamada `browser_batch` que inclui qualquer uma dessas ações.142Uma chamada `tabs_context_mcp` também solicita quando define `createIfEmpty`, e o mesmo ocorre com uma chamada `browser_batch` que inclui qualquer uma dessas ações.

144 143

claude-apps-gateway.md +21 −3

Details

263 Conectar desenvolvedores263 Conectar desenvolvedores

264</h2>264</h2>

265 265

266Os desenvolvedores se conectam de seus próprios laptops com um sign-in de navegador, usando sua conta de trabalho corporativa. Eles não precisam de uma conta claude.ai, uma chave de API ou uma assinatura, porque as requisições para o modelo passam pelo gateway usando a credencial upstream da organização. A conexão é orientada pelas [configurações gerenciadas no lado do cliente](/docs/pt/claude-apps-gateway-config#client-side-managed-settings) que você envia via MDM, então não há configuração manual no lado do desenvolvedor; esta seção cobre o que o administrador configura.266Os desenvolvedores se conectam de seus próprios laptops com um sign-in de navegador, usando sua conta de trabalho corporativa. Eles não precisam de uma conta claude.ai, uma chave de API ou uma assinatura, porque as requisições para o modelo passam pelo gateway usando a credencial upstream da organização. A conexão é orientada pelas [configurações gerenciadas no lado do cliente](/docs/pt/claude-apps-gateway-config#client-side-managed-settings) que você envia via MDM, e esta seção cobre o que o administrador configura.

267 267

268A CLI coloca a impressão digital do certificado TLS folha do gateway na primeira conexão e a fixa por nome de host. Ela verifica esse pino novamente durante o sign-in, em atualizações de sessão silenciosas e em buscas de configurações gerenciadas, enquanto requisições de inferência usam validação TLS padrão sem o pino. Requisições roteadas através de um proxy HTTPS pulam a verificação de pino, então adicione o host do gateway a `NO_PROXY` para mantê-las diretas.268A CLI coloca a impressão digital do certificado TLS folha do gateway na primeira conexão e a fixa por nome de host. Ela verifica esse pino novamente durante o sign-in, em atualizações de sessão silenciosas e em buscas de configurações gerenciadas, enquanto requisições de inferência usam validação TLS padrão sem o pino. Requisições roteadas através de um proxy HTTPS pulam a verificação de pino, então adicione o host do gateway a `NO_PROXY` para mantê-las diretas.

269 269

287 Defina a URL do gateway287 Defina a URL do gateway

288</h3>288</h3>

289 289

290Três chaves vão no arquivo de [configurações gerenciadas](/docs/pt/managed-settings#delivery-mechanisms) por SO que você implanta via MDM ou diretamente no disco. `forceLoginMethod` e `forceLoginGatewayUrl` abrem `/login` diretamente na tela **Cloud gateway** com a URL preenchida, e `parentSettingsBehavior: "merge"` permite que Claude Desktop entregue a allowlist de egresso do gateway para as sessões Claude Code que ele inicia, explicado em [Entregar política para sessões Claude Desktop](#deliver-policy-to-claude-desktop-sessions):290Três chaves vão no arquivo de [configurações gerenciadas](/docs/pt/managed-settings#delivery-mechanisms) por SO que você implanta via MDM ou diretamente no disco. Para uma máquina sem configurações gerenciadas, consulte [Defina a URL do gateway nas configurações de usuário](#set-the-gateway-url-in-user-settings). `forceLoginMethod` e `forceLoginGatewayUrl` abrem `/login` diretamente na tela **Cloud gateway** com a URL preenchida, e `parentSettingsBehavior: "merge"` permite que Claude Desktop entregue a allowlist de egresso do gateway para as sessões Claude Code que ele inicia, explicado em [Entregar política para sessões Claude Desktop](#deliver-policy-to-claude-desktop-sessions):

291 291

292```json theme={null}292```json theme={null}

293{293{

299 299

300O desenvolvedor pressiona Enter para se conectar. O [prompt de impressão digital TLS de primeira conexão](#connect-developers) ainda aparece. Uma vez que o arquivo está em uma máquina, um desenvolvedor que não completou o sign-in do gateway vê uma das mensagens descritas em [A política do administrador requer um sign-in Cloud gateway](/docs/pt/errors#administrator-policy-requires-a-cloud-gateway-sign-in). Desenvolvedores que selecionam um provedor de nuvem através de uma variável de ambiente como `CLAUDE_CODE_USE_BEDROCK` não precisam do sign-in do gateway.300O desenvolvedor pressiona Enter para se conectar. O [prompt de impressão digital TLS de primeira conexão](#connect-developers) ainda aparece. Uma vez que o arquivo está em uma máquina, um desenvolvedor que não completou o sign-in do gateway vê uma das mensagens descritas em [A política do administrador requer um sign-in Cloud gateway](/docs/pt/errors#administrator-policy-requires-a-cloud-gateway-sign-in). Desenvolvedores que selecionam um provedor de nuvem através de uma variável de ambiente como `CLAUDE_CODE_USE_BEDROCK` não precisam do sign-in do gateway.

301 301

302Um desenvolvedor não pode configurar isso manualmente. O seletor de login não tem opção de gateway, e `forceLoginGatewayUrl` é ignorado nos arquivos de configurações próprias de um desenvolvedor. `forceLoginMethod` sozinho, sem uma URL, deixa o desenvolvedor em uma mensagem "Entre em contato com seu administrador de TI". As chaves de login pertencem ao arquivo que você envia para máquinas, não ao bloco `managed.policies[].cli` do gateway, que só alcança clientes que já estão conectados.302O seletor de login não tem opção de gateway, e nas configurações gerenciadas `forceLoginMethod` sozinho, sem uma URL, deixa o desenvolvedor em uma mensagem "Entre em contato com seu administrador de TI". As chaves de login pertencem ao arquivo que você envia para máquinas, não ao bloco `managed.policies[].cli` do gateway, que só alcança clientes que já estão conectados.

303

304<h4 id="set-the-gateway-url-in-user-settings">

305 Defina a URL do gateway nas configurações de usuário

306</h4>

307

308Em máquinas sem configurações gerenciadas, peça que cada desenvolvedor adicione `forceLoginMethod` e `forceLoginGatewayUrl` ao seu próprio arquivo de configurações de usuário, `~/.claude/settings.json`. Isso requer Claude Code v2.1.295 ou posterior na máquina do desenvolvedor. Este exemplo nomeia um gateway em `claude-gateway.internal.example.com`:

309

310```json theme={null}

311{

312 "forceLoginMethod": "gateway",

313 "forceLoginGatewayUrl": "https://claude-gateway.internal.example.com"

314}

315```

316

317Quando o desenvolvedor executa `/login` no prompt do Claude Code, a tela **Cloud gateway** abre nesse endereço e ele pressiona Enter para se conectar. O [prompt de impressão digital TLS de primeira conexão](#connect-developers) ainda aparece. Estes limites se aplicam às chaves definidas dessa forma:

318

319* **Apenas configurações de usuário**: Claude Code lê as duas chaves de `~/.claude/settings.json`, não do `.claude/settings.json` ou `.claude/settings.local.json` de um projeto.

320* **Configurações gerenciadas as desativam**: assim que as configurações de um administrador chegam à máquina por meio de um arquivo de configurações gerenciadas, um plist do macOS ou uma política HKLM do Windows, ou um [policy helper](/docs/pt/settings-reference#policyhelper), Claude Code ignora um gateway nomeado nas configurações de usuário.

303 321

304<h3 id="allow-a-gateway-on-public-address-space-you-own">322<h3 id="allow-a-gateway-on-public-address-space-you-own">

305 Permitir um gateway em espaço de endereço público que você possui323 Permitir um gateway em espaço de endereço público que você possui

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

Details

981 * **Chaves misturadas**: um arquivo que tem tanto `code` quanto `cli`, ou sua grafia anterior `settings`, interrompe o gateway na inicialização. Coloque todos os blocos sob uma única chave, em uma única edição.981 * **Chaves misturadas**: um arquivo que tem tanto `code` quanto `cli`, ou sua grafia anterior `settings`, interrompe o gateway na inicialização. Coloque todos os blocos sob uma única chave, em uma única edição.

982</Warning>982</Warning>

983 983

984As configurações do Claude Code de uma política, como uma regra que nega a leitura de arquivos `.env`, ficam em um bloco sob a chave `cli` ou `code`. Ambas as chaves aceitam o mesmo conteúdo. A chave decide onde as configurações são aplicadas:984As configurações do Claude Code de uma política, como uma regra que nega a leitura de arquivos `.env`, ficam em um bloco sob a chave `cli` ou `code`. `code` é a chave recomendada, e `cli` é a chave legada. Ambas as chaves aceitam o mesmo conteúdo. A chave decide onde as configurações são aplicadas:

985 985

986* **`cli`**: o terminal, as extensões do VS Code e do JetBrains e o Agent SDK. Com `cli`, a aba Code do Claude Desktop recebe as [configurações derivadas](#claude-desktop-overlay), então uma regra com escopo como `Read(./.env)` não impede um usuário ali.986* **`cli`**: o terminal, as extensões do VS Code e do JetBrains e o Agent SDK. Com `cli`, a aba Code do Claude Desktop recebe as [configurações derivadas](#claude-desktop-overlay), então uma regra com escopo como `Read(./.env)` não impede um usuário ali.

987* **`code`**: os mesmos lugares, e a aba Code do Claude Desktop também pode ser coberta.987* **`code`**: os mesmos lugares, e a aba Code do Claude Desktop também pode ser coberta.

988 988

989A escolha é se essas configurações também devem cobrir a aba Code. Se não, não altere nada. Um arquivo que usa `cli` funciona como antes, e um gateway que encontra `cli` em uma política com uma chave [`desktop`](#claude-desktop-overlay) emite um aviso na inicialização e inicia mesmo assim. Para cobrir a aba Code, mude para `code`, a chave recomendada.989Um arquivo que usa `cli` funciona como antes, e um gateway que encontra `cli` em uma política com uma chave [`desktop`](#claude-desktop-overlay) emite um aviso na inicialização e inicia mesmo assim. Mude para `code` para que as configurações também possam cobrir a aba Code.

990 990

991Antes de mudar, leia [Aplicar configurações de `code` na aba Code](#apply-code-settings-in-the-code-tab). A política precisa de uma chave `desktop` e as máquinas dos usuários precisam de configuração antes que as configurações se apliquem ali, e a pesquisa na web é desativada no Claude Desktop.991Antes de mudar, leia [Aplicar configurações de `code` na aba Code](#apply-code-settings-in-the-code-tab). A política precisa de uma chave `desktop` e as máquinas dos usuários precisam de configuração antes que as configurações se apliquem ali, e a pesquisa na web é desativada no Claude Desktop.

992 992

1713 1713

1714Para Claude Desktop, defina a chave `bootstrapUrl` na própria [configuração gerenciada](https://claude.com/docs/third-party/claude-desktop/configuration) do Claude Desktop como `<listen.public_url>/user/bootstrap`. O fluxo de entrada e a política por grupo correspondem aos da CLI uma vez que uma política aceita no servidor com uma chave `desktop`; sem a aceitação, `/user/bootstrap` retorna 404. Veja [Claude Desktop overlay](#claude-desktop-overlay) para a metade do servidor.1714Para Claude Desktop, defina a chave `bootstrapUrl` na própria [configuração gerenciada](https://claude.com/docs/third-party/claude-desktop/configuration) do Claude Desktop como `<listen.public_url>/user/bootstrap`. O fluxo de entrada e a política por grupo correspondem aos da CLI uma vez que uma política aceita no servidor com uma chave `desktop`; sem a aceitação, `/user/bootstrap` retorna 404. Veja [Claude Desktop overlay](#claude-desktop-overlay) para a metade do servidor.

1715 1715

1716Claude Code honra [`forceLoginGatewayUrl`](/docs/pt/settings-reference#forcelogingatewayurl), [`gatewayInternalNetworks`](/docs/pt/settings-reference#gatewayinternalnetworks) e o valor `"gateway"` de [`forceLoginMethod`](/docs/pt/settings-reference#forceloginmethod) apenas de uma fonte gerenciada na máquina: `managed-settings.json`, o plist do macOS ou registro HKLM do Windows, ou um auxiliar de política. Defini-los no próprio `~/.claude/settings.json` de um desenvolvedor ou no payload do gateway não configura o login no gateway.1716Claude Code honra [`forceLoginGatewayUrl`](/docs/pt/settings-reference#forcelogingatewayurl), [`gatewayInternalNetworks`](/docs/pt/settings-reference#gatewayinternalnetworks) e o valor `"gateway"` de [`forceLoginMethod`](/docs/pt/settings-reference#forceloginmethod) de uma fonte gerenciada na máquina: `managed-settings.json`, o plist do macOS ou registro HKLM do Windows, ou um auxiliar de política. Defini-los no payload do gateway não configura o login no gateway. Para o próprio `~/.claude/settings.json` de um desenvolvedor, veja [Definir a URL do gateway nas configurações do usuário](/docs/pt/claude-apps-gateway#set-the-gateway-url-in-user-settings).

1717 1717

1718Deixe `forceLoginMethod` e `forceLoginOrgUUID` fora do payload. O Claude Code ainda lê ambas as chaves do payload para sua verificação de credenciais na inicialização, portanto um desenvolvedor que mantém uma credencial emitida pela Anthropic na máquina recebe a saída na inicialização descrita em [Administrator policy requires a Cloud gateway sign-in](/docs/pt/errors#administrator-policy-requires-a-cloud-gateway-sign-in) mesmo depois de fazer login.1718Deixe `forceLoginMethod` e `forceLoginOrgUUID` fora do payload. O Claude Code ainda lê ambas as chaves do payload para sua verificação de credenciais na inicialização, portanto um desenvolvedor que mantém uma credencial emitida pela Anthropic na máquina recebe a saída na inicialização descrita em [Administrator policy requires a Cloud gateway sign-in](/docs/pt/errors#administrator-policy-requires-a-cloud-gateway-sign-in) mesmo depois de fazer login.

1719 1719

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

Details

135 Envie a URL do gateway para máquinas de desenvolvedores135 Envie a URL do gateway para máquinas de desenvolvedores

136</h3>136</h3>

137 137

138Assim que o gateway estiver servindo, envie `forceLoginMethod`, `forceLoginGatewayUrl` e `parentSettingsBehavior: "merge"` para a máquina de cada desenvolvedor através de configurações gerenciadas, via MDM ou escrevendo o `managed-settings.json` por SO diretamente. Sem isso, `/login` mostra o seletor de conta padrão sem opção de gateway.138Assim que o gateway estiver servindo, envie `forceLoginMethod`, `forceLoginGatewayUrl` e `parentSettingsBehavior: "merge"` para a máquina de cada desenvolvedor através de configurações gerenciadas, via MDM ou escrevendo o `managed-settings.json` por SO diretamente.

139 139

140Uma vez que você implanta as chaves, Claude Code para de usar uma chave de API restante ou login claude.ai na máquina, então planeje o envio junto com suas instruções de sign-in. [A política do administrador requer um sign-in de gateway Cloud](/docs/pt/errors#administrator-policy-requires-a-cloud-gateway-sign-in) descreve as mensagens que os desenvolvedores veem.140Uma vez que você implanta as chaves, Claude Code para de usar uma chave de API restante ou login claude.ai na máquina, então planeje o envio junto com suas instruções de sign-in. [A política do administrador requer um sign-in de gateway Cloud](/docs/pt/errors#administrator-policy-requires-a-cloud-gateway-sign-in) descreve as mensagens que os desenvolvedores veem.

141 141

claude-projects.md +11 −5

Details

277 277

278As threads são executadas em [modo auto](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode) quando o modelo da thread o suporta, então a maioria das chamadas de ferramenta são executadas sem pedir a você. Quando uma thread precisa de sua aprovação, o prompt está dentro dessa thread e a thread aguarda até que você responda lá. Dizer a Claude na conversa do projeto para prosseguir não a alcança.278As threads são executadas em [modo auto](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode) quando o modelo da thread o suporta, então a maioria das chamadas de ferramenta são executadas sem pedir a você. Quando uma thread precisa de sua aprovação, o prompt está dentro dessa thread e a thread aguarda até que você responda lá. Dizer a Claude na conversa do projeto para prosseguir não a alcança.

279 279

280Cada aprovação cobre esse prompt, ou o resto dessa thread se você escolher a opção mais ampla. Para deixar cada thread executar certos comandos sem perguntar, ou para bloquear alguns, adicione [regras de permissão](/docs/pt/permissions) ao `.claude/settings.json` do repositório. As threads as aplicam apenas em um projeto com um repositório; veja [O que as threads pegam de seus repositórios](#what-threads-pick-up-from-your-repositories). Em um projeto com vários repositórios, nenhuma regra de permissão do repositório alcança uma thread na nuvem, então você depende do modo auto e das aprovações que você dá dentro de cada thread.280Cada aprovação cobre esse prompt, ou o resto dessa thread se você escolher a opção mais ampla.

281

282Para deixar cada thread executar certos comandos sem perguntar, ou para bloquear alguns, adicione [regras de permissão](/docs/pt/permissions) ao `.claude/settings.json` do repositório. Verifique se as threads na nuvem do seu projeto as aplicam:

283

284* **Um repositório**: as threads na nuvem aplicam as regras. Veja [O que as threads pegam de seus repositórios](#what-threads-pick-up-from-your-repositories).

285* **Vários repositórios, ambiente hospedado pela Anthropic**: nenhuma regra de permissão de repositório alcança uma thread na nuvem, então você depende do modo auto e das aprovações que você dá dentro de cada thread.

286* **Vários repositórios, ambiente auto-hospedado**: veja [quais configurações de repositório se aplicam](/docs/pt/self-hosted-environments-configuration#repository-settings-in-sessions-with-several-repositories).

281 287

282<h3 id="run-a-thread-on-your-own-computer">288<h3 id="run-a-thread-on-your-own-computer">

283 Executar uma thread no seu próprio computador289 Executar uma thread no seu próprio computador

381 O que as threads pegam de seus repositórios387 O que as threads pegam de seus repositórios

382</h3>388</h3>

383 389

384Cada thread em nuvem clona cada repositório no projeto e carrega `CLAUDE.md` e skills de todos eles. Regras de permissão, hooks e `env` vêm apenas do `.claude/settings.json` no diretório em que a thread começa: dentro do repositório quando o projeto tem um, e acima dos clones quando tem vários, onde nenhum arquivo de repositório é lido para eles.390Cada thread em nuvem clona cada repositório no projeto e carrega `CLAUDE.md` e skills de todos eles. Regras de permissão, hooks e `env` vêm apenas do `.claude/settings.json` no diretório em que a thread começa.

385 391

387| :- | :- | :- |393| :- | :- | :- |

390| Plugins habilitados em `.claude/settings.json` | Não carregado. Adicione o plugin em **Project settings > Plugins** em vez disso | Não carregado. Adicione o plugin em **Project settings > Plugins** em vez disso |396| Plugins habilitados em `.claude/settings.json` | Não carregado. Adicione o plugin em **Project settings > Plugins** em vez disso | Não carregado. Adicione o plugin em **Project settings > Plugins** em vez disso |

391| Regras de permissão, hooks e `env` definidos em `.claude/settings.json` | Aplicam-se à thread, exceto as chaves `env` que [nenhuma sessão na nuvem honra](/docs/pt/cloud-environments#what-carries-over-from-your-setup) | Não se aplicam |397| Regras de permissão, hooks e `env` definidos em `.claude/settings.json` | Aplicam-se à thread, exceto as chaves `env` que [nenhuma sessão na nuvem honra](/docs/pt/cloud-environments#what-carries-over-from-your-setup) | Não se aplicam em um ambiente hospedado pela Anthropic. Para um ambiente auto-hospedado, veja [quais configurações de repositório se aplicam](/docs/pt/self-hosted-environments-configuration#repository-settings-in-sessions-with-several-repositories) |

392 398

393Em um projeto com vários repositórios, cada clone é anexado à thread como um [diretório adicional](/docs/pt/memory#load-from-additional-directories) com carregamento de `CLAUDE.md` ativado, e é por isso que o `CLAUDE.md` e as skills de cada repositório carregam no início mesmo que a thread comece acima deles. Em tal projeto, coloque regras permanentes em instruções do projeto e dê às threads variáveis de ambiente através do [ambiente em nuvem](#choose-an-environment-for-threads).399Em um projeto com vários repositórios, coloque regras permanentes em instruções do projeto e dê às threads variáveis de ambiente através do [ambiente em nuvem](#choose-an-environment-for-threads).

394 400

395<h3 id="choose-an-environment-for-threads">401<h3 id="choose-an-environment-for-threads">

396 Escolher um ambiente para threads402 Escolher um ambiente para threads

406 412

407As threads em nuvem não têm as skills, servidores MCP, plugins e ferramentas instalados apenas na sua máquina. Uma thread que Claude executa na sua máquina através de [Remote Control](/docs/pt/remote-control) usa o que está instalado lá. Para disponibilizar cada um desses para threads em nuvem:413As threads em nuvem não têm as skills, servidores MCP, plugins e ferramentas instalados apenas na sua máquina. Uma thread que Claude executa na sua máquina através de [Remote Control](/docs/pt/remote-control) usa o que está instalado lá. Para disponibilizar cada um desses para threads em nuvem:

408 414

409* Skills, subagentes e comandos: faça commit deles em um repositório que você adicionou ao projeto, por exemplo uma skill em `.claude/skills/<skill-name>/SKILL.md`. Cada thread em nuvem clona cada repositório no projeto e carrega `.claude/skills/`, `.claude/agents/` e `.claude/commands/` de cada um deles, então uma skill com commit em um repositório está disponível em cada thread em nuvem. As threads em nuvem também carregam as skills que você habilita para sua conta claude.ai.415* Skills, subagentes e comandos: faça commit deles em um repositório que você adicionou ao projeto, por exemplo uma skill em `.claude/skills/<skill-name>/SKILL.md`. Cada thread em nuvem clona cada repositório no projeto e carrega `.claude/skills/`, `.claude/agents/` e `.claude/commands/` de cada um deles, então uma skill com commit em um repositório está disponível em cada thread em nuvem. As threads em nuvem também carregam as [skills que você habilita para sua conta claude.ai](/docs/pt/skills#skills-in-cowork-and-cloud-sessions).

410* Plugins: adicione-os em **Project settings > Plugins**; eles carregam em cada nova thread em nuvem. Plugins que um repositório declara em seu `.claude/settings.json` [não carregam em threads em nuvem](/docs/pt/cloud-environments#what-carries-over-from-your-setup).416* Plugins: adicione-os em **Project settings > Plugins**; eles carregam em cada nova thread em nuvem. Plugins que um repositório declara em seu `.claude/settings.json` [não carregam em threads em nuvem](/docs/pt/cloud-environments#what-carries-over-from-your-setup).

411* Servidores MCP: as threads em nuvem obtêm suas ferramentas MCP dos conectores em sua conta claude.ai, que são servidores MCP que você conecta uma vez em [claude.ai/customize/connectors](https://claude.ai/customize/connectors) ou através do link **Manage connectors** em **Project settings > Environment**. Cada thread em nuvem pode usar todos eles sem configuração por projeto. A conversa do projeto em si não tem conectores, então envie trabalho que precisa de um como uma tarefa para uma thread em nuvem. Em um projeto com um repositório, as threads em nuvem também carregam servidores MCP do [`.mcp.json`](/docs/pt/cloud-environments#what-carries-over-from-your-setup) desse repositório. [Como conectores alcançam Claude Code](/docs/pt/mcp#how-connectors-reach-claude-code) lista as regras para sessões na nuvem e as configurações que desativam conectores.417* Servidores MCP: as threads em nuvem obtêm suas ferramentas MCP dos conectores em sua conta claude.ai, que são servidores MCP que você conecta uma vez em [claude.ai/customize/connectors](https://claude.ai/customize/connectors) ou através do link **Manage connectors** em **Project settings > Environment**. Cada thread em nuvem pode usar todos eles sem configuração por projeto. A conversa do projeto em si não tem conectores, então envie trabalho que precisa de um como uma tarefa para uma thread em nuvem. Em um projeto com um repositório, as threads em nuvem também carregam servidores MCP do [`.mcp.json`](/docs/pt/cloud-environments#what-carries-over-from-your-setup) desse repositório. [Como conectores alcançam Claude Code](/docs/pt/mcp#how-connectors-reach-claude-code) lista as regras para sessões na nuvem e as configurações que desativam conectores.

412* Ferramentas de linha de comando e pacotes: instale-os no [script de configuração](/docs/pt/cloud-environments#setup-scripts) do ambiente.418* Ferramentas de linha de comando e pacotes: instale-os no [script de configuração](/docs/pt/cloud-environments#setup-scripts) do ambiente.

cli-reference.md +5 −5

Details

29| `claude auth status` | Mostrar status de autenticação como JSON. Use `--text` para saída legível por humanos. Sai com código 0 se conectado, 1 se não. O JSON inclui um campo `configDirectory` nomeando o [diretório de configuração](/docs/pt/claude-directory) que a CLI usa. O campo requer Claude Code v2.1.268 ou posterior. O campo `authMethod` do JSON é um de `none`, `claude.ai`, `oauth_token`, `api_key`, `api_key_helper` ou `third_party` | `claude auth status` |29| `claude auth status` | Mostrar status de autenticação como JSON. Use `--text` para saída legível por humanos. Sai com código 0 se conectado, 1 se não. O JSON inclui um campo `configDirectory` nomeando o [diretório de configuração](/docs/pt/claude-directory) que a CLI usa. O campo requer Claude Code v2.1.268 ou posterior. O campo `authMethod` do JSON é um de `none`, `claude.ai`, `oauth_token`, `api_key`, `api_key_helper` ou `third_party` | `claude auth status` |

30| `claude agents` | Abrir [visualização de agente](/docs/pt/agent-view) para monitorar e despachar sessões de fundo paralelas. Use `--cwd <path>` para mostrar apenas sessões iniciadas nesse diretório, ou `--json` para imprimir sessões ativas como um array JSON para scripts (`--json --all` também inclui sessões de fundo concluídas). Passe `--permission-mode`, `--model`, `--effort` ou `--agent` para definir [padrões para sessões despachadas](/docs/pt/agent-view#permission-mode-model-and-effort). Aceita `--settings`, `--add-dir`, `--plugin-dir` e `--mcp-config` como o comando `claude` de nível superior. Abrir visualização de agente requer um terminal interativo | `claude agents --json` |30| `claude agents` | Abrir [visualização de agente](/docs/pt/agent-view) para monitorar e despachar sessões de fundo paralelas. Use `--cwd <path>` para mostrar apenas sessões iniciadas nesse diretório, ou `--json` para imprimir sessões ativas como um array JSON para scripts (`--json --all` também inclui sessões de fundo concluídas). Passe `--permission-mode`, `--model`, `--effort` ou `--agent` para definir [padrões para sessões despachadas](/docs/pt/agent-view#permission-mode-model-and-effort). Aceita `--settings`, `--add-dir`, `--plugin-dir` e `--mcp-config` como o comando `claude` de nível superior. Abrir visualização de agente requer um terminal interativo | `claude agents --json` |

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

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

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

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

69| `--agents` | Definir subagents personalizados dinamicamente via JSON. Aceita os [campos listados para subagents definidos via CLI](/docs/pt/sub-agents#choose-the-subagent-scope). Com `--print`, o valor pode ser o caminho para um arquivo JSON contendo o objeto; a forma de arquivo requer Claude Code v2.1.281 ou posterior. Claude Code valida o valor na inicialização e sai em um valor inválido; veja [`Invalid --agents configuration`](/docs/pt/errors#invalid-agents-configuration) para a mensagem e para os sinalizadores e variável de ambiente que pulam a validação. A validação requer Claude Code v2.1.242 ou posterior | `claude --agents '{"reviewer":{"description":"Reviews code","prompt":"You are a code reviewer"}}'` |69| `--agents` | Definir subagents personalizados dinamicamente via JSON. Aceita os [campos listados para subagents definidos via CLI](/docs/pt/sub-agents#choose-the-subagent-scope). Com `--print`, o valor pode ser o caminho para um arquivo JSON contendo o objeto; a forma de arquivo requer Claude Code v2.1.281 ou posterior. Claude Code valida o valor na inicialização e sai em um valor inválido; veja [`Invalid --agents configuration`](/docs/pt/errors#invalid-agents-configuration) para a mensagem e para os sinalizadores e variável de ambiente que pulam a validação. A validação requer Claude Code v2.1.242 ou posterior | `claude --agents '{"reviewer":{"description":"Reviews code","prompt":"You are a code reviewer"}}'` |

70| `--allow-dangerously-skip-permissions` | Adicionar `bypassPermissions` ao ciclo de modo `Shift+Tab` sem iniciar nele. Permite começar em um modo diferente como `plan` e mudar para `bypassPermissions` depois. Veja [modos de permissão](/docs/pt/permission-modes#skip-all-checks-with-bypasspermissions-mode) | `claude --permission-mode plan --allow-dangerously-skip-permissions` |70| `--allow-dangerously-skip-permissions` | Adicionar `bypassPermissions` ao ciclo de modo `Shift+Tab` sem iniciar nele. Permite começar em um modo diferente como `plan` e mudar para `bypassPermissions` depois. Veja [modos de permissão](/docs/pt/permission-modes#skip-all-checks-with-bypasspermissions-mode) | `claude --permission-mode plan --allow-dangerously-skip-permissions` |

71| `--allowedTools`, `--allowed-tools` | Ferramentas que executam sem solicitar permissão. Veja [sintaxe de regra de permissão](/docs/pt/settings-reference#permission-rule-syntax) para correspondência de padrões. Para restringir quais ferramentas estão disponíveis, use `--tools` em vez disso. Se você nomear uma das [ferramentas de rastreamento de tarefas](/docs/pt/tools-reference#task-tool-availability) aqui, Claude Code também ativa a sessão | `"Bash(git log *)" "Bash(git diff *)" "Read"` |71| `--allowedTools`, `--allowed-tools` | Ferramentas que executam sem solicitar permissão, exceto leituras de [caminhos de rede](/docs/pt/permissions#network-paths). Veja [sintaxe de regra de permissão](/docs/pt/settings-reference#permission-rule-syntax) para correspondência de padrões. Para restringir quais ferramentas estão disponíveis, use `--tools` em vez disso. Se você nomear uma das [ferramentas de rastreamento de tarefas](/docs/pt/tools-reference#task-tool-availability) aqui, Claude Code também ativa a sessão | `"Bash(git log *)" "Bash(git diff *)" "Read"` |

72| `--append-subagent-system-prompt` | Anexar texto personalizado ao final do prompt do sistema de cada [subagent](/docs/pt/sub-agents), incluindo subagents aninhados, exceto um [subagent bifurcado](/docs/pt/sub-agents#fork-the-current-conversation), que reutiliza o prompt da conversa. Aplica-se apenas em modo não interativo com `-p`. Requer Claude Code v2.1.205 ou posterior | `claude -p --append-subagent-system-prompt "Cite file paths in every answer" "query"` |72| `--append-subagent-system-prompt` | Anexar texto personalizado ao final do prompt do sistema de cada [subagent](/docs/pt/sub-agents), incluindo subagents aninhados, exceto um [subagent bifurcado](/docs/pt/sub-agents#fork-the-current-conversation), que reutiliza o prompt da conversa. Aplica-se apenas em modo não interativo com `-p`. Requer Claude Code v2.1.205 ou posterior | `claude -p --append-subagent-system-prompt "Cite file paths in every answer" "query"` |

73| `--append-subagent-system-prompt-file` | Carregar texto de um arquivo e anexá-lo aos prompts do sistema de [subagent](/docs/pt/sub-agents). Uma alternativa a `--append-subagent-system-prompt` para texto muito longo para passar na linha de comando. Os dois sinalizadores não podem ser combinados. Aplica-se apenas em modo não interativo com `-p`. Requer Claude Code v2.1.261 ou posterior | `claude -p --append-subagent-system-prompt-file ./subagent-rules.txt "query"` |73| `--append-subagent-system-prompt-file` | Carregar texto de um arquivo e anexá-lo aos prompts do sistema de [subagent](/docs/pt/sub-agents). Uma alternativa a `--append-subagent-system-prompt` para texto muito longo para passar na linha de comando. Os dois sinalizadores não podem ser combinados. Aplica-se apenas em modo não interativo com `-p`. Requer Claude Code v2.1.261 ou posterior | `claude -p --append-subagent-system-prompt-file ./subagent-rules.txt "query"` |

81| `--channels` | (Visualização de pesquisa) Servidores MCP cujas notificações de [channel](/docs/pt/channels) Claude deve ouvir nesta sessão. Lista separada por espaço de entradas `plugin:<name>@<marketplace>`. Requer autenticação Anthropic através de claude.ai ou uma chave de API do Console | `claude --channels plugin:my-notifier@my-marketplace` |81| `--channels` | (Visualização de pesquisa) Servidores MCP cujas notificações de [channel](/docs/pt/channels) Claude deve ouvir nesta sessão. Lista separada por espaço de entradas `plugin:<name>@<marketplace>`. Requer autenticação Anthropic através de claude.ai ou uma chave de API do Console | `claude --channels plugin:my-notifier@my-marketplace` |

83| `--cloud` | Com uma descrição de tarefa, criar uma nova [sessão web](/docs/pt/claude-code-on-the-web). Com um ID de sessão (`session_...` ou `cse_...`) ou uma URL claude.ai/code, enfileirar uma mensagem nessa sessão existente em vez disso, com `-p`. Veja [enviar uma mensagem de acompanhamento](/docs/pt/claude-code-on-the-web#send-follow-ups-from-the-cli). | `claude --cloud "Fix the login bug"` |83| `--cloud` | Com uma descrição de tarefa, criar uma nova [sessão web](/docs/pt/claude-code-on-the-web). Com um ID de sessão (`session_...` ou `cse_...`) ou uma URL claude.ai/code, enfileirar uma mensagem nessa sessão existente em vez disso, com `-p`. Veja [enviar uma mensagem de acompanhamento](/docs/pt/claude-code-on-the-web#send-follow-ups-from-the-cli). | `claude --cloud "Fix the login bug"` |

84| `--continue`, `-c` | Carregar a conversa mais recente no diretório atual, incluindo uma [sessão de fundo que terminou](/docs/pt/sessions#resume-a-session); abrir sessões de fundo terminadas requer Claude Code v2.1.257 ou posterior. Pula sessões criadas com `claude -p` ou o Agent SDK, e sessões cujo primeiro prompt foi `/loop`. `claude -p --continue` inclui sessões `-p`, SDK e `/loop`. Inclui sessões que adicionaram este diretório com `/add-dir` | `claude --continue` |84| `--continue`, `-c` | Carregar a conversa mais recente no diretório atual, incluindo uma [sessão de fundo que terminou](/docs/pt/sessions#where-the-session-picker-looks); abrir sessões de fundo terminadas requer Claude Code v2.1.257 ou posterior. Pula sessões criadas com `claude -p` ou o Agent SDK, e sessões cujo primeiro prompt foi `/loop`. `claude -p --continue` inclui sessões `-p`, SDK e `/loop`. Inclui sessões que adicionaram este diretório com `/add-dir` | `claude --continue` |

85| `--dangerously-load-development-channels` | Ativar [canais](/docs/pt/channels-reference#test-during-the-research-preview) que não estão na allowlist aprovada, para desenvolvimento local. Aceita entradas `plugin:<name>@<marketplace>` e `server:<name>`. Solicita confirmação, portanto entra em vigor em sessões interativas. Com `-p`, Claude Code ignora a flag | `claude --dangerously-load-development-channels server:webhook` |85| `--dangerously-load-development-channels` | Ativar [canais](/docs/pt/channels-reference#test-during-the-research-preview) que não estão na allowlist aprovada, para desenvolvimento local. Aceita entradas `plugin:<name>@<marketplace>` e `server:<name>`. Solicita confirmação, portanto entra em vigor em sessões interativas. Com `-p`, Claude Code ignora a flag | `claude --dangerously-load-development-channels server:webhook` |

86| `--dangerously-skip-permissions` | Pular prompts de permissão. Equivalente a `--permission-mode bypassPermissions`. Veja [modos de permissão](/docs/pt/permission-modes#skip-all-checks-with-bypasspermissions-mode) para o que isso faz e não faz. Para sessões iniciadas com `--bg`, o modo [persiste quando o supervisor reinicia a sessão](/docs/pt/agent-view#permission-mode-model-and-effort) | `claude --dangerously-skip-permissions` |86| `--dangerously-skip-permissions` | Pular prompts de permissão. Equivalente a `--permission-mode bypassPermissions`. Veja [modos de permissão](/docs/pt/permission-modes#skip-all-checks-with-bypasspermissions-mode) para o que isso faz e não faz. Para sessões iniciadas com `--bg`, o modo [persiste quando o supervisor reinicia a sessão](/docs/pt/agent-view#permission-mode-model-and-effort) | `claude --dangerously-skip-permissions` |

87| `--debug` | Ativar modo de depuração com filtragem de categoria opcional, como `--debug='mcp,startup'` ou `--debug='!1p'`. O filtro se vincula apenas na forma `=`; um filtro separado por espaço ativa o modo de depuração sem filtragem | `claude --debug='mcp,startup'` |87| `--debug` | Ativar modo de depuração com filtragem de categoria opcional, como `--debug='mcp,startup'` ou `--debug='!1p'`. O filtro se vincula apenas na forma `=`; um filtro separado por espaço ativa o modo de depuração sem filtragem | `claude --debug='mcp,startup'` |

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

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

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

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

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

113| `--name`, `-n` | Definir um nome de exibição para a sessão, mostrado em `/resume` e no título do terminal. Você pode retomar uma sessão nomeada com `claude --resume <name>`. Em uma sessão interativa, se outra sessão ativa nesta máquina já usar o nome, Claude Code aplica [uma variante dele](/docs/pt/sessions#name-your-sessions) em vez disso. <br /><br />[`/rename`](/docs/pt/commands) altera o nome durante a sessão e também o mostra na barra de prompt | `claude -n "my-feature-work"` |113| `--name`, `-n` | Definir um nome de exibição para a sessão, mostrado em `/resume` e no título do terminal. Você pode retomar uma sessão nomeada com `claude --resume <name>`. <br /><br />[`/rename`](/docs/pt/commands) altera o nome durante a sessão e também o mostra na barra de prompt | `claude -n "my-feature-work"` |

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

cloud-environments.md +1 −1

Details

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

315| As [configurações gerenciadas pelo servidor](/docs/pt/server-managed-settings) de sua organização | Sim, exceto em sessões [Claude Tag](https://claude.com/docs/claude-tag/overview) | Buscadas dos servidores da Anthropic quando a sessão é iniciada. Veja [Cobertura de superfície](/docs/pt/model-config#surface-coverage) para como `availableModels` é aplicado em sessões na nuvem. As configurações implantadas em seu dispositivo através de MDM ou arquivos de configurações gerenciadas não se aplicam, porque a sessão é executada em uma VM gerenciada pela Anthropic; em um [ambiente auto-hospedado](/docs/pt/self-hosted-environments), as sessões também leem o arquivo de configurações gerenciadas na imagem do executor, por [como Claude Code combina fontes gerenciadas](/docs/pt/managed-settings#how-claude-code-combines-managed-sources) |315| As [configurações gerenciadas pelo servidor](/docs/pt/server-managed-settings) de sua organização | Sim, exceto em sessões [Claude Tag](https://claude.com/docs/claude-tag/overview) | Buscadas dos servidores da Anthropic quando a sessão é iniciada. Veja [Cobertura de superfície](/docs/pt/model-config#surface-coverage) para como `availableModels` é aplicado em sessões na nuvem. As configurações implantadas em seu dispositivo através de MDM ou arquivos de configurações gerenciadas não se aplicam, porque a sessão é executada em uma VM gerenciada pela Anthropic; em um [ambiente auto-hospedado](/docs/pt/self-hosted-environments), as sessões também leem o arquivo de configurações gerenciadas na imagem do executor, por [como Claude Code combina fontes gerenciadas](/docs/pt/managed-settings#how-claude-code-combines-managed-sources) |

316| Seu `~/.claude/CLAUDE.md` do usuário | Não | Vive em sua máquina, não no repositório. Veja [Adicione preferências pessoais sem fazer commit no repositório](#add-personal-preferences-without-committing-to-the-repo) |316| Seu `~/.claude/CLAUDE.md` do usuário | Não | Vive em sua máquina, não no repositório. Veja [Adicione preferências pessoais sem fazer commit no repositório](#add-personal-preferences-without-committing-to-the-repo) |

317| Seu `~/.claude/skills/`, `~/.claude/agents/`, `~/.claude/commands/` do usuário | Não | Vivem em sua máquina, não no repositório. Faça commit deles no diretório `.claude/` do repositório em vez disso. As sessões na nuvem carregam automaticamente skills que você ativa em claude.ai |317| Seu `~/.claude/skills/`, `~/.claude/agents/`, `~/.claude/commands/` do usuário | Não | Vivem em sua máquina, não no repositório. Faça commit deles no diretório `.claude/` do repositório em vez disso. As sessões na nuvem carregam automaticamente [skills que você ativa em claude.ai](/docs/pt/skills#skills-in-cowork-and-cloud-sessions) |

318| Plugins ativados apenas em suas configurações de usuário | Não | O `enabledPlugins` com escopo de usuário vive em `~/.claude/settings.json` em sua máquina |318| Plugins ativados apenas em suas configurações de usuário | Não | O `enabledPlugins` com escopo de usuário vive em `~/.claude/settings.json` em sua máquina |

319| Servidores MCP que você adicionou com `claude mcp add` no escopo local padrão ou no escopo de usuário | Não | Aqueles escrevem em `~/.claude.json` em sua máquina, não no repositório. Adicione o servidor com `claude mcp add --scope project`, que escreve o [`.mcp.json`](/docs/pt/mcp#project-scope) do repositório, e faça commit desse arquivo. Uma sessão com um repositório o carrega |319| Servidores MCP que você adicionou com `claude mcp add` no escopo local padrão ou no escopo de usuário | Não | Aqueles escrevem em `~/.claude.json` em sua máquina, não no repositório. Adicione o servidor com `claude mcp add --scope project`, que escreve o [`.mcp.json`](/docs/pt/mcp#project-scope) do repositório, e faça commit desse arquivo. Uma sessão com um repositório o carrega |

320| Variáveis de transporte em seu bloco `env` `.claude/settings.json` do repositório, como `NODE_EXTRA_CA_CERTS` e as [variáveis de certificado de cliente mTLS](/docs/pt/network-config#mtls-authentication) | Não | O ambiente de hospedagem gerencia a conexão de API da sessão, portanto Claude Code ignora essas chaves e anota cada chave ignorada no log de depuração da sessão |320| Variáveis de transporte em seu bloco `env` `.claude/settings.json` do repositório, como `NODE_EXTRA_CA_CERTS` e as [variáveis de certificado de cliente mTLS](/docs/pt/network-config#mtls-authentication) | Não | O ambiente de hospedagem gerencia a conexão de API da sessão, portanto Claude Code ignora essas chaves e anota cada chave ignorada no log de depuração da sessão |

code-review.md +4 −4

Details

267| Seção | O que mostra |267| Seção | O que mostra |

268| :- | :- |268| :- | :- |

269| PRs reviewed | Contagem diária de pull requests revisados durante o intervalo de tempo selecionado |269| PRs reviewed | Contagem diária de pull requests revisados durante o intervalo de tempo selecionado |

270| Cost weekly | Gasto semanal em Code Review |270| Code Review cost | Gasto em Code Review até o momento neste mês |

271| Feedback | Contagem de comentários de revisão que foram resolvidos automaticamente porque um desenvolvedor abordou o problema |271| Feedback | Contagem de comentários de revisão que foram resolvidos automaticamente porque um desenvolvedor abordou o problema |

272| Repository breakdown | Contagens por repo de PRs revisados e comentários resolvidos |272| Repository breakdown | Contagens por repo de PRs revisados, comentários resolvidos e execuções de revisão, com custo estimado e uma visualização por PR |

273 273

274Os números de custo do painel são estimativas para monitorar atividade. Para gasto preciso de fatura, consulte sua fatura da Anthropic.274O cartão Code Review cost mostra um valor somente quando o mês atual está selecionado. Os números de custo nas análises podem diferir da sua fatura. Os custos do Repository breakdown são estimados pelo preço de tabela, antes de quaisquer descontos ou créditos, e abrangem apenas as revisões que Claude publicou em um pull request. Para gasto preciso de fatura, consulte sua fatura da Anthropic.

275 275

276<h2 id="pricing">276<h2 id="pricing">

277 Preços277 Preços

289 289

290Os custos aparecem em sua fatura da Anthropic independentemente de sua organização usar Amazon Bedrock ou Google Cloud's Agent Platform para outros recursos do Claude Code. Para definir um limite de gasto mensal para Code Review, vá para [claude.ai/admin-settings/usage](https://claude.ai/admin-settings/usage) e configure o limite para o serviço Claude Code Review.290Os custos aparecem em sua fatura da Anthropic independentemente de sua organização usar Amazon Bedrock ou Google Cloud's Agent Platform para outros recursos do Claude Code. Para definir um limite de gasto mensal para Code Review, vá para [claude.ai/admin-settings/usage](https://claude.ai/admin-settings/usage) e configure o limite para o serviço Claude Code Review.

291 291

292Monitore gastos através do gráfico de custo semanal em [analytics](#view-usage) ou da coluna de custo médio por repo nas configurações de administrador.292Para monitorar gastos, use o [painel de analytics](#view-usage).

293 293

294<h2 id="troubleshooting">294<h2 id="troubleshooting">

295 Troubleshooting295 Troubleshooting

commands.md +2 −2

Details

77| `/compact [instructions]` | Libere contexto resumindo a conversa até agora. Opcionalmente passe instruções de foco para o resumo. Consulte [como a compactação lida com regras, skills e arquivos de memória](/docs/pt/context-window#what-survives-compaction) |77| `/compact [instructions]` | Libere contexto resumindo a conversa até agora. Opcionalmente passe instruções de foco para o resumo. Consulte [como a compactação lida com regras, skills e arquivos de memória](/docs/pt/context-window#what-survives-compaction) |

78| `/config [key=value ...]` | Abra a interface de [Configurações](/docs/pt/settings) para ajustar tema, modelo, [estilo de saída](/docs/pt/output-styles) e outras preferências. Passe um ou mais pares `key=value` para definir uma configuração diretamente sem abrir a interface, por exemplo `/config thinking=false`, `/config theme=dark`, ou `/config model=sonnet`. O formulário `key=value` também funciona em modo não interativo (`-p`) e do aplicativo móvel Claude via [Remote Control](/docs/pt/remote-control). O formulário `key=value` não pode ativar uma configuração que precisa de sua confirmação no painel, como [`autoContinueAtUsageLimit`](/docs/pt/interactive-mode#turn-automatic-continue-off), embora possa desativá-la. Execute `/config --help` para listar as chaves que aceita. Alias: `/settings` |78| `/config [key=value ...]` | Abra a interface de [Configurações](/docs/pt/settings) para ajustar tema, modelo, [estilo de saída](/docs/pt/output-styles) e outras preferências. Passe um ou mais pares `key=value` para definir uma configuração diretamente sem abrir a interface, por exemplo `/config thinking=false`, `/config theme=dark`, ou `/config model=sonnet`. O formulário `key=value` também funciona em modo não interativo (`-p`) e do aplicativo móvel Claude via [Remote Control](/docs/pt/remote-control). O formulário `key=value` não pode ativar uma configuração que precisa de sua confirmação no painel, como [`autoContinueAtUsageLimit`](/docs/pt/interactive-mode#turn-automatic-continue-off), embora possa desativá-la. Execute `/config --help` para listar as chaves que aceita. Alias: `/settings` |

79| `/context [all]` | Visualize o uso de contexto atual como uma grade colorida. Mostra sugestões de otimização para ferramentas pesadas em contexto, inchaço de memória e avisos de capacidade. Quando a conversa excede a janela de contexto, a saída inclui um [aviso](/docs/pt/errors#context-exceeds-the-token-limit) mostrando o quão longe você está do limite e qual comando libera espaço. Em [modo tela cheia](/docs/pt/fullscreen), `/context` recolhe o detalhamento por item para manter a grade visível. Passe `all` para expandi-lo |79| `/context [all]` | Visualize o uso de contexto atual como uma grade colorida. Mostra sugestões de otimização para ferramentas pesadas em contexto, inchaço de memória e avisos de capacidade. Quando a conversa excede a janela de contexto, a saída inclui um [aviso](/docs/pt/errors#context-exceeds-the-token-limit) mostrando o quão longe você está do limite e qual comando libera espaço. Em [modo tela cheia](/docs/pt/fullscreen), `/context` recolhe o detalhamento por item para manter a grade visível. Passe `all` para expandi-lo |

80| `/copy [N]` | Copie a última resposta do assistente para a área de transferência. Passe um número `N` para copiar a Nª-última resposta: `/copy 2` copia a segunda-última. Quando blocos de código estão presentes, mostra um seletor interativo para selecionar blocos individuais ou a resposta completa. Pressione `w` no seletor para escrever a seleção em um arquivo em vez da área de transferência, o que é útil sobre SSH |80| `/copy [N]` | Copie a última resposta do assistente para a área de transferência. Passe um número `N` para copiar a Nª-última resposta: `/copy 2` copia a segunda-última. Quando blocos de código ou citações em bloco estão presentes, mostra um seletor interativo para selecionar blocos individuais ou a resposta completa. Pressione `w` no seletor para escrever a seleção em um arquivo em vez da área de transferência, o que é útil sobre SSH |

81| `/cost` | Alias para `/usage` |81| `/cost` | Alias para `/usage` |

82| `/dataviz [request]` | **[Skill](/docs/pt/skills#bundled-skills).** Orientação de design para gráficos, gráficos e painéis. Claude escolhe a forma de gráfico para os dados, atribui cor por função, valida a paleta para segurança de daltonismo e contraste com um script incluído, e aplica regras de marca, interação e acessibilidade. Usa uma paleta de espaço reservado neutra da marca que você substitui pela sua própria |82| `/dataviz [request]` | **[Skill](/docs/pt/skills#bundled-skills).** Orientação de design para gráficos, gráficos e painéis. Claude escolhe a forma de gráfico para os dados, atribui cor por função, valida a paleta para segurança de daltonismo e contraste com um script incluído, e aplica regras de marca, interação e acessibilidade. Usa uma paleta de espaço reservado neutra da marca que você substitui pela sua própria |

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

132| `/reload-skills` | Rescaneie diretórios de [skill](/docs/pt/skills) e comando para que skills adicionadas ou alteradas no disco durante a sessão fiquem disponíveis sem reiniciar. Relata quantas skills estão disponíveis e quantas foram adicionadas ou removidas |132| `/reload-skills` | Rescaneie diretórios de [skill](/docs/pt/skills) e comando para que skills adicionadas ou alteradas no disco durante a sessão fiquem disponíveis sem reiniciar. Relata quantas skills estão disponíveis e quantas foram adicionadas ou removidas |

133| `/remote-control` | Disponibilize esta sessão para [Remote Control](/docs/pt/remote-control) de claude.ai. Executá-lo enquanto desconectado imprime que Remote Control requer uma assinatura claude.ai e diz como conectar; antes da v2.1.206 relatava `Unknown command: /remote-control`. Alias: `/rc` |133| `/remote-control` | Disponibilize esta sessão para [Remote Control](/docs/pt/remote-control) de claude.ai. Executá-lo enquanto desconectado imprime que Remote Control requer uma assinatura claude.ai e diz como conectar; antes da v2.1.206 relatava `Unknown command: /remote-control`. Alias: `/rc` |

134| `/remote-env` | Escolha o [ambiente na nuvem](/docs/pt/cloud-environments#select-an-environment-from-the-cli) padrão para sessões na nuvem que você inicia a partir da CLI |134| `/remote-env` | Escolha o [ambiente na nuvem](/docs/pt/cloud-environments#select-an-environment-from-the-cli) padrão para sessões na nuvem que você inicia a partir da CLI |

135| `/rename [name]` | Renomeie a sessão atual e mostre o nome na barra de prompt. Sem um nome, auto-gera um a partir do histórico de conversa. Também disponível em modo não interativo (`-p`); requer Claude Code v2.1.205 ou posterior. De cada superfície de renomeação, incluindo claude.ai e o aplicativo de desktop, Claude Code substitui caracteres de controle e invisíveis no novo nome com espaços e limita o nome a 200 caracteres. Se o nome estiver vazio uma vez que caracteres invisíveis são removidos, Claude Code o rejeita e mostra `That name is empty once invisible characters are removed. Usage: /rename <name>`. A substituição de caracteres e limite de comprimento requerem Claude Code v2.1.221 ou posterior. Se outra sessão ativa nesta máquina já usar um nome que você passa, Claude Code aplica [uma variante dele](/docs/pt/sessions#name-your-sessions) |135| `/rename [name]` | Renomeie a sessão atual e mostre o nome na barra de prompt. Sem um nome, auto-gera um a partir do histórico de conversa. Também disponível em modo não interativo (`-p`); requer Claude Code v2.1.205 ou posterior. De cada superfície de renomeação, incluindo claude.ai e o aplicativo de desktop, Claude Code substitui caracteres de controle e invisíveis no novo nome com espaços e limita o nome a 200 caracteres. Se o nome estiver vazio uma vez que caracteres invisíveis são removidos, Claude Code o rejeita e mostra `That name is empty once invisible characters are removed. Usage: /rename <name>`. A substituição de caracteres e limite de comprimento requerem Claude Code v2.1.221 ou posterior |

136| `/resume [session]` | Retome uma conversa por ID ou nome, ou abra o seletor de sessão. [Sessões em segundo plano](/docs/pt/agent-view) aparecem no seletor marcadas com `bg`. Retomar uma que ainda está em execução, do seletor ou por ID ou nome, [abre essa sessão](/docs/pt/sessions#resume-a-running-background-session): sua conversa atual vai para segundo plano e este terminal se anexa à em execução. Pressione `←` em um prompt vazio para retornar à visualização de agente, que também lista a conversa que você deixou. Antes da v2.1.285, Claude Code recusava e dizia para abrir a sessão com `claude attach` ou pará-la primeiro. Alias: `/continue` |136| `/resume [session]` | Retome uma conversa por ID ou nome, ou abra o seletor de sessão. [Sessões em segundo plano](/docs/pt/agent-view) aparecem no seletor marcadas com `bg`. Retomar uma que ainda está em execução, do seletor ou por ID ou nome, [abre essa sessão](/docs/pt/sessions#resume-a-running-background-session): sua conversa atual vai para segundo plano e este terminal se anexa à em execução. Pressione `←` em um prompt vazio para retornar à visualização de agente, que também lista a conversa que você deixou. Antes da v2.1.285, Claude Code recusava e dizia para abrir a sessão com `claude attach` ou pará-la primeiro. Alias: `/continue` |

137| `/review [low\|medium\|high\|xhigh\|max\|ultra] [--fix] [--comment] [--max-findings n\|all\|default] [pr#\|branch\|path]` | Alias de [`/code-review`](/docs/pt/code-review#review-a-diff-locally): revisa o diff atual, ou um número de PR, branch ou caminho que você passa, como `/review 1234`, e aceita os mesmos níveis de esforço e flags. Sem um nível dado, a revisão reutiliza o último nível `low` através `max` que você digitou; consulte [Revise um diff localmente](/docs/pt/code-review#review-a-diff-locally) para as regras exatas. Para uma revisão na nuvem profunda, use [`/code-review ultra`](/docs/pt/ultrareview). Antes da v2.1.223, `/review` era um comando separado que executava uma revisão de uma única passagem, somente leitura de um pull request GitHub por número, listando PRs abertos para escolher quando executado sem argumento; de v2.1.186 através v2.1.201, executava o mesmo mecanismo multi-agente que `/code-review medium` |137| `/review [low\|medium\|high\|xhigh\|max\|ultra] [--fix] [--comment] [--max-findings n\|all\|default] [pr#\|branch\|path]` | Alias de [`/code-review`](/docs/pt/code-review#review-a-diff-locally): revisa o diff atual, ou um número de PR, branch ou caminho que você passa, como `/review 1234`, e aceita os mesmos níveis de esforço e flags. Sem um nível dado, a revisão reutiliza o último nível `low` através `max` que você digitou; consulte [Revise um diff localmente](/docs/pt/code-review#review-a-diff-locally) para as regras exatas. Para uma revisão na nuvem profunda, use [`/code-review ultra`](/docs/pt/ultrareview). Antes da v2.1.223, `/review` era um comando separado que executava uma revisão de uma única passagem, somente leitura de um pull request GitHub por número, listando PRs abertos para escolher quando executado sem argumento; de v2.1.186 através v2.1.201, executava o mesmo mecanismo multi-agente que `/code-review medium` |

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

corporate-launcher.md +3 −4

Details

8 8

9Algumas organizações exigem que cada processo em uma estação de trabalho seja iniciado através de um launcher obrigatório. O launcher aplica a sandbox, controles de rede ou injeção de credenciais das quais a postura de segurança da empresa depende, e um binário que inicia sem isso é uma violação de política.9Algumas organizações exigem que cada processo em uma estação de trabalho seja iniciado através de um launcher obrigatório. O launcher aplica a sandbox, controles de rede ou injeção de credenciais das quais a postura de segurança da empresa depende, e um binário que inicia sem isso é uma violação de política.

10 10

11`CLAUDE_CODE_PROCESS_WRAPPER` inicia cada processo que Claude Code lança a partir de seu próprio binário através do seu launcher: o serviço de fundo, cada sessão que hospeda em [agent view](/docs/pt/agent-view), e os relançamentos do Claude Code após uma atualização. Defina-o como o caminho absoluto do seu launcher, e Claude Code executa o launcher com o comando Claude Code como seus argumentos.11`CLAUDE_CODE_PROCESS_WRAPPER` inicia cada processo que Claude Code lança a partir de seu próprio binário através do seu launcher: o [serviço de fundo](/docs/pt/agent-view#the-supervisor-process), cada sessão que ele hospeda em [agent view](/docs/pt/agent-view), e os relançamentos do Claude Code após uma atualização. Defina-o como o caminho absoluto do seu launcher, e Claude Code executa o launcher com o comando Claude Code como seus argumentos.

12 12

13Um launcher que envolve o comando `claude` no seu `PATH` não consegue alcançar o serviço de fundo ou as sessões que ele hospeda, porque eles iniciam a partir do caminho direto do binário sem consultar `claude`.13Um launcher que envolve o comando `claude` no seu `PATH` não consegue alcançar o serviço de fundo ou as sessões que ele hospeda, porque eles iniciam a partir do caminho direto do binário sem consultar `claude`.

14 14

39 39

40Os seguintes processos não iniciam através do launcher:40Os seguintes processos não iniciam através do launcher:

41 41

42* Um [serviço de fundo instalado](/docs/pt/agent-view#the-supervisor-process) cuja unidade foi escrita antes do launcher ser configurado: `launchd` ou `systemd` inicia esse processo a partir de seu arquivo de unidade. `/status` e `claude daemon status` avisam quando o serviço em execução e o launcher configurado não correspondem, e as sessões que o serviço gera ainda iniciam através do launcher uma vez que o serviço reinicia com a variável em suas configurações.

43* Uma sessão que você inicia você mesmo em um terminal, que executa da forma como você a invocou. Para cobrir essas sessões, coloque um script chamado `claude` em um diretório anterior no `PATH` que executa seu launcher com o binário real; não substitua o symlink gerenciado. O serviço de fundo e suas sessões iniciam sem uma consulta `PATH`, então os dois launchers não se empilham lá.42* Uma sessão que você inicia você mesmo em um terminal, que executa da forma como você a invocou. Para cobrir essas sessões, coloque um script chamado `claude` em um diretório anterior no `PATH` que executa seu launcher com o binário real; não substitua o symlink gerenciado. O serviço de fundo e suas sessões iniciam sem uma consulta `PATH`, então os dois launchers não se empilham lá.

44* O primeiro processo de um deep link `claude-cli://`, que o manipulador de protocolo do sistema operacional inicia diretamente. Tudo que essa sessão inicia em segundo plano depois executa através do launcher. Para fechar esse caminho completamente, [impeça o registro do manipulador](/docs/pt/deep-links#registration-and-supported-platforms) com a configuração `disableDeepLinkRegistration`.43* O primeiro processo de um deep link `claude-cli://`, que o manipulador de protocolo do sistema operacional inicia diretamente. Tudo que essa sessão inicia em segundo plano depois executa através do launcher. Para fechar esse caminho completamente, [impeça o registro do manipulador](/docs/pt/deep-links#registration-and-supported-platforms) com a configuração `disableDeepLinkRegistration`.

45* O relançamento que `--worktree` combinado com `--tmux` realiza: o multiplexador de terminal inicia esse painel, não o binário do Claude Code.44* O relançamento que `--worktree` combinado com `--tmux` realiza: o multiplexador de terminal inicia esse painel, não o binário do Claude Code.

104 </Step>103 </Step>

105 104

106 <Step title="Reinicie o serviço de fundo e suas sessões">105 <Step title="Reinicie o serviço de fundo e suas sessões">

107 Um serviço de fundo em execução e quaisquer sessões `claude` abertas leem a variável uma vez na inicialização, então continuam lançando processos sem envolvimento até serem reiniciados. Execute `claude daemon stop --any` para parar o serviço sob demanda; o próximo comando que o necessita, como `claude agents`, inicia um envolvido. Um [serviço instalado](/docs/pt/agent-view#the-supervisor-process) leva `claude daemon stop` sem `--any`. Então reinicie suas sessões `claude` abertas.106 Um serviço de fundo em execução e quaisquer sessões `claude` abertas leem a variável uma vez na inicialização, então continuam lançando processos sem envolvimento até serem reiniciados. Execute `claude daemon stop --any` para parar o serviço sob demanda. O próximo comando que o necessita, como `claude agents`, inicia um envolvido. Então reinicie suas sessões `claude` abertas.

108 107

109 Em máquinas que você não pode reiniciar manualmente, a primeira sessão iniciada após o push de configurações aposenta um serviço sob demanda sem envolvimento restante automaticamente. Uma máquina onde nenhuma nova sessão inicia mantém seu serviço sem envolvimento até que uma o faça, e um serviço instalado sempre precisa do reinício nesta etapa.108 Em máquinas que você não pode reiniciar manualmente, a primeira sessão iniciada após o push de configurações aposenta um serviço sob demanda sem envolvimento restante automaticamente. Uma máquina onde nenhuma nova sessão inicia mantém seu serviço de fundo sem envolvimento até que uma o faça.

110 </Step>109 </Step>

111 110

112 <Step title="Verifique">111 <Step title="Verifique">

cross-session-messaging.md +1 −1

Details

142 142

143Uma sessão responde ao nome que você define com o comando [`/rename`](/docs/pt/commands) ou a flag [`--name`](/docs/pt/cli-reference#cli-flags). Quando você não define um, Claude Code nomeia a sessão em si. Para uma sessão interativa, esse é o nome mostrado em [listagens de sessões em execução](/docs/pt/sessions#name-your-sessions).143Uma sessão responde ao nome que você define com o comando [`/rename`](/docs/pt/commands) ou a flag [`--name`](/docs/pt/cli-reference#cli-flags). Quando você não define um, Claude Code nomeia a sessão em si. Para uma sessão interativa, esse é o nome mostrado em [listagens de sessões em execução](/docs/pt/sessions#name-your-sessions).

144 144

145Quando você renomeia uma sessão, ou inicia ou retoma uma interativa, com um nome que outra sessão ao vivo nesta máquina já usa, Claude Code deixa o nome com a sessão que já o tem e [renomeia o seu para uma variante](/docs/pt/sessions#name-your-sessions). Sessões ainda podem compartilhar um nome, por exemplo quando uma delas executa uma versão anterior de Claude Code ou o nome compartilhado é um que Claude Code gerou. A menos que essa sessão esteja conectada a Remote Control, Claude Code mostra o diretório de trabalho de cada sessão local na saída `/list-agents`, então você pode distinguir sessões com mesmo nome quando executam em diretórios diferentes. Claude endereça a mensagem de uma das duas formas, dependendo de quantas sessões ao vivo respondem ao nome:145A menos que essa sessão esteja conectada a Remote Control, Claude Code mostra o diretório de trabalho de cada sessão local na saída `/list-agents`, então você pode distinguir sessões com mesmo nome quando executam em diretórios diferentes. Claude endereça a mensagem de uma das duas formas, dependendo de quantas sessões ao vivo respondem ao nome:

146 146

147* **Uma sessão responde ao nome**: Claude Code entrega a mensagem apenas no nome.147* **Uma sessão responde ao nome**: Claude Code entrega a mensagem apenas no nome.

148* **Várias sessões compartilham o nome, ou Claude Code não conseguiu verificar em todos os lugares onde suas sessões executam**: Claude adiciona um identificador curto a cada linha de sua listagem e usa o identificador no endereço.148* **Várias sessões compartilham o nome, ou Claude Code não conseguiu verificar em todos os lugares onde suas sessões executam**: Claude adiciona um identificador curto a cada linha de sua listagem e usa o identificador no endereço.

desktop.md +30 −4

Details

400 400

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

402 402

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

404 404

405Para incluir arquivos gitignored como `.env` em novos worktrees, crie um [arquivo `.worktreeinclude`](/docs/pt/worktrees#copy-gitignored-files-into-worktrees) na raiz do seu projeto.405* **Sessões locais**: defina **Worktree location** em **Settings > Claude Code**

406* **Sessões SSH**: defina **Worktree folder** na [conexão SSH](#choose-where-ssh-session-worktrees-go)

407

408Você também pode definir um **Branch prefix** em **Settings > Claude Code**. O Desktop o adiciona antes de cada nome de branch de worktree, o que é útil para manter organizados os branches criados por Claude.

409

410Para remover um worktree quando terminar, passe o mouse sobre a sessão na barra lateral e clique no ícone de arquivo. Para ter sessões se arquivarem automaticamente quando seu pull request for mesclado ou fechado, ative **Auto-archive after PR merge or close** em **Settings > Claude Code**. O arquivamento automático se aplica apenas a sessões locais que terminaram de executar.

411

412Para incluir arquivos gitignored como `.env` em novos worktrees, crie um [arquivo `.worktreeinclude`](/docs/pt/worktrees#copy-gitignored-files-into-worktrees) na raiz do seu projeto. Veja [O que os worktrees compartilham com o checkout principal](/docs/pt/worktrees#what-worktrees-share-with-the-main-checkout) para saber de onde uma sessão de worktree lê as configurações do projeto, hooks e skills.

406 413

407<Note>414<Note>

408 O isolamento de sessão requer [Git](https://git-scm.com/downloads). A maioria dos Macs inclui Git por padrão. Execute `git --version` no Terminal para verificar; se imprimir um número de versão, Git está instalado. Se você encontrar erros de Git, peça a Claude na aba [Cowork](https://claude.com/product/cowork) para ajudar a solucionar problemas de sua configuração.415 O isolamento de sessão requer [Git](https://git-scm.com/downloads). A maioria dos Macs inclui Git por padrão. Execute `git --version` no Terminal para verificar; se imprimir um número de versão, Git está instalado. Se você encontrar erros de Git, peça a Claude na aba [Cowork](https://claude.com/product/cowork) para ajudar a solucionar problemas de sua configuração.

811* **SSH host**: `user@hostname` ou um host definido em `~/.ssh/config`818* **SSH host**: `user@hostname` ou um host definido em `~/.ssh/config`

812* **SSH port**: padrão é 22 se deixado vazio, ou usa a porta do seu SSH config819* **SSH port**: padrão é 22 se deixado vazio, ou usa a porta do seu SSH config

813* **SSH key (optional)**: caminho para sua chave privada, como `~/.ssh/id_ed25519`. Deixe vazio para usar seu SSH config ou agente SSH.820* **SSH key (optional)**: caminho para sua chave privada, como `~/.ssh/id_ed25519`. Deixe vazio para usar seu SSH config ou agente SSH.

821* **Worktree folder**: uma pasta na máquina remota, como `~/worktrees`, onde novas sessões criam seus worktrees. Deixe vazio para usar o [padrão da máquina remota](#choose-where-ssh-session-worktrees-go).

814 822

815Uma vez adicionada, a conexão aparece em **SSH** no menu suspenso de ambiente. Selecione-a para iniciar uma sessão naquela máquina. Claude é executado na máquina remota com acesso aos seus arquivos e ferramentas.823Uma vez adicionada, a conexão aparece em **SSH** no menu suspenso de ambiente. Selecione-a para iniciar uma sessão naquela máquina. Claude é executado na máquina remota com acesso aos seus arquivos e ferramentas.

816 824

817A máquina remota deve executar Linux ou macOS. O aplicativo desktop instala Claude Code na máquina remota automaticamente na primeira vez que você se conecta. Uma vez conectado, sessões SSH suportam modos de permissão, conectores, plugins e MCP servers.825A máquina remota deve executar Linux ou macOS. O aplicativo desktop instala Claude Code na máquina remota automaticamente na primeira vez que você se conecta. Uma vez conectado, sessões SSH suportam modos de permissão, conectores, plugins e MCP servers.

818 826

827<h4 id="choose-where-ssh-session-worktrees-go">

828 Escolher onde ficam os worktrees das sessões SSH

829</h4>

830

831A menos que sua organização restrinja quais pastas as sessões podem usar, novas sessões SSH criam seus [worktrees](#work-in-parallel-with-sessions) no primeiro destes que estiver definido:

832

8331. **Worktree folder** na conexão SSH

8342. [`worktree.location`](/docs/pt/settings-reference#worktree-location) em `~/.claude/settings.json` na máquina remota

8353. `<project-root>/.claude/worktrees/`, o padrão

836

837Cada projeto recebe sua própria subpasta na pasta que você definir, então com `~/worktrees` o caminho de um worktree é `~/worktrees/<project>-<id>/<worktree-name>`. Se a pasta que você definir estiver dentro do projeto, o Desktop a ignora para esse projeto e usa o padrão.

838

839Para definir **Worktree folder** em uma conexão que você adicionou anteriormente ou em uma que sua organização gerencia, passe o mouse sobre ela no menu suspenso de ambiente e clique no ícone de engrenagem.

840

841O campo requer Claude Desktop v1.44121.0 ou posterior. Se sua organização restringe quais pastas as sessões podem usar, o Desktop oculta o campo e mantém os worktrees dentro do projeto.

842

819<h4 id="open-an-ssh-session-from-a-link">843<h4 id="open-an-ssh-session-from-a-link">

820 Abrir uma sessão SSH a partir de um link844 Abrir uma sessão SSH a partir de um link

821</h4>845</h4>

869 Pre-configure SSH connections for your team893 Pre-configure SSH connections for your team

870</h4>894</h4>

871 895

872Administradores podem distribuir conexões SSH para membros da equipe definindo `sshConfigs` nas [configurações gerenciadas](/docs/pt/managed-settings). Conexões definidas desta forma aparecem no menu suspenso de ambiente de cada usuário automaticamente e são mostradas como gerenciadas, para que os usuários possam selecioná-las mas não possam editá-las ou deletá-las no aplicativo.896Administradores podem distribuir conexões SSH para membros da equipe definindo `sshConfigs` nas [configurações gerenciadas](/docs/pt/managed-settings). Conexões definidas desta forma aparecem no menu suspenso de ambiente de cada usuário automaticamente e são mostradas como gerenciadas. Os usuários podem selecioná-las e [definir sua própria **Worktree folder**](#choose-where-ssh-session-worktrees-go) para elas, mas não podem editar mais nada nem deletá-las no aplicativo.

873 897

874O exemplo a seguir pré-configura uma única conexão:898O exemplo a seguir pré-configura uma única conexão:

875 899

935 O formulário OpenTelemetry para Cowork em **Monitoring** nas [configurações de Dados e privacidade](https://claude.ai/admin-settings/data-privacy-controls) do console de administração se aplica apenas a sessões Cowork. Em uma sessão Cowork nesta máquina, o aplicativo desktop passa esse coletor para Claude Code como variáveis de ambiente `OTEL_*`, portanto o formulário entra em vigor mesmo que Claude Code nessa sessão [nunca busque configurações do console de administração](#managed-settings).959 O formulário OpenTelemetry para Cowork em **Monitoring** nas [configurações de Dados e privacidade](https://claude.ai/admin-settings/data-privacy-controls) do console de administração se aplica apenas a sessões Cowork. Em uma sessão Cowork nesta máquina, o aplicativo desktop passa esse coletor para Claude Code como variáveis de ambiente `OTEL_*`, portanto o formulário entra em vigor mesmo que Claude Code nessa sessão [nunca busque configurações do console de administração](#managed-settings).

936 960

937 Para exportar telemetria de sessões da aba Code, defina `CLAUDE_CODE_ENABLE_TELEMETRY` e as variáveis `OTEL_*` no bloco `env` de suas configurações gerenciadas de Claude Code, conforme mostrado em [configuração de administrador para monitoramento](/docs/pt/monitoring-usage#administrator-configuration). Sessões locais, na nuvem e SSH leem [configurações gerenciadas de diferentes fontes](#managed-settings). Para os hosts que uma sessão na nuvem pode alcançar, veja [acesso à rede](/docs/pt/cloud-environments#network-access). Para o `service.name` que sessões da aba Code relatam, veja [informações de serviço](/docs/pt/monitoring-usage#service-information).961 Para exportar telemetria de sessões da aba Code, defina `CLAUDE_CODE_ENABLE_TELEMETRY` e as variáveis `OTEL_*` no bloco `env` de suas configurações gerenciadas de Claude Code, conforme mostrado em [configuração de administrador para monitoramento](/docs/pt/monitoring-usage#administrator-configuration). Sessões locais, na nuvem e SSH leem [configurações gerenciadas de diferentes fontes](#managed-settings). Para os hosts que uma sessão na nuvem pode alcançar, veja [acesso à rede](/docs/pt/cloud-environments#network-access). Para o `service.name` que sessões da aba Code relatam, veja [informações de serviço](/docs/pt/monitoring-usage#service-information).

962

963 Para descobrir em qual máquina remota uma sessão SSH foi executada, veja [Atribuir telemetria a sessões SSH do Desktop](/docs/pt/monitoring-usage#attribute-telemetry-to-desktop-ssh-sessions).

938</Note>964</Note>

939 965

940<h3 id="managed-settings">966<h3 id="managed-settings">

951| `browserExternalPageTools` | defina como `"disabled"` para impedir Claude de usar ferramentas para ler ou agir em páginas externas no [painel Browser](#browse-external-sites). Os usuários ainda podem navegar para sites externos por conta própria, e as visualizações do servidor de desenvolvimento local não são afetadas. |977| `browserExternalPageTools` | defina como `"disabled"` para impedir Claude de usar ferramentas para ler ou agir em páginas externas no [painel Browser](#browse-external-sites). Os usuários ainda podem navegar para sites externos por conta própria, e as visualizações do servidor de desenvolvimento local não são afetadas. |

952| `disableMobileSimulatorTools` | defina como `true` para bloquear as ferramentas de Claude para controlar e capturar dispositivos no [painel iOS Simulator](/docs/pt/desktop-ios-simulator#turn-off-simulator-access). O painel permanece utilizável para os toques do próprio usuário; apenas o acesso de Claude é removido. O valor deve ser o booleano JSON `true`; a string `"true"` é ignorada. |978| `disableMobileSimulatorTools` | defina como `true` para bloquear as ferramentas de Claude para controlar e capturar dispositivos no [painel iOS Simulator](/docs/pt/desktop-ios-simulator#turn-off-simulator-access). O painel permanece utilizável para os toques do próprio usuário; apenas o acesso de Claude é removido. O valor deve ser o booleano JSON `true`; a string `"true"` é ignorada. |

953| `disableBrowserExternalNavigation` | defina como `true` para desativar a navegação externa no [painel Browser](#browse-external-sites) inteiramente. Nem usuários nem Claude podem navegar para sites externos, e as visualizações do servidor localhost dev não são afetadas. O valor deve ser o booleano JSON `true`; a string `"true"` é ignorada. |979| `disableBrowserExternalNavigation` | defina como `true` para desativar a navegação externa no [painel Browser](#browse-external-sites) inteiramente. Nem usuários nem Claude podem navegar para sites externos, e as visualizações do servidor localhost dev não são afetadas. O valor deve ser o booleano JSON `true`; a string `"true"` é ignorada. |

954| `sshConfigs` | pré-configure [conexões SSH](#pre-configure-ssh-connections-for-your-team) que aparecem no dropdown de ambiente. Usuários não podem editar ou excluir conexões gerenciadas. |980| `sshConfigs` | pré-configure [conexões SSH](#pre-configure-ssh-connections-for-your-team) que aparecem no dropdown de ambiente. Usuários não podem excluir conexões gerenciadas nem editar nada além de sua própria **Worktree folder**. |

955| `sshHostAllowlist` | restrinja [sessões SSH](#restrict-which-ssh-hosts-users-can-connect-to) a hosts cujo nome de host resolvido corresponde a um desses padrões. Lido apenas de configurações gerenciadas. |981| `sshHostAllowlist` | restrinja [sessões SSH](#restrict-which-ssh-hosts-users-can-connect-to) a hosts cujo nome de host resolvido corresponde a um desses padrões. Lido apenas de configurações gerenciadas. |

956| `disableDesktopLocalSessions` | defina como `true` para desativar [sessões Code que são executadas no dispositivo](#local-sessions-on-managed-devices), deixando sessões SSH para outros hosts e sessões na nuvem disponíveis. O valor deve ser o booleano JSON `true`. Lido apenas de configurações gerenciadas. Requer Claude Desktop v1.37937.0 ou posterior. |982| `disableDesktopLocalSessions` | defina como `true` para desativar [sessões Code que são executadas no dispositivo](#local-sessions-on-managed-devices), deixando sessões SSH para outros hosts e sessões na nuvem disponíveis. O valor deve ser o booleano JSON `true`. Lido apenas de configurações gerenciadas. Requer Claude Desktop v1.37937.0 ou posterior. |

957| `disableSshSavedPasswords` | defina como `true` para impedir que o Desktop ofereça lembrar senhas SSH e que use ou mostre as que salvou anteriormente. Ativá-la não as exclui. Lido apenas de configurações gerenciadas. Requer Claude Desktop v1.49585.0 ou posterior. |983| `disableSshSavedPasswords` | defina como `true` para impedir que o Desktop ofereça lembrar senhas SSH e que use ou mostre as que salvou anteriormente. Ativá-la não as exclui. Lido apenas de configurações gerenciadas. Requer Claude Desktop v1.49585.0 ou posterior. |

env-vars.md +5 −5

Details

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

211| `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS` | Timeout de travamento em milissegundos para subagentes. Também abrange [agentes de workflow](/docs/pt/workflows#when-an-agent-stalls-and-restarts) no Claude Code v2.1.286 ou posterior. Padrão `600000` (10 minutos); se você aumentar `CLAUDE_STREAM_IDLE_TIMEOUT_MS` enquanto o watchdog de stream estiver ativo, o padrão aumenta junto, conforme descrito em [Lidar com respostas de API lentas ou travadas](/docs/pt/agent-sdk/typescript#handle-slow-or-stalled-api-responses) |211| `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS` | Timeout de travamento em milissegundos para subagentes. Também abrange [agentes de workflow](/docs/pt/workflows#when-an-agent-stalls-and-restarts) no Claude Code v2.1.286 ou posterior. Padrão `600000` (10 minutos); se você aumentar `CLAUDE_STREAM_IDLE_TIMEOUT_MS` enquanto o watchdog de stream estiver ativo, o padrão aumenta junto, conforme descrito em [Lidar com respostas de API lentas ou travadas](/docs/pt/agent-sdk/typescript#handle-slow-or-stalled-api-responses) |

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

213| `CLAUDE_AUTO_BACKGROUND_TASKS` | Defina como `1` para forçar a ativação do envio automático para segundo plano de tarefas de agente de longa duração. Quando ativado, os subagentes são movidos para segundo plano após cerca de dois minutos de execução. Também ativa o [envio automático para segundo plano de chamadas longas de ferramentas MCP](/docs/pt/mcp#automatic-backgrounding-of-long-tool-calls) no modo não interativo no Claude Code v2.1.212 ou posterior |213| `CLAUDE_AUTO_BACKGROUND_TASKS` | Defina como `1` para forçar a ativação do envio automático para segundo plano de tarefas de agente de longa duração. Quando ativado, um [subagente](/docs/pt/sub-agents#run-subagents-in-foreground-or-background) passa para o segundo plano após ser executado por aproximadamente dois minutos. Se o Claude enfileirou uma chamada de ferramenta, como uma edição de arquivo, atrás do subagente, o subagente termina em primeiro plano antes que essa chamada comece. Também ativa o [envio automático para segundo plano de chamadas longas de ferramentas MCP](/docs/pt/mcp#automatic-backgrounding-of-long-tool-calls) no modo não interativo no Claude Code v2.1.212 ou posterior |

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

215| `CLAUDE_AX_SCREEN_READER` | Defina como `1` para renderizar uma saída adequada a leitores de tela: texto simples sem bordas decorativas nem animações. Defina como `0` para forçar a desativação do modo de leitor de tela mesmo quando [`axScreenReader`](/docs/pt/settings-reference#axscreenreader) for `true`. A flag [`--ax-screen-reader`](/docs/pt/cli-reference#cli-flags) tem precedência. Requer o Claude Code v2.1.181 ou posterior |215| `CLAUDE_AX_SCREEN_READER` | Defina como `1` para renderizar uma saída adequada a leitores de tela: texto simples sem bordas decorativas nem animações. Defina como `0` para forçar a desativação do modo de leitor de tela mesmo quando [`axScreenReader`](/docs/pt/settings-reference#axscreenreader) for `true`. A flag [`--ax-screen-reader`](/docs/pt/cli-reference#cli-flags) tem precedência. Requer o Claude Code v2.1.181 ou posterior |

216| `CLAUDE_AX_STARTUP_QUIET_MS` | No [modo de leitor de tela](/docs/pt/accessibility), por quantos milissegundos o Claude Code retém a primeira renderização da interface após a linha de confirmação de inicialização, para que seu leitor de tela possa ler a linha por completo antes que uma nova saída a interrompa. Padrão `3000`. Defina `0` para renderizar imediatamente. O Claude Code limita a retenção a `600000` (10 minutos). Seu primeiro pressionamento de tecla encerra a retenção antecipadamente. Requer o Claude Code v2.1.217 ou posterior |216| `CLAUDE_AX_STARTUP_QUIET_MS` | No [modo de leitor de tela](/docs/pt/accessibility), por quantos milissegundos o Claude Code retém a primeira renderização da interface após a linha de confirmação de inicialização, para que seu leitor de tela possa ler a linha por completo antes que uma nova saída a interrompa. Padrão `3000`. Defina `0` para renderizar imediatamente. O Claude Code limita a retenção a `600000` (10 minutos). Seu primeiro pressionamento de tecla encerra a retenção antecipadamente. Requer o Claude Code v2.1.217 ou posterior |

285| `CLAUDE_CODE_DISABLE_REFUSAL_FALLBACK` | Defina como `1` para desativar a [troca automática de modelo quando um classificador de segurança sinaliza uma requisição](/docs/pt/model-config#automatic-model-fallback), o comportamento que a configuração [`switchModelsOnFlag`](/docs/pt/settings-reference#switchmodelsonflag) controla |285| `CLAUDE_CODE_DISABLE_REFUSAL_FALLBACK` | Defina como `1` para desativar a [troca automática de modelo quando um classificador de segurança sinaliza uma requisição](/docs/pt/model-config#automatic-model-fallback), o comportamento que a configuração [`switchModelsOnFlag`](/docs/pt/settings-reference#switchmodelsonflag) controla |

286| `CLAUDE_CODE_DISABLE_STRUCTURED_OUTPUTS` | Defina como `1` para impedir que o Claude Code envie o campo de saída estruturada `output_config.format` e o valor de `anthropic-beta` associado a ele, para um [gateway de LLM](/docs/pt/llm-gateway-protocol#feature-pass-through) cujo upstream os rejeita. Isso mantém ativados os outros recursos de pré-lançamento que [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS`](/docs/pt/llm-gateway-protocol#disable-pre-release-capabilities) desativa. Requer o Claude Code v2.1.288 ou posterior |286| `CLAUDE_CODE_DISABLE_STRUCTURED_OUTPUTS` | Defina como `1` para impedir que o Claude Code envie o campo de saída estruturada `output_config.format` e o valor de `anthropic-beta` associado a ele, para um [gateway de LLM](/docs/pt/llm-gateway-protocol#feature-pass-through) cujo upstream os rejeita. Isso mantém ativados os outros recursos de pré-lançamento que [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS`](/docs/pt/llm-gateway-protocol#disable-pre-release-capabilities) desativa. Requer o Claude Code v2.1.288 ou posterior |

287| `CLAUDE_CODE_DISABLE_SUBSTITUTION_RM_PROMPT` | Defina como `1` para desativar a verificação de [caminhos críticos](/docs/pt/permission-modes#critical-paths) para um `rm` recursivo cujo destino é inteiramente a saída de uma substituição de comando, como `rm -rf "$(pwd)"`. As outras verificações de caminhos críticos continuam sendo executadas. Defina-a no ambiente que inicia o Claude Code, pois o Claude Code ignora uma cópia entregue por meio de um bloco `env` de configurações. Requer o Claude Code v2.1.281 ou posterior |287| `CLAUDE_CODE_DISABLE_SUBSTITUTION_RM_PROMPT` | Defina como `1` para desativar a verificação de [caminhos críticos](/docs/pt/permission-modes#critical-paths) para um `rm` recursivo cujo destino é inteiramente a saída de uma substituição de comando, como `rm -rf "$(pwd)"`. As outras verificações de caminhos críticos continuam sendo executadas. Defina-a no ambiente que inicia o Claude Code, pois o Claude Code ignora uma cópia entregue por meio de um bloco `env` de configurações. Requer o Claude Code v2.1.281 ou posterior |

288| `CLAUDE_CODE_DISABLE_TERMINAL_TITLE` | Defina como `1` para desativar as atualizações automáticas do título do terminal com base no contexto da conversa. Isso também ignora a requisição em segundo plano ao modelo pequeno/rápido que [gera um título para a sessão](/docs/pt/sessions#name-your-sessions) |288| `CLAUDE_CODE_DISABLE_TERMINAL_TITLE` | Defina como `1` para desativar as atualizações automáticas do título do terminal com base no contexto da conversa. Isso também pula a requisição em segundo plano ao modelo pequeno/rápido que [gera um título de sessão](/docs/pt/sessions#name-your-sessions) e desativa os [relatórios de status para o seu terminal](/docs/pt/terminal-config#see-session-status-in-your-terminal) |

289| `CLAUDE_CODE_DISABLE_THINKING` | Defina como `1` para omitir completamente o parâmetro `thinking` das requisições de API. Esta é uma opção de compatibilidade para proxies e gateways que rejeitam o parâmetro. Em modelos que pensam por padrão, omitir o parâmetro significa que o modelo ainda pode pensar. Para desativar explicitamente o [pensamento estendido](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) na API da Anthropic, use `MAX_THINKING_TOKENS=0`. Nenhuma das duas variáveis desativa o pensamento no Opus 5.5, no Sonnet 5.5, no Haiku 5.5 ou nos modelos Fable, nos quais o pensamento não pode ser desativado. Em [provedores de terceiros](/docs/pt/third-party-integrations), `MAX_THINKING_TOKENS=0` também omite o parâmetro, então as duas variáveis se comportam da mesma forma nesses casos |289| `CLAUDE_CODE_DISABLE_THINKING` | Defina como `1` para omitir completamente o parâmetro `thinking` das requisições de API. Esta é uma opção de compatibilidade para proxies e gateways que rejeitam o parâmetro. Em modelos que pensam por padrão, omitir o parâmetro significa que o modelo ainda pode pensar. Para desativar explicitamente o [pensamento estendido](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) na API da Anthropic, use `MAX_THINKING_TOKENS=0`. Nenhuma das duas variáveis desativa o pensamento no Opus 5.5, no Sonnet 5.5, no Haiku 5.5 ou nos modelos Fable, nos quais o pensamento não pode ser desativado. Em [provedores de terceiros](/docs/pt/third-party-integrations), `MAX_THINKING_TOKENS=0` também omite o parâmetro, então as duas variáveis se comportam da mesma forma nesses casos |

290| `CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT` | Defina como `1` para ignorar a [compactação automática](/docs/pt/costs#reduce-token-usage) proativa quando o Claude Code não reconhece o ID do modelo, como um alias de [gateway de LLM](/docs/pt/llm-gateway). Sem esta variável, o Claude Code compacta na janela de contexto que presume para o ID. `CLAUDE_CODE_MAX_CONTEXT_TOKENS` pode corrigir a janela presumida; consulte [Corrigir a janela para um gateway ou ID de modelo personalizado](/docs/pt/model-config#correct-the-window-for-a-gateway-or-custom-model-id) para saber quando cada variável se aplica. Requer o Claude Code v2.1.223 ou posterior |290| `CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT` | Defina como `1` para ignorar a [compactação automática](/docs/pt/costs#reduce-token-usage) proativa quando o Claude Code não reconhece o ID do modelo, como um alias de [gateway de LLM](/docs/pt/llm-gateway). Sem esta variável, o Claude Code compacta na janela de contexto que presume para o ID. `CLAUDE_CODE_MAX_CONTEXT_TOKENS` pode corrigir a janela presumida; consulte [Corrigir a janela para um gateway ou ID de modelo personalizado](/docs/pt/model-config#correct-the-window-for-a-gateway-or-custom-model-id) para saber quando cada variável se aplica. Requer o Claude Code v2.1.223 ou posterior |

291| `CLAUDE_CODE_DISABLE_VIRTUAL_SCROLL` | Defina como `1` para desativar a rolagem virtual na [renderização em tela cheia](/docs/pt/fullscreen) e renderizar todas as mensagens da transcrição. Use se a rolagem no modo de tela cheia mostrar regiões em branco onde as mensagens deveriam aparecer |291| `CLAUDE_CODE_DISABLE_VIRTUAL_SCROLL` | Defina como `1` para desativar a rolagem virtual na [renderização em tela cheia](/docs/pt/fullscreen) e renderizar todas as mensagens da transcrição. Use se a rolagem no modo de tela cheia mostrar regiões em branco onde as mensagens deveriam aparecer |

309| `CLAUDE_CODE_EXIT_AFTER_STOP_DELAY` | Tempo em milissegundos a aguardar depois que o loop de consulta fica ocioso antes de sair automaticamente. Útil para fluxos de trabalho automatizados e scripts que usam o modo SDK |309| `CLAUDE_CODE_EXIT_AFTER_STOP_DELAY` | Tempo em milissegundos a aguardar depois que o loop de consulta fica ocioso antes de sair automaticamente. Útil para fluxos de trabalho automatizados e scripts que usam o modo SDK |

310| `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` | Defina como `1` para ativar as [equipes de agentes](/docs/pt/agent-teams). As equipes de agentes são experimentais e ficam desativadas por padrão |310| `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` | Defina como `1` para ativar as [equipes de agentes](/docs/pt/agent-teams). As equipes de agentes são experimentais e ficam desativadas por padrão |

311| `CLAUDE_CODE_EXTRA_BODY` | Objeto JSON a ser mesclado no nível superior do corpo de cada requisição à API. Útil para passar parâmetros específicos do provedor que o Claude Code não expõe diretamente. Um valor exportado no seu shell também se aplica às [sessões em segundo plano](/docs/pt/agent-view) que você despacha com `claude agents` ou `--bg`. Antes da v2.1.206, as sessões em segundo plano ignoravam um valor exportado no shell e usavam a cópia que o processo supervisor em segundo plano tivesse herdado |311| `CLAUDE_CODE_EXTRA_BODY` | Objeto JSON a ser mesclado no nível superior do corpo de cada requisição à API. Útil para passar parâmetros específicos do provedor que o Claude Code não expõe diretamente. Um valor exportado no seu shell também se aplica às [sessões em segundo plano](/docs/pt/agent-view) que você despacha com `claude agents` ou `--bg`. Antes da v2.1.206, as sessões em segundo plano ignoravam um valor exportado no shell e usavam a cópia que o processo supervisor em segundo plano tivesse herdado |

312| `CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS` | Sobrescreve o limite padrão de tokens para leituras de arquivos. Útil quando você precisa ler arquivos maiores por completo |312| `CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS` | Sobrescreve o limite padrão de tokens para [leituras de arquivos](/docs/pt/tools-reference#large-files), que é de 25.000 tokens. Útil quando você precisa ler arquivos maiores por inteiro. Uma leitura que o Claude faz com o parâmetro `allow_large` pode ultrapassar esse limite quando a janela de contexto tem espaço |

313| `CLAUDE_CODE_FORCE_SESSION_PERSISTENCE` | Defina como `1` para forçar a persistência da transcrição, o histórico de prompts e o registro em `claude agents` mesmo quando este `claude` foi iniciado de dentro de outra sessão do Claude Code. Use quando um valor herdado de `CLAUDE_CODE_CHILD_SESSION`, por exemplo de uma sessão do `screen` ou de um inicializador em segundo plano iniciado primeiro pela ferramenta Bash do Claude Code, fizer com que uma sessão genuinamente de nível superior seja classificada erroneamente como aninhada. A partir da v2.1.178, o Claude Code detecta o caso do tmux automaticamente e ignora o marcador herdado, então o tmux não precisa mais desta variável. Também respeitada na v2.1.169 e anteriores; não tem efeito na v2.1.170 e na v2.1.171, nas quais a detecção de sessão aninhada que ela sobrescreve foi removida |313| `CLAUDE_CODE_FORCE_SESSION_PERSISTENCE` | Defina como `1` para forçar a persistência da transcrição, o histórico de prompts e o registro em `claude agents` mesmo quando este `claude` foi iniciado de dentro de outra sessão do Claude Code. Use quando um valor herdado de `CLAUDE_CODE_CHILD_SESSION`, por exemplo de uma sessão do `screen` ou de um inicializador em segundo plano iniciado primeiro pela ferramenta Bash do Claude Code, fizer com que uma sessão genuinamente de nível superior seja classificada erroneamente como aninhada. A partir da v2.1.178, o Claude Code detecta o caso do tmux automaticamente e ignora o marcador herdado, então o tmux não precisa mais desta variável. Também respeitada na v2.1.169 e anteriores; não tem efeito na v2.1.170 e na v2.1.171, nas quais a detecção de sessão aninhada que ela sobrescreve foi removida |

314| `CLAUDE_CODE_FORCE_STRIKETHROUGH` | Defina como `1` para forçar a renderização tachada de `~~text~~` nas respostas do Claude quando o seu terminal oferece suporte, mas não é detectado automaticamente, como via SSH sem `TERM_PROGRAM` encaminhada. Sem isso, terminais não detectados mostram os marcadores `~~` literais em vez de renderizar o texto como tachado. Requer o Claude Code v2.1.186 ou posterior |314| `CLAUDE_CODE_FORCE_STRIKETHROUGH` | Defina como `1` para forçar a renderização tachada de `~~text~~` nas respostas do Claude quando o seu terminal oferece suporte, mas não é detectado automaticamente, como via SSH sem `TERM_PROGRAM` encaminhada. Sem isso, terminais não detectados mostram os marcadores `~~` literais em vez de renderizar o texto como tachado. Requer o Claude Code v2.1.186 ou posterior |

315| `CLAUDE_CODE_FORCE_SYNC_OUTPUT` | Defina como `1` para forçar a ativação da [saída sincronizada](https://gist.github.com/christianparpart/d8a62cc1ab659194337d73e399004036) do modo privado DEC 2026 quando o seu terminal oferece suporte, mas não é detectado automaticamente. Útil para emuladores como o `eat` do Emacs, que implementam BSU/ESU mas não respondem à sondagem de capacidade. Não tem efeito no tmux. Ao contrário de `CLAUDE_CODE_NO_FLICKER`, que muda para a [renderização em tela cheia](/docs/pt/fullscreen), esta não altera o renderizador |315| `CLAUDE_CODE_FORCE_SYNC_OUTPUT` | Defina como `1` para forçar a ativação da [saída sincronizada](https://gist.github.com/christianparpart/d8a62cc1ab659194337d73e399004036) do modo privado DEC 2026 quando o seu terminal oferece suporte, mas não é detectado automaticamente. Útil para emuladores como o `eat` do Emacs, que implementam BSU/ESU mas não respondem à sondagem de capacidade. Não tem efeito no tmux. Ao contrário de `CLAUDE_CODE_NO_FLICKER`, que muda para a [renderização em tela cheia](/docs/pt/fullscreen), esta não altera o renderizador |

340| `CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION` | Limite de chamadas de [WebSearch](/docs/pt/tools-reference#session-search-limit) (padrão: 200). Quando o Claude atinge o limite, chamadas adicionais de WebSearch retornam um aviso dizendo para continuar com as informações já reunidas. Aceita um número inteiro positivo sem limite superior. Qualquer outro valor é ignorado e o padrão se aplica, portanto o limite pode ser aumentado, mas não desativado. Requer o Claude Code v2.1.212 ou posterior |340| `CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION` | Limite de chamadas de [WebSearch](/docs/pt/tools-reference#session-search-limit) (padrão: 200). Quando o Claude atinge o limite, chamadas adicionais de WebSearch retornam um aviso dizendo para continuar com as informações já reunidas. Aceita um número inteiro positivo sem limite superior. Qualquer outro valor é ignorado e o padrão se aplica, portanto o limite pode ser aumentado, mas não desativado. Requer o Claude Code v2.1.212 ou posterior |

341| `CLAUDE_CODE_MCP_ALLOWLIST_ENV` | Defina como `1` para iniciar servidores MCP stdio apenas com um ambiente básico seguro mais o `env` configurado do servidor, em vez de herdar o ambiente do seu shell |341| `CLAUDE_CODE_MCP_ALLOWLIST_ENV` | Defina como `1` para iniciar servidores MCP stdio apenas com um ambiente básico seguro mais o `env` configurado do servidor, em vez de herdar o ambiente do seu shell |

342| `CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS` | Tempo decorrido em milissegundos antes que uma chamada de ferramenta MCP ainda em execução [passe para uma tarefa em segundo plano](/docs/pt/mcp#automatic-backgrounding-of-long-tool-calls) (padrão: 120000, ou 2 minutos). Defina como `0` para desativar a passagem automática para segundo plano. Requer o Claude Code v2.1.212 ou posterior |342| `CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS` | Tempo decorrido em milissegundos antes que uma chamada de ferramenta MCP ainda em execução [passe para uma tarefa em segundo plano](/docs/pt/mcp#automatic-backgrounding-of-long-tool-calls) (padrão: 120000, ou 2 minutos). Defina como `0` para desativar a passagem automática para segundo plano. Requer o Claude Code v2.1.212 ou posterior |

343| `CLAUDE_CODE_MCP_STARTUP_WAIT_MS` | Por quanto tempo, em milissegundos, o primeiro turno de uma sessão [não interativa](/docs/pt/headless) aguarda servidores MCP que ainda estão se conectando, no lugar da [espera padrão do primeiro turno](/docs/pt/agent-sdk/mcp#connection-timing). Quando definida, a espera abrange todos os servidores pendentes. Defina como `0` para ignorar a espera. Um servidor de [`--permission-prompt-tool`](/docs/pt/cli-reference#cli-flags) mantém sua própria espera de `MCP_TIMEOUT` independentemente do valor. Requer o Claude Code v2.1.274 ou posterior |343| `CLAUDE_CODE_MCP_STARTUP_WAIT_MS` | Quanto tempo, em milissegundos, o primeiro turno de uma sessão [não interativa](/docs/pt/headless) aguarda servidores MCP que ainda estão se conectando, no lugar da [espera padrão do primeiro turno](/docs/pt/agent-sdk/mcp#connection-timing). Quando definida, a espera abrange todos os servidores pendentes; em um [ambiente auto-hospedado](/docs/pt/self-hosted-environments-configuration#connection-timing), altera apenas quanto tempo a espera dura. Defina como `0` para ignorar a espera. Um servidor de [`--permission-prompt-tool`](/docs/pt/cli-reference#cli-flags) mantém sua própria espera de `MCP_TIMEOUT` independentemente do valor. Requer o Claude Code v2.1.274 ou posterior |

344| `CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT` | Timeout de inatividade em milissegundos para chamadas de ferramentas MCP. Quando um servidor MCP stdio, HTTP, SSE, WebSocket ou de [conector do claude.ai](/docs/pt/mcp#use-mcp-servers-from-claude-ai) não envia nenhuma resposta nem notificação de progresso por esse tempo, a chamada de ferramenta é abortada com um erro em vez de aguardar o `MCP_TOOL_TIMEOUT` geral. Sobrescreve os padrões por transporte de 300000 (5 minutos) para servidores de rede e 1800000 (30 minutos) para servidores stdio. Defina como `0` para desativar a verificação de inatividade. Valores abaixo de 1000 são elevados para um segundo, e o valor é limitado ao `MCP_TOOL_TIMEOUT` efetivo. Um `timeout` por servidor em `.mcp.json` de pelo menos 1000 eleva a janela de inatividade desse servidor para pelo menos o valor de `timeout`. Não se aplica a servidores de IDE nem a servidores SDK em processo. Requer o Claude Code v2.1.187 ou posterior. Antes da v2.1.203, os servidores stdio estavam isentos do timeout de inatividade |344| `CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT` | Timeout de inatividade em milissegundos para chamadas de ferramentas MCP. Quando um servidor MCP stdio, HTTP, SSE, WebSocket ou de [conector do claude.ai](/docs/pt/mcp#use-mcp-servers-from-claude-ai) não envia nenhuma resposta nem notificação de progresso por esse tempo, a chamada de ferramenta é abortada com um erro em vez de aguardar o `MCP_TOOL_TIMEOUT` geral. Sobrescreve os padrões por transporte de 300000 (5 minutos) para servidores de rede e 1800000 (30 minutos) para servidores stdio. Defina como `0` para desativar a verificação de inatividade. Valores abaixo de 1000 são elevados para um segundo, e o valor é limitado ao `MCP_TOOL_TIMEOUT` efetivo. Um `timeout` por servidor em `.mcp.json` de pelo menos 1000 eleva a janela de inatividade desse servidor para pelo menos o valor de `timeout`. Não se aplica a servidores de IDE nem a servidores SDK em processo. Requer o Claude Code v2.1.187 ou posterior. Antes da v2.1.203, os servidores stdio estavam isentos do timeout de inatividade |

345| `CLAUDE_CODE_MESSAGING_SOCKET` | Definida pelo Claude Code, não por você: em sessões que vinculam um [socket de caixa de entrada](/docs/pt/cross-session-messaging#the-sessions-inbox-socket), o Claude Code exporta o caminho desse socket para hooks e comandos Bash quando vincula o socket. Em uma sessão que começa com mensagens ativadas, o Claude Code vincula o socket antes de qualquer hook ser executado. Outras sessões na máquina entregam mensagens a este caminho. Cada sessão exporta seu próprio socket em vez de um herdado de um processo pai, e as mensagens que chegam nele passam pelos [controles de entrada](/docs/pt/cross-session-messaging#control-inbound-messages) da sessão. Blocos `env` de configurações não podem defini-la. Requer o Claude Code v2.1.224 ou posterior |345| `CLAUDE_CODE_MESSAGING_SOCKET` | Definida pelo Claude Code, não por você: em sessões que vinculam um [socket de caixa de entrada](/docs/pt/cross-session-messaging#the-sessions-inbox-socket), o Claude Code exporta o caminho desse socket para hooks e comandos Bash quando vincula o socket. Em uma sessão que começa com mensagens ativadas, o Claude Code vincula o socket antes de qualquer hook ser executado. Outras sessões na máquina entregam mensagens a este caminho. Cada sessão exporta seu próprio socket em vez de um herdado de um processo pai, e as mensagens que chegam nele passam pelos [controles de entrada](/docs/pt/cross-session-messaging#control-inbound-messages) da sessão. Blocos `env` de configurações não podem defini-la. Requer o Claude Code v2.1.224 ou posterior |

346| `CLAUDE_CODE_MESSAGING_TOKEN` | Definida pelo Claude Code, não por você: em sessões que vinculam um [socket de caixa de entrada](/docs/pt/cross-session-messaging#the-sessions-inbox-socket), o Claude Code exporta este token por sessão para hooks e comandos Bash junto com `CLAUDE_CODE_MESSAGING_SOCKET`. Um script que publica no socket pode enviar `{"type":"auth","token":"<token>"}` como primeira linha para provar que pertence à sessão. No Windows nativo, o Claude Code exige essa linha e fecha qualquer conexão que não comece com uma válida. As [regras de processo filho próprio](/docs/pt/cross-session-messaging#the-sessions-inbox-socket) dizem quando o Claude Code consulta o token. Cada sessão exporta seu próprio token, nunca um herdado de uma sessão pai. Blocos `env` de configurações não podem defini-la. Requer o Claude Code v2.1.228 ou posterior |346| `CLAUDE_CODE_MESSAGING_TOKEN` | Definida pelo Claude Code, não por você: em sessões que vinculam um [socket de caixa de entrada](/docs/pt/cross-session-messaging#the-sessions-inbox-socket), o Claude Code exporta este token por sessão para hooks e comandos Bash junto com `CLAUDE_CODE_MESSAGING_SOCKET`. Um script que publica no socket pode enviar `{"type":"auth","token":"<token>"}` como primeira linha para provar que pertence à sessão. No Windows nativo, o Claude Code exige essa linha e fecha qualquer conexão que não comece com uma válida. As [regras de processo filho próprio](/docs/pt/cross-session-messaging#the-sessions-inbox-socket) dizem quando o Claude Code consulta o token. Cada sessão exporta seu próprio token, nunca um herdado de uma sessão pai. Blocos `env` de configurações não podem defini-la. Requer o Claude Code v2.1.228 ou posterior |

443| `CLAUDE_ENABLE_BYTE_WATCHDOG` | Defina como `1` para forçar a ativação do watchdog de ociosidade de streaming em nível de byte, ou defina como `0` para forçar sua desativação. `0` também desativa o [prazo do primeiro byte](/docs/pt/network-config#streaming-idle-watchdogs) nas conexões em que esse prazo é aplicado. Quando não definida, o watchdog fica ativado por padrão para conexões diretas com a API da Anthropic e com o [Claude Platform on AWS](/docs/pt/claude-platform-on-aws), e para respostas de streaming em conexões de [gateway](/docs/pt/gateways) acessadas por meio de `ANTHROPIC_BASE_URL` ou `ANTHROPIC_AWS_BASE_URL`; antes da v2.1.222, ele não era executado nessas conexões de gateway, então o watchdog em nível de evento podia relatar uma paralisação nelas mesmo enquanto pings de keep-alive estavam chegando. Para timeouts e como os temporizadores interagem, consulte [Watchdogs de ociosidade de streaming](/docs/pt/network-config#streaming-idle-watchdogs) |443| `CLAUDE_ENABLE_BYTE_WATCHDOG` | Defina como `1` para forçar a ativação do watchdog de ociosidade de streaming em nível de byte, ou defina como `0` para forçar sua desativação. `0` também desativa o [prazo do primeiro byte](/docs/pt/network-config#streaming-idle-watchdogs) nas conexões em que esse prazo é aplicado. Quando não definida, o watchdog fica ativado por padrão para conexões diretas com a API da Anthropic e com o [Claude Platform on AWS](/docs/pt/claude-platform-on-aws), e para respostas de streaming em conexões de [gateway](/docs/pt/gateways) acessadas por meio de `ANTHROPIC_BASE_URL` ou `ANTHROPIC_AWS_BASE_URL`; antes da v2.1.222, ele não era executado nessas conexões de gateway, então o watchdog em nível de evento podia relatar uma paralisação nelas mesmo enquanto pings de keep-alive estavam chegando. Para timeouts e como os temporizadores interagem, consulte [Watchdogs de ociosidade de streaming](/docs/pt/network-config#streaming-idle-watchdogs) |

444| `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK` | Defina como `1` para ativar o watchdog de ociosidade de streaming em nível de byte em respostas `vnd.amazon.eventstream` do Amazon Bedrock, o que também ativa o [prazo do primeiro byte](/docs/pt/network-config#streaming-idle-watchdogs) em requisições de streaming do Bedrock. Desativado por padrão. Configure o timeout com `CLAUDE_STREAM_IDLE_TIMEOUT_MS` |444| `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK` | Defina como `1` para ativar o watchdog de ociosidade de streaming em nível de byte em respostas `vnd.amazon.eventstream` do Amazon Bedrock, o que também ativa o [prazo do primeiro byte](/docs/pt/network-config#streaming-idle-watchdogs) em requisições de streaming do Bedrock. Desativado por padrão. Configure o timeout com `CLAUDE_STREAM_IDLE_TIMEOUT_MS` |

445| `CLAUDE_ENABLE_STREAM_WATCHDOG` | Defina como `0` para forçar a desativação do watchdog de ociosidade de streaming em nível de evento, ou defina como `1` para forçar sua ativação. Quando não definida, o watchdog fica ativado por padrão para todos os provedores. Antes da v2.1.196, o padrão sem definição era controlado pelo servidor na API direta da Anthropic e desativado em outros provedores. Configure o timeout com `CLAUDE_STREAM_IDLE_TIMEOUT_MS`; para os outros temporizadores de paralisação executados junto com este, consulte [Watchdogs de ociosidade de streaming](/docs/pt/network-config#streaming-idle-watchdogs) |445| `CLAUDE_ENABLE_STREAM_WATCHDOG` | Defina como `0` para forçar a desativação do watchdog de ociosidade de streaming em nível de evento, ou defina como `1` para forçar sua ativação. Quando não definida, o watchdog fica ativado por padrão para todos os provedores. Antes da v2.1.196, o padrão sem definição era controlado pelo servidor na API direta da Anthropic e desativado em outros provedores. Configure o timeout com `CLAUDE_STREAM_IDLE_TIMEOUT_MS`; para os outros temporizadores de paralisação executados junto com este, consulte [Watchdogs de ociosidade de streaming](/docs/pt/network-config#streaming-idle-watchdogs) |

446| `CLAUDE_ENV_FILE` | Caminho para um script de shell cujo conteúdo o Claude Code executa antes de cada comando Bash no mesmo processo de shell, de modo que os exports no arquivo fiquem visíveis para o comando. Use para manter a ativação de virtualenv ou conda entre comandos. Também preenchida dinamicamente pelos hooks [SessionStart](/docs/pt/hooks#persist-environment-variables), [Setup](/docs/pt/hooks#setup), [CwdChanged](/docs/pt/hooks#cwdchanged) e [FileChanged](/docs/pt/hooks#filechanged) |446| `CLAUDE_ENV_FILE` | Caminho para um script de shell cujo conteúdo o Claude Code executa antes de cada comando Bash no mesmo processo de shell, para que as exportações no arquivo fiquem visíveis para o comando. Use para persistir a ativação de virtualenv ou conda entre comandos. Comandos do PowerShell também recebem suas variáveis, na v2.1.296 ou posterior, sob as condições descritas em [Variáveis persistidas em comandos do PowerShell](/docs/pt/hooks#persisted-variables-in-powershell-commands). Também é preenchida dinamicamente pelos hooks [SessionStart](/docs/pt/hooks#persist-environment-variables), [Setup](/docs/pt/hooks#setup), [CwdChanged](/docs/pt/hooks#cwdchanged) e [FileChanged](/docs/pt/hooks#filechanged) |

447| `CLAUDE_JOB_DIR` | Definida pelo Claude Code em cada [sessão em segundo plano](/docs/pt/agent-view) como o diretório `~/.claude/jobs/<id>` dessa sessão. Os comandos de shell que a sessão executa a herdam. Grave arquivos temporários em [`$CLAUDE_JOB_DIR/tmp`](/docs/pt/agent-view#where-state-is-stored). As chamadas `Write` e `Edit` do Claude nesse local não solicitam permissão, e o diretório é removido quando a sessão é excluída |447| `CLAUDE_JOB_DIR` | Definida pelo Claude Code em cada [sessão em segundo plano](/docs/pt/agent-view) como o diretório `~/.claude/jobs/<id>` dessa sessão. Os comandos de shell que a sessão executa a herdam. Grave arquivos temporários em [`$CLAUDE_JOB_DIR/tmp`](/docs/pt/agent-view#where-state-is-stored). As chamadas `Write` e `Edit` do Claude nesse local não solicitam permissão, e o diretório é removido quando a sessão é excluída |

448| `CLAUDE_PID` | O Claude Code define esta variável com seu próprio ID de processo nos subprocessos que ele cria: comandos das ferramentas Bash e PowerShell e comandos de hook. No Linux, a integração de shell da ferramenta Bash a usa para recusar um padrão `pkill` que corresponderia ao próprio processo do Claude Code; consulte [a referência de erros](/docs/pt/errors#pkill-pattern-matches-the-claude-code-process). Leia-a em seus próprios scripts para identificar ou sinalizar deliberadamente o processo pai do Claude Code. Requer Claude Code v2.1.214 ou posterior |448| `CLAUDE_PID` | O Claude Code define esta variável com seu próprio ID de processo nos subprocessos que ele cria: comandos das ferramentas Bash e PowerShell e comandos de hook. No Linux, a integração de shell da ferramenta Bash a usa para recusar um padrão `pkill` que corresponderia ao próprio processo do Claude Code; consulte [a referência de erros](/docs/pt/errors#pkill-pattern-matches-the-claude-code-process). Leia-a em seus próprios scripts para identificar ou sinalizar deliberadamente o processo pai do Claude Code. Requer Claude Code v2.1.214 ou posterior |

449| `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` | Prefixo para nomes de sessão do [Remote Control](/docs/pt/remote-control) gerados automaticamente quando nenhum nome explícito é fornecido. O padrão é o nome de host da sua máquina, produzindo nomes como `myhost-graceful-unicorn`. A flag de CLI `--remote-control-session-name-prefix` define o mesmo valor para uma única invocação |449| `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` | Prefixo para nomes de sessão do [Remote Control](/docs/pt/remote-control) gerados automaticamente quando nenhum nome explícito é fornecido. O padrão é o nome de host da sua máquina, produzindo nomes como `myhost-graceful-unicorn`. A flag de CLI `--remote-control-session-name-prefix` define o mesmo valor para uma única invocação |

errors.md +72 −9

Details

37| `Connection lost while your computer was asleep` | [Automatic retries](#automatic-retries) |37| `Connection lost while your computer was asleep` | [Automatic retries](#automatic-retries) |

38| `<model> is temporarily unavailable, so auto mode cannot determine the safety of...` | [Server errors](#auto-mode-cannot-determine-the-safety-of-an-action) |38| `<model> is temporarily unavailable, so auto mode cannot determine the safety of...` | [Server errors](#auto-mode-cannot-determine-the-safety-of-an-action) |

39| `Auto mode could not evaluate this action and is blocking it for safety` | [Server errors](#auto-mode-cannot-determine-the-safety-of-an-action) |39| `Auto mode could not evaluate this action and is blocking it for safety` | [Server errors](#auto-mode-cannot-determine-the-safety-of-an-action) |

40| `Not run · auto mode's check had no usable answer` | [Server errors](#auto-mode-cannot-determine-the-safety-of-an-action) |

40| `Auto mode classifier transcript exceeded context window` | [Server errors](#auto-mode-cannot-determine-the-safety-of-an-action) |41| `Auto mode classifier transcript exceeded context window` | [Server errors](#auto-mode-cannot-determine-the-safety-of-an-action) |

41| `Agent aborted: auto mode classifier request refused by the safety safeguard` | [Server errors](#auto-mode-cannot-determine-the-safety-of-an-action) |42| `Agent aborted: auto mode classifier request refused by the safety safeguard` | [Server errors](#auto-mode-cannot-determine-the-safety-of-an-action) |

42| `The server-side auto mode classifier gave no verdict` | [Server errors](#the-server-returned-no-safety-verdict) |43| `The server-side auto mode classifier gave no verdict` | [Server errors](#the-server-returned-no-safety-verdict) |

247| `Windows reported an error (EBADF) when Claude Code read this session's transcript file` | [Command-line errors](#windows-reported-an-error-ebadf) |248| `Windows reported an error (EBADF) when Claude Code read this session's transcript file` | [Command-line errors](#windows-reported-an-error-ebadf) |

249| `Cannot switch renderers while work is running in the background` | [Command-line errors](#cannot-switch-renderers-in-this-session) |250| `Cannot switch renderers while work is running in the background` | [Command-line errors](#cannot-switch-renderers-in-this-session) |

251| `Claude Code couldn't restart` | [Command-line errors](#claude-code-couldnt-restart) |

252| `Couldn't read your Zed keymap` / `Couldn't back up your Zed keymap` / `Couldn't update your Zed keymap` | [Command-line errors](#terminal-setup-left-your-zed-keymap-unchanged) |254| `Couldn't read your Zed keymap` / `Couldn't back up your Zed keymap` / `Couldn't update your Zed keymap` | [Command-line errors](#terminal-setup-left-your-zed-keymap-unchanged) |

262| `Marketplace "<name>" is already added from a different source` | [Plugin errors](#marketplace-is-already-added-from-a-different-source) |264| `Marketplace "<name>" is already added from a different source` | [Plugin errors](#marketplace-is-already-added-from-a-different-source) |

263| `"<name>" is another spelling of "<reserved>", a reserved marketplace name` | [Plugin errors](#marketplace-name-is-another-spelling-of-a-reserved-name) |265| `"<name>" is another spelling of "<reserved>", a reserved marketplace name` | [Plugin errors](#marketplace-name-is-another-spelling-of-a-reserved-name) |

264| `Cannot add marketplace "<name>": Claude Code cannot install plugins from a marketplace with this name` | [Plugin troubleshooting](/docs/pt/plugins/troubleshooting#cannot-install-plugins-from-a-marketplace-with-this-name) |266| `Cannot add marketplace "<name>": Claude Code cannot install plugins from a marketplace with this name` | [Plugin troubleshooting](/docs/pt/plugins/troubleshooting#cannot-install-plugins-from-a-marketplace-with-this-name) |

267| `Cannot add marketplace "<name>": Claude Code reserves this name and cannot register a marketplace under it` | [Plugin troubleshooting](/docs/pt/plugins/troubleshooting#claude-code-reserves-this-name) |

265| `Marketplace "<name>" is added but ignored` | [Plugin troubleshooting](/docs/pt/plugins/troubleshooting#marketplace-is-added-but-ignored) |268| `Marketplace "<name>" is added but ignored` | [Plugin troubleshooting](/docs/pt/plugins/troubleshooting#marketplace-is-added-but-ignored) |

266| `Marketplace "<name>" is registered but was refused (see the debug log)` | [Plugin troubleshooting](/docs/pt/plugins/troubleshooting#marketplace-is-added-but-ignored) |269| `Marketplace "<name>" is registered but was refused (see the debug log)` | [Plugin troubleshooting](/docs/pt/plugins/troubleshooting#marketplace-is-added-but-ignored) |

267| `references ${user_config.*} in a shell-form command` | [Plugin errors](#plugin-command-references-user-config) |270| `references ${user_config.*} in a shell-form command` | [Plugin errors](#plugin-command-references-user-config) |

308| `Your disk quota is full on the filesystem with Claude Code's temp directory <dir> (EDQUOT)` | [Tool errors](#disk-quota-or-temp-filesystem-is-full) |311| `Your disk quota is full on the filesystem with Claude Code's temp directory <dir> (EDQUOT)` | [Tool errors](#disk-quota-or-temp-filesystem-is-full) |

309| `The filesystem with Claude Code's temp directory <dir>, or your disk quota on it, is full (ENOSPC)` | [Tool errors](#disk-quota-or-temp-filesystem-is-full) |312| `The filesystem with Claude Code's temp directory <dir>, or your disk quota on it, is full (ENOSPC)` | [Tool errors](#disk-quota-or-temp-filesystem-is-full) |

310| `Command output was lost: the temp filesystem at <dir> is full` / `is out of inodes` | [Tool errors](#disk-quota-or-temp-filesystem-is-full) |313| `Command output was lost: the temp filesystem at <dir> is full` / `is out of inodes` | [Tool errors](#disk-quota-or-temp-filesystem-is-full) |

314| `File is not valid UTF-8. It may use a legacy encoding such as Windows-1252, Shift-JIS or GBK, or be binary` | [Tool errors](#file-is-not-valid-utf-8) |

311| `the source file is not valid UTF-8 text` / `the source file is not valid UTF-16 text` | [Tool errors](#the-source-file-is-not-valid-utf-8-text) |315| `the source file is not valid UTF-8 text` / `the source file is not valid UTF-16 text` | [Tool errors](#the-source-file-is-not-valid-utf-8-text) |

334| `Session isn't responding` / `Press enter again to restart this session — it isn't responding` | [Background session errors](#session-isnt-responding) |338| `Session isn't responding` / `Press enter again to restart this session — it isn't responding` | [Background session errors](#session-isnt-responding) |

335| `Session <id> was stopped while the respawn was in flight` | [Background session errors](#session-was-stopped-while-the-respawn-was-in-flight) |339| `Session <id> was stopped while the respawn was in flight` | [Background session errors](#session-was-stopped-while-the-respawn-was-in-flight) |

336| `This session was running agent '<name>', which is no longer available` | [Background session errors](#session-agent-no-longer-available) |340| `This session was running agent '<name>', which is no longer available` | [Background session errors](#session-agent-no-longer-available) |

341| `This session restarted <time> after its next /loop wakeup was due, so that wakeup will not fire` | [Background session errors](#restarted-after-its-next-loop-wakeup-was-due) |

337| `CLAUDE_CODE_PROCESS_WRAPPER: launcher ...` | [Background session errors](#claude_code_process_wrapper-launcher-errors) |342| `CLAUDE_CODE_PROCESS_WRAPPER: launcher ...` | [Background session errors](#claude_code_process_wrapper-launcher-errors) |

439| :- | :- | :- |444| :- | :- | :- |

440| [`CLAUDE_CODE_MAX_RETRIES`](/docs/pt/env-vars) | 10 | Número de novas tentativas. Limitado a 15 a partir da v2.1.186; a partir da v2.1.199 `CLAUDE_CODE_RETRY_WATCHDOG` aumenta o padrão e remove o limite. Reduza-o para expor falhas mais rapidamente em scripts. |445| [`CLAUDE_CODE_MAX_RETRIES`](/docs/pt/env-vars) | 10 | Número de novas tentativas. Limitado a 15 a partir da v2.1.186; a partir da v2.1.199 `CLAUDE_CODE_RETRY_WATCHDOG` aumenta o padrão e remove o limite. Reduza-o para expor falhas mais rapidamente em scripts. |

441| [`CLAUDE_CODE_RETRY_WATCHDOG`](/docs/pt/env-vars) | não definido | Defina como `1` em sessões não supervisionadas, como jobs de CI, para tentar novamente erros de capacidade `429` e `529` indefinidamente em vez de falhar após `CLAUDE_CODE_MAX_RETRIES` tentativas. Claude Code falha imediatamente quando uma requisição de velocidade padrão recebe um `429` que relata um limite de gastos ou créditos de uso esgotados, mesmo um de um [limite de gastos de gateway](#spend-limit-reached) que é redefinido em um cronograma. Antes da v2.1.239, o watchdog tentava novamente esses erros indefinidamente. Para requisições no modo rápido, veja [Handle rate limits](/docs/pt/fast-mode#handle-rate-limits). Na v2.1.199 ou posterior, também aumenta a contagem padrão de novas tentativas para outros erros transitórios, como erros de servidor, timeouts e conexões perdidas, para 300, aproximadamente três horas de backoff, e remove o limite de 15 em `CLAUDE_CODE_MAX_RETRIES` se você definir essa variável explicitamente. |446| [`CLAUDE_CODE_RETRY_WATCHDOG`](/docs/pt/env-vars) | não definido | Defina como `1` em sessões não supervisionadas, como jobs de CI, para tentar novamente erros de capacidade `429` e `529` indefinidamente em vez de falhar após `CLAUDE_CODE_MAX_RETRIES` tentativas. Claude Code falha imediatamente quando uma requisição de velocidade padrão recebe um `429` que relata um limite de gastos ou créditos de uso esgotados, mesmo um de um [limite de gastos de gateway](#spend-limit-reached) que é redefinido em um cronograma. Antes da v2.1.239, o watchdog tentava novamente esses erros indefinidamente. Para requisições no modo rápido, veja [Handle rate limits](/docs/pt/fast-mode#handle-rate-limits). Na v2.1.199 ou posterior, também aumenta a contagem padrão de novas tentativas para outros erros transitórios, como erros de servidor, timeouts e conexões perdidas, para 300, aproximadamente três horas de backoff, e remove o limite de 15 em `CLAUDE_CODE_MAX_RETRIES` se você definir essa variável explicitamente. |

447| [`CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS`](/docs/pt/env-vars) | não definido | Tempo máximo em milissegundos que cada requisição de API passa aguardando erros `429` e `529` quando `CLAUDE_CODE_RETRY_WATCHDOG` está definido. Quando não definido, a espera não tem limite. Requer Claude Code v2.1.295 ou posterior. |

442| [`CLAUDE_CODE_OVERLOADED_RETRY_BASE_DELAY_MS`](/docs/pt/env-vars) | 500 | Atraso inicial em milissegundos do backoff entre novas tentativas de uma requisição que a API rejeita com um erro de sobrecarga `529`. Aumente-o, até 32000, para distribuir as novas tentativas por uma janela mais longa quando a API estiver no limite de capacidade. Não tem efeito quando `CLAUDE_CODE_RETRY_WATCHDOG` está definido como `1`, ou quando a requisição rejeitada foi enviada no [modo rápido](/docs/pt/fast-mode#handle-rate-limits). Requer Claude Code v2.1.292 ou posterior. |448| [`CLAUDE_CODE_OVERLOADED_RETRY_BASE_DELAY_MS`](/docs/pt/env-vars) | 500 | Atraso inicial em milissegundos do backoff entre novas tentativas de uma requisição que a API rejeita com um erro de sobrecarga `529`. Aumente-o, até 32000, para distribuir as novas tentativas por uma janela mais longa quando a API estiver no limite de capacidade. Não tem efeito quando `CLAUDE_CODE_RETRY_WATCHDOG` está definido como `1`, ou quando a requisição rejeitada foi enviada no [modo rápido](/docs/pt/fast-mode#handle-rate-limits). Requer Claude Code v2.1.292 ou posterior. |

443| [`API_TIMEOUT_MS`](/docs/pt/env-vars) | 600000 | Timeout por requisição em milissegundos. Aumente-o para redes lentas ou proxies. Também limita quanto tempo Claude Code aguarda os cabeçalhos de resposta, conforme descrito em [No response from API](#no-response-from-api). |449| [`API_TIMEOUT_MS`](/docs/pt/env-vars) | 600000 | Timeout por requisição em milissegundos. Aumente-o para redes lentas ou proxies. Também limita quanto tempo Claude Code aguarda os cabeçalhos de resposta, conforme descrito em [No response from API](#no-response-from-api). |

444| [`CLAUDE_CODE_NONSTREAMING_TIMEOUT_RETRIES`](/docs/pt/env-vars) | não definido | Limite de reenvios de uma [requisição sem streaming](#streaming-response-ended-before-any-complete-data-was-received) que atinge o timeout. Ao atingir o limite, a requisição falha. Uma resposta do Claude que leva mais tempo que o timeout para ser gerada atinge o timeout novamente a cada reenvio, então defina um número baixo, como `0`, para falhar mais cedo. Cada tentativa sem streaming atinge o timeout após 300 segundos em uma sessão local, ou após `API_TIMEOUT_MS` quando você define um valor positivo. Requer Claude Code v2.1.285 ou posterior. |450| [`CLAUDE_CODE_NONSTREAMING_TIMEOUT_RETRIES`](/docs/pt/env-vars) | não definido | Limite de reenvios de uma [requisição sem streaming](#streaming-response-ended-before-any-complete-data-was-received) que atinge o timeout. Ao atingir o limite, a requisição falha. Uma resposta do Claude que leva mais tempo que o timeout para ser gerada atinge o timeout novamente a cada reenvio, então defina um número baixo, como `0`, para falhar mais cedo. Cada tentativa sem streaming atinge o timeout após 300 segundos em uma sessão local, ou após `API_TIMEOUT_MS` quando você define um valor positivo. Requer Claude Code v2.1.285 ou posterior. |

596<model> is temporarily unavailable, so auto mode cannot determine the safety of <tool> right now. Wait a moment and then try this action again.602<model> is temporarily unavailable, so auto mode cannot determine the safety of <tool> right now. Wait a moment and then try this action again.

597```603```

598 604

605Em uma sessão interativa, uma linha esmaecida `Not run · auto mode's check had no usable answer` aparece sob a chamada de ferramenta em vez desta mensagem. Pressione `Ctrl+O` para ler a mensagem no [visualizador de transcrição](/docs/pt/interactive-mode#transcript-viewer). As negações descritas em [The server returned no safety verdict](#the-server-returned-no-safety-verdict) mostram a mesma linha. Antes da v2.1.296, a mensagem aparecia sob a chamada como um erro vermelho.

606

599Quando Claude Code pode determinar a categoria de falha, ele nomeia a categoria entre parênteses após `temporarily unavailable`, por exemplo `<model> is temporarily unavailable (rate-limited), so auto mode cannot determine the safety of <tool> right now`. As categorias são `(rate-limited)`, `(overloaded)`, `(server error)`, `(timed out)` e `(connection failed)`. Se `(timed out)` ou `(connection failed)` se repetir, verifique sua conexão; veja [Unable to connect to API](#unable-to-connect-to-api). Antes da v2.1.229, a mensagem nunca nomeava uma categoria e lia `Wait briefly and then try this action again`.607Quando Claude Code pode determinar a categoria de falha, ele nomeia a categoria entre parênteses após `temporarily unavailable`, por exemplo `<model> is temporarily unavailable (rate-limited), so auto mode cannot determine the safety of <tool> right now`. As categorias são `(rate-limited)`, `(overloaded)`, `(server error)`, `(timed out)` e `(connection failed)`. Se `(timed out)` ou `(connection failed)` se repetir, verifique sua conexão; veja [Unable to connect to API](#unable-to-connect-to-api). Antes da v2.1.229, a mensagem nunca nomeava uma categoria e lia `Wait briefly and then try this action again`.

600 608

601Quando nenhuma categoria se encaixa, a mensagem aparece sem categoria entre parênteses; mais de uma falha produz essa forma. No [Amazon Bedrock](/docs/pt/amazon-bedrock), incluindo o [endpoint Mantle](/docs/pt/amazon-bedrock#use-the-mantle-endpoint), também aparece quando sua conta AWS não consegue invocar o modelo nomeado na mensagem, e essa falha se repete em cada tentativa até que sua conta receba acesso ao modelo.609Quando nenhuma categoria se encaixa, a mensagem aparece sem categoria entre parênteses; mais de uma falha produz essa forma. No [Amazon Bedrock](/docs/pt/amazon-bedrock), incluindo o [endpoint Mantle](/docs/pt/amazon-bedrock#use-the-mantle-endpoint), também aparece quando sua conta AWS não consegue invocar o modelo nomeado na mensagem, e essa falha se repete em cada tentativa até que sua conta receba acesso ao modelo.

1900 1908

1901Claude Code pula essa verificação quando um [arquivo de configurações gerenciadas, política MDM ou policy helper](/docs/pt/managed-settings) define [`forceLoginMethod`](/docs/pt/settings-reference#forceloginmethod) como `"gateway"`, ou define [`forceLoginGatewayUrl`](/docs/pt/settings-reference#forcelogingatewayurl) sem `forceLoginMethod`. Com qualquer uma das configurações, Claude Code abre a etapa de login na tela **Cloud gateway** em vez de um método de login Anthropic. Claude Code também pula a verificação quando uma fonte de configurações gerenciadas na máquina existe mas não pode ser lida, já que essa fonte pode conter a configuração do gateway. Antes da v2.1.247, Claude Code executava a verificação sob essa configuração também, e saía com esse erro quando os endpoints da Anthropic eram inacessíveis.1909Claude Code pula essa verificação quando um [arquivo de configurações gerenciadas, política MDM ou policy helper](/docs/pt/managed-settings) define [`forceLoginMethod`](/docs/pt/settings-reference#forceloginmethod) como `"gateway"`, ou define [`forceLoginGatewayUrl`](/docs/pt/settings-reference#forcelogingatewayurl) sem `forceLoginMethod`. Com qualquer uma das configurações, Claude Code abre a etapa de login na tela **Cloud gateway** em vez de um método de login Anthropic. Claude Code também pula a verificação quando uma fonte de configurações gerenciadas na máquina existe mas não pode ser lida, já que essa fonte pode conter a configuração do gateway. Antes da v2.1.247, Claude Code executava a verificação sob essa configuração também, e saía com esse erro quando os endpoints da Anthropic eram inacessíveis.

1902 1910

1911Claude Code também pula a verificação em uma máquina sem configurações gerenciadas quando seu próprio `~/.claude/settings.json` [nomeia um gateway](/docs/pt/claude-apps-gateway#set-the-gateway-url-in-user-settings) com `forceLoginMethod` e `forceLoginGatewayUrl`. Antes da v2.1.295, Claude Code executava a verificação nesse caso.

1912

1903**O que fazer:**1913**O que fazer:**

1904 1914

1905* Se a mensagem nomear uma variável de proxy, verifique se seu valor aponta para o proxy correto e peça ao seu time de rede para permitir conexões HTTPS através dele para o host na mensagem. Veja [Network configuration](/docs/pt/network-config).1915* Se a mensagem nomear uma variável de proxy, verifique se seu valor aponta para o proxy correto e peça ao seu time de rede para permitir conexões HTTPS através dele para o host na mensagem. Veja [Network configuration](/docs/pt/network-config).

3562 3572

3563* **Você não passou um branch base**: o Claude Code comparou com o branch padrão do repositório e sugere passar seu branch base explicitamente, como no exemplo acima3573* **Você não passou um branch base**: o Claude Code comparou com o branch padrão do repositório e sugere passar seu branch base explicitamente, como no exemplo acima

3564* **Você passou um branch base que já estava no seu clone**: a dica diz ``Make sure <branch> exists locally or on origin (try `git fetch origin <branch>`)``3574* **Você passou um branch base que já estava no seu clone**: a dica diz ``Make sure <branch> exists locally or on origin (try `git fetch origin <branch>`)``

3565* **Você passou um branch base que não estava no seu clone**: o Claude Code fez o fetch dele a partir do origin antes de comparar. A dica diz ``<branch> was fetched from origin but shares no history with HEAD. If another branch is your real base, pass it explicitly (`/code-review ultra <branch>`)``; quando o Claude Code não consegue determinar se seu clone é raso (shallow), ele sugere `git fetch --unshallow origin`. Antes da v2.1.221, a dica sugeria `git fetch --unshallow origin` para todo branch base obtido via fetch, e em um clone completo esse comando falha com `fatal: --unshallow on a complete repository does not make sense`.3575* **Você passou um branch base que não estava no seu clone**: o Claude Code fez fetch dele a partir do origin antes de comparar. A dica diz ``<branch> was fetched from origin but shares no history with HEAD. If another branch is your real base, pass it explicitly (`/code-review ultra <branch>`)``; quando o Claude Code não consegue determinar se seu clone é raso (shallow), ele sugere `git fetch --unshallow origin` em vez disso. Antes da v2.1.221, a dica sugeria `git fetch --unshallow origin` para todo branch base obtido por fetch, e em um clone completo esse comando falha com `fatal: --unshallow on a complete repository does not make sense`.

3566 3576

3567**O que fazer:**3577**O que fazer:**

3568 3578

3756No conversation found with session ID: <session-id>3766No conversation found with session ID: <session-id>

3757```3767```

3758 3768

3759O Claude Code sai com o código 1 após mostrar a mensagem. O Claude Code [procura o ID primeiro no projeto atual e depois em todos os outros projetos desta máquina](/docs/pt/sessions#resume-a-session). Antes da v2.1.223, a busca parava no diretório do projeto atual e em seus worktrees do git, então retome a partir do diretório em que a sessão trabalhou por último.3769O Claude Code sai com o código 1 após mostrar a mensagem. O Claude Code [pesquisa primeiro o projeto atual e depois todos os outros projetos nesta máquina](/docs/pt/sessions#where-the-session-picker-looks) em busca do ID. Antes da v2.1.223, a busca parava no diretório do projeto atual e em seus git worktrees, então retome a partir do diretório em que a sessão trabalhou por último.

3760 3770

3761Causas comuns:3771Causas comuns:

3762 3772

3816 3826

3817* Em uma sessão iniciada sem essas restrições, execute `/tui fullscreen`, ou `/tui default` para voltar. O Claude Code salva a [configuração `tui`](/docs/pt/settings-reference#tui) ali3827* Em uma sessão iniciada sem essas restrições, execute `/tui fullscreen`, ou `/tui default` para voltar. O Claude Code salva a [configuração `tui`](/docs/pt/settings-reference#tui) ali

3818 3828

3829<h3 id="claude-code-couldnt-restart">

3830 Claude Code couldn't restart

3831</h3>

3832

3833O Claude Code estava reiniciando, por exemplo para ativar ou desativar a renderização em tela cheia depois que você executou [`/tui`](/docs/pt/fullscreen#enable-fullscreen-rendering). Ele fechou a sessão, mas não conseguiu iniciar o novo processo, então imprimiu esta mensagem e saiu com o status 1:

3834

3835```text theme={null}

3836Claude Code couldn't restart. Your conversation is saved. Start Claude Code again and run /resume to pick it up.

3837```

3838

3839Quando a reinicialização não tinha nenhuma conversa para reabrir, por exemplo porque `/tui` foi sua primeira entrada em uma nova sessão, a mensagem diz `Claude Code couldn't restart. Start Claude Code again.`

3840

3841**O que fazer:**

3842

3843* Execute `claude` novamente no seu shell a partir do mesmo diretório. Se a mensagem disse que sua conversa foi salva, execute [`/resume`](/docs/pt/sessions#resume-a-session) na nova sessão e selecione-a

3844* Se as reinicializações continuarem falhando, inicie o Claude Code a partir do seu shell com [`claude --debug-file claude-debug.log`](/docs/pt/cli-reference#cli-flags). Se uma reinicialização a partir dessa sessão falhar, o `claude-debug.log` no diretório de onde você iniciou registra uma linha `Failed to relaunch:` com o erro do sistema operacional. Inclua essa linha ao [relatar o problema](#report-an-error)

3845

3819<h3 id="couldnt-open-claude-desktop">3846<h3 id="couldnt-open-claude-desktop">

3820 Não foi possível abrir o Claude Desktop3847 Não foi possível abrir o Claude Desktop

3821</h3>3848</h3>

4593* Ou reinicie Claude Code com [`CLAUDE_CODE_TMPDIR`](/docs/pt/env-vars) definido para um diretório em um sistema de arquivos com espaço4620* Ou reinicie Claude Code com [`CLAUDE_CODE_TMPDIR`](/docs/pt/env-vars) definido para um diretório em um sistema de arquivos com espaço

4594* Então peça ao Claude para executar o comando novamente. A saída que ele imprimiu foi perdida, não truncada4621* Então peça ao Claude para executar o comando novamente. A saída que ele imprimiu foi perdida, não truncada

4595 4622

4623<h3 id="file-is-not-valid-utf-8">

4624 File is not valid UTF-8

4625</h3>

4626

4627Claude usou a ferramenta Edit ou NotebookEdit em um arquivo cujos bytes não decodificam como UTF-8, e Claude Code recusou a alteração. Nada foi escrito, então o arquivo está como estava. Essas ferramentas salvam o arquivo inteiro de volta como UTF-8, o que teria transformado cada byte que não conseguissem decodificar no caractere de substituição `U+FFFD`. A mensagem aparece no resultado da ferramenta:

4628

4629```text wrap theme={null}

4630File is not valid UTF-8. It may use a legacy encoding such as Windows-1252, Shift-JIS or GBK, or be binary. This tool saves the whole file as UTF-8, which would replace every byte it cannot decode with U+FFFD. Nothing was written. Make the change with a shell command that reads and writes the file in its own encoding, or ask the user whether to convert the file to UTF-8 first.

4631```

4632

4633Um arquivo que deveria ser UTF-8 também recebe essa mensagem quando contém até mesmo uma única sequência de bytes inválida, porque a verificação cobre os bytes do arquivo como um todo.

4634

4635**O que fazer:**

4636

4637* Para manter o arquivo em sua codificação atual, deixe Claude fazer a alteração com um comando de shell que lê e escreve o arquivo nessa codificação, como a mensagem diz a ele para fazer

4638* Para continuar editando o arquivo com a ferramenta Edit, converta-o para UTF-8, ou corrija os bytes inválidos em um arquivo que deveria ser UTF-8, e então peça ao Claude para fazer a edição novamente

4639

4640Antes da v2.1.296, Edit e NotebookEdit aplicavam tal edição e salvavam cada byte que não conseguiam decodificar como `U+FFFD`. Nessas versões, atualize Claude Code.

4641

4596<h3 id="the-source-file-is-not-valid-utf-8-text">4642<h3 id="the-source-file-is-not-valid-utf-8-text">

4597 O arquivo de origem não é texto UTF-8 válido4643 O arquivo de origem não é texto UTF-8 válido

4598</h3>4644</h3>

4752 Comando bloqueado pelas verificações de isolamento de worktree4798 Comando bloqueado pelas verificações de isolamento de worktree

4753</h3>4799</h3>

4754 4800

4755Claude executou um comando Bash ou Monitor em uma [sessão isolada em um worktree](/docs/pt/worktrees#how-claude-code-enforces-isolation), e Claude Code recusou-o por uma de duas razões:4801Claude executou um comando Bash, [PowerShell](/docs/pt/tools-reference#powershell-tool) ou [Monitor](/docs/pt/tools-reference#monitor-tool) em uma [sessão isolada em um worktree](/docs/pt/worktrees#how-claude-code-enforces-isolation), e Claude Code recusou-o por uma destas razões:

4756 4802

4757* O comando aponta git para o checkout principal.4803* O comando seria executado no checkout principal ou em outro worktree. A mensagem diz que seu diretório de trabalho `resolved to the shared checkout` ou `is in a different worktree`.

4758* Claude Code não consegue verificar a partir do texto do comando que qualquer git que o comando executa fica dentro do worktree. Um comando que nunca nomeia git ainda pode ser recusado por essa razão, porque expandir uma indireção de variável como `${!name}` ou executar uma substituição de função Bash como `${ command; }` produz um valor em tempo de execução que pode ser um comando em si.4804* Um comando Bash ou Monitor aponta git para o checkout principal.

4805* Claude Code não consegue verificar a partir do texto de um comando Bash ou Monitor que qualquer git que o comando executa fica dentro do worktree. Um comando que nunca nomeia git ainda pode ser recusado por essa razão, porque expandir uma indireção de variável como `${!name}` ou executar uma substituição de função Bash como `${ command; }` produz um valor em tempo de execução que pode ser um comando em si.

4759 4806

4760O meio da mensagem nomeia o que não pôde ser verificado:4807A mensagem diz `is isolated in the worktree <path>, but this command`, seguido pela razão, como um comando cujo texto Claude Code não conseguiu verificar:

4761 4808

4762```text wrap theme={null}4809```text wrap theme={null}

4763This session is isolated in the worktree /path/to/worktree, but this command evaluates ${!x@P} arithmetically inside a construct too complex to verify, which can run a command hidden in a variable's value. Refusing to run it — a worktree-isolated session's git operations must target its own worktree. Split it into plain, separate commands and run them from /path/to/worktree.4810This session is isolated in the worktree /path/to/worktree, but this command evaluates ${!x@P} arithmetically inside a construct too complex to verify, which can run a command hidden in a variable's value. Refusing to run it — a worktree-isolated session's git operations must target its own worktree. Split it into plain, separate commands and run them from /path/to/worktree.

4765 4812

4766**O que fazer:**4813**O que fazer:**

4767 4814

4768* Geralmente nada: Claude lê a mensagem e reescreve o comando da forma que sua sentença final pede4815* **Git apontado para o checkout principal, ou texto de comando que não pode ser verificado**: nada. Claude lê a mensagem e reescreve o comando da forma que sua sentença final pede. Se um comando que você pediu continua sendo recusado por causa de uma expansão em seu texto, escreva o valor sinalizado literalmente e execute git como seu próprio comando simples de dentro do worktree

4769* Se um comando que você pediu continua sendo recusado, escreva o valor sinalizado literalmente: substitua a indireção ou substituição por seu valor, e execute git como seu próprio comando simples de dentro do worktree

4770* Para agir no checkout principal propositalmente, execute o comando você mesmo em um terminal fora da sessão4816* Para agir no checkout principal propositalmente, execute o comando você mesmo em um terminal fora da sessão

4771 4817

4772<h3 id="this-session-has-no-saved-transcript">4818<h3 id="this-session-has-no-saved-transcript">

4946* Ou retome com `--agent <name>` nomeando um agente que existe, para executar a sessão como esse agente em vez disso4992* Ou retome com `--agent <name>` nomeando um agente que existe, para executar a sessão como esse agente em vez disso

4947* Se o agente tem escopo de projeto e você não confiou no diretório original da sessão, execute Claude Code lá uma vez, aceite o diálogo de confiança, depois retome novamente4993* Se o agente tem escopo de projeto e você não confiou no diretório original da sessão, execute Claude Code lá uma vez, aceite o diálogo de confiança, depois retome novamente

4948 4994

4995<h3 id="restarted-after-its-next-loop-wakeup-was-due">

4996 Esta sessão reiniciou depois que seu próximo despertar do /loop estava previsto

4997</h3>

4998

4999Um [`/loop` autorregulado](/docs/pt/scheduled-tasks#let-claude-choose-the-interval) em uma [sessão em background](/docs/pt/agent-view) parou. O processo da sessão terminou enquanto o loop estava esperando seu próximo despertar, e esse despertar venceu antes que o [próximo processo](/docs/pt/agent-view#the-supervisor-process) da sessão iniciasse. O despertar perdido não dispara com atraso. O aviso diz quão atrasado o despertar estava quando a sessão reiniciou:

5000

5001```text theme={null}

5002This session restarted 12m after its next /loop wakeup was due, so that wakeup will not fire. The loop stays stopped until Claude schedules it again: reply to continue it.

5003```

5004

5005Antes da v2.1.295, o loop parava nessa situação sem um aviso.

5006

5007**O que fazer:**

5008

5009* Para continuar o loop, [responda à sessão](/docs/pt/agent-view#peek-and-reply) e diga isso, como `keep the loop running`. Claude lê o aviso com sua resposta e pode agendar o próximo despertar

5010* Se você terminou com o loop, não faça nada. Ele já parou

5011

4949<h3 id="claude_code_process_wrapper-launcher-errors">5012<h3 id="claude_code_process_wrapper-launcher-errors">

4950 Erros do launcher CLAUDE\_CODE\_PROCESS\_WRAPPER5013 Erros do launcher CLAUDE\_CODE\_PROCESS\_WRAPPER

4951</h3>5014</h3>

5343Os caminhos que Claude Code recusa desta forma incluem:5406Os caminhos que Claude Code recusa desta forma incluem:

5344 5407

5345* Compartilhamentos UNC como `\\server\share`5408* Compartilhamentos UNC como `\\server\share`

5346* Caminhos de montagem automática como `/net/<host>`, a menos que você tenha iniciado Claude Code de um diretório sob a montagem automática desse host5409* Caminhos de montagem automática como `/net/<host>`, a menos que você tenha iniciado Claude Code de um diretório sob a montagem automática desse host. Leituras sob essa montagem automática ainda passam pela [verificação de caminho de rede](/docs/pt/permissions#network-paths).

5347* Caminhos locais que alcançam um local de rede através de um link simbólico ou junção5410* Caminhos locais que alcançam um local de rede através de um link simbólico ou junção

5348 5411

5349Letras de unidade mapeadas e caminhos `\\wsl$` não contam como caminhos de rede.5412Letras de unidade mapeadas e caminhos `\\wsl$` não contam como caminhos de rede.

github-enterprise-server.md +5 −5

Details

33 33

56 Na página do GitHub App em sua instância GHES, instale o app nos repositórios ou organizações que você deseja que Claude acesse. Você pode começar com um subconjunto e adicionar mais depois.56 Na página do GitHub App em sua instância GHES, instale o app nos repositórios ou organizações que você deseja que Claude acesse. Você pode começar com um subconjunto e adicionar mais depois.

57 </Step>57 </Step>

58 58

~~59 <Step title="Ative os recursos">~~59 <Step title="Ative o Code Review">

60 Vá para [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code) e ative [Code Review](/docs/pt/code-review#set-up-code-review) e [métricas de contribuição](/docs/pt/analytics#enable-contribution-metrics) para seus repositórios GHES usando a mesma configuração que github.com.60 Vá para [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code) e ative o [Code Review](/docs/pt/code-review#set-up-code-review) para seus repositórios GHES usando a mesma configuração que github.com.

61 </Step>61 </Step>

62</Steps>62</Steps>

63 63

65 Permissões do GitHub App65 Permissões do GitHub App

66</h3>66</h3>

67 67

68O manifesto configura o GitHub App com as permissões e eventos de webhook abaixo, que juntos cobrem sessões na nuvem, Code Review, Claude Security, marketplaces de plugins e métricas de contribuição:68O manifesto configura o GitHub App com as permissões e eventos de webhook abaixo, que juntos cobrem sessões na nuvem, Code Review, Claude Security e marketplaces de plugins:

69 69

71| :- | :- | :- |71| :- | :- | :- |

270* [Use Claude Code na nuvem](/docs/pt/claude-code-on-the-web): execute sessões do Claude Code em infraestrutura em nuvem270* [Use Claude Code na nuvem](/docs/pt/claude-code-on-the-web): execute sessões do Claude Code em infraestrutura em nuvem

271* [Code Review](/docs/pt/code-review): revisões automatizadas de PR271* [Code Review](/docs/pt/code-review): revisões automatizadas de PR

272* [Marketplaces de plugins](/docs/pt/plugins/host-marketplace): construir e distribuir catálogos de plugins272* [Marketplaces de plugins](/docs/pt/plugins/host-marketplace): construir e distribuir catálogos de plugins

273* [Analytics](/docs/pt/analytics): rastrear uso e métricas de contribuição273* [Analytics](/docs/pt/analytics): rastrear o uso do Claude Code em toda a sua organização

274* [Configurações gerenciadas](/docs/pt/settings): configuração de política em toda a organização274* [Configurações gerenciadas](/docs/pt/settings): configuração de política em toda a organização

275* [Configuração de rede](/docs/pt/network-config): requisitos de firewall e lista de permissões de IP275* [Configuração de rede](/docs/pt/network-config): requisitos de firewall e lista de permissões de IP

headless.md +19 −17

Details

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

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

91 91

92Quando stderr é um terminal e a execução já aguardou cinco segundos, Claude Code imprime uma linha em stderr que começa com `Waiting for background work to finish` e nomeia o trabalho. Com [saída `json` ou `stream-json`](#get-structured-output), a linha é impressa apenas quando stdout não é um terminal, para que o JSON que seu script lê nunca a contenha.

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

93 95

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

130cat build-error.txt | claude -p 'concisely explain the root cause of this build error' > output.txt132cat build-error.txt | claude -p 'concisely explain the root cause of this build error' > output.txt

131```133```

132 134

133Com `--output-format json`, a carga de resposta inclui `total_cost_usd` e um detalhamento de custo por modelo, para que os chamadores com script possam rastrear gastos sem consultar o [painel de uso](/docs/pt/costs). Quando você continua uma conversa anterior com `--continue` ou `--resume`, a execução relata o total da conversa, [gastos de execuções anteriores inclusos](/docs/pt/agent-sdk/cost-tracking#accumulate-costs-across-multiple-calls). Ambas as figuras são [estimativas do lado do cliente](/docs/pt/agent-sdk/cost-tracking) e podem diferir da sua fatura real.135Com `--output-format json`, o payload da resposta inclui `total_cost_usd` e um detalhamento de custo por modelo, para que os chamadores com script possam rastrear gastos sem consultar o [painel de uso](/docs/pt/costs). Quando você continua uma conversa anterior com `--continue` ou `--resume`, a execução relata o total da conversa, [gastos de execuções anteriores inclusos](/docs/pt/agent-sdk/cost-tracking#accumulate-costs-across-multiple-calls). Ambas as figuras são [estimativas do lado do cliente](/docs/pt/agent-sdk/cost-tracking) e podem diferir da sua fatura real.

134 136

135<Note>137<Note>

136 Stdin canalizado é limitado a 10MB. Se você exceder o limite, Claude Code sai com um erro claro e um status diferente de zero. Para trabalhar com entradas maiores, escreva o conteúdo em um arquivo e faça referência ao caminho do arquivo em seu prompt em vez de canalizá-lo.138 Stdin canalizado é limitado a 10MB. Se você exceder o limite, Claude Code sai com um erro claro e um status diferente de zero. Para trabalhar com entradas maiores, escreva o conteúdo em um arquivo e faça referência ao caminho do arquivo em seu prompt em vez de canalizá-lo.

172claude -p "Summarize this project" --output-format json174claude -p "Summarize this project" --output-format json

173```175```

174 176

175Para obter saída em conformidade com um esquema específico, use `--output-format json` com `--json-schema` e uma definição de [JSON Schema](https://json-schema.org/). A resposta inclui metadados sobre a solicitação (ID de sessão, uso, etc.) com a saída estruturada no campo `structured_output`.177Para obter saída em conformidade com um esquema específico, use `--output-format json` com `--json-schema` e uma definição de [JSON Schema](https://json-schema.org/). A resposta inclui metadados sobre a requisição (ID de sessão, uso, etc.) com a saída estruturada no campo `structured_output`.

176 178

177Este exemplo extrai nomes de funções e os retorna como uma matriz de strings:179Este exemplo extrai nomes de funções e os retorna como uma matriz de strings:

178 180

257 Lidar com tentativas de API259 Lidar com tentativas de API

258</h4>260</h4>

259 261

260Quando uma solicitação de API falha com um erro que pode ser repetido, Claude Code emite um evento `system/api_retry` antes de tentar novamente. Na v2.1.246 ou posterior, quando um `401` ou `403` rejeita uma credencial [`apiKeyHelper`](/docs/pt/settings-reference#apikeyhelper), Claude Code faz as duas primeiras tentativas silenciosamente sem evento, depois emite o evento como usual a partir da terceira tentativa consecutiva em diante. As tentativas silenciosas ainda contam para `attempt`. Você pode usar o evento para mostrar progresso de repetição em sua própria interface.262Quando uma requisição de API falha com um erro que pode ser repetido, Claude Code emite um evento `system/api_retry` antes de tentar novamente. Na v2.1.246 ou posterior, quando um `401` ou `403` rejeita uma credencial [`apiKeyHelper`](/docs/pt/settings-reference#apikeyhelper), Claude Code faz as duas primeiras tentativas silenciosamente sem evento, depois emite o evento como usual a partir da terceira tentativa consecutiva em diante. As tentativas silenciosas ainda contam para `attempt`. Você pode usar o evento para mostrar progresso de repetição em sua própria interface.

261 263

263| - | - | - |265| - | - | - |

296 298

297Quando um diretório ou arquivo `--plugin-dir` em si falha ao carregar, sua entrada `plugin_errors` inclui o caminho absoluto resolvido como `path`. Use-o para dizer qual de vários valores `--plugin-dir` falhou. O campo `path` requer Claude Code v2.1.283 ou posterior.299Quando um diretório ou arquivo `--plugin-dir` em si falha ao carregar, sua entrada `plugin_errors` inclui o caminho absoluto resolvido como `path`. Use-o para dizer qual de vários valores `--plugin-dir` falhou. O campo `path` requer Claude Code v2.1.283 ou posterior.

298 300

299Use os campos de servidor MCP da mesma forma. Quando você passa [`--mcp-config`](/docs/pt/cli-reference#cli-flags) com `-p`, Claude Code aguarda servidores ainda pendentes antes de executar a primeira volta, até o tempo limite de inicialização [`MCP_TIMEOUT`](/docs/pt/env-vars), 30 segundos por padrão. Um servidor remoto com uma [lista de ferramentas em cache](/docs/pt/agent-sdk/mcp#connection-timing) pula a espera, mostra `pending` em `system/init` e se conecta em sua primeira chamada de ferramenta. A espera requer Claude Code v2.1.221 ou posterior.301Use os campos de servidor MCP da mesma forma. Quando você passa [`--mcp-config`](/docs/pt/cli-reference#cli-flags) com `-p`, Claude Code aguarda servidores ainda pendentes antes de executar o primeiro turno, até o timeout de inicialização [`MCP_TIMEOUT`](/docs/pt/env-vars), 30 segundos por padrão. Um servidor remoto com uma [lista de ferramentas em cache](/docs/pt/agent-sdk/mcp#connection-timing) pula a espera, mostra `pending` em `system/init` e se conecta em sua primeira chamada de ferramenta. Em um [ambiente auto-hospedado](/docs/pt/self-hosted-environments-configuration#connection-timing), aplica-se uma espera mais curta. A espera requer Claude Code v2.1.221 ou posterior.

300 302

301Claude Code valida cada entrada `--mcp-config` na inicialização e pula entradas que falham na validação, por exemplo uma entrada `url` sem `type`. A execução continua e sai limpa, então verifique esses campos para capturar um servidor que nunca foi carregado:303Claude Code valida cada entrada `--mcp-config` na inicialização e pula entradas que falham na validação, por exemplo uma entrada `url` sem `type`. A execução continua e sai limpa, então verifique esses campos para capturar um servidor que nunca foi carregado:

302 304

311 Rastrear instalações de plugin313 Rastrear instalações de plugin

312</h4>314</h4>

313 315

314Quando [`CLAUDE_CODE_SYNC_PLUGIN_INSTALL`](/docs/pt/env-vars) está definido, Claude Code emite eventos `system/plugin_install` enquanto plugins do marketplace instalam antes da primeira volta. Use estes para exibir o progresso de instalação em sua própria UI.316Quando [`CLAUDE_CODE_SYNC_PLUGIN_INSTALL`](/docs/pt/env-vars) está definido, Claude Code emite eventos `system/plugin_install` enquanto plugins do marketplace instalam antes do primeiro turno. Use estes para exibir o progresso de instalação em sua própria UI.

315 317

317| - | - | - |319| - | - | - |

327 Aprovar ferramentas automaticamente329 Aprovar ferramentas automaticamente

328</h3>330</h3>

329 331

330Use `--allowedTools` para permitir que Claude use certas ferramentas sem solicitar. Listar `Read` e `Edit` permite que Claude leia e edite arquivos sem pedir permissão. Listar `Bash` faz o mesmo para comandos de shell, exceto em uma execução que começa em [modo auto](/docs/pt/permission-modes#how-auto-mode-evaluates-actions), onde Claude Code descarta uma entrada `Bash` simples como uma regra de permissão ampla e o modo auto avalia cada comando em vez disso. Este exemplo executa um conjunto de testes e corrige falhas com essas três ferramentas listadas:332Use `--allowedTools` para permitir que Claude use certas ferramentas sem solicitar. Listar `Read` e `Edit` permite que Claude leia e edite arquivos sem pedir permissão, exceto leituras de [caminhos de rede](/docs/pt/permissions#network-paths). Listar `Bash` faz o mesmo para comandos de shell, exceto em uma execução que começa em [modo auto](/docs/pt/permission-modes#how-auto-mode-evaluates-actions), onde Claude Code descarta uma entrada `Bash` simples como uma regra de permissão ampla e o modo auto avalia cada comando em vez disso. Este exemplo executa um conjunto de testes e corrige falhas com essas três ferramentas listadas:

331 333

332```bash theme={null}334```bash theme={null}

333claude -p "Run the test suite and fix any failures" \335claude -p "Run the test suite and fix any failures" \

337Para definir uma linha de base para toda a sessão em vez de listar ferramentas individuais, passe um [modo de permissão](/docs/pt/permission-modes). Uma execução onde nada define um modo de permissão toma o [modo de permissão inicial integrado](/docs/pt/permission-modes#which-mode-a-session-starts-in), que pode ser `auto`, então passe o que você deseja:339Para definir uma linha de base para toda a sessão em vez de listar ferramentas individuais, passe um [modo de permissão](/docs/pt/permission-modes). Uma execução onde nada define um modo de permissão toma o [modo de permissão inicial integrado](/docs/pt/permission-modes#which-mode-a-session-starts-in), que pode ser `auto`, então passe o que você deseja:

338 340

339* **`auto`**: passe `--permission-mode auto` para ter um classificador revisar a maioria das ações em vez de você341* **`auto`**: passe `--permission-mode auto` para ter um classificador revisar a maioria das ações em vez de você

340* **`dontAsk`**: Claude Code nega qualquer chamada que de outra forma solicitaria, o que é útil para execuções de CI bloqueadas. Ações que não precisam de aprovação no modo Manual ainda são executadas, como leituras de arquivo em seus diretórios de trabalho e o [conjunto de comandos somente leitura](/docs/pt/permissions#read-only-commands), e também ações que suas entradas `--allowedTools` ou regras `permissions.allow` cobrem. `AskUserQuestion`, ferramentas de conector [que sua organização definiu como `ask`](/docs/pt/mcp#organization-controls-on-connector-tools), e ferramentas MCP marcadas [`requiresUserInteraction`](/docs/pt/mcp#require-approval-for-a-specific-tool) são negadas mesmo quando uma regra de permissão corresponde342* **`dontAsk`**: Claude Code nega qualquer chamada que de outra forma solicitaria, o que é útil para execuções de CI bloqueadas. Ações que não precisam de aprovação no modo Manual ainda são executadas, como leituras de arquivo em seus diretórios de trabalho e o [conjunto de comandos somente leitura](/docs/pt/permissions#read-only-commands), e também ações que suas entradas `--allowedTools` ou regras `permissions.allow` cobrem. `AskUserQuestion`, ferramentas de conector [que sua organização definiu como `ask`](/docs/pt/mcp#organization-controls-on-connector-tools), ferramentas MCP marcadas [`requiresUserInteraction`](/docs/pt/mcp#require-approval-for-a-specific-tool) e [leituras de caminhos de rede](/docs/pt/permissions#network-paths) são negadas mesmo quando uma regra de permissão corresponde

341* **`acceptEdits`**: Claude escreve arquivos sem solicitar, e Claude Code aprova automaticamente comandos comuns do sistema de arquivos como `mkdir`, `touch`, `mv` e `cp`. As [ações que nenhum modo aprova automaticamente](/docs/pt/permission-modes#actions-no-mode-auto-approves) ainda se aplicam. Além do conjunto de comandos somente leitura, outros comandos de shell e solicitações de rede ainda precisam de uma entrada `--allowedTools` ou uma regra `permissions.allow`. Consulte [o que `acceptEdits` aprova automaticamente](/docs/pt/permission-modes#auto-approve-file-edits-with-acceptedits-mode) para a lista completa343* **`acceptEdits`**: Claude escreve arquivos sem solicitar, e Claude Code aprova automaticamente comandos comuns do sistema de arquivos como `mkdir`, `touch`, `mv` e `cp`. As [ações que nenhum modo aprova automaticamente](/docs/pt/permission-modes#actions-no-mode-auto-approves) ainda se aplicam. Além do conjunto de comandos somente leitura, outros comandos de shell e requisições de rede ainda precisam de uma entrada `--allowedTools` ou uma regra `permissions.allow`. Consulte [o que `acceptEdits` aprova automaticamente](/docs/pt/permission-modes#auto-approve-file-edits-with-acceptedits-mode) para a lista completa

342 344

343Este exemplo aplica correções de lint com `acceptEdits` como a linha de base:345Este exemplo aplica correções de lint com `acceptEdits` como a linha de base:

344 346

350 Desativar prompts de permissão em execuções autônomas352 Desativar prompts de permissão em execuções autônomas

351</h3>353</h3>

352 354

353Passe `--permission-prompts none` quando ninguém estiver disponível para responder prompts de permissão, por exemplo em um trabalho agendado. O sinalizador é mais importante quando sua execução tem um host de permissão: um aplicativo Agent SDK com um callback [`canUseTool`](/docs/pt/agent-sdk/user-input), ou uma ferramenta MCP que você passa com [`--permission-prompt-tool`](/docs/pt/cli-reference#cli-flags). Sem o sinalizador, sua execução aguarda que esse host responda cada solicitação de permissão.355Passe `--permission-prompts none` quando ninguém estiver disponível para responder prompts de permissão, por exemplo em um trabalho agendado. A flag é mais importante quando sua execução tem um host de permissão: um aplicativo Agent SDK com um callback [`canUseTool`](/docs/pt/agent-sdk/user-input), ou uma ferramenta MCP que você passa com [`--permission-prompt-tool`](/docs/pt/cli-reference#cli-flags). Sem a flag, sua execução aguarda que esse host responda cada solicitação de permissão.

354 356

355Com o sinalizador, sua execução não consulta o host ou aguarda por ele. Qualquer coisa que solicitaria é negada a menos que um hook `PermissionRequest` a permita, Claude é informado que ninguém pode aprovar a solicitação e não deve tentar novamente, e a execução continua. Em uma execução `-p` sem host, essas solicitações são negadas de qualquer forma, e o sinalizador também diz a Claude não tentar novamente. Regras de permissão, [hooks `PermissionRequest`](/docs/pt/hooks#permissionrequest) e o modo de permissão que você definir ainda decidem cada chamada primeiro; Claude Code nega apenas as solicitações que nada mais resolve.357Com a flag, sua execução não consulta o host ou aguarda por ele. Qualquer coisa que solicitaria é negada a menos que um hook `PermissionRequest` a permita, Claude é informado que ninguém pode aprovar a solicitação e não deve tentar novamente, e a execução continua. Em uma execução `-p` sem host, essas solicitações são negadas de qualquer forma, e a flag também diz a Claude não tentar novamente. Regras de permissão, [hooks `PermissionRequest`](/docs/pt/hooks#permissionrequest) e o modo de permissão que você definir ainda decidem cada chamada primeiro; Claude Code nega apenas as solicitações que nada mais resolve.

356 358

357Este exemplo executa uma tarefa autônoma em [modo auto](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode). O classificador revisa cada ação como usual, e Claude Code nega qualquer coisa que teria caído de volta para um prompt:359Este exemplo executa uma tarefa autônoma em [modo auto](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode). O classificador revisa cada ação como usual, e Claude Code nega qualquer coisa que teria caído de volta para um prompt:

358 360

365Com `--output-format stream-json`, negações aparecem como mensagens de sistema `permission_denied`, e a mensagem de resultado final as lista em `permission_denials`.367Com `--output-format stream-json`, negações aparecem como mensagens de sistema `permission_denied`, e a mensagem de resultado final as lista em `permission_denials`.

366 368

367<Note>369<Note>

368 O sinalizador `--permission-prompts` requer Claude Code v2.1.259 ou posterior. Versões anteriores o rejeitam com um erro de opção desconhecida.370 A flag `--permission-prompts` requer Claude Code v2.1.259 ou posterior. Versões anteriores a rejeitam com um erro de opção desconhecida.

369</Note>371</Note>

370 372

371<h3 id="create-a-commit">373<h3 id="create-a-commit">

379 --allowedTools "Bash(git diff *),Bash(git log *),Bash(git status *),Bash(git commit *)"381 --allowedTools "Bash(git diff *),Bash(git log *),Bash(git status *),Bash(git commit *)"

380```382```

381 383

382O sinalizador `--allowedTools` usa [sintaxe de regra de permissão](/docs/pt/settings-reference#permission-rule-syntax). O ` *` à direita habilita correspondência de prefixo, então `Bash(git diff *)` permite qualquer comando começando com `git diff`. O espaço antes de `*` é importante: sem ele, `Bash(git diff*)` também corresponderia a `git diff-index`.384A flag `--allowedTools` usa [sintaxe de regra de permissão](/docs/pt/settings-reference#permission-rule-syntax). O ` *` à direita habilita correspondência de prefixo, então `Bash(git diff *)` permite qualquer comando começando com `git diff`. O espaço antes de `*` é importante: sem ele, `Bash(git diff*)` também corresponderia a `git diff-index`.

383 385

384<Note>386<Note>

385 O suporte a comandos difere no modo `-p`:387 O suporte a comandos difere no modo `-p`:

386 388

387 * [Skills](/docs/pt/skills) invocadas pelo usuário e comandos personalizados funcionam. Inclua `/skill-name` na string de prompt e Claude Code o expande antes de executar.389 * [Skills](/docs/pt/skills) invocadas pelo usuário e comandos personalizados funcionam. Inclua `/skill-name` na string de prompt e Claude Code o expande antes de executar.

388 * Comandos integrados que abrem um diálogo interativo, como `/login`, não estão disponíveis no modo `-p`.390 * Comandos integrados que só são executados na interface do terminal, como `/login`, não estão disponíveis.

389 * `/model`, `/effort`, `/fast`, `/color` e `/rename` aceitam o valor como um argumento, por exemplo `/model sonnet`, e `/mcp` sem argumento imprime um resumo de texto do status do servidor. Essas formas requerem Claude Code v2.1.205 ou posterior e seguem as [notas de disponibilidade de cada comando](/docs/pt/commands#all-commands).391 * `/model`, `/effort`, `/fast`, `/color` e `/rename` aceitam o valor como um argumento, por exemplo `/model sonnet`, e `/mcp` sem argumento imprime um resumo de texto do status do servidor. Essas formas requerem Claude Code v2.1.205 ou posterior e seguem as [notas de disponibilidade de cada comando](/docs/pt/commands#all-commands).

390 * Para alterar uma configuração, passe `key=value` para `/config`, por exemplo `/config thinking=false`.392 * Para alterar uma configuração, passe `key=value` para `/config`, por exemplo `/config thinking=false`.

391 * `/output-style <style>` alterna [estilos de saída](/docs/pt/output-styles) e `/output-style` sozinho os lista. Requer Claude Code v2.1.269 ou posterior.393 * `/output-style <style>` alterna [estilos de saída](/docs/pt/output-styles) e `/output-style` sozinho os lista. Requer Claude Code v2.1.269 ou posterior.

392</Note>394</Note>

393 395

394<h3 id="customize-the-system-prompt">396<h3 id="customize-the-system-prompt">

395 Personalizar o prompt do sistema397 Personalizar o system prompt

396</h3>398</h3>

397 399

398Use `--append-system-prompt` para adicionar instruções mantendo o comportamento padrão do Claude Code. Este exemplo envia um diff de PR para Claude e o instrui a revisar vulnerabilidades de segurança. Salve como um script de shell, por exemplo `review.sh`:400Use `--append-system-prompt` para adicionar instruções mantendo o comportamento padrão do Claude Code. Este exemplo envia um diff de PR para Claude e o instrui a revisar vulnerabilidades de segurança. Salve como um script de shell, por exemplo `review.sh`:

405 407

406No script, `"$1"` representa o primeiro argumento que você passa na linha de comando. Execute `bash review.sh 123` e o shell substitui `"$1"` por `123`, então o script busca o diff para PR 123. Claude Code imprime a revisão como JSON, com o texto no campo `result`.408No script, `"$1"` representa o primeiro argumento que você passa na linha de comando. Execute `bash review.sh 123` e o shell substitui `"$1"` por `123`, então o script busca o diff para PR 123. Claude Code imprime a revisão como JSON, com o texto no campo `result`.

407 409

408Consulte [system prompt flags](/docs/pt/cli-reference#system-prompt-flags) para mais opções, incluindo `--system-prompt` para substituir completamente o prompt padrão.410Consulte [flags de system prompt](/docs/pt/cli-reference#system-prompt-flags) para mais opções, incluindo `--system-prompt` para substituir completamente o prompt padrão.

409 411

410<h3 id="continue-conversations">412<h3 id="continue-conversations">

411 Continuar conversas413 Continuar conversas

412</h3>414</h3>

413 415

414Use `--continue` para continuar a conversa mais recente, ou `--resume` com um ID de sessão para continuar uma conversa específica. Na Claude Code v2.1.257 ou posterior, quando você passa `--continue`, Claude Code abre uma [sessão em background](/docs/pt/sessions#resume-a-session) que terminou, mas não uma que ainda está em execução. Este exemplo executa uma revisão e depois envia prompts de acompanhamento:416Use `--continue` para continuar a conversa mais recente, ou `--resume` com um ID de sessão para continuar uma conversa específica. Na Claude Code v2.1.257 ou posterior, quando você passa `--continue`, Claude Code abre uma [sessão em background](/docs/pt/sessions#where-the-session-picker-looks) que terminou, mas não uma que ainda está em execução. Este exemplo executa uma revisão e depois envia prompts de acompanhamento:

415 417

416```bash theme={null}418```bash theme={null}

417# First request419# First request

429claude -p "Continue that review" --resume "$session_id"431claude -p "Continue that review" --resume "$session_id"

430```432```

431 433

432Você pode executar os dois comandos de diretórios diferentes: Claude Code [encontra a sessão por seu ID](/docs/pt/sessions#resume-a-session) em qualquer projeto nesta máquina. Antes da v2.1.223, Claude Code procurava o ID apenas no diretório do projeto atual e seus git worktrees, então você tinha que executar ambos os comandos do mesmo diretório.434Você pode executar os dois comandos de diretórios diferentes: Claude Code [encontra a sessão por seu ID](/docs/pt/sessions#where-the-session-picker-looks) em qualquer projeto nesta máquina.

433 435

434No lugar do ID da sessão, você pode passar para `--resume` o caminho absoluto para o arquivo de [transcrição](/docs/pt/sessions#where-transcripts-are-stored) `.jsonl` de uma sessão, e Claude Code continua a conversa armazenada nesse arquivo.436No lugar do ID da sessão, você pode passar para `--resume` o caminho absoluto para o arquivo de [transcrição](/docs/pt/sessions#where-transcripts-are-stored) `.jsonl` de uma sessão, e Claude Code continua a conversa armazenada nesse arquivo.

435 437

hooks.md +40 −13

Details

425 425

426Todos os hooks correspondentes executam em paralelo. Se você definir o mesmo manipulador em mais de um arquivo de configurações, ele executa uma vez. Uma cópia do mesmo manipulador de um plugin ou skill permanece separada.426Todos os hooks correspondentes executam em paralelo. Se você definir o mesmo manipulador em mais de um arquivo de configurações, ele executa uma vez. Uma cópia do mesmo manipulador de um plugin ou skill permanece separada.

427 427

428Manipuladores executam no diretório atual com o ambiente do Claude Code. Se o diretório atual não existir mais, por exemplo uma worktree ou diretório temporário que outro shell deletou no meio da sessão, Claude Code executa hooks de comando a partir do primeiro destes que ainda existe: o diretório em que a sessão começou, a raiz do projeto, seu diretório home ou o diretório temporário do sistema. Claude Code registra um aviso nomeando o diretório de fallback no [log de debug](#debug-hooks).428Manipuladores executam no diretório atual com o ambiente do Claude Code. Se o diretório atual não existir mais, por exemplo um worktree ou diretório temporário que outro shell deletou no meio da sessão, Claude Code executa hooks de comando a partir do primeiro destes que ainda existe: o diretório em que a sessão começou, a raiz do projeto, seu diretório home ou o diretório temporário do sistema. Claude Code registra um aviso nomeando o diretório de fallback no [log de debug](#debug-hooks). Para uma sessão de worktree que você inicia a partir do aplicativo desktop, consulte [O que os worktrees compartilham com o checkout principal](/docs/pt/worktrees#what-worktrees-share-with-the-main-checkout).

429 429

430A variável de ambiente `$CLAUDE_CODE_REMOTE` é `"true"` em ambientes web remotos e não é definida na CLI local. Claude Code v2.1.199 e posterior define [`$CLAUDE_CODE_BRIDGE_SESSION_ID`](/docs/pt/env-vars) para o ID de sessão [Remote Control](/docs/pt/remote-control) enquanto a sessão local tem uma conexão Remote Control ativa.430A variável de ambiente `$CLAUDE_CODE_REMOTE` é `"true"` em ambientes web remotos e não é definida na CLI local. Claude Code v2.1.199 e posterior define [`$CLAUDE_CODE_BRIDGE_SESSION_ID`](/docs/pt/env-vars) para o ID de sessão [Remote Control](/docs/pt/remote-control) enquanto a sessão local tem uma conexão Remote Control ativa.

431 431

644 **Worktrees são diferentes.** Se Claude entra em uma [worktree](/docs/pt/worktrees) durante a sessão, Claude Code mantém `${CLAUDE_PROJECT_DIR}` onde estava e passa o caminho da worktree para seus hooks de uma forma diferente:644 **Worktrees são diferentes.** Se Claude entra em uma [worktree](/docs/pt/worktrees) durante a sessão, Claude Code mantém `${CLAUDE_PROJECT_DIR}` onde estava e passa o caminho da worktree para seus hooks de uma forma diferente:

645 645

646 * **`${CLAUDE_PROJECT_DIR}` fica no lugar**: ainda aponta para a raiz do projeto onde a sessão começou, então um comando como `${CLAUDE_PROJECT_DIR}/.claude/hooks/check-style.sh` ainda executa o script no checkout principal.646 * **`${CLAUDE_PROJECT_DIR}` fica no lugar**: ainda aponta para a raiz do projeto onde a sessão começou, então um comando como `${CLAUDE_PROJECT_DIR}/.claude/hooks/check-style.sh` ainda executa o script no checkout principal.

647 * **`cwd` segue Claude**: o campo `cwd` na [entrada JSON](#common-input-fields) do hook é a raiz da worktree após Claude entrar em uma worktree, e o novo diretório após Claude executar `cd`. Leia-o quando um hook precisa saber em qual diretório Claude está trabalhando.647 * **`cwd` segue Claude**: o campo `cwd` na [entrada JSON](#common-input-fields) do hook é a raiz do worktree após Claude entrar em um worktree, e o novo diretório após Claude executar `cd`. Leia-o quando um hook precisa saber em qual diretório Claude está trabalhando.

648

649 Para uma sessão de worktree que você inicia a partir do aplicativo desktop, consulte [O que os worktrees compartilham com o checkout principal](/docs/pt/worktrees#what-worktrees-share-with-the-main-checkout) para saber para onde `${CLAUDE_PROJECT_DIR}` aponta.

648</Note>650</Note>

649 651

650Prefira [forma exec](#exec-form-and-shell-form) para qualquer hook que referencie um placeholder de caminho. Em forma shell, envolva cada placeholder em aspas duplas.652Prefira [forma exec](#exec-form-and-shell-form) para qualquer hook que referencie um placeholder de caminho. Em forma shell, envolva cada placeholder em aspas duplas.

782| `effort` | Objeto com um campo `level` contendo o [nível de esforço](/docs/pt/model-config#adjust-effort-level) em vigor quando o hook é executado: `"low"`, `"medium"`, `"high"`, `"xhigh"` ou `"max"`. Se você definir um nível que o modelo ativo não suporta, `level` relata o nível que Claude Code executou em vez disso; [Ajustar nível de esforço](/docs/pt/model-config#adjust-effort-level) diz como ele escolhe esse nível. O objeto corresponde ao campo `effort` da [linha de status](/docs/pt/statusline#available-data). Presente para eventos que disparam dentro de um contexto de uso de ferramenta, como `PreToolUse`, `PostToolUse`, `Stop` e `SubagentStop`, quando o modelo atual suporta o parâmetro de esforço. O nível também está disponível para comandos de hook e a ferramenta Bash como a variável de ambiente `$CLAUDE_EFFORT`. |784| `effort` | Objeto com um campo `level` contendo o [nível de esforço](/docs/pt/model-config#adjust-effort-level) em vigor quando o hook é executado: `"low"`, `"medium"`, `"high"`, `"xhigh"` ou `"max"`. Se você definir um nível que o modelo ativo não suporta, `level` relata o nível que Claude Code executou em vez disso; [Ajustar nível de esforço](/docs/pt/model-config#adjust-effort-level) diz como ele escolhe esse nível. O objeto corresponde ao campo `effort` da [linha de status](/docs/pt/statusline#available-data). Presente para eventos que disparam dentro de um contexto de uso de ferramenta, como `PreToolUse`, `PostToolUse`, `Stop` e `SubagentStop`, quando o modelo atual suporta o parâmetro de esforço. O nível também está disponível para comandos de hook e a ferramenta Bash como a variável de ambiente `$CLAUDE_EFFORT`. |

784 786

785Ao executar com `--agent` ou dentro de um subagente, dois campos adicionais são incluídos:787`agent_id` e `agent_type` dizem ao seu script em qual agente um hook disparou, como um subagente, um [colega de equipe em processo](/docs/pt/agent-teams#choose-a-display-mode) ou o agente que você escolheu com `--agent`:

786 788

787| Campo | Descrição |789| Campo | Descrição |

788| :- | :- |790| :- | :- |

789| `agent_id` | Identificador único para o subagente. Presente apenas quando o hook dispara dentro de uma chamada de subagente. Use isso para distinguir chamadas de hook de subagente de chamadas de thread principal. |791| `agent_id` | Identificador único para o subagente ou colega de equipe em processo no qual o hook dispara. |

790| `agent_type` | Nome do agente (por exemplo, `"Explore"` ou `"security-reviewer"`). Presente quando a sessão usa `--agent` ou o hook dispara dentro de um subagente. Para subagentes, o tipo do subagente tem precedência sobre o valor `--agent` da sessão. Consulte [SubagentStart](#subagentstart) para os valores que subagentes personalizados e de plugin relatam e como escrever um matcher contra um nome com escopo de plugin. |792| `agent_type` | Nome do agente (por exemplo, `"Explore"` ou `"security-reviewer"`). Presente quando a sessão usa `--agent` ou o hook dispara dentro de um subagente. Para subagentes, o tipo do subagente tem precedência sobre o valor `--agent` da sessão. Consulte [SubagentStart](#subagentstart) para os valores que subagentes personalizados e de plugin relatam e como escrever um matcher contra um nome com escopo de plugin. |

791 793

792Apenas hooks [`SessionStart`](#sessionstart) podem receber um campo `model`, e Claude Code nem sempre o inclui. Hooks [`PreModelSwitch`](#premodelswitch) e [`PostModelSwitch`](#postmodelswitch) recebem `from_model` e `to_model` em vez disso, portanto use um hook PostModelSwitch para acompanhar o modelo conforme ele muda durante uma sessão.794Apenas hooks [`SessionStart`](#sessionstart) podem receber um campo `model`, e Claude Code nem sempre o inclui. Hooks [`PreModelSwitch`](#premodelswitch) e [`PostModelSwitch`](#postmodelswitch) recebem `from_model` e `to_model` em vez disso, portanto use um hook PostModelSwitch para acompanhar o modelo conforme ele muda durante uma sessão.

855 857

856Para a maioria dos eventos, Claude Code escreve stdout no log de debug e não o mostra na transcrição. As exceções são `UserPromptSubmit`, `UserPromptExpansion`, `SessionStart` e `PostModelSwitch`, onde Claude Code adiciona stdout em texto simples como contexto que Claude pode ver e agir.858Para a maioria dos eventos, Claude Code escreve stdout no log de debug e não o mostra na transcrição. As exceções são `UserPromptSubmit`, `UserPromptExpansion`, `SessionStart` e `PostModelSwitch`, onde Claude Code adiciona stdout em texto simples como contexto que Claude pode ver e agir.

857 859

858Se Claude Code lê seu stdout como [saída JSON](#json-output) ou como texto simples depende de como ele começa e termina, ignorando espaço em branco ao redor:860Para um hook que não é [async](#how-async-hooks-execute), Claude Code analisa seu stdout como [saída JSON](#json-output) quando toda a saída é um único objeto JSON sem nada ao redor além de espaço em branco, e caso contrário como texto simples ou uma falha de análise:

859 861

860* **Começa com `{` e termina com `}`**: Claude Code o analisa como JSON. Quando a saída é duas ou mais linhas que cada uma analisa como JSON por conta própria, e nenhuma linha é um objeto [saída JSON](#json-output) que define um campo, Claude Code trata toda a saída como texto simples. Quando uma dessas linhas define um campo, toda a saída é uma falha de análise.862* **Um objeto JSON, em uma linha ou em várias**: analisado como saída JSON.

861* **Começa com `{` mas não termina com `}`**: Claude Code o trata como texto simples.863* **Saída que não começa com `{`, ou que começa com `{` e não termina com `}`**: texto simples. Um array JSON e uma string JSON entre aspas são texto simples por esta regra.

862* **Começa com qualquer outra coisa**: Claude Code o trata como texto simples, um array JSON ou uma string JSON entre aspas incluída.864* **Duas ou mais linhas que cada uma analisa como JSON por conta própria, a primeira começando com `{` e a última terminando com `}`**: texto simples quando nenhuma linha é um objeto de saída JSON que define um campo, e uma falha de análise quando alguma é.

865* **Qualquer outra coisa que começa com `{` e termina com `}` mas não é JSON válido**: uma falha de análise.

863 866

864Quando Claude Code tenta analisar seu stdout como JSON e não consegue, ou o objeto analisado falha na [validação de esquema](#json-output), a execução é um [erro não-bloqueador](#exit-code-output). O aviso `<hook name> hook error` carrega a mensagem de análise ou validação. Nos eventos que adicionam stdout em texto simples como contexto, Claude Code não adiciona stdout que não conseguiu analisar.867Quando Claude Code tenta analisar seu stdout como JSON e não consegue, ou o objeto analisado falha na [validação de esquema](#json-output), a execução é um [erro não-bloqueador](#exit-code-output). O aviso `<hook name> hook error` carrega a mensagem de análise ou validação. Nos eventos que adicionam stdout em texto simples como contexto, Claude Code não adiciona stdout que não conseguiu analisar.

865 868

1050 Escolha uma abordagem por hook: ou use códigos de saída sozinhos para sinalizar, ou saia 0 e imprima JSON para controle estruturado. Se você misturar, saída 2 mantém seu [efeito de bloqueio](#exit-code-2-behavior-per-event), e Claude Code ainda lê os campos JSON, com a exceção de elicitação única anotada em [Código de saída 2](#exit-code-2).1053 Escolha uma abordagem por hook: ou use códigos de saída sozinhos para sinalizar, ou saia 0 e imprima JSON para controle estruturado. Se você misturar, saída 2 mantém seu [efeito de bloqueio](#exit-code-2-behavior-per-event), e Claude Code ainda lê os campos JSON, com a exceção de elicitação única anotada em [Código de saída 2](#exit-code-2).

1051</Note>1054</Note>

1052 1055

1053O stdout do seu hook deve conter apenas o objeto JSON. Se seu perfil shell imprime texto na inicialização, pode interferir com análise JSON. Consulte [Hook JSON não tem efeito](/docs/pt/hooks-guide#hook-json-has-no-effect) no guia de solução de problemas.1056Imprima apenas o objeto JSON em stdout. Para um hook que não é [async](#how-async-hooks-execute), outro texto ali, como uma linha que seu perfil shell imprime na inicialização, impede Claude Code de ler o objeto como JSON, e [Hook JSON não tem efeito](/docs/pt/hooks-guide#hook-json-has-no-effect) mostra como encontrar e silenciar esse texto.

1054 1057

1055As strings de saída de hook `additionalContext`, `systemMessage` e `initialUserMessage`, e seu stdout simples, são limitadas a 10.000 caracteres:1058As strings de saída de hook `additionalContext`, `systemMessage` e `initialUserMessage`, e seu stdout simples, são limitadas a 10.000 caracteres:

1056 1059

1142 1145

1143Quando vários hooks retornam `additionalContext` para o mesmo evento, Claude recebe todos os valores.1146Quando vários hooks retornam `additionalContext` para o mesmo evento, Claude recebe todos os valores.

1144 1147

1148Se sua string contiver uma tag `<system-reminder>` ou `</system-reminder>`, Claude recebe a string com o `<` dessa tag substituído por `<`.

1149

1145Se um valor exceder 10.000 caracteres, Claude Code escreve o texto em um arquivo no diretório de sessão e passa Claude o caminho do arquivo com uma visualização de até os primeiros 2.000 caracteres em vez disso. Claude pode ler o arquivo, mas Claude Code não pede a Claude para.1150Se um valor exceder 10.000 caracteres, Claude Code escreve o texto em um arquivo no diretório de sessão e passa Claude o caminho do arquivo com uma visualização de até os primeiros 2.000 caracteres em vez disso. Claude pode ler o arquivo, mas Claude Code não pede a Claude para.

1146 1151

1147Use `additionalContext` para informações que Claude deve saber sobre o estado atual do seu ambiente ou a operação que acabou de executar:1152Use `additionalContext` para informações que Claude deve saber sobre o estado atual do seu ambiente ou a operação que acabou de executar:

1364 Persistir variáveis de ambiente1369 Persistir variáveis de ambiente

1365</h4>1370</h4>

1366 1371

1367Os hooks SessionStart têm acesso à variável de ambiente `CLAUDE_ENV_FILE`, que fornece um caminho de arquivo onde você pode persistir variáveis de ambiente para comandos Bash subsequentes.1372Os hooks SessionStart têm acesso à variável de ambiente `CLAUDE_ENV_FILE`, que fornece um caminho de arquivo onde você pode persistir variáveis de ambiente para os comandos de shell que o Claude executa mais tarde na sessão.

1368 1373

1369Para definir variáveis de ambiente individuais, escreva instruções `export` em `CLAUDE_ENV_FILE`. Use anexação (`>>`) para preservar variáveis definidas por outros hooks:1374Para definir variáveis de ambiente individuais, escreva instruções `export` em `CLAUDE_ENV_FILE`. Use anexação (`>>`) para preservar variáveis definidas por outros hooks:

1370 1375

1399exit 01404exit 0

1400```1405```

1401 1406

1407Cada comando Bash executa o conteúdo do arquivo como código de shell antes do próprio comando, portanto uma linha ali pode usar qualquer coisa que o Bash avalie, como a referência `$PATH` em `export PATH="$PATH:./node_modules/.bin"`.

1408

1409<a id="persisted-variables-in-powershell-commands" />

1410

1411<h5 id="persisted-variables-in-powershell-commands">

1412 Variáveis persistidas em comandos PowerShell

1413</h5>

1414

1415Os comandos [PowerShell](/docs/pt/tools-reference#powershell-tool) também recebem as variáveis de `CLAUDE_ENV_FILE`, no Claude Code v2.1.296 ou posterior, mas o PowerShell nunca executa o arquivo. Em vez disso, o Claude Code lê as atribuições do arquivo e as copia para o ambiente do comando PowerShell. Ele faz isso somente quando cada linha é uma das seguintes, considerando o que todos os hooks desta sessão gravaram e qualquer script para o qual você [definiu `CLAUDE_ENV_FILE`](/docs/pt/env-vars) antes da inicialização:

1416

1417* Uma linha em branco ou um comentário `#`

1418* Uma atribuição no início da linha, escrita como `export NAME=value`, `declare -x NAME=value` ou `NAME=value`, com um valor que o Bash usaria exatamente como escrito, composto por qualquer combinação destas partes: texto sem aspas que usa apenas letras, dígitos e os caracteres `_ @ % + = : , . / -`, texto entre aspas simples e texto entre aspas duplas em que qualquer `$`, crase ou `"` interno esteja escapado com uma barra invertida

1419

1420Se qualquer linha for de outro tipo, como `export PATH="$PATH:./node_modules/.bin"` com seu `$PATH` não escapado, um comando `source` ou as strings `$'...'` que `direnv export bash` imprime, os comandos PowerShell não recebem nenhuma das variáveis, e `claude --debug` registra `Session environment is not all plain assignments`. Os comandos Bash ainda recebem todas elas. No Windows, os comandos PowerShell também não recebem uma variável cujo valor contenha `/` ou `\`, porque o Git Bash e o Windows escrevem caminhos de forma diferente. Um comando PowerShell em [sandbox](/docs/pt/sandboxing) não recebe nenhuma das variáveis.

1421

1402<Note>1422<Note>

1403 `CLAUDE_ENV_FILE` está disponível para os hooks SessionStart, [Setup](#setup), [CwdChanged](#cwdchanged) e [FileChanged](#filechanged). Outros tipos de hook não têm acesso a essa variável.1423 `CLAUDE_ENV_FILE` está disponível para os hooks SessionStart, [Setup](#setup), [CwdChanged](#cwdchanged) e [FileChanged](#filechanged). Outros eventos de hook não têm acesso a esta variável, nem um hook que é executado no PowerShell, seja por meio de [`"shell": "powershell"`](#command-hook-fields) ou por padrão no Windows sem Git Bash.

1404</Note>1424</Note>

1405 1425

1406<h3 id="setup">1426<h3 id="setup">

2030 2050

2031| Campo | Descrição |2051| Campo | Descrição |

2032| :- | :- |2052| :- | :- |

2033| `permissionDecision` | `"allow"` pula o prompt de permissão, exceto para as [ações que nenhum modo aprova automaticamente](/docs/pt/permission-modes#actions-no-mode-auto-approves) e para `AskUserQuestion` e `ExitPlanMode`, que precisam de [`updatedInput` combinado com ele](#allow-with-updatedinput). `"deny"` impede a chamada de ferramenta. `"ask"` solicita confirmação ao usuário. `"defer"` sai de forma controlada para que a ferramenta possa ser retomada depois. [Regras de negação e de confirmação](/docs/pt/permissions#manage-permissions) ainda são avaliadas, independentemente do que o hook retornar |2053| `permissionDecision` | `"allow"` ignora o prompt de permissão, exceto para as [ações que nenhum modo aprova automaticamente](/docs/pt/permission-modes#actions-no-mode-auto-approves), para [leituras de caminhos de rede](/docs/pt/permissions#network-paths) e para `AskUserQuestion` e `ExitPlanMode`, que precisam de [`updatedInput` combinado com ele](#allow-with-updatedinput). `"deny"` impede a chamada de ferramenta. `"ask"` pede ao usuário que confirme. `"defer"` sai de forma controlada para que a ferramenta possa ser retomada mais tarde. As [regras de negação e de confirmação](/docs/pt/permissions#manage-permissions) ainda são avaliadas independentemente do que o hook retorne |

2034| `permissionDecisionReason` | Para `"ask"`, mostrado ao usuário no prompt de permissão. Quando o Claude Code [nega a chamada](/docs/pt/headless#turn-off-permission-prompts-in-unattended-runs) em uma execução `-p` em que ninguém pode responder a esse prompt, o Claude lê o motivo no resultado da ferramenta. Para `"deny"`, mostrado ao Claude. Para `"allow"` e `"defer"`, gravado apenas no [log de depuração](#debug-hooks) |2054| `permissionDecisionReason` | Para `"ask"`, mostrado ao usuário no prompt de permissão. Quando o Claude Code [nega a chamada](/docs/pt/headless#turn-off-permission-prompts-in-unattended-runs) em uma execução `-p` em que ninguém pode responder a esse prompt, o Claude lê o motivo no resultado da ferramenta. Para `"deny"`, mostrado ao Claude. Para `"allow"` e `"defer"`, gravado apenas no [log de depuração](#debug-hooks) |

2035| `updatedInput` | Modifica os parâmetros de entrada da ferramenta antes da execução. Substitui todo o objeto de entrada, portanto inclua os campos inalterados junto com os modificados. O Claude Code avalia as regras de permissão e a [elegibilidade para segundo plano automático](/docs/pt/tools-reference#foreground-commands-that-move-to-the-background) de um comando Bash com base na entrada que seu hook retorna, não na entrada que o Claude enviou. Combine com `"allow"` para aprovar automaticamente, ou com `"ask"` para mostrar a entrada modificada ao usuário. Para `"defer"`, é ignorado |2055| `updatedInput` | Modifica os parâmetros de entrada da ferramenta antes da execução. Substitui todo o objeto de entrada, portanto inclua os campos inalterados junto com os modificados. O Claude Code avalia as regras de permissão e a [elegibilidade para segundo plano automático](/docs/pt/tools-reference#foreground-commands-that-move-to-the-background) de um comando Bash com base na entrada que seu hook retorna, não na entrada que o Claude enviou. Combine com `"allow"` para aprovar automaticamente, ou com `"ask"` para mostrar a entrada modificada ao usuário. Para `"defer"`, é ignorado |

2036| `additionalContext` | String adicionada ao contexto do Claude junto com o resultado da ferramenta. Ignorada quando `permissionDecision` é `"defer"`. Consulte [Adicionar contexto para o Claude](#add-context-for-claude) |2056| `additionalContext` | String adicionada ao contexto do Claude junto com o resultado da ferramenta. Ignorada quando `permissionDecision` é `"defer"`. Consulte [Adicionar contexto para o Claude](#add-context-for-claude) |

2136Se a ferramenta adiada não estiver mais disponível quando você retomar, o processo sai com `stop_reason: "tool_deferred_unavailable"` e `is_error: true` antes de o hook ser disparado. Isso acontece quando um servidor MCP que fornecia a ferramenta não está conectado na sessão retomada. O payload `deferred_tool_use` ainda é incluído para que você possa identificar qual ferramenta ficou indisponível.2156Se a ferramenta adiada não estiver mais disponível quando você retomar, o processo sai com `stop_reason: "tool_deferred_unavailable"` e `is_error: true` antes de o hook ser disparado. Isso acontece quando um servidor MCP que fornecia a ferramenta não está conectado na sessão retomada. O payload `deferred_tool_use` ainda é incluído para que você possa identificar qual ferramenta ficou indisponível.

2137 2157

2138<Note>2158<Note>

2139 Para retomar uma sessão adiada no modo de planejamento, passe [`--permission-prompt-tool`](/docs/pt/cli-reference#cli-flags) junto com `--resume` para que o Claude Code possa apresentar o plano para aprovação. Se você passar certas outras flags de inicialização, a execução retomada não volta ao modo de planejamento; consulte [Retomar no modo de planejamento com `-p`](/docs/pt/sessions#resume-in-plan-mode-with-p). Exige o Claude Code v2.1.246 ou posterior.2159 Para retomar uma sessão adiada no modo de planejamento, passe [`--permission-prompt-tool`](/docs/pt/cli-reference#cli-flags) junto com `--resume` para que o Claude Code possa apresentar o plano para aprovação. Para as demais condições, consulte [Retomar no modo de planejamento com `-p`](/docs/pt/sessions#resume-in-plan-mode-with-p). Requer o Claude Code v2.1.246 ou posterior.

2140 2160

2141 Quando você retoma com `-p`, o Claude Code não restaura nenhum outro modo de permissão armazenado. Ele inicia a execução no modo de permissão em que uma nova execução `claude -p` iniciaria, portanto passe `--permission-mode` ou `--dangerously-skip-permissions` novamente se a sessão adiada usava um deles. Quando você retoma com `claude --resume <session-id>` sem `-p`, o Claude Code restaura o modo de permissão armazenado, com as exceções listadas em [modo de permissão na retomada](/docs/pt/sessions#permission-mode-on-resume).2161 Quando você retoma com `-p`, o Claude Code não restaura nenhum outro modo de permissão armazenado. Ele inicia a execução no modo de permissão em que uma nova execução `claude -p` iniciaria, portanto passe `--permission-mode` ou `--dangerously-skip-permissions` novamente se a sessão adiada usava um deles. Quando você retoma com `claude --resume <session-id>` sem `-p`, o Claude Code restaura o modo de permissão armazenado, com as exceções listadas em [modo de permissão na retomada](/docs/pt/sessions#permission-mode-on-resume).

2142</Note>2162</Note>

4304 4324

4305Após o processo em background sair, Claude Code entrega os campos `additionalContext` e `systemMessage` da resposta JSON do hook ao Claude no próximo turno de conversa. Diferentemente de um `systemMessage` de hook síncrono, nenhum dos dois campos é mostrado para você.4325Após o processo em background sair, Claude Code entrega os campos `additionalContext` e `systemMessage` da resposta JSON do hook ao Claude no próximo turno de conversa. Diferentemente de um `systemMessage` de hook síncrono, nenhum dos dois campos é mostrado para você.

4306 4326

4327Imprima a resposta JSON sozinha no stdout ou em uma linha própria:

4328

4329* **Sozinha no stdout**: quando a resposta é o único texto no stdout, ela pode ocupar várias linhas, como a saída formatada do `jq`. Ocupar várias linhas requer Claude Code v2.1.295 ou posterior.

4330* **Em uma linha própria**: um hook assíncrono pode imprimir outro texto no stdout quando a resposta cabe sozinha em uma linha, por exemplo com `jq -c`.

4331

4307Claude Code valida que a resposta JSON contra o mesmo [esquema de saída](#json-output) que hooks síncronos, e descarta qualquer campo cujo valor tenha o tipo errado, como um `systemMessage` que não seja uma string, em vez de entregá-lo. Execute com `--debug` para ver um aviso nomeando cada campo descartado. Antes da v2.1.202, saída JSON malformada de um hook assíncrono poderia travar a sessão, e a falha recorria cada vez que a sessão era retomada.4332Claude Code valida que a resposta JSON contra o mesmo [esquema de saída](#json-output) que hooks síncronos, e descarta qualquer campo cujo valor tenha o tipo errado, como um `systemMessage` que não seja uma string, em vez de entregá-lo. Execute com `--debug` para ver um aviso nomeando cada campo descartado. Antes da v2.1.202, saída JSON malformada de um hook assíncrono poderia travar a sessão, e a falha recorria cada vez que a sessão era retomada.

4308 4333

4309Notificações de conclusão de hook assíncrono são suprimidas por padrão. Para vê-las, ative modo verbose com `Ctrl+O` ou inicie Claude Code com `--verbose`.4334Notificações de conclusão de hook assíncrono são suprimidas por padrão. Para vê-las, ative modo verbose com `Ctrl+O` ou inicie Claude Code com `--verbose`.

44572026-07-19T02:03:24.382Z [DEBUG] "Hook PostToolUse:Write (PostToolUse) success:\nhook-ran"44822026-07-19T02:03:24.382Z [DEBUG] "Hook PostToolUse:Write (PostToolUse) success:\nhook-ran"

4458```4483```

4459 4484

4485Para encontrar um hook lento, pesquise no log por linhas `Hooks:` que terminam com uma duração. No Claude Code v2.1.296 ou posterior, cada hook de comando em um evento de ferramenta, `UserPromptSubmit`, `SessionStart`, `Stop` e vários outros eventos deixa uma dessas linhas quando termina, independentemente do que tenha impresso. A linha fornece o nome do evento, unido por dois-pontos ao nome da ferramenta ou a outro valor com o qual o hook correspondeu, depois o comando do hook entre colchetes, o plugin de onde ele veio, se houver, como a execução terminou e quanto tempo levou, como em `Hooks: PostToolUse:Write [.claude/hooks/log-write.sh] finished with status 0 (31ms)`. Uma execução também pode terminar como `timed out after <N>ms`, `cancelled`, `moved to the background` ou `failed to start`. Em alguns eventos, como `Notification`, `SessionEnd` e `PreCompact`, um hook de comando deixa, em vez disso, uma linha `completed with status` sem duração.

4486

4460Para detalhes de correspondência de hook mais granulares, defina `CLAUDE_CODE_DEBUG_LOG_LEVEL=verbose` para ver linhas de log adicionais como contagens de matcher de hook e correspondência de consulta.4487Para detalhes de correspondência de hook mais granulares, defina `CLAUDE_CODE_DEBUG_LOG_LEVEL=verbose` para ver linhas de log adicionais como contagens de matcher de hook e correspondência de consulta.

4461 4488

4462Para troubleshooting de problemas comuns como hooks não disparando, Stop hooks que continuam bloqueando, ou erros de configuração, consulte [Limitações e troubleshooting](/docs/pt/hooks-guide#limitations-and-troubleshooting) no guia. Para um passo a passo de diagnóstico mais amplo cobrindo `/context`, `/doctor` e precedência de configurações, consulte [Debug your config](/docs/pt/debug-your-config).4489Para troubleshooting de problemas comuns como hooks não disparando, Stop hooks que continuam bloqueando, ou erros de configuração, consulte [Limitações e troubleshooting](/docs/pt/hooks-guide#limitations-and-troubleshooting) no guia. Para um passo a passo de diagnóstico mais amplo cobrindo `/context`, `/doctor` e precedência de configurações, consulte [Debug your config](/docs/pt/debug-your-config).

hooks-guide.md +15 −7

Details

664 664

665Em `PreToolUse`, Claude Code trata cada valor `permissionDecision` da seguinte forma:665Em `PreToolUse`, Claude Code trata cada valor `permissionDecision` da seguinte forma:

666 666

667* `"allow"`: pular o prompt de permissão interativo. Regras de negação e pedido, incluindo listas de negação gerenciadas por empresa, ainda se aplicam, assim como prompts para ferramentas MCP marcadas [`requiresUserInteraction`](/docs/pt/mcp#require-approval-for-a-specific-tool) e para ferramentas de conector [que sua organização definiu como `ask`](/docs/pt/mcp#organization-controls-on-connector-tools) em sessões onde essa configuração chega ao Claude Code667* `"allow"`: pular o prompt de permissão interativo. Regras de negação e pedido, incluindo listas de negação gerenciadas por empresa, ainda se aplicam, assim como prompts para leituras de [caminhos de rede](/docs/pt/permissions#network-paths), para ferramentas MCP marcadas [`requiresUserInteraction`](/docs/pt/mcp#require-approval-for-a-specific-tool) e para ferramentas de conector [que sua organização definiu como `ask`](/docs/pt/mcp#organization-controls-on-connector-tools) em sessões onde essa configuração chega ao Claude Code

668* `"deny"`: cancelar a chamada de ferramenta e enviar o motivo ao Claude668* `"deny"`: cancelar a chamada de ferramenta e enviar o motivo ao Claude

669* `"ask"`: mostrar o prompt de permissão ao usuário normalmente669* `"ask"`: mostrar o prompt de permissão ao usuário normalmente

670 670

1015 1015

1016Hooks `PreToolUse` disparam antes de qualquer verificação de modo de permissão, em cada [modo de permissão](/docs/pt/permission-modes), incluindo `dontAsk`. Um hook que retorna `permissionDecision: "deny"` bloqueia a ferramenta mesmo em modo `bypassPermissions` ou com `--dangerously-skip-permissions`. Isto permite que você aplique política que usuários não podem contornar mudando seu modo de permissão.1016Hooks `PreToolUse` disparam antes de qualquer verificação de modo de permissão, em cada [modo de permissão](/docs/pt/permission-modes), incluindo `dontAsk`. Um hook que retorna `permissionDecision: "deny"` bloqueia a ferramenta mesmo em modo `bypassPermissions` ou com `--dangerously-skip-permissions`. Isto permite que você aplique política que usuários não podem contornar mudando seu modo de permissão.

1017 1017

1018O inverso não é verdadeiro: um hook retornando `"allow"` não contorna regras de negação de configurações, e não pode suprimir o prompt para ferramentas MCP marcadas [`requiresUserInteraction`](/docs/pt/mcp#require-approval-for-a-specific-tool) ou para ferramentas de conector [que sua organização definiu como `ask`](/docs/pt/mcp#organization-controls-on-connector-tools) em sessões onde essa configuração chega ao Claude Code. Hooks em arquivos de configuração e no `hooks/hooks.json` de um plugin podem apertar restrições mas não afrouxá-las além do que regras de permissão permitem.1018O inverso não é verdadeiro: um hook retornando `"allow"` não contorna regras de negação de configurações, e não pode suprimir o prompt para leituras de [caminhos de rede](/docs/pt/permissions#network-paths), para ferramentas MCP marcadas [`requiresUserInteraction`](/docs/pt/mcp#require-approval-for-a-specific-tool) ou para ferramentas de conector [que sua organização definiu como `ask`](/docs/pt/mcp#organization-controls-on-connector-tools) em sessões onde essa configuração chega ao Claude Code. Hooks em arquivos de configuração e no `hooks/hooks.json` de um plugin podem apertar restrições mas não afrouxá-las além do que regras de permissão permitem.

1019 1019

1020Um [mod](/docs/pt/plugins/mods/overview) que você instala e que trata `tool.check` pode aprovar uma chamada que seu hook `PreToolUse` bloqueou, a menos que o hook esteja em configurações gerenciadas. [Estender permissões com hooks](/docs/pt/permissions#extend-permissions-with-hooks) lista quais regras prevalecem sobre um mod.1020Um [mod](/docs/pt/plugins/mods/overview) que você instala e que trata `tool.check` pode aprovar uma chamada que seu hook `PreToolUse` bloqueou, a menos que o hook esteja em configurações gerenciadas. [Estender permissões com hooks](/docs/pt/permissions#extend-permissions-with-hooks) lista quais regras prevalecem sobre um mod.

1021 1021

1083 1083

1084Seu hook imprime JSON válido, mas a decisão não entra em vigor e nenhum erro aparece na transcrição. Verifique qual causa se aplica:1084Seu hook imprime JSON válido, mas a decisão não entra em vigor e nenhum erro aparece na transcrição. Verifique qual causa se aplica:

1085 1085

1086* **Saída extra antes do JSON**: algo mais escreve para stdout primeiro, geralmente um `echo` incondicional no seu perfil de shell, então a saída não começa mais com `{` e Claude Code não a analisa como JSON. A causa e correção seguem esta lista.1086* **Saída extra antes do JSON**: algo mais escreve para stdout primeiro, geralmente um `echo` incondicional no seu perfil de shell, então a saída não começa mais com `{`. Veja [Saída do perfil de shell antes do JSON](#shell-profile-output-before-the-json).

1087* **Um campo no nível errado**: compare a colocação de cada campo contra o formato [saída JSON](/docs/pt/hooks#json-output). Por exemplo, `permissionDecision` pertence dentro de `hookSpecificOutput`, não no nível superior.1087* **Um campo no nível errado**: compare a colocação de cada campo contra o formato [saída JSON](/docs/pt/hooks#json-output). Por exemplo, `permissionDecision` pertence dentro de `hookSpecificOutput`, não no nível superior. Veja [Campos no nível errado](#fields-at-the-wrong-level).

1088 1088

1089Quando Claude Code executa um hook de comando em forma de shell, um sem `args`, ele gera `sh -c` no macOS e Linux, Git Bash no Windows, ou PowerShell quando Git Bash não está instalado por padrão. Este shell é não-interativo, mas Git Bash e algumas configurações, como `BASH_ENV` apontando para `~/.bashrc`, ainda fornecem seu perfil. Se esse perfil contiver instruções `echo` incondicionais, a saída é adicionada ao seu JSON do hook:1089<h4 id="shell-profile-output-before-the-json">

1090 Saída do perfil de shell antes do JSON

1091</h4>

1092

1093Hooks executam em shells não interativos, mas Git Bash e algumas configurações, como `BASH_ENV` apontando para `~/.bashrc`, ainda carregam seu perfil, e qualquer coisa que o perfil imprima chega à stdout antes do JSON do seu hook:

1090 1094

1091```text theme={null}1095```text theme={null}

1092Shell ready on arm641096Shell ready on arm64

1093{"decision": "block", "reason": "Not allowed"}1097{"decision": "block", "reason": "Not allowed"}

1094```1098```

1095 1099

1096A saída combinada não começa mais com `{`, então Claude Code trata toda a stdout como texto simples e ignora o JSON. Em saída 0 nada é reportado na transcrição; a tentativa de análise é registrada apenas no [log de debug](/docs/pt/hooks#debug-hooks). Para corrigir isto, envolva instruções echo no seu perfil shell para que executem apenas em shells interativos:1100A menos que o hook seja [assíncrono](/docs/pt/hooks#how-async-hooks-execute), Claude Code lê saída que não começa com `{` como texto simples, então seu JSON é ignorado. Como o hook saiu com 0, a transcrição também não mostra nenhum erro. Para verificar esta causa, inicie Claude Code com `claude --debug`, acione o hook e procure no [log de debug](/docs/pt/hooks#debug-hooks) por `Hook output does not start with {`. Para corrigir isto, envolva as instruções `echo` no seu perfil para que executem apenas em shells interativos:

1097 1101

1098```bash theme={null}1102```bash theme={null}

1099# Em ~/.zshrc ou ~/.bashrc1103# Em ~/.zshrc ou ~/.bashrc

1104 1108

1105A variável `$-` contém flags de shell, e `i` significa interativo. Hooks executam em shells não-interativos, então o echo é pulado.1109A variável `$-` contém flags de shell, e `i` significa interativo. Hooks executam em shells não-interativos, então o echo é pulado.

1106 1110

1111<h4 id="fields-at-the-wrong-level">

1112 Campos no nível errado

1113</h4>

1114

1107Quando seu hook retorna `permissionDecision` ou `additionalContext` no nível superior em vez de dentro de `hookSpecificOutput`, o JSON ainda analisa, e Claude Code ignora os campos deslocados sem reportar um erro. Para ver quais campos foram ignorados, inicie Claude Code com `claude --debug` e procure no [log de debug](/docs/pt/hooks#debug-hooks) por `Hook JSON output had unrecognized keys`.1115Quando seu hook retorna `permissionDecision` ou `additionalContext` no nível superior em vez de dentro de `hookSpecificOutput`, o JSON ainda analisa, e Claude Code ignora os campos deslocados sem reportar um erro. Para ver quais campos foram ignorados, inicie Claude Code com `claude --debug` e procure no [log de debug](/docs/pt/hooks#debug-hooks) por `Hook JSON output had unrecognized keys`.

1108 1116

1109<h3 id="check-what-a-hook-did">1117<h3 id="check-what-a-hook-did">

1119 1127

1120Para consultar o resultado de um código de saída e stdout específicos, incluindo as exceções por evento, veja [Saída de código de saída](/docs/pt/hooks#exit-code-output) na referência.1128Para consultar o resultado de um código de saída e stdout específicos, incluindo as exceções por evento, veja [Saída de código de saída](/docs/pt/hooks#exit-code-output) na referência.

1121 1129

1122Para detalhes de execução completos incluindo códigos de saída, stdout e stderr dos hooks, leia o log de debug. Inicie Claude Code com `claude --debug-file /tmp/claude.log` para escrever em um caminho conhecido, depois `tail -f /tmp/claude.log` em outro terminal. Se você iniciou sem essa flag, execute `/debug` no meio da sessão para habilitar logging e encontrar o caminho do log.1130Para detalhes de execução completos incluindo códigos de saída, stdout e stderr dos hooks, leia o [log de debug](/docs/pt/hooks#debug-hooks). Inicie Claude Code com `claude --debug-file /tmp/claude.log` para escrever em um caminho conhecido, depois `tail -f /tmp/claude.log` em outro terminal. Se você iniciou sem essa flag, execute `/debug` no meio da sessão para habilitar logging e encontrar o caminho do log.

1123 1131

1124<h2 id="learn-more">1132<h2 id="learn-more">

1125 Saiba mais1133 Saiba mais

interactive-mode.md +3 −1

Details

22 22

24| :- | :- | :- |24| :- | :- | :- |

25| `Ctrl+C` | Interromper ou limpar entrada | Interrompe uma operação em execução. Se nada estiver em execução, o primeiro pressionamento limpa a entrada do prompt e um segundo pressionamento sai do Claude Code |25| `Ctrl+C` | Interromper ou limpar entrada | Interrompe uma operação em execução. Se nada estiver em execução, o primeiro pressionamento limpa a entrada do prompt e um segundo pressionamento sai do Claude Code. Pressione `Up` enquanto o prompt ainda estiver vazio para trazer de volta o rascunho limpo, o que requer Claude Code v2.1.288 ou posterior |

26| `Ctrl+X Ctrl+K` | Parar todos os [subagentes em segundo plano](/docs/pt/sub-agents#run-subagents-in-foreground-or-background) nesta sessão e desativar [respostas automáticas de artefatos](/docs/pt/artifacts#let-claude-reply-to-comments-on-its-own) para o resto dela. Pressione duas vezes em 3 segundos para confirmar. Você pode pressioná-lo enquanto o prompt de permissão de um subagente em segundo plano estiver aberto | Controle de subagente |26| `Ctrl+X Ctrl+K` | Parar todos os [subagentes em segundo plano](/docs/pt/sub-agents#run-subagents-in-foreground-or-background) nesta sessão e desativar [respostas automáticas de artefatos](/docs/pt/artifacts#let-claude-reply-to-comments-on-its-own) para o resto dela. Pressione duas vezes em 3 segundos para confirmar. Você pode pressioná-lo enquanto o prompt de permissão de um subagente em segundo plano estiver aberto | Controle de subagente |

27| `Ctrl+D` | Sair da sessão do Claude Code | O primeiro pressionamento mostra uma dica de confirmação e um segundo pressionamento em 800ms sai. Quando o prompt tem texto, `Ctrl+D` deleta o caractere após o cursor |27| `Ctrl+D` | Sair da sessão do Claude Code | O primeiro pressionamento mostra uma dica de confirmação e um segundo pressionamento em 800ms sai. Quando o prompt tem texto, `Ctrl+D` deleta o caractere após o cursor |

28| `Ctrl+G` ou `Ctrl+X Ctrl+E` | Abrir no editor de texto padrão | Edite seu prompt ou resposta personalizada no seu editor de texto padrão. `Ctrl+X Ctrl+E` é a vinculação nativa do readline. Ative **Mostrar última resposta no editor externo** em `/config` para adicionar a resposta anterior do Claude como contexto comentado com `#` acima do seu prompt; Claude Code remove o bloco de comentário quando você salva |28| `Ctrl+G` ou `Ctrl+X Ctrl+E` | Abrir no editor de texto padrão | Edite seu prompt ou resposta personalizada no seu editor de texto padrão. `Ctrl+X Ctrl+E` é a vinculação nativa do readline. Ative **Mostrar última resposta no editor externo** em `/config` para adicionar a resposta anterior do Claude como contexto comentado com `#` acima do seu prompt; Claude Code remove o bloco de comentário quando você salva |

442 442

443Claude Code recupera comandos shell enfileirados apenas quando a caixa de entrada está vazia e você não tem nada mais enfileirado, e alterna a caixa de entrada para modo shell quando o faz. Caso contrário, os deixa na fila, listados com seu prefixo `!`, e os executa após o término do turno.443Claude Code recupera comandos shell enfileirados apenas quando a caixa de entrada está vazia e você não tem nada mais enfileirado, e alterna a caixa de entrada para modo shell quando o faz. Caso contrário, os deixa na fila, listados com seu prefixo `!`, e os executa após o término do turno.

444 444

445Se você recuperar texto enfileirado enquanto `←` [aguarda para mover a sessão para o background](/docs/pt/agent-view#switch-sessions-without-leaving-the-terminal), o texto permanece na caixa de entrada e Claude Code cancela a troca. Se você o recuperar no momento em que a sessão se move, o texto desaparece com a tela em primeiro plano: ele não foi enviado. Cada mensagem que você recuperou é salva como uma entrada própria no [histórico de comandos](#command-history). Para recuperar uma delas, reabra a sessão e pressione `Up` em um prompt vazio sem nada enfileirado.

446

445<h2 id="prompt-suggestions">447<h2 id="prompt-suggestions">

446 Sugestões de prompt448 Sugestões de prompt

447</h2>449</h2>

llm-gateway-connect.md +1 −1

Details

299 299

300[Claude Code no Slack](/docs/pt/slack) e [sessões na nuvem](/docs/pt/claude-code-on-the-web) não fazem parte de uma implantação de gateway. Variáveis de gateway definidas na configuração de ambiente de uma sessão na nuvem não são aplicadas. Se seu tráfego deve permanecer no gateway, não ative essas superfícies para esses usuários.300[Claude Code no Slack](/docs/pt/slack) e [sessões na nuvem](/docs/pt/claude-code-on-the-web) não fazem parte de uma implantação de gateway. Variáveis de gateway definidas na configuração de ambiente de uma sessão na nuvem não são aplicadas. Se seu tráfego deve permanecer no gateway, não ative essas superfícies para esses usuários.

301 301

302[Remote Control](/docs/pt/remote-control) e [ditado por voz](/docs/pt/voice-dictation) ambos dependem de uma identidade claude.ai: Remote Control para emparelhar uma sessão ao vivo com sua conta e ditado por voz para alcançar o endpoint de transcrição claude.ai. Eles não estão disponíveis enquanto `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN` ou um `apiKeyHelper` está ativo. Remote Control também está desabilitado enquanto `ANTHROPIC_BASE_URL` aponta para um host não-Anthropic, então fazer login com claude.ai não é suficiente por si só. Antes da v2.1.196, uma URL base não-Anthropic não bloqueava Remote Control.302[Remote Control](/docs/pt/remote-control) e [ditado por voz](/docs/pt/voice-dictation) ambos dependem de uma identidade claude.ai: Remote Control para emparelhar uma sessão ao vivo com sua conta e ditado por voz para alcançar o endpoint de transcrição claude.ai. Eles não estão disponíveis enquanto `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN` ou um `apiKeyHelper` está ativo. Remote Control também está desabilitado enquanto `ANTHROPIC_BASE_URL` aponta para um host não-Anthropic, então fazer login com claude.ai não é suficiente por si só.

303 303

304Para restaurar qualquer um dos recursos, faça login com claude.ai e desdefina as variáveis de gateway que o recurso verifica. A seção Remote Control de `claude doctor` nomeia o que está bloqueando Remote Control no momento.304Para restaurar qualquer um dos recursos, faça login com claude.ai e desdefina as variáveis de gateway que o recurso verifica. A seção Remote Control de `claude doctor` nomeia o que está bloqueando Remote Control no momento.

305 305

mcp.md +4 −4

Details

283 Aprovações de servidor de projeto e confiança do workspace283 Aprovações de servidor de projeto e confiança do workspace

284</h4>284</h4>

285 285

286A partir da v2.1.196, `claude mcp list` e `claude mcp get` leem aprovações `.mcp.json` apenas de arquivos de configurações que não estão no repositório até que você confie no workspace executando `claude` nele e aceitando o diálogo de confiança do workspace. Um repositório clonado não pode aprovar seus próprios servidores: [`enableAllProjectMcpServers`](/docs/pt/settings-reference#enableallprojectmcpservers) ou [`enabledMcpjsonServers`](/docs/pt/settings-reference#enabledmcpjsonservers) incluído via commit no `.claude/settings.json` do projeto é ignorado em uma pasta não confiável, e o servidor permanece em `⏸ Pending approval` em vez de ser conectado e verificado quanto à saúde.286`claude mcp list` e `claude mcp get` leem aprovações `.mcp.json` apenas de arquivos de configurações que não estão no repositório até que você confie no workspace executando `claude` nele e aceitando o diálogo de confiança do workspace. Um repositório clonado não pode aprovar seus próprios servidores: [`enableAllProjectMcpServers`](/docs/pt/settings-reference#enableallprojectmcpservers) ou [`enabledMcpjsonServers`](/docs/pt/settings-reference#enabledmcpjsonservers) incluído via commit no `.claude/settings.json` do projeto é ignorado em uma pasta não confiável, e o servidor permanece em `⏸ Pending approval` em vez de ser conectado e verificado quanto à saúde.

287 287

288As aprovações dessas fontes ainda se aplicam em uma pasta não confiável:288As aprovações dessas fontes ainda se aplicam em uma pasta não confiável:

289 289

859 859

860O aviso anuncia cada servidor uma vez e o deixa de fora da contagem em inicializações posteriores até que esse servidor tenha se conectado e precise de login novamente. `/mcp` ainda lista todos os servidores que precisam de login.860O aviso anuncia cada servidor uma vez e o deixa de fora da contagem em inicializações posteriores até que esse servidor tenha se conectado e precise de login novamente. `/mcp` ainda lista todos os servidores que precisam de login.

861 861

862No modo não interativo não há painel `/mcp`, então Claude Code não pode executar o fluxo OAuth para você. A partir da v2.1.196, quando um servidor configurado precisa de autenticação durante uma execução `claude -p` ou Agent SDK com [busca de ferramentas](#scale-with-mcp-tool-search) ativada, que é o padrão, Claude Code informa ao Claude que as ferramentas do servidor estão indisponíveis até que você o autorize. Claude pode então nomear o servidor que precisa de login em vez de responder como se o servidor não estivesse configurado. Complete o login de uma sessão interativa com `/mcp` ou `claude mcp login <name>`.862No modo não interativo não há painel `/mcp`, então Claude Code não pode executar o fluxo OAuth para você. Quando um servidor configurado precisa de autenticação durante uma execução `claude -p` ou Agent SDK com [busca de ferramentas](#scale-with-mcp-tool-search) ativada, que é o padrão, Claude Code informa ao Claude que as ferramentas do servidor estão indisponíveis até que você o autorize. Claude pode então nomear o servidor que precisa de login. Complete o login de uma sessão interativa com `/mcp` ou `claude mcp login <name>`.

863 863

864Se você configurou `headers.Authorization` para o servidor e o servidor rejeita esse cabeçalho, Claude Code relata a conexão como falha em vez de voltar para OAuth. Verifique se o token é válido para o endpoint MCP, ou remova o cabeçalho para usar o fluxo OAuth.864Se você configurou `headers.Authorization` para o servidor e o servidor rejeita esse cabeçalho, Claude Code relata a conexão como falha em vez de voltar para OAuth. Verifique se o token é válido para o endpoint MCP, ou remova o cabeçalho para usar o fluxo OAuth.

865 865

1048 1048

1049`oauth.scopes` tem precedência sobre `authServerMetadataUrl` e os escopos que o servidor descobre em `/.well-known`. Deixe-o indefinido para permitir que o servidor MCP determine o conjunto de escopos solicitado.1049`oauth.scopes` tem precedência sobre `authServerMetadataUrl` e os escopos que o servidor descobre em `/.well-known`. Deixe-o indefinido para permitir que o servidor MCP determine o conjunto de escopos solicitado.

1050 1050

1051A partir da v2.1.196, quando `oauth.scopes` não está definido, Claude Code solicita o escopo fornecido pelo cabeçalho `WWW-Authenticate` do servidor ou seus metadados de recurso protegido, e não envia nenhum parâmetro `scope` quando nenhum dos dois fornece um. Ele não solicita mais o catálogo completo de `scopes_supported` dos metadados do servidor de autorização descobertos automaticamente. Solicitar esse catálogo fez com que provedores de identidade que anunciam escopos apenas para administrador ou escopos de modelo rejeitassem a solicitação de autorização com um erro `invalid_scope`. Os metadados obtidos de um `authServerMetadataUrl` configurado ainda fornecem seus `scopes_supported` como os escopos solicitados.1051Quando `oauth.scopes` não está definido, Claude Code não solicita o catálogo completo de `scopes_supported` dos metadados do servidor de autorização descobertos automaticamente. Os metadados obtidos de um `authServerMetadataUrl` configurado ainda fornecem seus `scopes_supported` como os escopos solicitados.

1052 1052

1053Se o servidor de autorização anuncia `offline_access` em `scopes_supported`, Claude Code o acrescenta aos escopos fixados para que o token de acesso possa ser atualizado sem um novo login no navegador.1053Se o servidor de autorização anuncia `offline_access` em `scopes_supported`, Claude Code o acrescenta aos escopos fixados para que o token de acesso possa ser atualizado sem um novo login no navegador.

1054 1054

1141 1141

1142Com exceção das variáveis `GIT_CONFIG_KEY_<n>` do Git, Claude Code remove todas as variáveis do seu ambiente cujo nome parece uma credencial, como um nome com `TOKEN`, `SECRET`, `PASSWORD`, `KEY`, ou `AUTH` nele em qualquer caso de letra, então `ANTHROPIC_API_KEY` e `MY_REGISTRY_TOKEN` são ambos removidos. Claude Code também remove uma lista fixa de variáveis de credencial cujos nomes não seguem esse padrão, como `ANTHROPIC_CUSTOM_HEADERS`.1142Com exceção das variáveis `GIT_CONFIG_KEY_<n>` do Git, Claude Code remove todas as variáveis do seu ambiente cujo nome parece uma credencial, como um nome com `TOKEN`, `SECRET`, `PASSWORD`, `KEY`, ou `AUTH` nele em qualquer caso de letra, então `ANTHROPIC_API_KEY` e `MY_REGISTRY_TOKEN` são ambos removidos. Claude Code também remove uma lista fixa de variáveis de credencial cujos nomes não seguem esse padrão, como `ANTHROPIC_CUSTOM_HEADERS`.

1143 1143

1144Quando isso se aplica ao seu auxiliar, faça o script ler sua credencial de um arquivo ou de um armazenamento de credenciais. Se a `url` do servidor [expande uma dessas variáveis](#environment-variable-expansion-in-mcp-json), o valor `CLAUDE_CODE_MCP_SERVER_URL` que o auxiliar recebe tem essa parte substituída por `REDACTED` também.1144Quando isso se aplica ao seu auxiliar, faça o script ler sua credencial de um arquivo ou de um armazenamento de credenciais. Se a `url` do servidor [carrega o valor real de uma dessas variáveis](#environment-variable-expansion-in-mcp-json), como `MY_REGISTRY_TOKEN`, o valor `CLAUDE_CODE_MCP_SERVER_URL` que o auxiliar recebe tem essa parte substituída por `REDACTED` também.

1145 1145

1146<h4 id="trust-a-folder-before-its-headershelper-runs">1146<h4 id="trust-a-folder-before-its-headershelper-runs">

1147 Confiar em uma pasta antes de seu headersHelper ser executado1147 Confiar em uma pasta antes de seu headersHelper ser executado

monitoring-usage.md +35 −3

Details

470 Colocar os valores entre aspas não faz o escape de espaços. Por exemplo, `org.name="My Company"` resulta no valor literal `"My Company"` com as aspas incluídas, e não `My Company`.470 Colocar os valores entre aspas não faz o escape de espaços. Por exemplo, `org.name="My Company"` resulta no valor literal `"My Company"` com as aspas incluídas, e não `My Company`.

471</Warning>471</Warning>

472 472

473<h3 id="attribute-telemetry-to-desktop-ssh-sessions">

474 Atribuir telemetria a sessões SSH do Desktop

475</h3>

476

477Para ver em qual máquina remota uma [sessão SSH do Desktop](/docs/pt/desktop#ssh-sessions) foi executada, nomeie cada máquina em um atributo personalizado. Métricas e eventos não informam a máquina em que uma sessão foi executada.

478

479Em cada máquina remota, adicione [`OTEL_RESOURCE_ATTRIBUTES`](#multi-team-organization-support) ao bloco `env` que ativa a telemetria, no [arquivo de configurações gerenciadas que a sessão lê](/docs/pt/desktop#managed-settings). Escreva o nome por extenso no arquivo de cada máquina. O Claude Code não expande o valor, portanto `host.name=$(hostname)` chega exatamente com esses caracteres.

480

481O exemplo a seguir nomeia a máquina `build-7`:

482

483```json theme={null}

484{

485 "env": {

486 "CLAUDE_CODE_ENABLE_TELEMETRY": "1",

487 "OTEL_METRICS_EXPORTER": "otlp",

488 "OTEL_LOGS_EXPORTER": "otlp",

489 "OTEL_EXPORTER_OTLP_PROTOCOL": "grpc",

490 "OTEL_EXPORTER_OTLP_ENDPOINT": "http://collector.example.com:4317",

491 "OTEL_RESOURCE_ATTRIBUTES": "host.name=build-7"

492 }

493}

494```

495

496Quando nada mais define a variável, `host.name` chega no bloco de recurso, em sessões SSH do Desktop e na CLI dessa máquina. Para saber onde mais os atributos personalizados aparecem, consulte [Suporte a organizações com várias equipes](#multi-team-organization-support).

497

498Se o nome não chegar, verifique uma destas causas:

499

500* **Você o definiu no computador que executa o Desktop**: o Desktop não passa para a sessão SSH um valor que você define ali

501* **Você o exportou em um arquivo de login**: somente shells de login leem um arquivo como `/etc/profile`. Um valor que você define com `export` ali chega ao Claude Code que você inicia a partir de um shell de login. Ele não chega a uma sessão SSH do Desktop, porque o Desktop não inicia o Claude Code por meio de um shell de login.

502* **Um valor contém um espaço**: nesse caso, o Claude Code não copia nenhuma das chaves para eventos ou pontos de dados e não informa nenhum erro. [Remova o espaço do valor](#multi-team-organization-support).

503* **Outra coisa já define a variável**: em uma sessão que o aplicativo desktop inicia, uma variável já definida no ambiente de inicialização [tem precedência sobre os arquivos de configurações](/docs/pt/settings-reference#how-env-values-interact-with-your-shell). O [log de depuração](/docs/pt/debug-your-config) indica cada variável ignorada. Quando uma implantação do Desktop de terceiros [especifica um endpoint OTLP](#how-managed-settings-lock-the-otlp-destination) no ambiente que ela fornece, esse ambiente carrega o próprio `OTEL_RESOURCE_ATTRIBUTES` do Desktop.

504

473<h3 id="example-configurations">505<h3 id="example-configurations">

474 Exemplos de configuração506 Exemplos de configuração

475</h3>507</h3>

1746 1778

1747Todas as métricas e eventos são exportados com os seguintes atributos de recurso:1779Todas as métricas e eventos são exportados com os seguintes atributos de recurso:

1748 1780

1749* `service.name`: `claude-code` para sessões de terminal, `claude-code-desktop` para sessões iniciadas a partir da aba Code no [aplicativo Claude Desktop](/docs/pt/desktop)1781* `service.name`: `claude-code` para sessões de terminal, `claude-code-desktop` para sessões locais iniciadas a partir da aba Code no [aplicativo Claude Desktop](/docs/pt/desktop)

1750* `service.version`: Versão atual do Claude Code, ou a versão do aplicativo Desktop para sessões da aba Code1782* `service.version`: Versão atual do Claude Code, ou a versão do aplicativo Desktop para sessões locais da aba Code

1751* `os.type`: Tipo de sistema operacional (por exemplo, `linux`, `darwin`, `windows`)1783* `os.type`: Tipo de sistema operacional (por exemplo, `linux`, `darwin`, `windows`)

1752* `os.version`: String de versão do sistema operacional1784* `os.version`: String de versão do sistema operacional

1753* `host.arch`: Arquitetura do host (por exemplo, `amd64`, `arm64`)1785* `host.arch`: Arquitetura do host (por exemplo, `amd64`, `arm64`)

1754* `wsl.version`: Número de versão do WSL (apenas presente ao executar no Windows Subsystem for Linux)1786* `wsl.version`: Número de versão do WSL (apenas presente ao executar no Windows Subsystem for Linux)

1755* Nome do Medidor: `com.anthropic.claude_code`1787* Nome do Medidor: `com.anthropic.claude_code`

1756 1788

1757Se seus pipelines de coletor ou painéis filtrarem em `service.name = claude-code`, adicione `claude-code-desktop` ao filtro para também capturar telemetria de sessões da aba Code.1789Se seus pipelines de coletor ou painéis filtrarem em `service.name = claude-code`, adicione `claude-code-desktop` ao filtro para também capturar telemetria de sessões locais da aba Code.

1758 1790

1759<h2 id="roi-measurement-resources">1791<h2 id="roi-measurement-resources">

1760 Recursos de medição de ROI1792 Recursos de medição de ROI

network-config.md +2 −2

Details

183 Defina variáveis de rede em configurações, não no shell183 Defina variáveis de rede em configurações, não no shell

184</h3>184</h3>

185 185

186O supervisor é um processo compartilhado por cada terminal. Ele herda o ambiente de qualquer shell que o inicie primeiro, e um supervisor instalado pelo SO não recebe nenhum ambiente de shell. Se você exportar um proxy, caminho de CA ou variável mTLS apenas no seu shell, ele chega aos agentes em segundo plano quando esse shell aconteceu de iniciar a frio o supervisor, e silenciosamente não chega quando um shell diferente fez isso.186O supervisor é um processo compartilhado por cada terminal. Ele herda o ambiente de qualquer shell que o inicie primeiro. Se você exportar um proxy, caminho de CA ou variável mTLS apenas no seu shell, ele chega aos agentes em segundo plano quando esse shell aconteceu de iniciar a frio o supervisor, e silenciosamente não chega quando um shell diferente fez isso.

187 187

188Coloque as mesmas variáveis no bloco `env` de `~/.claude/settings.json` ou [configurações gerenciadas](/docs/pt/settings). Cada variável nesta página pode ser definida lá, e as configurações são a única configuração que chega a cada sessão em segundo plano em cada máquina.188Coloque as mesmas variáveis no bloco `env` de `~/.claude/settings.json` ou [configurações gerenciadas](/docs/pt/settings). Cada variável nesta página pode ser definida lá, e as configurações são a única configuração que chega a cada sessão em segundo plano em cada máquina.

189 189

196Defina a configuração [`processWrapper`](/docs/pt/settings-reference#processwrapper) para prefixar o supervisor, seus workers e os outros processos em segundo plano listados em [O que o inicializador cobre](/docs/pt/corporate-launcher#what-the-launcher-covers) com seu inicializador. A variável de ambiente equivalente [`CLAUDE_CODE_PROCESS_WRAPPER`](/docs/pt/env-vars) tem precedência quando ambas são definidas, e está sujeita à mesma regra: entregue-a através de configurações gerenciadas ou `~/.claude/settings.json`, não uma exportação de shell. [Execute Claude Code atrás de um inicializador corporativo](/docs/pt/corporate-launcher) cobre o contrato que o inicializador deve satisfazer, o que faz e não faz, e como implementá-lo.196Defina a configuração [`processWrapper`](/docs/pt/settings-reference#processwrapper) para prefixar o supervisor, seus workers e os outros processos em segundo plano listados em [O que o inicializador cobre](/docs/pt/corporate-launcher#what-the-launcher-covers) com seu inicializador. A variável de ambiente equivalente [`CLAUDE_CODE_PROCESS_WRAPPER`](/docs/pt/env-vars) tem precedência quando ambas são definidas, e está sujeita à mesma regra: entregue-a através de configurações gerenciadas ou `~/.claude/settings.json`, não uma exportação de shell. [Execute Claude Code atrás de um inicializador corporativo](/docs/pt/corporate-launcher) cobre o contrato que o inicializador deve satisfazer, o que faz e não faz, e como implementá-lo.

197 197

198<Note>198<Note>

199 Um supervisor já em execução mantém a configuração de inicialização com a qual foi iniciado. Após implantar a configuração do inicializador, execute [`claude daemon stop --any`](/docs/pt/agent-view#the-supervisor-process) para que o próximo `claude agents` ou `--bg` inicie um supervisor que a honre. Um serviço instalado leva `claude daemon stop` sem `--any`.199 Um supervisor já em execução mantém a configuração de inicialização com a qual foi iniciado. Após implantar a configuração do inicializador, execute [`claude daemon stop --any`](/docs/pt/agent-view#the-supervisor-process) para que o próximo `claude agents` ou `--bg` inicie um supervisor que a honre.

200</Note>200</Note>

201 201

202<h2 id="streaming-idle-watchdogs">202<h2 id="streaming-idle-watchdogs">

permission-modes.md +16 −7

Details

22| [`acceptEdits`](#auto-approve-file-edits-with-acceptedits-mode) | Leituras, edições de arquivo e comandos comuns do sistema de arquivos (`mkdir`, `touch`, `mv`, `cp`, etc.) | Iterando sobre código que você está revisando |22| [`acceptEdits`](#auto-approve-file-edits-with-acceptedits-mode) | Leituras, edições de arquivo e comandos comuns do sistema de arquivos (`mkdir`, `touch`, `mv`, `cp`, etc.) | Iterando sobre código que você está revisando |

23| [`plan`](#analyze-before-you-edit-with-plan-mode) | Leituras, mais comandos aprovados pelo classificador quando [modo automático](#eliminate-prompts-with-auto-mode) está disponível | Explorando uma base de código antes de alterá-la |23| [`plan`](#analyze-before-you-edit-with-plan-mode) | Leituras, mais comandos aprovados pelo classificador quando [modo automático](#eliminate-prompts-with-auto-mode) está disponível | Explorando uma base de código antes de alterá-la |

~~25| [`dontAsk`](#allow-only-pre-approved-tools-with-dontask-mode) | Leituras e ferramentas pré-aprovadas; qualquer coisa que geraria um prompt é negada | CI bloqueado e scripts |~~25| [`dontAsk`](#allow-only-pre-approved-tools-with-dontask-mode) | Leituras de arquivos dentro dos seus diretórios de trabalho e ferramentas pré-aprovadas; qualquer coisa que geraria um prompt é negada | CI bloqueado e scripts |

27 27

28O modo que revisa cada ação é nomeado **Manual** na CLI, em `claude --help`, nas extensões VS Code e JetBrains, e no aplicativo de desktop. Seu valor de configuração é `default`, que é o que hooks e integrações SDK usam. A CLI aceita `manual` como um alias em qualquer lugar onde você digita o valor, por exemplo `claude --permission-mode manual` ou `"defaultMode": "manual"`.28O modo que revisa cada ação é nomeado **Manual** na CLI, em `claude --help`, nas extensões VS Code e JetBrains, e no aplicativo de desktop. Seu valor de configuração é `default`, que é o que hooks e integrações SDK usam. A CLI aceita `manual` como um alias em qualquer lugar onde você digita o valor, por exemplo `claude --permission-mode manual` ou `"defaultMode": "manual"`.

466 A primeira leitura fora dos diretórios de trabalho466 A primeira leitura fora dos diretórios de trabalho

467</h3>467</h3>

468 468

469Enquanto [`permissions.blockReadsOutsideWorkingDirectories`](/docs/pt/settings-reference#permissions-blockreadsoutsideworkingdirectories) estiver desativado, leituras de arquivo executam sem um prompt no modo auto, incluindo leituras fora dos [diretórios de trabalho](/docs/pt/permissions#working-directories). Na primeira vez que Claude usa a ferramenta Read, Grep ou Glob em um caminho fora deles, Claude Code pergunta se deve permitir essa leitura.469Enquanto [`permissions.blockReadsOutsideWorkingDirectories`](/docs/pt/settings-reference#permissions-blockreadsoutsideworkingdirectories) estiver desativado, leituras de arquivo que não sejam [leituras de caminhos de rede](/docs/pt/permissions#network-paths) executam sem um prompt no modo auto, incluindo leituras fora dos [diretórios de trabalho](/docs/pt/permissions#working-directories). Na primeira vez que Claude usa a ferramenta Read, Grep ou Glob em um caminho fora deles, Claude Code pergunta se deve permitir essa leitura.

470 470

471O prompt não aparece em execuções `-p` não interativas ou em sessões em segundo plano; leituras nelas executam como antes.471O prompt não aparece em execuções `-p` não interativas ou em sessões em segundo plano; leituras nelas executam como antes.

472 472

530 Cada ação passa por uma ordem de decisão fixa. O primeiro passo correspondente prevalece:530 Cada ação passa por uma ordem de decisão fixa. O primeiro passo correspondente prevalece:

531 531

532 1. Ações que correspondem às suas [regras de permitir, solicitar ou negar](/docs/pt/permissions#manage-permissions) são resolvidas imediatamente, com estas exceções:532 1. Ações que correspondem às suas [regras de permitir, solicitar ou negar](/docs/pt/permissions#manage-permissions) são resolvidas imediatamente, com estas exceções:

533 * Escritas em [caminhos protegidos](#protected-paths) são roteadas para o classificador mesmo quando uma regra de permitir corresponde533 * Escritas em [caminhos protegidos](#protected-paths) são roteadas para o classificador mesmo quando uma regra de permitir corresponde. Quando o caminho protegido é o arquivo para o qual um arquivo de configurações com link simbólico aponta, a escrita pode pedir sua confirmação em vez disso, como a lista de [caminhos protegidos](#protected-paths) descreve

534 * Nenhuma regra de permitir aprova remoções de `rm` e `rmdir` direcionadas a um [caminho crítico](#critical-paths)534 * Nenhuma regra de permitir aprova remoções de `rm` e `rmdir` direcionadas a um [caminho crítico](#critical-paths)

535 * Ferramentas MCP marcadas com [`requiresUserInteraction`](/docs/pt/mcp#require-approval-for-a-specific-tool) pedem sua confirmação diretamente mesmo quando uma regra de permitir corresponde, assim como ferramentas de conector que [sua organização definiu como `ask`](/docs/pt/mcp#organization-controls-on-connector-tools) em sessões onde essa configuração chega a Claude Code535 * Ferramentas MCP marcadas com [`requiresUserInteraction`](/docs/pt/mcp#require-approval-for-a-specific-tool) pedem sua confirmação diretamente mesmo quando uma regra de permitir corresponde, assim como ferramentas de conector que [sua organização definiu como `ask`](/docs/pt/mcp#organization-controls-on-connector-tools) em sessões onde essa configuração chega a Claude Code

536 * Um comando de shell que carrega [domínios permitidos por comando](/docs/pt/sandboxing#per-command-allowed-domains-in-auto-mode) também é roteado para o classificador mesmo quando uma regra de permitir corresponde, porque uma regra aprova o comando, não seus hosts536 * Um comando de shell que carrega [domínios permitidos por comando](/docs/pt/sandboxing#per-command-allowed-domains-in-auto-mode) também é roteado para o classificador mesmo quando uma regra de permitir corresponde, porque uma regra aprova o comando, não seus hosts

537 * Regras de solicitação que correspondem ao conteúdo de um comando, como `Bash(git push *)`, recorrem a um prompt de permissão537 * Regras de solicitação que correspondem ao conteúdo de um comando, como `Bash(git push *)`, recorrem a um prompt de permissão

538 * Uma escrita que a [verificação de symlink](/docs/pt/permissions#symlinks) resolve para um caminho protegido pede sua confirmação quando o caminho que Claude solicitou não é em si protegido538 * Uma escrita que a [verificação de symlink](/docs/pt/permissions#symlinks) resolve para um caminho protegido pede sua confirmação quando o caminho que Claude solicitou não é em si protegido

539 * Uma leitura de um [caminho de rede](/docs/pt/permissions#network-paths) pede sua confirmação mesmo quando uma regra de permitir corresponde

539 2. Ações somente leitura e edições de arquivo em seu diretório de trabalho são aprovadas automaticamente, exceto escritas em [caminhos protegidos](#protected-paths) e [a primeira leitura fora dos diretórios de trabalho](#first-read-outside-the-working-directories), que pede sua confirmação540 2. Ações somente leitura e edições de arquivo em seu diretório de trabalho são aprovadas automaticamente, exceto escritas em [caminhos protegidos](#protected-paths) e [a primeira leitura fora dos diretórios de trabalho](#first-read-outside-the-working-directories), que pede sua confirmação

540 * Em uma sessão com [revisão do classificador no servidor](#server-side-classifier-review), comandos de shell somente leitura e [em sandbox](/docs/pt/sandboxing#sandbox-modes) esperam por essa revisão e são bloqueados se ela os sinalizar541 * Em uma sessão com [revisão do classificador no servidor](#server-side-classifier-review), comandos de shell somente leitura e [em sandbox](/docs/pt/sandboxing#sandbox-modes) esperam por essa revisão e são bloqueados se ela os sinalizar

541 * Uma escrita dentro de seu diretório de trabalho que a [verificação de symlink](/docs/pt/permissions#symlinks) resolve para um local fora dele pede sua confirmação542 * Uma escrita dentro de seu diretório de trabalho que a [verificação de symlink](/docs/pt/permissions#symlinks) resolve para um local fora dele pede sua confirmação

542 * Quando Claude lê um [artefato que outra pessoa criou](/docs/pt/artifacts#read-an-artifact-shared-with-you), os casos de aprovação listados nessa seção se aplicam543 * Quando Claude lê um [artefato que outra pessoa criou](/docs/pt/artifacts#read-an-artifact-shared-with-you), os casos de aprovação listados nessa seção se aplicam

544 * Uma leitura de um [caminho de rede](/docs/pt/permissions#network-paths) pede sua confirmação

543 3. Todo o resto vai para o classificador, exceto [remoções de caminho crítico](#critical-paths) sob seu tratamento padrão. As ferramentas de conector e as ferramentas MCP com `requiresUserInteraction` que pedem sua confirmação diretamente na etapa 1 também nunca chegam ao classificador, então nem uma aprovação exigida pela organização nem uma etapa de consentimento é aprovada automaticamente545 3. Todo o resto vai para o classificador, exceto [remoções de caminho crítico](#critical-paths) sob seu tratamento padrão. As ferramentas de conector e as ferramentas MCP com `requiresUserInteraction` que pedem sua confirmação diretamente na etapa 1 também nunca chegam ao classificador, então nem uma aprovação exigida pela organização nem uma etapa de consentimento é aprovada automaticamente

544 4. Se o classificador bloquear, Claude recebe o motivo. Na maioria das sessões, o motivo nomeia a regra que o classificador identificou, como `[Data Exfiltration]`, em vez de dar uma explicação escrita; consulte [Revisar negações](/docs/pt/auto-mode-config#review-denials)546 4. Se o classificador bloquear, Claude recebe o motivo. Na maioria das sessões, o motivo nomeia a regra que o classificador identificou, como `[Data Exfiltration]`, em vez de dar uma explicação escrita; consulte [Revisar negações](/docs/pt/auto-mode-config#review-denials)

545 547

593 595

594Claude Code nega chamadas que correspondem às suas [regras `ask`](/docs/pt/permissions#manage-permissions) explícitas em vez de solicitar. Também nega a ferramenta integrada `AskUserQuestion` mesmo que suas regras de permissão correspondam a ela, e faz o mesmo para ferramentas de conector [que sua organização definiu como `ask`](/docs/pt/mcp#organization-controls-on-connector-tools) em sessões onde essa configuração chega a Claude Code. Nega ferramentas MCP marcadas [`_meta["anthropic/requiresUserInteraction"]`](/docs/pt/mcp#require-approval-for-a-specific-tool) da mesma forma, porque seu cartão de aprovação precisa de uma resposta que este modo nunca coleta.596Claude Code nega chamadas que correspondem às suas [regras `ask`](/docs/pt/permissions#manage-permissions) explícitas em vez de solicitar. Também nega a ferramenta integrada `AskUserQuestion` mesmo que suas regras de permissão correspondam a ela, e faz o mesmo para ferramentas de conector [que sua organização definiu como `ask`](/docs/pt/mcp#organization-controls-on-connector-tools) em sessões onde essa configuração chega a Claude Code. Nega ferramentas MCP marcadas [`_meta["anthropic/requiresUserInteraction"]`](/docs/pt/mcp#require-approval-for-a-specific-tool) da mesma forma, porque seu cartão de aprovação precisa de uma resposta que este modo nunca coleta.

595 597

596Remoções `rm` e `rmdir` direcionadas a um [caminho crítico](#critical-paths), como `rm -rf /` e `rm -rf ~`, são negadas mesmo quando uma regra de permissão corresponde a elas ou um hook `PreToolUse` as permite.598Remoções `rm` e `rmdir` direcionadas a um [caminho crítico](#critical-paths), como `rm -rf /` e `rm -rf ~`, são negadas mesmo quando uma regra de permissão corresponde a elas ou um hook `PreToolUse` as permite. Uma leitura de um [caminho de rede](/docs/pt/permissions#network-paths) é negada da mesma forma.

597 599

598Sessões em nuvem em [Claude Code na web](/docs/pt/claude-code-on-the-web) ignoram `defaultMode: "dontAsk"`; veja [bypassPermissions](#skip-all-checks-with-bypasspermissions-mode) para detalhes.600Sessões em nuvem em [Claude Code na web](/docs/pt/claude-code-on-the-web) ignoram `defaultMode: "dontAsk"`; veja [bypassPermissions](#skip-all-checks-with-bypasspermissions-mode) para detalhes.

599 601

639* **Se você aceitar**: Claude Code define `skipDangerousModePermissionPrompt` como `true` em `~/.claude/settings.json`, para que sessões posteriores ignorem o diálogo. Para ver o diálogo novamente, remova a chave desse arquivo ou defina-a como `false`. A [referência `skipDangerousModePermissionPrompt`](/docs/pt/settings-reference#skipdangerousmodepermissionprompt) lista os outros arquivos de configurações onde você ou sua organização podem defini-la.641* **Se você aceitar**: Claude Code define `skipDangerousModePermissionPrompt` como `true` em `~/.claude/settings.json`, para que sessões posteriores ignorem o diálogo. Para ver o diálogo novamente, remova a chave desse arquivo ou defina-a como `false`. A [referência `skipDangerousModePermissionPrompt`](/docs/pt/settings-reference#skipdangerousmodepermissionprompt) lista os outros arquivos de configurações onde você ou sua organização podem defini-la.

640* **Se você recusar**: Claude Code sai.642* **Se você recusar**: Claude Code sai.

641 643

642Em [modo não-interativo](/docs/pt/headless) nenhum diálogo é mostrado, e uma [sessão em segundo plano](/docs/pt/agent-view) iniciada com `--bg` é recusada até que você tenha aceitado o diálogo em uma sessão interativa.644Em [modo não interativo](/docs/pt/headless) nenhum diálogo é mostrado. Uma [sessão em segundo plano](/docs/pt/agent-view) respeita sua aceitação quando ela está registrada nas configurações de usuário ou nas configurações gerenciadas:

645

646* Sem aceitação registrada, `claude --bg --permission-mode bypassPermissions` é recusado até que você aceite o diálogo em uma sessão interativa.

647* Com `skipDangerousModePermissionPrompt` definido apenas em `.claude/settings.local.json`, a sessão em segundo plano inicia com a requisição de bypass ignorada e fixa o aviso `Bypass permissions was requested at launch and ignored · if that was you, ~/.claude/settings.json needs "skipDangerousModePermissionPrompt": true`. Para que o bypass seja respeitado, adicione essa chave a `~/.claude/settings.json` e, em seguida, inicie uma nova sessão em segundo plano.

643 648

644Em Linux e macOS, Claude Code recusa iniciar neste modo quando executado como root ou sob `sudo`:649Em Linux e macOS, Claude Code recusa iniciar neste modo quando executado como root ou sob `sudo`:

645 650

708* `.devcontainer.json`713* `.devcontainer.json`

709* `.ripgreprc`, `pyrightconfig.json`714* `.ripgreprc`, `pyrightconfig.json`

710* `.mcp.json`, `.claude.json`715* `.mcp.json`, `.claude.json`

716* O arquivo para o qual seu [arquivo de configurações](/docs/pt/settings#settings-files-and-who-they-affect) de usuário, de projeto ou local aponta quando o próprio arquivo de configurações é um link simbólico, por exemplo, para um repositório de dotfiles. Nos modos que roteiam gravações em caminhos protegidos para o classificador, uma gravação nesse arquivo solicita você em vez disso, mesmo quando uma regra de permissão corresponde. Se o caminho do próprio arquivo também for o de um arquivo de configurações, como `.claude/settings.json` em outra pasta, a gravação vai para o classificador como as demais gravações em caminhos protegidos

711 717

712<h2 id="critical-paths">718<h2 id="critical-paths">

713 Caminhos críticos719 Caminhos críticos

727 733

728* A raiz do sistema de arquivos734* A raiz do sistema de arquivos

729* Diretórios de nível superior, significando qualquer filho direto da raiz, como `/usr`, `/etc` ou `/data`735* Diretórios de nível superior, significando qualquer filho direto da raiz, como `/usr`, `/etc` ou `/data`

730* Seu diretório home736* Seu diretório home. No Windows, seu nome curto 8.3 também conta, como `C:\Users\LONGNA~1`

731* Raízes de unidade do Windows e seus diretórios de nível superior, como `C:\` e `C:\Windows`737* Raízes de unidade do Windows e seus diretórios de nível superior, como `C:\` e `C:\Windows`. Grafias como `\\?\C:\` e `\\localhost\C$` contam como `C:\`

732* Seu diretório de trabalho e seus pais738* Seu diretório de trabalho e seus pais

733* Seus diretórios de trabalho adicionais e seus pais, mas apenas quando a remoção é um glob sob um deles, como `rm -rf <dir>/*`. `rm -rf <dir>` no próprio diretório não dispara essa verificação739* Seus diretórios de trabalho adicionais e seus pais, mas apenas quando a remoção é um glob sob um deles, como `rm -rf <dir>/*`. `rm -rf <dir>` no próprio diretório não dispara essa verificação

734 740

741As verificações do nome curto 8.3 do diretório home e das grafias `\\?\C:\` e `\\localhost\C$` requerem Claude Code v2.1.292 ou posterior.

742

735<h3 id="other-targets-that-count-as-critical-paths">743<h3 id="other-targets-that-count-as-critical-paths">

736 Outros alvos que contam como caminhos críticos744 Outros alvos que contam como caminhos críticos

737</h3>745</h3>

747| Um alvo que é apenas a saída de uma substituição de comando, quando o `rm` é recursivo | `rm -rf "$(pwd)"` | Claude Code não pode verificar o alvo antes do comando ser executado |755| Um alvo que é apenas a saída de uma substituição de comando, quando o `rm` é recursivo | `rm -rf "$(pwd)"` | Claude Code não pode verificar o alvo antes do comando ser executado |

748| Uma substituição de comando à direita após um caminho crítico | `rm -rf ~/$(cmd)` | Claude Code verifica o caminho que permaneceria se a substituição se expandisse vazia, aqui seu diretório home |756| Uma substituição de comando à direita após um caminho crítico | `rm -rf ~/$(cmd)` | Claude Code verifica o caminho que permaneceria se a substituição se expandisse vazia, aqui seu diretório home |

749| Um alvo que é apenas barras invertidas | `rm -rf "\\"` | Git Bash no Windows lê uma barra invertida solitária como a raiz da unidade atual, então a verificação se aplica em todas as plataformas |757| Um alvo que é apenas barras invertidas | `rm -rf "\\"` | Git Bash no Windows lê uma barra invertida solitária como a raiz da unidade atual, então a verificação se aplica em todas as plataformas |

758| Um caminho do Windows que nomeia um volume por GUID em vez de uma letra de unidade | `rm -rf '\\?\Volume{GUID}\work\build'` | O caminho não diz em qual unidade está, então pode ser um caminho crítico. Requer Claude Code v2.1.292 ou posterior |

750| Alguns alvos que terminam em `/*` ou `/*/` | `rm -rf logs/*/*`, `rm -rf logs/*/`, `cd logs && rm -rf a/*` | Claude Code não consegue determinar, antes do comando ser executado, quais diretórios eles alcançam |759| Alguns alvos que terminam em `/*` ou `/*/` | `rm -rf logs/*/*`, `rm -rf logs/*/`, `cd logs && rm -rf a/*` | Claude Code não consegue determinar, antes do comando ser executado, quais diretórios eles alcançam |

751 760

752Para desativar a verificação em um alvo que é apenas saída de substituição de comando, defina [`CLAUDE_CODE_DISABLE_SUBSTITUTION_RM_PROMPT=1`](/docs/pt/env-vars#variables) no ambiente que inicia Claude Code.761Para desativar a verificação em um alvo que é apenas saída de substituição de comando, defina [`CLAUDE_CODE_DISABLE_SUBSTITUTION_RM_PROMPT=1`](/docs/pt/env-vars#variables) no ambiente que inicia Claude Code.

permissions.md +87 −56

Details

36 36

37Antes da v2.1.211, Claude Code sempre salvava a regra no diretório inicial, então uma aprovação concedida em uma worktree ou subdiretório não se aplicava ao resto do repositório. Regras que versões anteriores salvaram em um subdiretório ou worktree ainda se aplicam a sessões iniciadas lá.37Antes da v2.1.211, Claude Code sempre salvava a regra no diretório inicial, então uma aprovação concedida em uma worktree ou subdiretório não se aplicava ao resto do repositório. Regras que versões anteriores salvaram em um subdiretório ou worktree ainda se aplicam a sessões iniciadas lá.

38 38

39Às vezes um prompt de permissão oferece apenas uma aprovação única, sem opção de "não pergunte novamente" e sem opção de permitir a ação pelo resto da sessão. Claude Code oferece essas opções apenas quando o prompt pode mostrar a você tudo o que elas permitiriam, então uma regra que você salva de um prompt cobre apenas o que sua opção nomeada. Quando um prompt oferece apenas a aprovação única, aprove a ação uma vez, ou adicione a regra você mesmo em [`/permissions`](#manage-permissions).39Às vezes um prompt de permissão oferece apenas uma aprovação única, sem opção de "não pergunte novamente" e sem opção de permitir a ação pelo resto da sessão. Claude Code oferece essas opções apenas quando o prompt pode mostrar a você tudo o que elas permitiriam, então uma regra que você salva de um prompt cobre apenas o que sua opção nomeou. Quando um prompt oferece apenas a aprovação única, aprove a ação uma vez, ou adicione a regra você mesmo em [`/permissions`](#manage-permissions). Para interromper os prompts para um comando que começa com um exec wrapper como `watch`, ou para um comando `find` com uma ação como `-delete`, consulte [Exec wrappers e ações `find`](#exec-wrappers-and-find-actions).

40 40

41<h3 id="add-a-comment-when-you-answer-a-permission-prompt">41<h3 id="add-a-comment-when-you-answer-a-permission-prompt">

42 Adicione um comentário quando você responder a um prompt de permissão42 Adicione um comentário quando você responder a um prompt de permissão

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

92| `plan` | Claude lê arquivos e executa comandos shell somente leitura para explorar, mas não edita seus arquivos de origem; com [modo automático](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode) disponível, comandos aprovados pelo classificador também são executados. Rotulado como Plan na CLI e na extensão VS Code |92| `plan` | Claude lê arquivos e executa comandos shell somente leitura para explorar, mas não edita seus arquivos de origem; com [modo automático](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode) disponível, comandos aprovados pelo classificador também são executados. Rotulado como Plan na CLI e na extensão VS Code |

93| `auto` | Executa sem prompts rotineiros; antes de ações como comandos shell e solicitações de rede serem executadas, um [classificador](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode) em segundo plano verifica se elas se alinham com sua solicitação |93| `auto` | Executa sem prompts rotineiros; antes de ações como comandos shell e solicitações de rede serem executadas, um [classificador](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode) em segundo plano verifica se elas se alinham com sua solicitação |

94| `dontAsk` | Nega automaticamente toda chamada que de outra forma solicitaria permissão; leituras de arquivo em seus diretórios de trabalho e outras ações que não precisam de aprovação ainda são executadas, assim como ferramentas pré-aprovadas via `/permissions` ou regras `permissions.allow`. `AskUserQuestion`, ferramentas MCP marcadas [`requiresUserInteraction`](/docs/pt/mcp#require-approval-for-a-specific-tool) e ferramentas de conector [sua organização definida como `ask`](/docs/pt/mcp#organization-controls-on-connector-tools) em sessões onde essa configuração chega ao Claude Code são negadas mesmo se você as permitiu |94| `dontAsk` | Nega automaticamente toda chamada que de outra forma solicitaria permissão; leituras de arquivo em seus diretórios de trabalho e outras ações que não precisam de aprovação ainda são executadas, assim como ferramentas pré-aprovadas via `/permissions` ou regras `permissions.allow`. `AskUserQuestion`, ferramentas MCP marcadas [`requiresUserInteraction`](/docs/pt/mcp#require-approval-for-a-specific-tool), [leituras de caminhos de rede](#network-paths) e ferramentas de conector [sua organização definida como `ask`](/docs/pt/mcp#organization-controls-on-connector-tools) em sessões onde essa configuração chega ao Claude Code são negadas mesmo se você as permitiu |

95| `bypassPermissions` | Ignora prompts de permissão, exceto pelas [ações que nenhum modo aprova automaticamente](/docs/pt/permission-modes#actions-no-mode-auto-approves) |95| `bypassPermissions` | Ignora prompts de permissão, exceto pelas [ações que nenhum modo aprova automaticamente](/docs/pt/permission-modes#actions-no-mode-auto-approves) |

96 96

97<Warning>97<Warning>

240 Bash240 Bash

241</h3>241</h3>

242 242

243As regras Bash correspondem ao texto do comando inteiro, com `*` representando qualquer texto. [Padrões com caracteres curinga](#wildcard-patterns) mostra quais comandos cada forma de regra corresponde e onde colocar o `*`. O resto desta seção cobre como Claude Code corresponde a comandos compostos e wrappers, o que uma regra não corresponde, comandos somente leitura e redirecionamentos.243As regras Bash correspondem ao texto do comando inteiro, com `*` representando qualquer texto. [Padrões com caracteres curinga](#wildcard-patterns) mostra quais comandos cada forma de regra corresponde e onde colocar o `*`. O resto desta seção cobre como Claude Code corresponde a comandos compostos e wrappers, quais wrappers e ações `find` uma regra de prefixo não pode aprovar, o que uma regra não corresponde, comandos somente leitura e redirecionamentos.

244 244

245<h4 id="compound-commands">245<h4 id="compound-commands">

246 Comandos compostos246 Comandos compostos

254 254

255Quando `&&` ou `||` não tem nada depois, como em `npm test &&`, Claude Code trata o comando como não analisável e não o divide em subcomandos para correspondência de regra allow, portanto uma regra como `Bash(npm *)` não o aprova.255Quando `&&` ou `||` não tem nada depois, como em `npm test &&`, Claude Code trata o comando como não analisável e não o divide em subcomandos para correspondência de regra allow, portanto uma regra como `Bash(npm *)` não o aprova.

256 256

257Quando você aprova um comando composto com "Sim, não pergunte novamente", Claude Code salva uma regra separada para cada subcomando que requer aprovação, em vez de uma única regra para a string completa. Por exemplo, aprovar `git status && npm test` salva uma regra para `npm test`, portanto futuras invocações de `npm test` são reconhecidas independentemente do que precede o `&&`. Subcomandos como `cd` em um subdiretório geram sua própria regra Read para esse caminho. Até 5 regras podem ser salvas para um único comando composto.257Quando você aprova um comando composto com "Sim, não pergunte novamente", Claude Code salva uma regra separada para cada subcomando que requer aprovação, em vez de uma única regra para a string completa. Por exemplo, aprovar `git status && npm test` salva uma regra para `npm test`, portanto futuras invocações de `npm test` são reconhecidas independentemente do que precede o `&&`. Subcomandos como `cd` em um diretório fora dos seus diretórios de trabalho geram sua própria regra Read para esse caminho. Até 5 regras podem ser salvas para um único comando composto.

258 258

259<h4 id="process-wrappers">259<h4 id="process-wrappers">

260 Wrappers260 Wrappers

268 268

269Esta lista de wrapper é integrada e não é configurável. Executores de ambiente de desenvolvimento como `direnv exec`, `devbox run`, `mise exec`, `npx` e `docker exec` não estão na lista. Porque essas ferramentas executam seus argumentos como um comando, uma regra como `Bash(devbox run *)` corresponde a tudo que vem após `run`, incluindo `devbox run rm -rf .`. Para aprovar trabalho dentro de um executor de ambiente, escreva uma regra específica que inclua tanto o executor quanto o comando interno, como `Bash(devbox run npm test)`. Adicione uma regra por comando interno que você quer permitir.269Esta lista de wrapper é integrada e não é configurável. Executores de ambiente de desenvolvimento como `direnv exec`, `devbox run`, `mise exec`, `npx` e `docker exec` não estão na lista. Porque essas ferramentas executam seus argumentos como um comando, uma regra como `Bash(devbox run *)` corresponde a tudo que vem após `run`, incluindo `devbox run rm -rf .`. Para aprovar trabalho dentro de um executor de ambiente, escreva uma regra específica que inclua tanto o executor quanto o comando interno, como `Bash(devbox run npm test)`. Adicione uma regra por comando interno que você quer permitir.

270 270

271Wrappers exec como `watch`, `setsid`, `ionice` e `flock` não podem ser auto-aprovados por uma regra de prefixo como `Bash(watch *)`, portanto em modo Manual sempre solicitam. O mesmo se aplica a `find` com `-exec` ou `-delete`: uma regra `Bash(find *)` não cobre essas formas. Para aprovar uma invocação específica, escreva uma regra de correspondência exata para a string de comando completa.271<h4 id="exec-wrappers-and-find-actions">

272 Wrappers exec e ações `find`

273</h4>

274

275Uma regra de prefixo como `Bash(watch *)` ou `Bash(find *)` não pode aprovar automaticamente os seguintes comandos, portanto em modo Manual eles solicitam:

276

277* **Wrappers exec**: como `watch`, `setsid`, `ionice` e `flock`

278* **`find`**: com uma ação que executa comandos, exclui arquivos ou escreve arquivos, como `-exec`, `-delete` ou `-fprint`, ou com `-files0-from`, que lê de um arquivo os caminhos a pesquisar

279

280Para aprovar uma invocação específica que não tem `*`, escreva uma regra de correspondência exata para a string de comando completa, como `Bash(find build -type f -delete)`.

281

282Quando o comando tem um `*`, como em `find . -name '*.tmp' -delete`, Claude Code lê a regra como um [padrão com caracteres curinga](#wildcard-patterns), não como uma correspondência exata, portanto o comando ainda solicita. Aprove-o cada vez que ele solicitar, ou use um [hook PreToolUse](/docs/pt/hooks#pretooluse-decision-control) que retorne `"allow"` para ele.

272 283

273<h4 id="bash-rule-limits">284<h4 id="bash-rule-limits">

274 O que uma regra Bash não corresponde285 O que uma regra Bash não corresponde

290 Comandos somente leitura301 Comandos somente leitura

291</h4>302</h4>

292 303

293Claude Code reconhece um conjunto integrado de comandos Bash como somente leitura e os executa sem um prompt de permissão em cada modo, exceto por um caminho que [`permissions.blockReadsOutsideWorkingDirectories`](/docs/pt/settings-reference#permissions-blockreadsoutsideworkingdirectories) protege. O conjunto inclui `ls`, `cat`, `echo`, `pwd`, `head`, `tail`, `grep`, `find`, `wc`, `which`, `diff`, `stat`, `du`, `cd` e formas somente leitura de `git`. O conjunto não é configurável; para exigir um prompt para um desses comandos, adicione uma regra `ask` ou `deny` para ele. Em modo auto, esses comandos também podem aguardar a revisão do classificador; veja [como o classificador avalia ações](/docs/pt/permission-modes#how-the-classifier-evaluates-actions).304Claude Code reconhece um conjunto integrado de comandos Bash como somente leitura e os executa sem um prompt de permissão em cada modo, exceto conforme [`permissions.blockReadsOutsideWorkingDirectories`](/docs/pt/settings-reference#permissions-blockreadsoutsideworkingdirectories) altera para caminhos fora dos seus diretórios de trabalho. O conjunto inclui `ls`, `cat`, `echo`, `pwd`, `head`, `tail`, `grep`, `find`, `wc`, `which`, `diff`, `stat`, `du`, `cd` e formas somente leitura de `git`. O conjunto não é configurável; para exigir um prompt para um desses comandos, adicione uma regra `ask` ou `deny` para ele. Em modo auto, esses comandos também podem aguardar a revisão do classificador; veja [como o classificador avalia ações](/docs/pt/permission-modes#how-the-classifier-evaluates-actions).

294 305

295Um redirecionamento como `ls > out.txt` adiciona uma verificação no alvo. Veja [Redirecionamentos](#redirections).306Um redirecionamento como `ls > out.txt` adiciona uma verificação no alvo. Veja [Redirecionamentos](#redirections).

296 307

301* **Globs sem aspas para comandos com flags capazes de escrita**: comandos com flags capazes de escrita ou execução, como `find`, `sort`, `sed` e `git`, solicitam quando um glob sem aspas está presente, porque o glob poderia expandir para uma flag como `-delete`.312* **Globs sem aspas para comandos com flags capazes de escrita**: comandos com flags capazes de escrita ou execução, como `find`, `sort`, `sed` e `git`, solicitam quando um glob sem aspas está presente, porque o glob poderia expandir para uma flag como `-delete`.

302* **`docker` apontado para outro daemon**: formas somente leitura de `docker` solicitam quando o comando carrega uma flag que seleciona um daemon diferente, como `-H`, `--context` ou `--url` e `--connection` do Podman.313* **`docker` apontado para outro daemon**: formas somente leitura de `docker` solicitam quando o comando carrega uma flag que seleciona um daemon diferente, como `-H`, `--context` ou `--url` e `--connection` do Podman.

303* **`file` com flags de abertura de caminho**: `file` solicita quando passa `-m`/`--magic-file` ou `-f`/`--files-from`, porque essas flags fazem `file` abrir os caminhos nomeados no valor da flag.314* **`file` com flags de abertura de caminho**: `file` solicita quando passa `-m`/`--magic-file` ou `-f`/`--files-from`, porque essas flags fazem `file` abrir os caminhos nomeados no valor da flag.

315* **`ps` que poderia imprimir variáveis de ambiente**: `ps` solicita quando um de seus argumentos poderia atuar como a opção `e`, como em `ps auxe` ou `ps aux -e`, porque essa opção imprime as variáveis de ambiente dos processos. `ps aux` e `ps -ef` são executados sem um prompt. A verificação em formas com hífen como `ps aux -e` requer Claude Code v2.1.290 ou posterior.

304* **Caminhos de rede no Windows**: um comando cujos argumentos incluem um caminho de rede (UNC), como `\\server\share\file`, solicita porque acessar um caminho de rede pode enviar suas credenciais do Windows para o host que ele nomeia. A mesma verificação se aplica a comandos da [ferramenta PowerShell](/docs/pt/tools-reference#powershell-tool).316* **Caminhos de rede no Windows**: um comando cujos argumentos incluem um caminho de rede (UNC), como `\\server\share\file`, solicita porque acessar um caminho de rede pode enviar suas credenciais do Windows para o host que ele nomeia. A mesma verificação se aplica a comandos da [ferramenta PowerShell](/docs/pt/tools-reference#powershell-tool).

305* **Escrita em variáveis de shell especiais**: um comando que define, desdefine ou itera sobre certas variáveis de shell especiais, como `PATH` ou `IFS`, solicita mesmo quando o resto do comando é somente leitura.317* **Escrita em variáveis de shell especiais**: um comando que define, desdefine ou itera sobre certas variáveis de shell especiais, como `PATH` ou `IFS`, solicita mesmo quando o resto do comando é somente leitura.

306* **Comandos que a análise não consegue analisar**: quando Claude Code não consegue analisar completamente um comando, solicita aprovação em vez de tratar o comando como somente leitura. Comandos mais longos que 10.000 caracteres sempre solicitam porque excedem o que a análise analisa.318* **Comandos que a análise não consegue analisar**: quando Claude Code não consegue analisar completamente um comando, solicita aprovação em vez de tratar o comando como somente leitura. Comandos mais longos que 10.000 caracteres sempre solicitam porque excedem o que a análise analisa.

320 332

321 Para filtragem de URL mais confiável, considere:333 Para filtragem de URL mais confiável, considere:

322 334

323 * **Restringir ferramentas de rede Bash**: use regras deny para bloquear `curl`, `wget` e ferramentas similares, depois use a ferramenta WebFetch com permissão `WebFetch(domain:github.com)` para domínios permitidos. Uma regra deny não corresponde ao mesmo programa por caminho ou dentro de `sh -c`, portanto combine com a [lista de permissões de rede do sandbox](/docs/pt/sandboxing#network-isolation) quando a restrição deve ser mantida; veja [o que uma regra Bash não corresponde](#bash-rule-limits)335 * **Restringir ferramentas de rede Bash**: use regras deny para bloquear `curl`, `wget` e comandos similares, depois use a ferramenta WebFetch com permissão `WebFetch(domain:github.com)` para domínios permitidos. Uma regra deny não corresponde ao mesmo programa por caminho ou dentro de `sh -c`, portanto combine com a [allowlist de rede do sandbox](/docs/pt/sandboxing#network-isolation) quando a restrição deve ser mantida; veja [o que uma regra Bash não corresponde](#bash-rule-limits)

324 * **Use hooks PreToolUse**: implemente um hook que valida URLs em comandos Bash e bloqueia domínios não permitidos336 * **Use hooks PreToolUse**: implemente um hook que valida URLs em comandos Bash e bloqueia domínios não permitidos

325 * **Adicione orientação CLAUDE.md**: descreva seus padrões curl permitidos em `CLAUDE.md`. Isso molda o que Claude tenta mas não impõe um limite, portanto combine com uma das opções acima337 * **Adicione orientação CLAUDE.md**: descreva seus padrões curl permitidos em `CLAUDE.md`. Isso molda o que Claude tenta mas não impõe um limite, portanto combine com uma das opções acima

326 338

362 374

363Aliases comuns são canonicalizados antes da correspondência. Uma regra escrita para o nome do cmdlet também corresponde a seus aliases, portanto `PowerShell(Get-ChildItem *)` corresponde a `gci`, `ls` e `dir` também. A correspondência é insensível a maiúsculas e minúsculas.375Aliases comuns são canonicalizados antes da correspondência. Uma regra escrita para o nome do cmdlet também corresponde a seus aliases, portanto `PowerShell(Get-ChildItem *)` corresponde a `gci`, `ls` e `dir` também. A correspondência é insensível a maiúsculas e minúsculas.

364 376

365Claude Code analisa o AST do PowerShell e verifica cada comando em um comando composto independentemente. Os operadores de pipeline `|`, separadores de instrução `;` e nos operadores de cadeia PowerShell 7+ `&&` e `||` dividem um comando composto em subcomandos. Uma regra deve corresponder a cada subcomando para que o comando composto seja permitido.377Claude Code analisa o AST do PowerShell e verifica cada comando em um comando composto independentemente. Os operadores de pipeline `|`, separadores de instrução `;` e, no PowerShell 7+, os operadores de cadeia `&&` e `||` dividem um comando composto em subcomandos. Uma regra deve corresponder a cada subcomando para que o comando composto seja permitido.

366 378

367<h3 id="read-and-edit">379<h3 id="read-and-edit">

368 Read e Edit380 Read e Edit

405 417

406Uma regra que você adiciona através de `/permissions` segue a linha para o arquivo de configurações que você a salva.418Uma regra que você adiciona através de `/permissions` segue a linha para o arquivo de configurações em que você a salva.

407 419

408As regras de configurações locais ancoram no [diretório de trabalho primário](#working-directories) da sessão, não na raiz do repositório onde Claude Code [armazena o arquivo](#permission-system) em v2.1.211 e posterior. Em uma sessão iniciada na raiz do repositório, os dois diretórios são os mesmos; em uma sessão de [worktree](/docs/pt/worktrees), uma regra compartilhada como `Edit(/src/**)` corresponde ao diretório `src/` próprio dessa worktree.420As regras de configurações locais ancoram no [diretório de trabalho primário](#working-directories) da sessão, não na raiz do repositório onde Claude Code [armazena o arquivo](#permission-system) em v2.1.211 e posterior. Em uma sessão iniciada na raiz do repositório, os dois diretórios são os mesmos; em uma sessão de [worktree](/docs/pt/worktrees), uma regra compartilhada como `Edit(/src/**)` corresponde ao diretório `src/` próprio desse worktree.

409 421

410Uma regra deny como `Read(/secrets/**)` em configurações de usuário bloqueia `~/.claude/secrets/**`, não um diretório `secrets` em seu projeto. Para escrever uma regra em configurações de usuário que se aplique dentro de cada projeto, use um caminho absoluto `//` ou um caminho relativo à home `~/` em vez disso.422Uma regra deny como `Read(/secrets/**)` em configurações de usuário bloqueia `~/.claude/secrets/**`, não um diretório `secrets` em seu projeto. Para escrever uma regra em configurações de usuário que se aplique dentro de cada projeto, use um caminho absoluto `//` ou um caminho relativo à home `~/` em vez disso.

411 423

435O exemplo a seguir mostra cada forma de padrão contra um projeto com um diretório `src/` de nível superior e uma cópia aninhada sob `vendor/`:447O exemplo a seguir mostra cada forma de padrão contra um projeto com um diretório `src/` de nível superior e uma cópia aninhada sob `vendor/`:

436 448

437```text theme={null}449```text theme={null}

438<diretório-atual>/450<current-directory>/

439├── src/451├── src/

440│ └── app.ts452│ └── app.ts

441└── vendor/453└── vendor/

461 473

462Uma regra deny ou ask cujo caminho não é utilizável como um padrão gitignore ainda protege esse caminho exato. Uma regra allow com um padrão não utilizável não aprova nada.474Uma regra deny ou ask cujo caminho não é utilizável como um padrão gitignore ainda protege esse caminho exato. Uma regra allow com um padrão não utilizável não aprova nada.

463 475

464Uma regra deny ou ask que começa com `!` é uma negação gitignore. Ela remove os caminhos que corresponde dos `path` ou `./path` regras listadas antes dela. Em uma lista `deny` de um arquivo de configurações, `Read(*.env)` seguido por `Read(!sample.env)` bloqueia cada arquivo cujo nome termina em `.env` em qualquer profundidade, exceto arquivos nomeados `sample.env`. Uma regra `!` listada primeiro remove nada.476Um padrão deny ou ask que começa com `!` é uma negação gitignore. Ele remove os caminhos que corresponde das regras `path` ou `./path` listadas antes dele. Em uma lista `deny` de um arquivo de configurações, `Read(*.env)` seguido por `Read(!sample.env)` bloqueia cada arquivo cujo nome termina em `.env` em qualquer profundidade, exceto arquivos nomeados `sample.env`. Uma regra `!` listada primeiro não remove nada.

465 477

466A remoção alcança apenas regras da mesma fonte. Um `Read(!.env)` em configurações de projeto ou em `--disallowedTools` não cancela um `Read(./.env)` deny de configurações gerenciadas ou qualquer outro arquivo de configurações.478A remoção alcança apenas regras da mesma fonte. Um `Read(!.env)` em configurações de projeto ou em `--disallowedTools` não cancela um `Read(./.env)` deny de configurações gerenciadas ou qualquer outro arquivo de configurações.

467 479

468Dois limites estreitam o que um padrão `!` pode remover:480Dois limites estreitam o que um padrão `!` pode remover:

469 481

470* Claude Code lê um padrão `!` relativo ao diretório atual mesmo quando `/`, `~/` ou `//` segue o `!`, portanto o padrão não consegue alcançar uma regra ancorada com um desses prefixos. `Read(!~/notes/public/**)` remove nada de `Read(~/notes/**)`.482* Claude Code lê um padrão `!` relativo ao diretório atual mesmo quando `/`, `~/` ou `//` segue o `!`, portanto o padrão não consegue alcançar uma regra ancorada com um desses prefixos. `Read(!~/notes/public/**)` não remove nada de `Read(~/notes/**)`.

471* Uma remoção não consegue reabrir um arquivo dentro de um diretório que uma regra bloqueia como um todo. Com `Read(secrets/**)` e `Read(!secrets/public/**)`, Claude Code ainda bloqueia `secrets/public` junto com o resto de `secrets`.483* Uma remoção não consegue reabrir um arquivo dentro de um diretório que uma regra bloqueia como um todo. Com `Read(secrets/**)` e `Read(!secrets/public/**)`, Claude Code ainda bloqueia `secrets/public` junto com o resto de `secrets`.

472 484

473<h4 id="symlinks">485<h4 id="symlinks">

487 499

488Em macOS e Linux, uma regra deny ou ask escrita através de um diretório com symlink com um padrão `//`, `~/` ou `/` também se aplica na localização real do diretório. Por exemplo, em macOS, onde `/etc` se resolve para `/private/etc`, `Read(//etc/**)` também bloqueia `/private/etc/hosts`. Antes de v2.1.268, uma regra deny ou ask escrita através de um diretório com symlink não se aplicava a um caminho dado por sua localização real.500Em macOS e Linux, uma regra deny ou ask escrita através de um diretório com symlink com um padrão `//`, `~/` ou `/` também se aplica na localização real do diretório. Por exemplo, em macOS, onde `/etc` se resolve para `/private/etc`, `Read(//etc/**)` também bloqueia `/private/etc/hosts`. Antes de v2.1.268, uma regra deny ou ask escrita através de um diretório com symlink não se aplicava a um caminho dado por sua localização real.

489 501

502Grep e Glob pesquisam o diretório para o qual o argumento `path` se resolve. Claude Code aplica regras deny `Read` a esse diretório.

503

490<h5 id="writes-through-a-symlink">504<h5 id="writes-through-a-symlink">

491 Escritas através de um symlink505 Escritas através de um symlink

492</h5>506</h5>

507 520

508Quando uma ferramenta então abre o arquivo aprovado, ela [confirma que o caminho ainda se resolve para a localização que a verificação de permissão aprovou](/docs/pt/errors#refusing-after-a-symlink-changed).521Quando uma ferramenta então abre o arquivo aprovado, ela [confirma que o caminho ainda se resolve para a localização que a verificação de permissão aprovou](/docs/pt/errors#refusing-after-a-symlink-changed).

509 522

510Grep e Glob pesquisam o diretório para o qual o argumento `path` se resolve. Claude Code aplica regras deny `Read` a esse diretório.523<h4 id="network-paths">

524 Caminhos de rede

525</h4>

526

527Quando as ferramentas de leitura de arquivos do Claude, como Read, Grep e Glob, leem de um caminho de rede, a leitura recebe sua própria verificação de permissão. Um caminho de rede é aquele que pode alcançar outro computador: no Windows, um caminho UNC como `\\server\share\file`, e em macOS e Linux, um caminho de automount `/net` como `/net/fileserver/notes.txt`. Consultar esse caminho pode contatar o host que ele nomeia, e no Windows esse contato pode enviar suas credenciais ao host. Comandos de shell têm sua própria verificação: em modo Manual, um comando Bash ou PowerShell somente leitura cujos argumentos incluem um caminho UNC [ainda solicita no Windows](#read-only-commands).

528

529No Claude Code v2.1.292 e posterior, cada um destes mantém o prompt:

530

531* **Regras allow**: uma regra não pré-aprova a leitura, incluindo uma regra para a ferramenta inteira, como `Read`

532* **Hooks PreToolUse**: um [hook](#extend-permissions-with-hooks) que retorna `"allow"` não pula o prompt

533* **Modo auto**: o prompt chega até você, e o [classificador](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode) não decide a leitura

534

535No modo `dontAsk`, Claude Code nega a leitura em vez de solicitar. No modo `bypassPermissions`, e em sessões de terminal interativas no modo de planejamento com [bypass de permissões](/docs/pt/permission-modes#skip-all-checks-with-bypasspermissions-mode) disponível, a leitura é executada sem esse prompt.

536

537Para ler arquivos em um compartilhamento de rede sem esse prompt, dê primeiro ao compartilhamento um caminho local:

538

539* **Windows**: mapeie o compartilhamento para uma letra de unidade e passe a unidade com `--add-dir` ao iniciar Claude Code, conforme descrito em [Diretórios de trabalho](#working-directories)

540* **macOS e Linux**: monte o compartilhamento em um caminho local, como um diretório sob `/mnt` ou `/Volumes`, e leia os arquivos a partir daí, conforme descrito em [O diretório de trabalho é um caminho de rede](/docs/pt/errors#working-directory-is-a-network-path)

511 541

512<h3 id="webfetch">542<h3 id="webfetch">

513 WebFetch543 WebFetch

515 545

516As regras WebFetch usam um prefixo `domain:` e correspondem ao hostname da URL solicitada. A correspondência é insensível a maiúsculas e minúsculas, suporta caracteres curinga `*` e remove um `.` final tanto da regra quanto do hostname para que `example.com.` e `example.com` sejam tratados da mesma forma.546As regras WebFetch usam um prefixo `domain:` e correspondem ao hostname da URL solicitada. A correspondência é insensível a maiúsculas e minúsculas, suporta caracteres curinga `*` e remove um `.` final tanto da regra quanto do hostname para que `example.com.` e `example.com` sejam tratados da mesma forma.

517 547

518* `WebFetch(domain:example.com)` corresponde a solicitações para `example.com`548* `WebFetch(domain:example.com)` corresponde apenas a requisições para `example.com`. Para cobrir também subdomínios como `api.example.com`, adicione uma regra `WebFetch(domain:*.example.com)`

519* `WebFetch(domain:*.example.com)` corresponde a qualquer subdomínio em qualquer profundidade, como `api.example.com` ou `a.b.example.com`, mas não a `example.com` em si549* `WebFetch(domain:*.example.com)` corresponde a qualquer subdomínio em qualquer profundidade, como `api.example.com` ou `a.b.example.com`, mas não a `example.com` em si

520* `WebFetch(domain:*)` corresponde a cada domínio. Não é o mesmo que uma regra `WebFetch` simples; veja [Permitir ou negar cada fetch](#allow-or-deny-every-fetch)550* `WebFetch(domain:*)` corresponde a cada domínio. Não é o mesmo que uma regra `WebFetch` simples; veja [Permitir ou negar cada fetch](#allow-or-deny-every-fetch)

521 551

536| `WebFetch` | Claude faz fetch sem solicitar você. Não muda quais hosts comandos em sandbox podem alcançar. | Claude Code remove a ferramenta `WebFetch`, portanto Claude não consegue fazer fetch. Não muda quais hosts comandos em sandbox podem alcançar. |566| `WebFetch` | Claude faz fetch sem solicitar você. Não muda quais hosts comandos em sandbox podem alcançar. | Claude Code remove a ferramenta `WebFetch`, portanto Claude não consegue fazer fetch. Não muda quais hosts comandos em sandbox podem alcançar. |

537| `WebFetch(domain:*)` | Claude faz fetch sem solicitar você, e comandos em sandbox podem alcançar qualquer host. | Claude Code mantém a ferramenta e recusa cada fetch, e comandos em sandbox não conseguem alcançar nenhum host. |567| `WebFetch(domain:*)` | Claude faz fetch sem solicitar você, e comandos em sandbox podem alcançar qualquer host. | Claude Code mantém a ferramenta e recusa cada fetch, e comandos em sandbox não conseguem alcançar nenhum host. |

538 568

539As duas formas também diferem em leituras de [artifacts](/docs/pt/artifacts), as páginas que a ferramenta Artifact publica em claude.ai. Uma regra deny ou ask `WebFetch` simples não se aplica a essas leituras. Uma regra `domain:` cobrindo `claude.ai` ou o host de conteúdo `*.claudeusercontent.com`, como `WebFetch(domain:claude.ai)` ou `WebFetch(domain:*)`, nega cada leitura ou solicita antes dela. Uma [regra `Artifact`](/docs/pt/artifacts#disable-artifacts) faz o mesmo.569As duas formas também diferem em leituras de [artefatos](/docs/pt/artifacts), as páginas que a ferramenta Artifact publica em claude.ai. Uma regra deny ou ask `WebFetch` simples não se aplica a essas leituras. Uma regra `domain:` cobrindo `claude.ai` ou o host de conteúdo `*.claudeusercontent.com`, como `WebFetch(domain:claude.ai)` ou `WebFetch(domain:*)`, nega cada leitura ou solicita antes dela. Uma [regra `Artifact`](/docs/pt/artifacts#disable-artifacts) faz o mesmo.

540 570

541Quando uma regra bloqueia uma leitura, a negação nomeia a regra. Antes de v2.1.268, uma regra deny `WebFetch` simples bloqueava cada leitura de artifact, e uma regra ask simples solicitava antes de cada uma.571Quando uma regra bloqueia uma leitura, a negação nomeia a regra. Antes de v2.1.268, uma regra deny `WebFetch` simples bloqueava cada leitura de artefato, e uma regra ask simples solicitava antes de cada uma.

542 572

543Para deixar Claude fazer fetch livremente enquanto mantém a lista de permissões do sandbox como está, use a forma simples. Este `settings.json` faz isso:573Para deixar Claude fazer fetch livremente enquanto mantém a allowlist do sandbox como está, use a forma simples. Este `settings.json` faz isso:

544 574

545```json theme={null}575```json theme={null}

546{576{

550}580}

551```581```

552 582

553Quando você pede a Claude para fazer fetch de uma página, ele faz fetch sem um prompt. Quando você pede a ele para executar um `curl` [em sandbox](/docs/pt/sandboxing) contra um host fora da lista de permissões do sandbox, Claude Code ainda solicita você para esse host, porque a regra simples não adicionou o host à lista de permissões.583Quando você pede a Claude para fazer fetch de uma página, ele faz fetch sem um prompt. Quando você pede a ele para executar um `curl` [em sandbox](/docs/pt/sandboxing) contra um host fora da allowlist do sandbox, Claude Code ainda solicita você para esse host, porque a regra simples não adicionou o host à allowlist.

554 584

555Em [modo auto](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode), Claude em vez disso nomeia o host no [domínios permitidos por comando](/docs/pt/sandboxing#per-command-allowed-domains-in-auto-mode) do comando para o classificador revisar.585Em [modo auto](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode), Claude em vez disso nomeia o host nos [domínios permitidos por comando](/docs/pt/sandboxing#per-command-allowed-domains-in-auto-mode) do comando para o classificador revisar.

556 586

557<h3 id="mcp">587<h3 id="mcp">

558 MCP588 MCP

564* `mcp__puppeteer__*` usa sintaxe com caracteres curinga e também corresponde a todas as ferramentas do servidor `puppeteer`594* `mcp__puppeteer__*` usa sintaxe com caracteres curinga e também corresponde a todas as ferramentas do servidor `puppeteer`

565* `mcp__puppeteer__puppeteer_navigate` corresponde à ferramenta `puppeteer_navigate` fornecida pelo servidor `puppeteer`595* `mcp__puppeteer__puppeteer_navigate` corresponde à ferramenta `puppeteer_navigate` fornecida pelo servidor `puppeteer`

566 596

567Se sua organização definiu uma ferramenta [conector claude.ai](/docs/pt/mcp#organization-controls-on-connector-tools) como `ask` e essa configuração chega a Claude Code em sua sessão, as regras allow para essa ferramenta não entram em vigor: Claude Code solicita em cada chamada, mesmo em modos `auto` e `bypassPermissions`. No modo `dontAsk`, que nunca solicita, Claude Code nega a chamada em vez disso. As ferramentas de conector que Claude Code busca por si próprio aparecem como `mcp__claude_ai_<server>__<tool>`.597Se sua organização definiu uma ferramenta de [conector claude.ai](/docs/pt/mcp#organization-controls-on-connector-tools) como `ask` e essa configuração chega a Claude Code em sua sessão, as regras allow para essa ferramenta não entram em vigor: Claude Code solicita em cada chamada, mesmo em modos `auto` e `bypassPermissions`. No modo `dontAsk`, que nunca solicita, Claude Code nega a chamada em vez disso. As ferramentas de conectores que Claude Code busca por si próprio aparecem como `mcp__claude_ai_<server>__<tool>`.

568 598

569Em uma sessão de [Cowork](https://claude.com/docs/cowork/overview) no aplicativo Claude Desktop, Claude executa comandos de shell através da ferramenta `mcp__workspace__bash` do Cowork em vez da ferramenta `Bash` integrada, e Cowork igualmente fornece `mcp__workspace__web_fetch` para web fetches. Claude Code também aplica regras deny que nomeiam a ferramenta inteira `Bash` ou `WebFetch` a essas ferramentas Cowork, portanto uma regra deny `Bash` gerenciada impede Claude de executar comandos de shell em Cowork. Quando Claude Code bloqueia tal chamada, a mensagem nomeia a ferramenta Cowork: `Permission to use mcp__workspace__bash has been denied.` As regras allow não se transferem: Claude Code nunca aplica uma regra allow `Bash` a `mcp__workspace__bash`.599Em uma sessão de [Cowork](https://claude.com/docs/cowork/overview) no aplicativo Claude Desktop, Claude executa comandos de shell através da ferramenta `mcp__workspace__bash` do Cowork em vez da ferramenta `Bash` integrada, e Cowork igualmente fornece `mcp__workspace__web_fetch` para web fetches. Claude Code também aplica regras deny que nomeiam a ferramenta inteira `Bash` ou `WebFetch` a essas ferramentas Cowork, portanto uma regra deny `Bash` gerenciada impede Claude de executar comandos de shell em Cowork. Quando Claude Code bloqueia tal chamada, a mensagem nomeia a ferramenta Cowork: `Permission to use mcp__workspace__bash has been denied.` As regras allow não se transferem: Claude Code nunca aplica uma regra allow `Bash` a `mcp__workspace__bash`.

570 600

571<h3 id="agent-subagents">601<h3 id="agent-subagents">

572 Agent (subagents)602 Agent (subagentes)

573</h3>603</h3>

574 604

575Use regras `Agent(AgentName)` para controlar quais [subagents](/docs/pt/sub-agents) Claude pode usar:605Use regras `Agent(AgentName)` para controlar quais [subagentes](/docs/pt/sub-agents) Claude pode usar:

576 606

577* `Agent(Explore)` corresponde ao subagent Explore607* `Agent(Explore)` corresponde ao subagente Explore

578* `Agent(Plan)` corresponde ao subagent Plan608* `Agent(Plan)` corresponde ao subagente Plan

579* `Agent(my-custom-agent)` corresponde a um subagent personalizado nomeado `my-custom-agent`609* `Agent(my-custom-agent)` corresponde a um subagente personalizado nomeado `my-custom-agent`

580 610

581Adicione essas regras ao array `deny` em suas configurações ou use a flag CLI `--disallowedTools` para desabilitar agentes específicos. Para desabilitar o agente Explore:611Adicione essas regras ao array `deny` em suas configurações ou use a flag CLI `--disallowedTools` para desabilitar agentes específicos. Para desabilitar o agente Explore:

582 612

594 624

595As regras `Cd` controlam para quais diretórios o [comando `/cd`](/docs/pt/commands) pode mover a sessão. `Cd` não é uma ferramenta invocável pelo modelo: Claude não pode chamá-la, e as regras se aplicam apenas quando você executa `/cd` você mesmo.625As regras `Cd` controlam para quais diretórios o [comando `/cd`](/docs/pt/commands) pode mover a sessão. `Cd` não é uma ferramenta invocável pelo modelo: Claude não pode chamá-la, e as regras se aplicam apenas quando você executa `/cd` você mesmo.

596 626

597Uma regra deny `Cd` simples desabilita `/cd` inteiramente. Uma regra deny `Cd(<path-pattern>)` bloqueia alvos correspondentes. As regras deny verificam cada grafia do alvo, incluindo cada salto de symlink que ele se resolve através, portanto uma regra escrita para um caminho também bloqueia alvos que se resolvem para ele.627Uma regra deny `Cd` simples desabilita `/cd` inteiramente. Uma regra deny `Cd(<path-pattern>)` bloqueia alvos correspondentes. As regras deny verificam cada grafia do alvo, incluindo cada salto de symlink através do qual ele se resolve, portanto uma regra escrita para um caminho também bloqueia alvos que se resolvem para ele.

598 628

599Adicionar qualquer regra allow `Cd` muda `/cd` para modo de lista de permissões: o diretório alvo resolvido deve corresponder a uma de suas regras allow, ou `/cd` recusa. Sem regras `Cd` configuradas, `/cd` mantém seu comportamento padrão e solicita que você confie em um diretório desconhecido.629Adicionar qualquer regra allow `Cd` muda `/cd` para modo de allowlist: o diretório alvo resolvido deve corresponder a uma de suas regras allow, ou `/cd` recusa. Sem regras `Cd` configuradas, `/cd` mantém seu comportamento padrão e solicita que você confie em um diretório desconhecido.

600 630

601Os padrões de caminho compartilham as âncoras `//`, `~/` e `/` das [regras Read e Edit](#read-and-edit), mas a correspondência é ancorada ao caminho do diretório inteiro em vez de estilo gitignore. `*` corresponde a exatamente um segmento de caminho e `**` corresponde entre segmentos. Um `/**` final também corresponde à sua raiz nomeada.631Os padrões de caminho compartilham as âncoras `//`, `~/` e `/` das [regras Read e Edit](#read-and-edit), mas a correspondência é ancorada ao caminho do diretório inteiro em vez de estilo gitignore. `*` corresponde a exatamente um segmento de caminho e `**` corresponde entre segmentos. Um `/**` final também corresponde à sua raiz nomeada.

602 632

623 653

624Veja [Decidir se confia em um mod](/docs/pt/plugins/mods/overview#decide-whether-to-trust-a-mod), ou [Gerenciar mods para sua organização](/docs/pt/plugins/mods/admin#know-what-happens-by-default) se você implantar configurações gerenciadas.654Veja [Decidir se confia em um mod](/docs/pt/plugins/mods/overview#decide-whether-to-trust-a-mod), ou [Gerenciar mods para sua organização](/docs/pt/plugins/mods/admin#know-what-happens-by-default) se você implantar configurações gerenciadas.

625 655

626As ferramentas MCP marcadas como [`requiresUserInteraction`](/docs/pt/mcp#require-approval-for-a-specific-tool) também ainda solicitam quando um hook retorna `"allow"`, assim como as ferramentas connector [que sua organização definiu como `ask`](/docs/pt/mcp#organization-controls-on-connector-tools) em sessões onde essa configuração chega ao Claude Code.656Para uma [ferramenta que requer interação do usuário](/docs/pt/permission-modes#actions-no-mode-auto-approves), como `AskUserQuestion` ou uma ferramenta MCP marcada como `requiresUserInteraction`, a aprovação `tool.check` de um mod não pula o prompt. Requer Claude Code v2.1.292 ou posterior. As ferramentas MCP marcadas como [`requiresUserInteraction`](/docs/pt/mcp#require-approval-for-a-specific-tool) também ainda solicitam quando um hook retorna `"allow"`, assim como as leituras de [caminhos de rede](#network-paths) e as ferramentas de conector [que sua organização definiu como `ask`](/docs/pt/mcp#organization-controls-on-connector-tools) em sessões onde essa configuração chega ao Claude Code.

627 657

628Um hook de bloqueio também tem precedência sobre regras allow. Um hook que sai com código 2 interrompe a chamada de ferramenta antes das regras de permissão serem avaliadas, portanto o bloqueio se aplica mesmo quando uma regra allow permitiria a chamada. Para executar todos os comandos Bash sem prompts exceto por alguns que você quer bloqueados, adicione `"Bash"` à sua lista allow e registre um hook PreToolUse que rejeita esses comandos específicos. Veja [Bloquear edições em arquivos protegidos](/docs/pt/hooks-guide#block-edits-to-protected-files) para um script de hook que você pode adaptar.658Um hook de bloqueio também tem precedência sobre regras allow. Um hook que sai com código 2 interrompe a chamada de ferramenta antes das regras de permissão serem avaliadas, portanto o bloqueio se aplica mesmo quando uma regra allow permitiria a chamada. Para executar todos os comandos Bash sem prompts exceto por alguns que você quer bloqueados, adicione `"Bash"` à sua lista allow e registre um hook PreToolUse que rejeita esses comandos específicos. Veja [Bloquear edições em arquivos protegidos](/docs/pt/hooks-guide#block-edits-to-protected-files) para um script de hook que você pode adaptar.

629 659

631 Diretórios de trabalho661 Diretórios de trabalho

632</h2>662</h2>

633 663

634Por padrão, Claude tem acesso a arquivos no diretório onde você o iniciou. Esse diretório é o diretório de trabalho primário da sessão até que você [mova a sessão com `/cd`](#move-the-session-to-another-directory). Você pode estender este acesso:664Por padrão, Claude tem acesso aos arquivos no diretório em que você o iniciou. Esse diretório é o diretório de trabalho principal da sessão até que você [mova a sessão com `/cd`](#move-the-session-to-another-directory). Você pode estender esse acesso:

635 665

636* **Durante a inicialização**: use o argumento CLI `--add-dir <path>`666* **Durante a inicialização**: use o argumento de CLI `--add-dir <path>`

637* **Durante a sessão**: use o comando `/add-dir`667* **Durante a sessão**: use o comando `/add-dir`

638* **Configuração persistente**: adicione a `additionalDirectories` em [arquivos de configuração](/docs/pt/settings#where-settings-live)668* **Configuração persistente**: adicione a `additionalDirectories` nos [arquivos de configuração](/docs/pt/settings#where-settings-live)

639 669

640Arquivos em diretórios adicionais seguem as mesmas regras de permissão do diretório de trabalho original: eles se tornam legíveis sem prompts, e as permissões de edição de arquivo seguem o modo de permissão atual.670Os arquivos em diretórios adicionais seguem as mesmas regras de permissão do diretório de trabalho original: eles se tornam legíveis sem prompts, exceto pela verificação de [caminho de rede](#network-paths), e as permissões de edição de arquivos seguem o modo de permissão atual.

641 671

642Você não pode adicionar a maioria dos [caminhos de rede](/docs/pt/errors#working-directory-is-a-network-path), como o compartilhamento UNC `\\server\share`, como diretórios de trabalho, porque procurar um pode entrar em contato com o host que ele nomeia. No Windows, mapeie o compartilhamento para uma letra de unidade e passe a unidade com `--add-dir` na inicialização.672Você não pode adicionar a maioria dos [caminhos de rede](/docs/pt/errors#working-directory-is-a-network-path), como o compartilhamento UNC `\\server\share`, como diretórios de trabalho, porque consultá-los pode contatar o host que eles nomeiam. No Windows, mapeie o compartilhamento para uma letra de unidade e passe a unidade com `--add-dir` na inicialização.

643 673

644Defina [`permissions.blockReadsOutsideWorkingDirectories`](/docs/pt/settings-reference#permissions-blockreadsoutsideworkingdirectories) para fazer com que as ferramentas de arquivo recusem os caminhos que ele delimita em cada modo de permissão. No modo automático, Claude Code oferece ativá-lo na primeira vez que Claude [lê fora dos diretórios de trabalho](/docs/pt/permission-modes#first-read-outside-the-working-directories).674Defina [`permissions.blockReadsOutsideWorkingDirectories`](/docs/pt/settings-reference#permissions-blockreadsoutsideworkingdirectories) para fazer com que as ferramentas de arquivo recusem os caminhos que ela delimita em todos os modos de permissão. No modo auto, Claude Code oferece ativá-la na primeira vez que Claude [lê fora dos diretórios de trabalho](/docs/pt/permission-modes#first-read-outside-the-working-directories).

645 675

646Em sessões em segundo plano no macOS, o host da sessão solicita acesso a pastas protegidas como `~/Desktop`, `~/Documents` e `~/Downloads` separadamente do seu terminal quando Claude precisa ler ou escrever arquivos lá; se as leituras falharem com `Operation not permitted`, consulte [como conceder acesso a pastas para sessões em segundo plano](/docs/pt/agent-view#background-sessions-can%E2%80%99t-read-desktop-documents-or-downloads-on-macos).676Em sessões em segundo plano no macOS, o host da sessão solicita acesso a pastas protegidas como `~/Desktop`, `~/Documents` e `~/Downloads` separadamente do seu terminal quando Claude precisa ler ou gravar arquivos nelas; se as leituras nessas pastas falharem com `Operation not permitted`, consulte [como conceder acesso a pastas para sessões em segundo plano](/docs/pt/agent-view#background-sessions-can’t-read-desktop-documents-or-downloads-on-macos).

647 677

648<h3 id="move-the-session-to-another-directory">678<h3 id="move-the-session-to-another-directory">

649 Mover a sessão para outro diretório679 Mover a sessão para outro diretório

650</h3>680</h3>

651 681

652Para mover a sessão para um diretório de trabalho primário diferente, em vez de [adicionar um diretório](#working-directories) ao lado do atual, execute `/cd <path>`. Claude Code mantém a conversa, carrega o `CLAUDE.md` do novo diretório e solicita que você [confie no workspace](#project-allow-rules-and-workspace-trust) se você não tiver trabalhado nele antes. Depois, Claude Code [encontra a sessão movida](/docs/pt/sessions#resume-a-session) quando você executa `--resume` do novo diretório.682Para mover a sessão para um diretório de trabalho principal diferente, em vez de [adicionar um diretório](#working-directories) junto ao atual, execute `/cd <path>`. Claude Code mantém a conversa, carrega o `CLAUDE.md` do novo diretório e solicita que você [confie no workspace](#project-allow-rules-and-workspace-trust) se ainda não tiver trabalhado nele. Depois disso, Claude Code [encontra a sessão movida](/docs/pt/sessions#where-the-session-picker-looks) quando você executa `--resume` a partir do novo diretório.

653 683

654Assim que você se move, Claude Code aplica a configuração do projeto do novo diretório:684Assim que você se move, Claude Code aplica a configuração de projeto do novo diretório:

655 685

656* Suas configurações de projeto, incluindo suas regras de permissão e [hooks](/docs/pt/hooks)686* Suas configurações de projeto, incluindo suas regras de permissão e [hooks](/docs/pt/hooks)

657* Seus servidores [`.mcp.json`](/docs/pt/mcp#project-scope), sujeitos à mesma [aprovação de servidor](/docs/pt/mcp#project-server-approvals-and-workspace-trust) que na inicialização, e os servidores MCP [local-scope](/docs/pt/mcp#local-scope) que você registrou nele687* Seus [servidores do `.mcp.json`](/docs/pt/mcp#project-scope), sujeitos à mesma [aprovação de servidor](/docs/pt/mcp#project-server-approvals-and-workspace-trust) da inicialização, e os servidores MCP de [escopo local](/docs/pt/mcp#local-scope) que você registrou nele

658* Os [plugins](/docs/pt/plugins/overview) que suas configurações habilitam, suas [skills](/docs/pt/skills#discovery-from-parent-and-nested-directories) e seus [subagentes](/docs/pt/sub-agents)688* Os [plugins](/docs/pt/plugins/overview) que suas configurações habilitam, suas [skills](/docs/pt/skills#discovery-from-parent-and-nested-directories) e seus [subagentes](/docs/pt/sub-agents)

659* Seus valores [`env`](/docs/pt/settings-reference#env), aplicados sobre as variáveis de ambiente das configurações do diretório anterior, que permanecem em vigor689* Seus valores de [`env`](/docs/pt/settings-reference#env), aplicados sobre as variáveis de ambiente das configurações do diretório anterior, que continuam em vigor

660 690

661Claude Code também desconecta os servidores MCP [local-scope](/docs/pt/mcp#local-scope) do projeto do diretório anterior e os servidores dos [plugins](/docs/pt/mcp#plugin-provided-mcp-servers) que não estão mais habilitados após a mudança. Ele pega [diretórios adicionais](#working-directories) das configurações do novo diretório em vez do anterior, e mantém os diretórios que você adicionou com `--add-dir` ou `/add-dir`. Hooks que a mudança ativa ainda recebem [`${CLAUDE_PROJECT_DIR}`](/docs/pt/hooks#reference-scripts-by-path) definido para a raiz do projeto onde a sessão começou.691Claude Code também desconecta os servidores MCP de projeto e de [escopo local](/docs/pt/mcp#local-scope) do diretório anterior, e os servidores de [plugins](/docs/pt/mcp#plugin-provided-mcp-servers) que não estão mais habilitados após a mudança. Ele obtém os [diretórios adicionais](#working-directories) das configurações do novo diretório em vez das do anterior, e mantém os diretórios que você adicionou com `--add-dir` ou `/add-dir`. Os hooks ativados pela mudança ainda recebem [`${CLAUDE_PROJECT_DIR}`](/docs/pt/hooks#reference-scripts-by-path) definido como a raiz do projeto onde a sessão começou.

662 692

663Quando o novo diretório ainda não é confiável, Claude Code lista no prompt de confiança as regras de permissão, diretórios adicionais, hooks e comandos auxiliares que as configurações do diretório ativariam, para que você possa revisá-los antes de aceitar. Se você recusar, a sessão permanece onde está. Antes da v2.1.246, `/cd` não aplicava as configurações, hooks, servidores MCP ou skills do novo diretório até que você retomasse a sessão, e seu prompt de confiança não listava o que as configurações do diretório ativariam.693Quando o novo diretório ainda não é confiável, Claude Code lista no prompt de confiança as regras de allow, os diretórios adicionais, os hooks e os comandos auxiliares que as configurações do diretório ativariam, para que você possa revisá-los antes de aceitar. Se você recusar, a sessão permanece onde está. Antes da v2.1.246, `/cd` não aplicava as configurações, hooks, servidores MCP ou skills do novo diretório até que você retomasse a sessão, e seu prompt de confiança não listava o que as configurações do diretório ativariam.

664 694

665Restrinja ou desabilite destinos `/cd` com regras de permissão [`Cd`](#cd).695Restrinja ou desative destinos de `/cd` com [regras de permissão `Cd`](#cd).

666 696

667<h3 id="additional-directories-grant-file-access-not-configuration">697<h3 id="additional-directories-grant-file-access-not-configuration">

668 Diretórios adicionais concedem acesso a arquivos, não configuração698 Diretórios adicionais concedem acesso a arquivos, não configuração

669</h3>699</h3>

670 700

671Adicionar um diretório estende onde Claude pode ler e editar arquivos. Não faz desse diretório uma raiz de configuração completa: a maioria da configuração `.claude/` não é descoberta de diretórios adicionais, embora alguns tipos sejam carregados como exceções.701Adicionar um diretório estende os locais onde Claude pode ler e editar arquivos. Isso não torna esse diretório uma raiz de configuração completa: a maior parte da configuração em `.claude/` não é descoberta a partir de diretórios adicionais, embora alguns tipos sejam carregados como exceções.

672 702

673Essas exceções se aplicam apenas a diretórios adicionados com o sinalizador `--add-dir` ou o comando `/add-dir`, incluindo diretórios que o Agent SDK adiciona através do sinalizador. Diretórios listados em `permissions.additionalDirectories` em um arquivo de configuração concedem apenas acesso a arquivos e não carregam nenhuma das configurações abaixo.703Essas exceções se aplicam apenas a diretórios adicionados com a flag `--add-dir` ou o comando `/add-dir`, incluindo diretórios que o Agent SDK adiciona por meio da flag. Diretórios listados em `permissions.additionalDirectories` em um arquivo de configuração concedem apenas acesso a arquivos e não carregam nenhuma das configurações abaixo.

674 704

675O [`additionalDirectories`](/docs/pt/agent-sdk/typescript#options) do Agent SDK em TypeScript e a opção [`add_dirs`](/docs/pt/agent-sdk/python#claudeagentoptions) em Python recebem as exceções também, mesmo que a opção TypeScript compartilhe seu nome com a chave de configurações. O SDK passa cada entrada para Claude Code como `--add-dir`, para que esses diretórios se comportem como diretórios adicionados por sinalizador. Skills, comandos e subagentes de qualquer diretório adicionado por sinalizador carregam através da fonte de configuração [`project`](/docs/pt/agent-sdk/claude-code-features#control-filesystem-settings-with-settingsources), então eles não carregam quando você exclui essa fonte com [`--setting-sources`](/docs/pt/cli-reference) na CLI ou `settingSources` no SDK, e [bare mode](/docs/pt/headless#start-faster-with-bare-mode) pula os comandos e subagentes entre eles.705A opção [`additionalDirectories`](/docs/pt/agent-sdk/typescript#options) do Agent SDK em TypeScript e a opção [`add_dirs`](/docs/pt/agent-sdk/python#claudeagentoptions) em Python também recebem as exceções, embora a opção do TypeScript compartilhe o nome com a chave de configuração. O SDK passa cada entrada para Claude Code como `--add-dir`, então esses diretórios se comportam como diretórios adicionados pela flag. Skills, comandos e subagentes de qualquer diretório adicionado pela flag são carregados por meio da [fonte de configuração](/docs/pt/agent-sdk/claude-code-features#control-filesystem-settings-with-settingsources) `project`, portanto não são carregados quando você exclui essa fonte com [`--setting-sources`](/docs/pt/cli-reference) na CLI ou `settingSources` no SDK, e o [modo bare](/docs/pt/headless#start-faster-with-bare-mode) ignora os comandos e subagentes entre eles.

676 706

677Os seguintes tipos de configuração são carregados de diretórios `--add-dir`:707Os seguintes tipos de configuração são carregados de diretórios `--add-dir`:

678 708

680| :- | :- |710| :- | :- |

682| [Arquivos de comando](/docs/pt/skills#where-skills-live) em `.claude/commands/` | Sim, sem recarga ao vivo. Quando o diretório adicionado e seu projeto definem um comando com o mesmo nome, Claude Code executa o comando do seu projeto |712| [Arquivos de comando](/docs/pt/skills#where-skills-live) em `.claude/commands/` | Sim, sem recarregamento ao vivo. Quando o diretório adicionado e o seu projeto definem um comando com o mesmo nome, Claude Code executa o comando do seu projeto |

684| [Configurações](/docs/pt/settings) em `.claude/settings.json` e `.claude/settings.local.json` | Apenas chaves `enabledPlugins` e [`extraKnownMarketplaces`](/docs/pt/settings-reference#extraknownmarketplaces) |714| [Configurações](/docs/pt/settings) em `.claude/settings.json` e `.claude/settings.local.json` | Apenas as chaves `enabledPlugins` e [`extraKnownMarketplaces`](/docs/pt/settings-reference#extraknownmarketplaces) |

685| Arquivos [CLAUDE.md](/docs/pt/memory), `.claude/rules/` e `CLAUDE.local.md` | Apenas quando `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1` está definido. `CLAUDE.local.md` adicionalmente requer a fonte de configuração `local`, que é ativada por padrão |715| Arquivos [CLAUDE.md](/docs/pt/memory), `.claude/rules/` e `CLAUDE.local.md` | Somente quando `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1` está definido. `CLAUDE.local.md` também requer a fonte de configuração `local`, que é habilitada por padrão |

686 716

687Para carregar as skills, comandos e subagentes de um subdiretório do seu [diretório de trabalho primário](#working-directories) no meio da sessão, execute `/add-dir` com o caminho desse subdiretório. Claude Code os carrega pelo resto da sessão sem solicitá-lo ou adicionar um diretório de trabalho, porque o subdiretório já é legível. Isso requer Claude Code v2.1.257 ou posterior.717Para carregar as skills, comandos e subagentes de um subdiretório do seu [diretório de trabalho principal](#working-directories) no meio da sessão, execute `/add-dir` com o caminho desse subdiretório. Claude Code os carrega pelo restante da sessão sem solicitar confirmação nem adicionar um diretório de trabalho, porque o subdiretório já é legível. Isso requer Claude Code v2.1.257 ou posterior.

688 718

689Claude Code descobre estilos de saída do diretório de trabalho atual e seus pais, seu diretório de usuário em `~/.claude/` e configurações gerenciadas. Hooks e outras chaves `.claude/settings.json` carregam da pasta `.claude/` do diretório de trabalho atual sem fallback de diretório pai, juntamente com seu `~/.claude/settings.json` de usuário e configurações gerenciadas. `.claude/settings.local.json` carrega da raiz do repositório git, mesmo quando você inicia Claude Code em um subdiretório, exceto nos casos em que Claude Code [não usa a raiz do repositório](/docs/pt/settings#where-claude-code-looks-for-each-file), como no Windows; antes da v2.1.211, ele também carregava apenas do diretório de trabalho atual. Sessões do [Agent SDK](/docs/pt/agent-sdk/claude-code-features#control-filesystem-settings-with-settingsources) o carregam do diretório de trabalho em todas as versões.719Claude Code descobre estilos de saída a partir do diretório de trabalho atual e de seus diretórios pais, do seu diretório de usuário em `~/.claude/` e das configurações gerenciadas. Hooks e outras chaves de `.claude/settings.json` são carregados da pasta `.claude/` do diretório de trabalho atual, sem fallback para diretórios pais, junto com o seu `~/.claude/settings.json` de usuário e as configurações gerenciadas. `.claude/settings.local.json` é carregado a partir da raiz do repositório git, mesmo quando você inicia Claude Code em um subdiretório, exceto nos casos em que Claude Code [não usa a raiz do repositório](/docs/pt/settings#where-claude-code-looks-for-each-file), como no Windows; antes da v2.1.211, ele também era carregado apenas do diretório de trabalho atual. Sessões do [Agent SDK](/docs/pt/agent-sdk/claude-code-features#control-filesystem-settings-with-settingsources) o carregam do diretório de trabalho em todas as versões.

690 720

691Para compartilhar essa configuração entre projetos, use uma destas abordagens:721Para compartilhar essa configuração entre projetos, use uma destas abordagens:

692 722

693* **Configuração em nível de usuário**: coloque arquivos em `~/.claude/agents/`, `~/.claude/output-styles/` ou `~/.claude/settings.json` para torná-los disponíveis em cada projeto723* **Configuração no nível do usuário**: coloque arquivos em `~/.claude/agents/`, `~/.claude/output-styles/` ou `~/.claude/settings.json` para disponibilizá-los em todos os projetos

694* **Plugins**: empacote e distribua configuração como um [plugin](/docs/pt/plugins/overview) que as equipes podem instalar724* **Plugins**: empacote e distribua a configuração como um [plugin](/docs/pt/plugins/overview) que as equipes possam instalar

695* **Inicie do diretório de configuração**: execute Claude Code do diretório contendo a configuração `.claude/` que você deseja725* **Iniciar a partir do diretório de configuração**: execute Claude Code a partir do diretório que contém a configuração `.claude/` desejada

696 726

697<h2 id="how-permissions-interact-with-sandboxing">727<h2 id="how-permissions-interact-with-sandboxing">

698 Como as permissões interagem com sandboxing728 Como as permissões interagem com sandboxing

plugins/components.md +2 −0

Details

790 790

791Hooks em `hooks/hooks.json` e na chave de manifesto `hooks` ambos carregam. Para cada evento e sua carga útil, consulte [Eventos de hook](/docs/pt/hooks#hook-events).791Hooks em `hooks/hooks.json` e na chave de manifesto `hooks` ambos carregam. Para cada evento e sua carga útil, consulte [Eventos de hook](/docs/pt/hooks#hook-events).

792 792

793Quando outro plugin habilitado tem o mesmo nome, um dos dois registra seus hooks de `hooks/hooks.json` e os do outro ficam de fora. Consulte [Hooks quando dois plugins habilitados compartilham um nome](/docs/pt/plugins/loading#hooks-when-two-enabled-plugins-share-a-name) para saber qual deles, e para a nota em `/plugin` que informa isso a você.

794

793Para escrever hooks como funções JavaScript que são executadas dentro do Claude Code e podem desenhar em sua interface, liste um arquivo de módulo sob uma chave `modules` no mesmo `hooks/hooks.json`. Um plugin com um é um mod. Consulte [Criar um mod](/docs/pt/plugins/mods/create).795Para escrever hooks como funções JavaScript que são executadas dentro do Claude Code e podem desenhar em sua interface, liste um arquivo de módulo sob uma chave `modules` no mesmo `hooks/hooks.json`. Um plugin com um é um mod. Consulte [Criar um mod](/docs/pt/plugins/mods/create).

794 796

795<h4 id="when-plugin-hooks-fire">797<h4 id="when-plugin-hooks-fire">

plugins/dependencies.md +1 −1

Details

209* **Plugin com seu próprio repositório**: a instalação falha com uma mensagem contendo `Dependency "secrets-vault@your-marketplace" has no git tag satisfying`.209* **Plugin com seu próprio repositório**: a instalação falha com uma mensagem contendo `Dependency "secrets-vault@your-marketplace" has no git tag satisfying`.

210* **Plugin referenciado por um caminho relativo**: a instalação usa a cópia atual do marketplace em vez disso, e a restrição é verificada quando o plugin carrega. Se essa cópia estiver fora do intervalo, o plugin dependente permanece desativado e `claude plugin list` mostra `Requires "secrets-vault@your-marketplace" ~2.1.0, installed 3.0.0`.210* **Plugin referenciado por um caminho relativo**: a instalação usa a cópia atual do marketplace em vez disso, e a restrição é verificada quando o plugin carrega. Se essa cópia estiver fora do intervalo, o plugin dependente permanece desativado e `claude plugin list` mostra `Requires "secrets-vault@your-marketplace" ~2.1.0, installed 3.0.0`.

211 211

212Para um plugin que o marketplace referencia por um caminho relativo, um marketplace que você adicionou como um caminho de pasta local também resolve restrições contra as tags git dessa pasta, quando a pasta é um repositório git. Isto requer Claude Code v2.1.196 ou posterior. Uma pasta local que não é um repositório git não tem tags, portanto Claude Code instala a dependência a partir do conteúdo atual da pasta em vez disso.212Para um plugin que o marketplace referencia por um caminho relativo, um marketplace que você adicionou como um caminho de pasta local também resolve restrições contra as tags git dessa pasta, quando a pasta é um repositório git. Uma pasta local que não é um repositório git não tem tags, portanto Claude Code instala a dependência a partir do conteúdo atual da pasta em vez disso.

213 213

214<h3 id="confirm-the-resolved-version">214<h3 id="confirm-the-resolved-version">

215 Confirme a versão resolvida215 Confirme a versão resolvida

plugins/host-marketplace.md +3 −1

Details

144Estas entry sources não precisam de conta git:144Estas entry sources não precisam de conta git:

145 145

146* **`archive`**: um zip baixado sobre HTTPS. Os usuários não precisam de `git` nem de uma conta, apenas acesso de rede à URL. Requer Claude Code v2.1.224 ou posterior. Fixe cada archive com `sha256` para que Claude Code recuse um download alterado. Para enviar credenciais com o download, veja [Authenticate archive downloads](#authenticate-archive-downloads).146* **`archive`**: um zip baixado sobre HTTPS. Os usuários não precisam de `git` nem de uma conta, apenas acesso de rede à URL. Requer Claude Code v2.1.224 ou posterior. Fixe cada archive com `sha256` para que Claude Code recuse um download alterado. Para enviar credenciais com o download, veja [Authenticate archive downloads](#authenticate-archive-downloads).

147* **Um repositório git público**: Claude Code clona um source `url` ou `git-subdir` público sobre HTTPS sem credenciais quando a entrada fornece uma URL `https://`. Para um source `github` ou um source `git-subdir` escrito como `owner/repo`, os usuários sem uma chave SSH do GitHub definem `CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1`.147* **Um repositório git público**: Claude Code clona um source `url` ou `git-subdir` público sobre HTTPS sem credenciais quando a entrada fornece uma URL `https://`. Para um source `github` ou um source `git-subdir` escrito como `owner/repo`, diga aos usuários sem uma chave SSH do GitHub para definir `CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1`.

148

149Mantenha `CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1` em suas instruções mesmo que `claude plugin install` funcione sem ela a partir do shell em uma máquina sem chave SSH. Para um source `github`, esse comando pode recorrer ao HTTPS por conta própria, imprimindo `SSH not configured, cloning via HTTPS`. Instalações a partir de `/plugin` dentro de uma sessão e atualizações de plugin não recorrem ao HTTPS, então, sem a variável, elas falham para usuários que não têm chave SSH do GitHub.

148 150

149Para uma equipe em uma rede, um marketplace `directory` em um sistema de arquivos compartilhado também funciona sem contas git. Os usuários precisam apenas de acesso de leitura ao caminho.151Para uma equipe em uma rede, um marketplace `directory` em um sistema de arquivos compartilhado também funciona sem contas git. Os usuários precisam apenas de acesso de leitura ao caminho.

150 152

plugins/loading.md +15 −1

Details

80 80

81Uma sessão em nuvem não adiciona os marketplaces que um repositório lista sob [`extraKnownMarketplaces`](/docs/pt/settings-reference#extraknownmarketplaces), porque isso requer o diálogo de confiança do workspace, que uma sessão em nuvem nunca mostra.81Uma sessão em nuvem não adiciona os marketplaces que um repositório lista sob [`extraKnownMarketplaces`](/docs/pt/settings-reference#extraknownmarketplaces), porque isso requer o diálogo de confiança do workspace, que uma sessão em nuvem nunca mostra.

82 82

83Um plugin de diretório de skills com escopo de projeto carrega apenas a partir do `.claude/skills/` do [diretório de trabalho primário](/docs/pt/permissions#working-directories) da sessão, e apenas depois que você aceita o [diálogo de confiança do workspace](/docs/pt/permissions#what-runs-before-you-trust-a-folder) para essa pasta. Ele não [procura diretórios pai até a raiz do repositório](/docs/pt/skills#discovery-from-parent-and-nested-directories) da forma que skills e comandos simples fazem. Se você iniciar a partir de um subdiretório, um plugin na raiz do repositório não carrega. Inicie a partir da raiz do repositório em vez disso, ou [mova a sessão para lá com `/cd`](/docs/pt/permissions#move-the-session-to-another-directory) na v2.1.246 ou posterior.83Se um plugin no `.claude/skills/` do seu repositório não carregar, verifique onde você iniciou a sessão e se você confiou na pasta:

85* **Em um subdiretório**: um plugin na raiz do repositório não carrega. Claude Code lê o `.claude/skills/` do [diretório de trabalho primário](/docs/pt/permissions#working-directories) da sessão e, diferentemente de skills e comandos simples, não [procura em diretórios pai](/docs/pt/skills#discovery-from-parent-and-nested-directories) por plugins. Inicie a partir da raiz do repositório em vez disso, ou [mova a sessão para lá com `/cd`](/docs/pt/permissions#move-the-session-to-another-directory) na v2.1.246 ou posterior

86* **A partir do aplicativo desktop, em um worktree**: o plugin carrega a partir do `.claude/skills/` do checkout principal em vez do `.claude/skills/` do worktree. Veja [O que os worktrees compartilham com o checkout principal](/docs/pt/worktrees#what-worktrees-share-with-the-main-checkout)

87* **Em uma pasta na qual você não confiou**: o plugin carrega apenas depois que você aceita o [diálogo de confiança do workspace](/docs/pt/permissions#what-runs-before-you-trust-a-folder) para essa pasta

84 88

85Um plugin com escopo de projeto é verificado no repositório e chega a cada colaborador que o clona. Como esse conteúdo vem do repositório em vez de você, ele carrega apenas após a mesma verificação de confiança que se aplica às regras de permissão de projeto em `.claude/settings.json`. Confiar em uma pasta pai ou executar com `-p` não é suficiente. Componentes que executam código são ainda mais restritos:89Um plugin com escopo de projeto é verificado no repositório e chega a cada colaborador que o clona. Como esse conteúdo vem do repositório em vez de você, ele carrega apenas após a mesma verificação de confiança que se aplica às regras de permissão de projeto em `.claude/settings.json`. Confiar em uma pasta pai ou executar com `-p` não é suficiente. Componentes que executam código são ainda mais restritos:

86 90

421 425

422Como a ordem compara nomes de manifesto, um plugin `--plugin-dir` nomeado `hello-plugin` substitui `hello@example-marketplace` quando o manifesto desse plugin também diz `"name": "hello-plugin"`.426Como a ordem compara nomes de manifesto, um plugin `--plugin-dir` nomeado `hello-plugin` substitui `hello@example-marketplace` quando o manifesto desse plugin também diz `"name": "hello-plugin"`.

423 427

428<h3 id="hooks-when-two-enabled-plugins-share-a-name">

429 Hooks quando dois plugins habilitados compartilham um nome

430</h3>

431

432Quando você instala e habilita dois plugins com o mesmo nome de manifesto de marketplaces diferentes, ambos aparecem como habilitados em `/plugin`, mas os hooks de um deles ficam de fora. Um plugin por nome registra os hooks em seu `hooks/hooks.json`, e um plugin por nome carrega um [módulo de hooks](/docs/pt/plugins/mods/overview). Quando as configurações gerenciadas da sua organização ativam uma das cópias, essa cópia detém o nome. Caso contrário, a cópia que Claude Code carrega primeiro o detém.

433

434Para ver qual cópia detém o nome, execute `/plugin` na sua sessão e abra a aba **Errors**. Uma nota ali para a cópia cujos hooks ficaram de fora nomeia a cópia que detém o nome, e os detalhes da cópia deixada de fora mostram a mesma nota. Para hooks de `hooks/hooks.json`, a nota começa com `Its hooks.json hooks do not run`, e para um módulo de hooks ela começa com `Its hooks module does not load`. A nota requer Claude Code v2.1.296 ou posterior.

435

436Para executar os hooks da cópia deixada de fora em vez disso, desabilite ou desinstale a cópia que detém o nome e, em seguida, execute `/reload-plugins` na sua sessão. O recarregamento registra os hooks da cópia restante e limpa a nota. Quando a cópia que detém o nome é uma que suas configurações gerenciadas ativam, você não pode desabilitá-la, e os hooks da outra cópia permanecem desativados enquanto ambas estiverem instaladas.

437

424<h3 id="keep-a-session-only-plugin-from-loading">438<h3 id="keep-a-session-only-plugin-from-loading">

425 Manter um plugin de sessão única de carregar439 Manter um plugin de sessão única de carregar

426</h3>440</h3>

plugins/marketplace-reference.md +1 −0

Details

51* <span id="reserved-name-spellings" />**Outra grafia de um nome reservado**: um nome que difere de um nome reservado apenas por um ponto final, ou por um símbolo diferente de um hífen no lugar de um hífen, então `claude.code.plugins` conta como `claude-code-plugins`. Adicionar o marketplace falha com [`is another spelling of "<reserved>", a reserved marketplace name`](/docs/pt/errors#marketplace-name-is-another-spelling-of-a-reserved-name), e um marketplace já registrado sob um para de carregar. Esta verificação requer Claude Code v2.1.280 ou posterior.51* <span id="reserved-name-spellings" />**Outra grafia de um nome reservado**: um nome que difere de um nome reservado apenas por um ponto final, ou por um símbolo diferente de um hífen no lugar de um hífen, então `claude.code.plugins` conta como `claude-code-plugins`. Adicionar o marketplace falha com [`is another spelling of "<reserved>", a reserved marketplace name`](/docs/pt/errors#marketplace-name-is-another-spelling-of-a-reserved-name), e um marketplace já registrado sob um para de carregar. Esta verificação requer Claude Code v2.1.280 ou posterior.

52* **Nomes que Claude Code usa para plugins que não vêm de um marketplace**: `inline` para plugins carregados com [`--plugin-dir`](/docs/pt/cli-reference), `builtin` para plugins integrados, `skills-dir` para plugins carregados automaticamente de [`.claude/skills/`](/docs/pt/skills) e `synced` para plugins sincronizados de sua conta claude.ai. `claude-plugin-test` também é reservado. `skills-dir` também aparece como `{"source": "skills-dir"}` em `strictKnownMarketplaces` e `blockedMarketplaces`, descrito em [Source values valid only in policy lists](#source-values-valid-only-in-policy-lists).52* **Nomes que Claude Code usa para plugins que não vêm de um marketplace**: `inline` para plugins carregados com [`--plugin-dir`](/docs/pt/cli-reference), `builtin` para plugins integrados, `skills-dir` para plugins carregados automaticamente de [`.claude/skills/`](/docs/pt/skills) e `synced` para plugins sincronizados de sua conta claude.ai. `claude-plugin-test` também é reservado. `skills-dir` também aparece como `{"source": "skills-dir"}` em `strictKnownMarketplaces` e `blockedMarketplaces`, descrito em [Source values valid only in policy lists](#source-values-valid-only-in-policy-lists).

53* **`npm`, `pip`, `uv`, `cargo`, `github` e `gh`**: reservado em qualquer capitalização. Esta verificação requer Claude Code v2.1.275 ou posterior.53* **`npm`, `pip`, `uv`, `cargo`, `github` e `gh`**: reservado em qualquer capitalização. Esta verificação requer Claude Code v2.1.275 ou posterior.

54* **Nomes de membros que todo objeto JavaScript possui**: `constructor`, `hasOwnProperty`, `isPrototypeOf`, `propertyIsEnumerable`, `toLocaleString`, `toString` e `valueOf`. `claude plugin marketplace add` recusa um marketplace que use um deles com [`Claude Code reserves this name and cannot register a marketplace under it`](/docs/pt/plugins/troubleshooting#claude-code-reserves-this-name). Esta verificação requer Claude Code v2.1.296 ou posterior.

54* **Nomes começando com `claudeai-`**: reservado para marketplaces hospedados em claude.ai. `claude plugin marketplace add` recusa qualquer outro marketplace que use um com `Cannot add marketplace "<name>": names starting with "claudeai-" are reserved for marketplaces hosted on claude.ai`.55* **Nomes começando com `claudeai-`**: reservado para marketplaces hospedados em claude.ai. `claude plugin marketplace add` recusa qualquer outro marketplace que use um com `Cannot add marketplace "<name>": names starting with "claudeai-" are reserved for marketplaces hosted on claude.ai`.

55* **A pasta de download de um marketplace GitHub registrado, `<owner>-<repo>`**: Claude Code baixa um marketplace adicionado de uma origem `github` como `acme/x-tools` por meio de uma pasta chamada `acme-x-tools`, qualquer que seja o `name` próprio desse marketplace. Enquanto esse marketplace estiver registrado sob um nome diferente de `acme-x-tools`, `claude plugin marketplace add` recusa um marketplace diferente chamado `acme-x-tools` após baixá-lo e relata `Can't use the marketplace name "acme-x-tools"`. Esta verificação requer Claude Code v2.1.290 ou posterior.56* **A pasta de download de um marketplace GitHub registrado, `<owner>-<repo>`**: Claude Code baixa um marketplace adicionado de uma origem `github` como `acme/x-tools` por meio de uma pasta chamada `acme-x-tools`, qualquer que seja o `name` próprio desse marketplace. Enquanto esse marketplace estiver registrado sob um nome diferente de `acme-x-tools`, `claude plugin marketplace add` recusa um marketplace diferente chamado `acme-x-tools` após baixá-lo e relata `Can't use the marketplace name "acme-x-tools"`. Esta verificação requer Claude Code v2.1.290 ou posterior.

56 57

plugins/mods/admin.md +7 −2

Details

68* **O guard protege o que você gerencia.** Um mod de um usuário não pode mudar o que seus hooks gerenciados recebem ou decidem, o prompt do sistema, seu `CLAUDE.md` gerenciado e outras instruções gerenciadas, o que qualquer mod lê como configurações, ou as ferramentas e descrições de seus servidores MCP gerenciados.68* **O guard protege o que você gerencia.** Um mod de um usuário não pode mudar o que seus hooks gerenciados recebem ou decidem, o prompt do sistema, seu `CLAUDE.md` gerenciado e outras instruções gerenciadas, o que qualquer mod lê como configurações, ou as ferramentas e descrições de seus servidores MCP gerenciados.

69* **Tudo mais é permitido.** O guard não adiciona outras restrições. Um mod de um usuário ainda pode ler e escrever arquivos, iniciar processos, fazer solicitações de rede, reescrever chamadas de ferramentas e prompts, negar uma chamada de ferramenta, aprovar uma que de outra forma solicitaria, e desenhar na interface, tudo com as permissões desse usuário.69* **Tudo mais é permitido.** O guard não adiciona outras restrições. Um mod de um usuário ainda pode ler e escrever arquivos, iniciar processos, fazer solicitações de rede, reescrever chamadas de ferramentas e prompts, negar uma chamada de ferramenta, aprovar uma que de outra forma solicitaria, e desenhar na interface, tudo com as permissões desse usuário.

70* **Regras de negação e seus hooks gerenciados têm precedência.** Onde o guard é carregado, um mod de um usuário não pode aprovar uma chamada que uma regra `deny` recusa, qualquer que seja o arquivo de configurações que contém a regra. Um bloqueio de um hook `PreToolUse` em configurações gerenciadas também é final. Ambos se aplicam às chamadas de ferramenta do Claude. Nenhum se aplica às [chamadas `$.fs` e `$.process` próprias de um mod](/docs/pt/plugins/mods/api#reach-files-processes-and-the-network): com `Read(.env)` negado, um mod ainda pode ler esse arquivo com `$.fs.read` ou iniciar um programa que o faça. Para limitar essas chamadas, impeça o mod de ser carregado ou trate a chamada em um [mod de política](#enforce-a-policy-with-a-mod-of-your-own).70* **Regras de negação e seus hooks gerenciados têm precedência.** Onde o guard é carregado, um mod de um usuário não pode aprovar uma chamada que uma regra `deny` recusa, qualquer que seja o arquivo de configurações que contém a regra. Um bloqueio de um hook `PreToolUse` em configurações gerenciadas também é final. Ambos se aplicam às chamadas de ferramenta do Claude. Nenhum se aplica às [chamadas `$.fs` e `$.process` próprias de um mod](/docs/pt/plugins/mods/api#reach-files-processes-and-the-network): com `Read(.env)` negado, um mod ainda pode ler esse arquivo com `$.fs.read` ou iniciar um programa que o faça. Para limitar essas chamadas, impeça o mod de ser carregado ou trate a chamada em um [mod de política](#enforce-a-policy-with-a-mod-of-your-own).

71* **Outras verificações de permissão podem ser substituídas.** Um mod de um usuário que aprova chamadas de ferramentas pode aprovar uma chamada que uma regra `ask` solicitaria, ou que um hook `PreToolUse` fora de configurações gerenciadas bloqueou. Em modo automático, uma chamada que o mod aprova é executada sem uma verificação de classificador.71* **Outras verificações de permissão podem ser substituídas.** Um mod de um usuário que aprova chamadas de ferramenta pode aprovar uma chamada para a qual uma regra `ask` pediria confirmação, ou que um hook `PreToolUse` fora de configurações gerenciadas bloqueou. No modo auto, uma chamada que o mod aprova é executada sem uma verificação de classificador. Para os prompts que a aprovação `tool.check` de um mod não ignora, veja [Estender permissões com hooks](/docs/pt/permissions#extend-permissions-with-hooks).

72 72

73A fonte do guard é pública no [diretório `mods/sec-default` do repositório Claude Code](https://github.com/anthropics/claude-code/tree/main/mods/sec-default).73A fonte do guard é pública no [diretório `mods/sec-default` do repositório Claude Code](https://github.com/anthropics/claude-code/tree/main/mods/sec-default).

74 74

81* **Hooks de configurações continuam funcionando.** Hooks de comando, HTTP, prompt e agente em arquivos de configurações e em `hooks/hooks.json` de plugins são executados como antes, ao lado de mods. Nada sobre eles está descontinuado.81* **Hooks de configurações continuam funcionando.** Hooks de comando, HTTP, prompt e agente em arquivos de configurações e em `hooks/hooks.json` de plugins são executados como antes, ao lado de mods. Nada sobre eles está descontinuado.

82* **Regras de negação têm precedência onde o guard é carregado.** Um mod de um usuário não pode aprovar uma chamada que uma regra `deny` recusa, a menos que você defina [`allowModsToOverrideDenyRules`](#set-options-on-the-built-in-guard).82* **Regras de negação têm precedência onde o guard é carregado.** Um mod de um usuário não pode aprovar uma chamada que uma regra `deny` recusa, a menos que você defina [`allowModsToOverrideDenyRules`](#set-options-on-the-built-in-guard).

83* **Hooks gerenciados são executados primeiro.** Um hook `PreToolUse` em configurações gerenciadas é executado antes de qualquer mod ver a chamada de ferramenta, e seu bloqueio é final. Se um mod então reescrever a chamada, seus hooks gerenciados são executados novamente na chamada reescrita, então um bloqueio ainda se aplica. Hooks `PreToolUse` de outros arquivos de configurações e de plugins são executados após o último mod, então um mod que retorna seu próprio resultado no lugar de executar a ferramenta impede que aqueles sejam executados. Veja [A ordem em que mods são executados](/docs/pt/plugins/mods/events#the-order-mods-run-in).83* **Hooks gerenciados são executados primeiro.** Um hook `PreToolUse` em configurações gerenciadas é executado antes de qualquer mod ver a chamada de ferramenta, e seu bloqueio é final. Se um mod então reescrever a chamada, seus hooks gerenciados são executados novamente na chamada reescrita, então um bloqueio ainda se aplica. Hooks `PreToolUse` de outros arquivos de configurações e de plugins são executados após o último mod, então um mod que retorna seu próprio resultado no lugar de executar a ferramenta impede que aqueles sejam executados. Veja [A ordem em que mods são executados](/docs/pt/plugins/mods/events#the-order-mods-run-in).

84* **Política de rede cobre `$.http.fetch`.** Se sua organização desativa busca na web, ou tráfego de rede não essencial é desativado para a sessão, Claude Code recusa uma solicitação de rede que um mod faz com `$.http.fetch`. A política não cobre um programa que o mod inicia com `$.process.run`. Esse programa alcança a rede com o acesso próprio do usuário.84* **Política de rede cobre `$.http.fetch`.**

86 * **A política da sua organização não permite WebFetch**: Claude Code também recusa toda requisição `$.http.fetch` de qualquer mod. Veja [Disponibilidade do WebFetch](/docs/pt/tools-reference#webfetch-availability).

87 * **Você define [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](/docs/pt/env-vars)**: um mod que você ou seus usuários instalam ainda pode fazer essas requisições. A variável bloqueia apenas os [mods integrados ao Claude Code](/docs/pt/plugins/mods/overview#mods-built-into-claude-code), além de qualquer requisição `$.http.fetch` que carregue as credenciais da Anthropic da sessão. Antes da v2.1.288, a variável bloqueava toda requisição `$.http.fetch` de qualquer mod.

89 Nenhuma das duas cobre um programa que o mod inicia com `$.process.run`, que alcança a rede com o acesso próprio do usuário.

85* **Controles de plugin cobrem mods.** Um mod é um plugin, então as [configurações que restringem o que os usuários podem instalar](/docs/pt/plugins/org#restrict-what-users-can-install), como `strictKnownMarketplaces`, decidem se ele pode ser instalado.90* **Controles de plugin cobrem mods.** Um mod é um plugin, então as [configurações que restringem o que os usuários podem instalar](/docs/pt/plugins/org#restrict-what-users-can-install), como `strictKnownMarketplaces`, decidem se ele pode ser instalado.

86* **Mods não podem mudar o prompt de permissão.** Um mod pode restylar muito da interface do Claude Code, mas não o prompt de permissão, então não pode mudar o que um prompt mostra. Um mod ainda pode aprovar ou negar uma chamada de ferramenta antes do prompt aparecer, como [Saiba o que acontece por padrão](#know-what-happens-by-default) descreve.91* **Mods não podem mudar o prompt de permissão.** Um mod pode restylar muito da interface do Claude Code, mas não o prompt de permissão, então não pode mudar o que um prompt mostra. Um mod ainda pode aprovar ou negar uma chamada de ferramenta antes do prompt aparecer, como [Saiba o que acontece por padrão](#know-what-happens-by-default) descreve.

87* **Prompts de confiança vêm primeiro.** Em uma sessão interativa em um diretório que o usuário ainda não confiou, nenhum mod é carregado até que ele responda ao prompt de confiança.92* **Prompts de confiança vêm primeiro.** Em uma sessão interativa em um diretório que o usuário ainda não confiou, nenhum mod é carregado até que ele responda ao prompt de confiança.

plugins/mods/api.md +3 −2

Details

303| `$.session` | `messages()` retorna a transcrição como uma lista de `{ role, text, toolUses }`. Também o diretório de trabalho, modelo e mais. [`usage()`](/docs/pt/plugins/mods/reference#mods-api-methods) retorna o uso da janela de contexto e limites de plano. |303| `$.session` | `messages()` retorna a transcrição como uma lista de `{ role, text, toolUses }`. Também o diretório de trabalho, modelo e mais. [`usage()`](/docs/pt/plugins/mods/reference#mods-api-methods) retorna o uso da janela de contexto e limites de plano. |

304| `$.mcp` | `call` uma ferramenta em um servidor MCP conectado |304| `$.mcp` | `call` uma ferramenta em um servidor MCP conectado |

305 305

306Arquivos e processos têm algumas regras próprias:306Arquivos, processos e requisições têm algumas regras próprias:

307 307

308* **Paths**: um caminho relativo é resolvido em relação ao diretório de trabalho da sessão308* **Paths**: um caminho relativo é resolvido em relação ao diretório de trabalho da sessão, ou do subagente cujo evento o hook está tratando

309* **`$.fs.list`**: retorna as entradas de um diretório como `{ name, kind, size, isLink }` e não é recursivo309* **`$.fs.list`**: retorna as entradas de um diretório como `{ name, kind, size, isLink }` e não é recursivo

310* **`$.process.run`**: leva uma lista de argumentos e não usa shell. Ele resolve para `{ exitCode, stdout, stderr }` qualquer que seja o código de saída. Ele rejeita se o programa não puder iniciar ou ainda estiver em execução no timeout, que é 30 segundos por padrão, então envolva em `try` e `catch`.310* **`$.process.run`**: leva uma lista de argumentos e não usa shell. Ele resolve para `{ exitCode, stdout, stderr }` qualquer que seja o código de saída. Ele rejeita se o programa não puder iniciar ou ainda estiver em execução no timeout, que é 30 segundos por padrão, então envolva em `try` e `catch`.

311* **`$.http.fetch`**: segue até cinco redirecionamentos. Em um redirecionamento para uma origem diferente, ele mantém apenas os cabeçalhos de requisição `accept`, `accept-language`, `content-type` e `user-agent` que você definiu e descarta o restante, então uma requisição que depende de outro cabeçalho, como `Authorization`, pode falhar após esse redirecionamento. Os [limites](/docs/pt/plugins/mods/reference#limits) informam seu timeout e tamanhos de corpo.

311 312

312Cada uma dessas chamadas é em si um evento, nomeado para seu namespace e método sem o `$.`, como `fs.read` para `$.fs.read`. Um mod [anterior na cadeia](/docs/pt/plugins/mods/events#the-order-mods-run-in) pode observar, reescrever ou recusar sua chamada, que é como uma organização restringe o que os mods alcançam.313Cada uma dessas chamadas é em si um evento, nomeado para seu namespace e método sem o `$.`, como `fs.read` para `$.fs.read`. Um mod [anterior na cadeia](/docs/pt/plugins/mods/events#the-order-mods-run-in) pode observar, reescrever ou recusar sua chamada, que é como uma organização restringe o que os mods alcançam.

313 314

plugins/mods/reference.md +8 −0

Details

148| `agent.offer` | Um tipo de subagente é oferecido ao Claude | `{ isOffered: false }` para retê-lo |148| `agent.offer` | Um tipo de subagente é oferecido ao Claude | `{ isOffered: false }` para retê-lo |

149| `agent.spawn` | Um subagente ou um colega de uma [equipe de agentes](/docs/pt/agent-teams) está prestes a iniciar. Para um colega de equipe, `e.isTeammate` é `true`. | `next({ ...e, model })` para escolher seu modelo, ou `{ deny: reason }` |149| `agent.spawn` | Um subagente ou um colega de uma [equipe de agentes](/docs/pt/agent-teams) está prestes a iniciar. Para um colega de equipe, `e.isTeammate` é `true`. | `next({ ...e, model })` para escolher seu modelo, ou `{ deny: reason }` |

150 150

151Quando o Claude retoma um subagente com a ferramenta [`SendMessage`](/docs/pt/sub-agents#resume-subagents), seu hook `agent.spawn` não é executado novamente. Para recusar as chamadas de `SendMessage` que retomam um subagente, faça a correspondência dessa ferramenta em um hook [`tool.call`](/docs/pt/plugins/mods/events#guard-or-change-a-tool-call).

152

151<h3 id="interface">153<h3 id="interface">

152 Interface154 Interface

153</h3>155</h3>

175| [`plugin.register`](/docs/pt/plugins/mods/admin#enforce-a-policy-with-a-mod-of-your-own) | Um módulo de hooks está prestes a ser carregado. `e.uses` lista seus eventos, chamadas à API de mods, variáveis de ambiente e estado, como o `claude plugin validate` os imprime. Cada chamada é escrita sem o prefixo `$.`, como `fs.read`. | `{ refuse: reason }` |177| [`plugin.register`](/docs/pt/plugins/mods/admin#enforce-a-policy-with-a-mod-of-your-own) | Um módulo de hooks está prestes a ser carregado. `e.uses` lista seus eventos, chamadas à API de mods, variáveis de ambiente e estado, como o `claude plugin validate` os imprime. Cada chamada é escrita sem o prefixo `$.`, como `fs.read`. | `{ refuse: reason }` |

176| `engine.create` | A API de mods está sendo construída para este mod | Uma API de mods alterada, para adicionar um namespace. Um mod fora do [nível](#the-hook-function) `user` também pode reter um. |178| `engine.create` | A API de mods está sendo construída para este mod | Uma API de mods alterada, para adicionar um namespace. Um mod fora do [nível](#the-hook-function) `user` também pode reter um. |

177 179

180Quando o hook de outro mod chama um método em um namespace que você adicionou em `engine.create`, as chamadas `$` do seu método são executadas no contexto desse hook até que todos os hooks nesse evento retornem. Por exemplo, um caminho relativo é resolvido em relação ao diretório de trabalho desse hook, e `$.prompt.submit` é rejeitado enquanto o turno está aguardando esse hook. As chamadas que seu método faz depois disso são executadas no próprio contexto do seu mod.

181

178<h3 id="telemetry">182<h3 id="telemetry">

179 Telemetria183 Telemetria

180</h3>184</h3>

324| O corpo de uma requisição de `$.http.fetch` | 4 MiB, contados em caracteres. Uma chamada com um corpo maior é rejeitada. |

325| O corpo de uma resposta de `$.http.fetch` | 4 MiB. `text` contém os primeiros 4 MiB e o restante não é lido. Quando o cabeçalho `Content-Length` declara mais, a chamada é rejeitada em vez disso, com um motivo que termina em `is over the 4194304-byte limit`, exceto quando a última requisição após quaisquer redirecionamentos usa o método `HEAD`. A isenção para `HEAD` requer o Claude Code v2.1.296 ou posterior. |

326| Uma chamada de `$.http.fetch`, incluindo redirecionamentos e corpo | 30 segundos |

327| Redirecionamentos que uma chamada de `$.http.fetch` segue | 5 |

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

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

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

plugins/mods/troubleshoot.md +9 −1

Details

78| `disableAllHooks in managed settings` | Sua organização desativou hooks de plugins instalados |78| `disableAllHooks in managed settings` | Sua organização desativou hooks de plugins instalados |

79| `only managed plugins and built-in plugins run` | `allowManagedHooksOnly` está definido, ou `disableAllHooks` está definido em um arquivo de configurações diferente de configurações gerenciadas |79| `only managed plugins and built-in plugins run` | `allowManagedHooksOnly` está definido, ou `disableAllHooks` está definido em um arquivo de configurações diferente de configurações gerenciadas |

80| `installed plugins that are not managed load no hooks module in this mode (--bare)` | Você iniciou Claude Code com `--bare` |80| `installed plugins that are not managed load no hooks module in this mode (--bare)` | Você iniciou Claude Code com `--bare` |

~~81| `another plugin of that name loads first` | Dois plugins compartilham um nome. O gerenciado, ou o carregado primeiro, é usado. |~~81| `another plugin of that name loads first` | Outro plugin ativado tem o mesmo nome do seu mod e [detém o nome](/docs/pt/plugins/loading#hooks-when-two-enabled-plugins-share-a-name), então seu módulo de hooks não carrega |

82 82

83<h3 id="messages-from-the-built-in-guard">83<h3 id="messages-from-the-built-in-guard">

84 Mensagens do guarda integrado84 Mensagens do guarda integrado

191 191

192Antes da v2.1.292, a chamada era executada uma segunda vez, então o prompt era enviado, o comando executado ou o subagente iniciado duas vezes.192Antes da v2.1.292, a chamada era executada uma segunda vez, então o prompt era enviado, o comando executado ou o subagente iniciado duas vezes.

193 193

194<h3 id="$-agent-register-refused-the-hooks-module-that-made-the-call-is-no-longer-loaded">

195 `$.agent.register refused: the hooks module that made the call is no longer loaded`

196</h3>

197

198A linha começa com o nome do seu mod, como em `first-mod: $.agent.register refused: the hooks module that made the call is no longer loaded (it was reloaded or removed)`, e o agente não é registrado. Seu mod foi recarregado ou descarregado antes da chamada. Um recarregamento carrega uma nova cópia do módulo de hooks, e essa chamada veio de código ainda em execução na cópia antiga, como um hook que ainda não havia retornado.

199

200Se esse hook não capturar a rejeição, ele falha e Claude Code [o ignora](#hook-skipped). Para registrar o agente a partir da cópia que permanece carregada, faça a chamada no seu hook [`session.start`](/docs/pt/plugins/mods/reference#session), que é executado novamente em cada nova cópia após um recarregamento.

201

194<h3 id="mods-that-run-in-the-hooks-worker-are-off-for-this-session">202<h3 id="mods-that-run-in-the-hooks-worker-are-off-for-this-session">

195 `mods that run in the hooks worker are off for this session`203 `mods that run in the hooks worker are off for this session`

196</h3>204</h3>

plugins/troubleshooting.md +22 −1

Details

256 256

257Antes da v2.1.295, Claude Code relatava a adição neste exemplo como bem-sucedida.257Antes da v2.1.295, Claude Code relatava a adição neste exemplo como bem-sucedida.

258 258

259<h3 id="claude-code-reserves-this-name">

260 `Cannot add marketplace "<name>": Claude Code reserves this name and cannot register a marketplace under it`

261</h3>

262

263Você adicionou um marketplace, e o [`name`](/docs/pt/plugins/marketplace-reference#top-level-fields) no seu `marketplace.json` é um dos nomes de membro que todo objeto JavaScript tem, como `constructor`, `toString` ou `valueOf`. Claude Code reserva esses nomes, então recusa a adição e não registra nada. [Nomes reservados](/docs/pt/plugins/marketplace-reference#reserved-names) os lista.

264

265Neste exemplo, o marketplace se chama `constructor`:

266

267```text theme={null}

268Cannot add marketplace "constructor": Claude Code reserves this name and cannot register a marketplace under it. The name is set by "name" in the marketplace's marketplace.json; ask its maintainer to change it.

269```

270

271Se um arquivo de configurações declara o marketplace em [`extraKnownMarketplaces`](/docs/pt/settings-reference#extraknownmarketplaces), a tentativa do Claude Code de adicioná-lo na inicialização falha da mesma forma, e a mensagem aparece na aba **Errors** em `/plugin`.

272

273Dê ao marketplace outro nome, depois adicione-o novamente:

274

275* **Você é o proprietário do marketplace**: altere `name` em `marketplace.json`

276* **Alguém mais o hospeda**: peça ao proprietário para alterar o nome

277

278Antes da v2.1.296, adicionar tal marketplace falhava com um erro interno no lugar desta mensagem.

279

259<h3 id="ssh-authentication-failed-or-https-authentication-failed">280<h3 id="ssh-authentication-failed-or-https-authentication-failed">

260 `SSH authentication failed` or `HTTPS authentication failed`281 `SSH authentication failed` or `HTTPS authentication failed`

261</h3>282</h3>

907 Hook loads but never fires928 Hook loads but never fires

908</h4>929</h4>

909 930

910Se um hook carrega sem erro mas nunca dispara, verifique sua definição e depois observe-o ser executado:931Se um hook carrega sem erro mas nunca dispara, primeiro execute `/plugin` em sua sessão e abra os detalhes do plugin. Uma nota ali que começa com `Its hooks.json hooks do not run` significa que outro plugin habilitado com o mesmo nome registrou seus hooks em vez disso, e [Hooks when two enabled plugins share a name](/docs/pt/plugins/loading#hooks-when-two-enabled-plugins-share-a-name) explica qual cópia é essa e como alternar. Caso contrário, verifique a definição do hook e depois observe-o ser executado:

911 932

912<Steps>933<Steps>

913 <Step title="Check the event name">934 <Step title="Check the event name">

routines.md +3 −3

Details

86 </Step>86 </Step>

87 87

88 <Step title="Selecionar repositórios">88 <Step title="Selecionar repositórios">

89 Adicione um ou mais repositórios do GitHub para Claude trabalhar. Cada repositório é clonado no início de uma execução, começando a partir do branch padrão. Claude cria branches com prefixo `claude/` para suas alterações.89 Adicione um ou mais repositórios do GitHub para Claude trabalhar. Cada repositório é clonado no início de uma execução. Claude cria branches com prefixo `claude/` para suas alterações.

90 </Step>90 </Step>

91 91

92 <Step title="Selecionar um ambiente">92 <Step title="Selecionar um ambiente">

359 Repositórios e permissões de branch359 Repositórios e permissões de branch

360</h3>360</h3>

361 361

362As rotinas precisam de acesso ao GitHub para clonar repositórios. Quando você cria uma rotina a partir da CLI com `/schedule`, Claude verifica se sua conta tem acesso ao GitHub para o repositório do qual você a executou e, se não tiver, adiciona uma nota de configuração nomeando como conceder acesso. Consulte [Opções de autenticação do GitHub](/docs/pt/claude-code-on-the-web#github-authentication-options) para as duas maneiras de conceder acesso.362As rotinas precisam de acesso ao GitHub para clonar repositórios. Quando você cria uma rotina a partir da CLI com `/schedule`, Claude verifica se sua conta tem acesso ao GitHub para o repositório do qual você a executou e, se não tiver, adiciona uma nota de configuração nomeando como conceder acesso. Consulte [Opções de autenticação do GitHub](/docs/pt/claude-code-on-the-web#github-authentication-options) para as duas maneiras de conceder acesso. Nos planos Team e Enterprise, um [Owner](/docs/pt/server-managed-settings#access-control) da sua organização Claude precisa ativar cada método antes que você possa usá-lo; consulte [Conectar o GitHub](/docs/pt/web-quickstart#connect-github).

363 363

364Se sua conexão do GitHub estiver ausente ou expirada quando uma execução estiver programada, a rotina pula execuções até que você se reconecte, por até 72 horas. Reconecte o GitHub dentro dessa janela e a rotina retoma automaticamente. Após 72 horas sem uma conexão, a rotina se desativa e você a reativa após reconectar o GitHub.364Se sua conexão do GitHub estiver ausente ou expirada quando uma execução estiver programada, a rotina pula execuções até que você se reconecte, por até 72 horas. Reconecte o GitHub dentro dessa janela e a rotina retoma automaticamente. Após 72 horas sem uma conexão, a rotina se desativa e você a reativa após reconectar o GitHub.

365 365

366Cada repositório que você adiciona é clonado em cada execução. Claude começa a partir do branch padrão do repositório, a menos que seu prompt especifique o contrário.366Cada repositório que você adiciona é clonado em cada execução. Claude começa a partir do branch padrão do repositório, a menos que seu prompt especifique o contrário. Se um [evento de pull request do GitHub](#add-a-github-trigger) acionar a execução e o repositório do pull request for o primeiro repositório da rotina, esse repositório começa a partir do commit head do pull request.

367 367

368Claude faz push de seu trabalho para um branch com prefixo `claude/`, a menos que seu prompt o direcione a fazer push para outro branch. Para controlar para quais branches uma execução pode fazer push, use regras de proteção de branch ou rulesets no GitHub. Para execuções na infraestrutura gerenciada pela Anthropic, e para execuções auto-hospedadas que fazem push através do [proxy git da Anthropic](/docs/pt/self-hosted-environments-deploy#use-the-anthropic-git-proxy), o GitHub as aplica ao acesso do GitHub que você conectou, portanto uma regra que esse acesso pode contornar não bloqueia o push de uma execução. Uma execução auto-hospedada que faz push com as credenciais git fornecidas pela sua implantação é verificada em relação a essas credenciais. Consulte [Configurar git](/docs/pt/self-hosted-environments-deploy#configure-git).368Claude faz push de seu trabalho para um branch com prefixo `claude/`, a menos que seu prompt o direcione a fazer push para outro branch. Para controlar para quais branches uma execução pode fazer push, use regras de proteção de branch ou rulesets no GitHub. Para execuções na infraestrutura gerenciada pela Anthropic, e para execuções auto-hospedadas que fazem push através do [proxy git da Anthropic](/docs/pt/self-hosted-environments-deploy#use-the-anthropic-git-proxy), o GitHub as aplica ao acesso do GitHub que você conectou, portanto uma regra que esse acesso pode contornar não bloqueia o push de uma execução. Uma execução auto-hospedada que faz push com as credenciais git fornecidas pela sua implantação é verificada em relação a essas credenciais. Consulte [Configurar git](/docs/pt/self-hosted-environments-deploy#configure-git).

369 369

sandboxing.md +1 −0

Details

203* Comandos `rm` ou `rmdir` que têm como alvo um [caminho crítico](/docs/pt/permission-modes#critical-paths) ainda passam pelo fluxo de permissão regular203* Comandos `rm` ou `rmdir` que têm como alvo um [caminho crítico](/docs/pt/permission-modes#critical-paths) ainda passam pelo fluxo de permissão regular

204* [Regras de solicitação](/docs/pt/permissions) com escopo de conteúdo, como `Bash(git push *)`, ainda forçam um prompt mesmo para comandos em sandbox204* [Regras de solicitação](/docs/pt/permissions) com escopo de conteúdo, como `Bash(git push *)`, ainda forçam um prompt mesmo para comandos em sandbox

205* Uma regra de solicitação `Bash` simples, ou a forma equivalente `Bash(*)`, é ignorada para comandos executados em sandbox; ela ainda se aplica a comandos que recorrem ao fluxo de permissão regular. No [modo de planejamento](/docs/pt/permission-modes#analyze-before-you-edit-with-plan-mode), a regra não é ignorada: ela solicita confirmação também para comandos em sandbox, incluindo os somente leitura205* Uma regra de solicitação `Bash` simples, ou a forma equivalente `Bash(*)`, é ignorada para comandos executados em sandbox; ela ainda se aplica a comandos que recorrem ao fluxo de permissão regular. No [modo de planejamento](/docs/pt/permission-modes#analyze-before-you-edit-with-plan-mode), a regra não é ignorada: ela solicita confirmação também para comandos em sandbox, incluindo os somente leitura

206* Os comandos da [ferramenta Monitor](/docs/pt/tools-reference#monitor-tool) não são aprovados automaticamente, embora ainda sejam executados no sandbox. Para pular o prompt, adicione uma [regra de permissão](/docs/pt/permissions#bash) que corresponda ao comando, como `Bash(npm run *)`

206 207

207<Info>208<Info>

208 O modo auto-allow funciona independentemente da configuração do seu modo de permissão, com três exceções: o [modo de planejamento](/docs/pt/permission-modes#analyze-before-you-edit-with-plan-mode), um comando do modo auto que traz [domínios permitidos por comando](#per-command-allowed-domains-in-auto-mode) e a [revisão do classificador no lado do servidor](/docs/pt/permission-modes#how-the-classifier-evaluates-actions) de comandos em sandbox no modo auto. Mesmo que você não esteja no modo "accept edits", os comandos Bash em sandbox são executados automaticamente quando o auto-allow está ativado. Isso significa que comandos Bash que modificam arquivos dentro dos limites do sandbox são executados sem solicitar confirmação, mesmo no modo Manual, em que as ferramentas de edição de arquivos solicitariam.209 O modo auto-allow funciona independentemente da configuração do seu modo de permissão, com três exceções: o [modo de planejamento](/docs/pt/permission-modes#analyze-before-you-edit-with-plan-mode), um comando do modo auto que traz [domínios permitidos por comando](#per-command-allowed-domains-in-auto-mode) e a [revisão do classificador no lado do servidor](/docs/pt/permission-modes#how-the-classifier-evaluates-actions) de comandos em sandbox no modo auto. Mesmo que você não esteja no modo "accept edits", os comandos Bash em sandbox são executados automaticamente quando o auto-allow está ativado. Isso significa que comandos Bash que modificam arquivos dentro dos limites do sandbox são executados sem solicitar confirmação, mesmo no modo Manual, em que as ferramentas de edição de arquivos solicitariam.

self-hosted-environments.md +5 −3

Details

132O runner e suas sessões fazem vários tipos de conexão de saída, e nenhuma conectividade de entrada de Anthropic é necessária:132O runner e suas sessões fazem vários tipos de conexão de saída, e nenhuma conectividade de entrada de Anthropic é necessária:

133 133

134* **Plano de controle**: o runner sonda `api.anthropic.com` para trabalho e publica eventos de progresso de configuração e falha, tudo HTTPS de saída. A sondagem funciona como o batimento cardíaco do runner.134* **Plano de controle**: o runner sonda `api.anthropic.com` para trabalho e publica eventos de progresso de configuração e falha, tudo HTTPS de saída. A sondagem funciona como o batimento cardíaco do runner.

135* **Conector SCM**: o orquestrador opcional [conector SCM](/docs/pt/self-hosted-environments-reference#scm-connector-flags) tunnel é a única conexão WebSocket.135* **Git**: o runner clona de e envia para seu host git por HTTPS ou SSH, autenticado com credenciais que sua implantação fornece. Consulte [Configurar git](/docs/pt/self-hosted-environments-deploy#configure-git) para as opções, incluindo credenciais cunhadas por sessão. Com o [proxy git Anthropic](/docs/pt/self-hosted-environments-deploy#use-the-anthropic-git-proxy), o tráfego git para repositórios no github.com passa por `api.anthropic.com` em vez disso.

136* **Git**: o runner clona de e envia para seu host git por HTTPS ou SSH, autenticado com credenciais que sua implantação fornece; [Configurar git](/docs/pt/self-hosted-environments-deploy#configure-git) cobre as opções, incluindo credenciais cunhadas por sessão e o [proxy git Anthropic](/docs/pt/self-hosted-environments-deploy#use-the-anthropic-git-proxy), que roteia git através de `api.anthropic.com` em vez disso.136* **Filho da sessão**: o processo filho de Claude Code mantém o fluxo de eventos da sessão para `api.anthropic.com` e faz suas próprias chamadas de saída para inferência de modelo e para comandos git executados durante a sessão. Em uma sessão que usa [git gerenciado pela Anthropic](/docs/pt/self-hosted-environments-deploy#use-the-anthropic-git-proxy), o filho envia seu tráfego `git` e `gh` para github.com por uma conexão WebSocket que ele abre para `api.anthropic.com`.

137* **Filho da sessão**: o processo filho de Claude Code mantém o fluxo de eventos da sessão para `api.anthropic.com` e faz suas próprias chamadas de saída para inferência de modelo e para comandos git executados durante a sessão. Consulte [Requisitos de rede](/docs/pt/self-hosted-environments-deploy#network-requirements) para a lista completa de saída. O [diagrama acima](#how-self-hosted-environments-work) mostra esses caminhos, além do conector SCM opcional.137* **Conector SCM**: o [conector SCM](/docs/pt/self-hosted-environments-reference#scm-connector-flags) opcional do orquestrador não está disponível, portanto seu túnel não é aberto. O túnel é uma conexão WebSocket para `api.anthropic.com`.

138

139Consulte [Requisitos de rede](/docs/pt/self-hosted-environments-deploy#network-requirements) para a lista completa de saída. O [diagrama acima](#how-self-hosted-environments-work) mostra esses caminhos, exceto o conector SCM opcional e a conexão git gerenciada pela Anthropic.

138 140

139Por padrão, a inferência de modelo usa a API Anthropic. O plano de controle entrega o endpoint da API para cada sessão, e a sessão se autentica com um token OAuth emitido pela Anthropic, com escopo de sessão. Para enviar requisições de modelo para sua própria conta de nuvem em vez disso, consulte [Enviar requisições de modelo para Bedrock ou Agent Platform](/docs/pt/self-hosted-environments-configuration#send-model-requests-to-bedrock-or-agent-platform).141Por padrão, a inferência de modelo usa a API Anthropic. O plano de controle entrega o endpoint da API para cada sessão, e a sessão se autentica com um token OAuth emitido pela Anthropic, com escopo de sessão. Para enviar requisições de modelo para sua própria conta de nuvem em vez disso, consulte [Enviar requisições de modelo para Bedrock ou Agent Platform](/docs/pt/self-hosted-environments-configuration#send-model-requests-to-bedrock-or-agent-platform).

140 142

self-hosted-environments-configuration.md +134 −28

Details

31| Variável | Descrição |31| Variável | Descrição |

32| :- | :- |32| :- | :- |

33| `CLAUDE_CODE_SESSION_ACCESS_TOKEN` | O JWT da sessão, prefixado com `sk-ant-cc-`. Sua reivindicação `act` identifica o criador da sessão, com o email do criador quando a superfície criadora o registrou. O valor é o token no momento do spawn; atualizações chegam pela stdin do filho, então um wrapper vê apenas o valor inicial. Consulte [Verify session identity](/docs/pt/self-hosted-environments-identity). |33| `CLAUDE_CODE_SESSION_ACCESS_TOKEN` | O JWT da sessão, prefixado com `sk-ant-cc-`. Sua reivindicação `act` identifica o criador da sessão, com o email do criador quando a superfície criadora o registrou. O valor é o token no momento do spawn; atualizações chegam pela stdin do filho, então um wrapper vê apenas o valor inicial. Consulte [Verify session identity](/docs/pt/self-hosted-environments-identity). |

34| `CCR_SESSION_ACCOUNT_EMAIL` | O email do criador da sessão, pré-extraído pelo runner da reivindicação `act.email` do token sem verificação de assinatura. Adequado para rotulagem, como trailers de commit. Quando o email controla a emissão de credenciais, verifique o token e leia a reivindicação dele em vez disso; consulte [Provision credentials scoped to the session creator](#provision-credentials-scoped-to-the-session-creator). Não definido quando o token não carrega email do criador. Trate como informação de identificação pessoal. |34| `CCR_SESSION_ACCOUNT_EMAIL` | O email do criador da sessão, pré-extraído pelo runner da reivindicação `act.email` do token sem verificação de assinatura. Adequado para rotulagem, como trailers de commit. Quando o email controla a emissão de credenciais, verifique o token e leia a reivindicação dele em vez disso. Consulte [Provision credentials scoped to the session creator](#provision-credentials-scoped-to-the-session-creator). Não definido quando o token não carrega email do criador, por exemplo em sessões que a identidade de serviço da sua organização cria. Trate como informação de identificação pessoal. |

35| `CLAUDE_RUNNER_CLIENT_PLATFORM` | A superfície do cliente que criou a sessão, como `web_claude_ai`, `desktop_app`, `ios`, `claude_code_cli` ou `scheduled_trigger`. Anthropic registra o valor uma vez na criação da sessão, então o wrapper e cada hook de ciclo de vida veem o mesmo valor. Use-o apenas para análise de adoção e rotulagem, não como sinal de autorização. Não definido quando a sessão não tem superfície registrada ou reconhecida, então referencie-o como `${CLAUDE_RUNNER_CLIENT_PLATFORM:-}` sob `set -u`. Requer Claude Code v2.1.229 ou posterior. |35| `CLAUDE_RUNNER_CLIENT_PLATFORM` | A superfície do cliente que criou a sessão, como `web_claude_ai`, `desktop_app`, `ios`, `claude_code_cli` ou `scheduled_trigger`. Anthropic registra o valor uma vez na criação da sessão, então o wrapper e cada hook de ciclo de vida veem o mesmo valor. Use-o apenas para análise de adoção e rotulagem, não como sinal de autorização. Não definido quando a sessão não tem superfície registrada ou reconhecida. Requer Claude Code v2.1.229 ou posterior. |

36| `CLAUDE_RUNNER_CLAUDE_BIN` | Caminho absoluto para o binário Claude Code próprio do runner. Termine seu wrapper com `exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@"` para passar o controle para o binário fixado sem codificar um caminho de instalação. |36| `CLAUDE_RUNNER_CLAUDE_BIN` | Caminho absoluto para o binário Claude Code próprio do runner. Termine seu wrapper com `exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@"` para passar o controle para o binário fixado sem codificar um caminho de instalação. |

37| `CLAUDE_CODE_REMOTE_SESSION_ID` | ID da sessão na forma marcada `cse_...`. Esta é a mesma sessão que os [lifecycle hooks](#lifecycle-hooks) veem como `CLAUDE_RUNNER_SESSION_ID` na forma `session_...`; as variáveis UUID correspondem em ambos, e substituir o prefixo `cse_` por `session_` produz o ID mostrado na URL da sessão. |37| `CLAUDE_CODE_REMOTE_SESSION_ID` | ID da sessão na forma marcada `cse_...`. Esta é a mesma sessão que os [lifecycle hooks](#lifecycle-hooks) veem como `CLAUDE_RUNNER_SESSION_ID` na forma `session_...`; as variáveis UUID correspondem em ambos, e substituir o prefixo `cse_` por `session_` produz o ID mostrado na URL da sessão. |

38| `CLAUDE_CODE_REMOTE_SESSION_UUID` | O mesmo ID da sessão na forma UUID canônica, para sistemas que usam UUIDs como chave. |38| `CLAUDE_CODE_REMOTE_SESSION_UUID` | O mesmo ID da sessão na forma UUID canônica, para sistemas que usam UUIDs como chave. |

39| `CLAUDE_CODE_REMOTE_SLACK_THREAD_URL` | Para uma sessão do [Claude Tag](https://claude.com/docs/claude-tag/overview) que pertence a uma thread do Slack, o link para essa thread. Não definido para outras sessões, e pode não estar definido também para uma sessão de thread. |

40| `CLAUDE_CODE_REMOTE_SLACK_THREAD_TS` | Para uma sessão do Claude Tag que pertence a uma thread do Slack, o timestamp do Slack dessa thread, como `1700000000.000100`. Pode não estar definido, e pode estar definido quando `CLAUDE_CODE_REMOTE_SLACK_THREAD_URL` não está, então verifique cada variável separadamente. |

39| `CLAUDE_SESSION_INGRESS_TOKEN_FILE` | Caminho absoluto para um arquivo por sessão contendo o JWT da sessão atual, mantido atualizado em atualizações de token. Subprocessos shell o leem para seu cabeçalho `Authorization` ao baixar anexos que o usuário adicionou à sessão. `exec` preserva a variável automaticamente; um wrapper que reconstrói o ambiente do filho deve levar a variável, ou downloads de anexos param silenciosamente de funcionar. |41| `CLAUDE_SESSION_INGRESS_TOKEN_FILE` | Caminho absoluto para um arquivo por sessão contendo o JWT da sessão atual, mantido atualizado em atualizações de token. Subprocessos shell o leem para seu cabeçalho `Authorization` ao baixar anexos que o usuário adicionou à sessão. `exec` preserva a variável automaticamente; um wrapper que reconstrói o ambiente do filho deve levar a variável, ou downloads de anexos param silenciosamente de funcionar. |

40| `CLAUDE_CONFIG_DIR` | Diretório de configuração Claude por sessão, escrito no início da sessão a partir do snapshot da configuração do host do runner que o runner captura na inicialização; consulte [Permissions and tool approval](#permissions-and-tool-approval). Escritas aqui são isoladas para esta sessão. O diretório fica sob `<base-dir>/_sessions/` após o término da sessão, a menos que você inicie o runner com [`--remove-session-state`](/docs/pt/self-hosted-environments-reference#runner-cli-flags); consulte [Reuse a pre-warmed checkout](/docs/pt/self-hosted-environments-deploy#reuse-a-pre-warmed-checkout). |42| `CLAUDE_CONFIG_DIR` | Diretório de configuração Claude por sessão, escrito no início da sessão a partir do snapshot da configuração do host do runner que o runner captura na inicialização; consulte [Permissions and tool approval](#permissions-and-tool-approval). Escritas aqui são isoladas para esta sessão. O diretório fica sob `<base-dir>/_sessions/` após o término da sessão, a menos que você inicie o runner com [`--remove-session-state`](/docs/pt/self-hosted-environments-reference#runner-cli-flags); consulte [Reuse a pre-warmed checkout](/docs/pt/self-hosted-environments-deploy#reuse-a-pre-warmed-checkout). |

41| `ANTHROPIC_BASE_URL` | A URL base da API que o filho usará, entregue pelo plano de controle por sessão e normalmente `https://api.anthropic.com`. Não a sobrescreva: a credencial de inferência da sessão é um token OAuth emitido pela Anthropic que outros provedores não aceitam. |43| `ANTHROPIC_BASE_URL` | A URL base da API que o filho usará, entregue pelo plano de controle por sessão e normalmente `https://api.anthropic.com`. Não a sobrescreva: a credencial de inferência da sessão é um token OAuth emitido pela Anthropic que outros provedores não aceitam. |

43 45

44O wrapper também herda o resto do ambiente gerenciado do filho, incluindo quaisquer variáveis de ambiente fornecidas pelo servidor. `exec` propaga tudo automaticamente; se seu wrapper gera o filho de outra forma, encaminhe o ambiente completo.46O wrapper também herda o resto do ambiente gerenciado do filho, incluindo quaisquer variáveis de ambiente fornecidas pelo servidor. `exec` propaga tudo automaticamente; se seu wrapper gera o filho de outra forma, encaminhe o ambiente completo.

45 47

48`CLAUDE_CODE_REMOTE_SLACK_THREAD_URL` e `CLAUDE_CODE_REMOTE_SLACK_THREAD_TS` chegam ao seu wrapper ou [hook `command`](#command). Elas também chegam ao que a sessão executa, como comandos shell, hooks do git e hooks do Claude Code. Os hooks `checkout`, `post-session` e `spawn-runner` não as recebem.

50<h3 id="give-a-default-to-variables-that-can-be-unset">

51 Give a default to variables that can be unset

52</h3>

54`CCR_SESSION_ACCOUNT_EMAIL`, `CLAUDE_RUNNER_CLIENT_PLATFORM`, `CLAUDE_CODE_REMOTE_SLACK_THREAD_URL` e `CLAUDE_CODE_REMOTE_SLACK_THREAD_TS` podem, cada uma, não estar definidas. Se seu script usa `set -u`, o Bash para com `unbound variable` ao expandir uma que não está definida, então expanda-as com um valor padrão, como `${CCR_SESSION_ACCOUNT_EMAIL:-}`.

56Onde quer que um shell expanda o link da thread do Slack, tome estas precauções:

58* **Coloque-o entre aspas**: o link pode conter caracteres que um shell interpreta, como `?` e `&`, então coloque a variável entre aspas, como em `"${CLAUDE_CODE_REMOTE_SLACK_THREAD_URL:-}"`.

59* **Mantenha seu valor fora de strings de `eval` e `sh -c`**: não substitua seu valor em uma string que `eval` ou `sh -c` executa, mesmo entre aspas. Em vez disso, faça essa string referenciar a variável.

46<h3 id="keep-stdin-and-file-descriptor-3-attached">61<h3 id="keep-stdin-and-file-descriptor-3-attached">

47 Keep stdin and file descriptor 3 attached62 Keep stdin and file descriptor 3 attached

48</h3>63</h3>

49 64

50A stdin do filho é o canal de controle do runner. Rotações de token e sinais de fim de sessão chegam nela. O runner também abre um pipe no descritor de arquivo 3 e lê sinais de atividade do filho dele para conduzir timeouts de inatividade e inicialização. Um simples `exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@"` preserva ambos automaticamente.65A stdin do filho é o canal de controle do runner. Rotações de token e sinais de fim de sessão chegam nela. O runner também abre um pipe no descritor de arquivo 3 e lê sinais de atividade do filho dele para conduzir timeouts de inatividade e inicialização. Um simples `exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@"` preserva ambos automaticamente.

51 66

52Se seu wrapper coloca o filho em background com um simples `&`, ele corta a stdin do filho: a sessão parece saudável até a vida útil do token OAuth inicial de aproximadamente 30 minutos expirar, então cada chamada de API falha com `401 authentication_error`. Se seu wrapper deve colocar o filho em background, por exemplo para manter uma trap de teardown viva, salve stdin no descritor de arquivo 4 ou superior e re-anexe-a explicitamente:67Se seu wrapper coloca o filho em background com um simples `&`, ele corta a stdin do filho. A sessão parece saudável até a vida útil do token OAuth inicial de aproximadamente 30 minutos expirar, e então cada chamada de API que usa o token falha com `401 authentication_error`. Se seu wrapper deve colocar o filho em background, por exemplo para manter uma trap de teardown viva, salve stdin no descritor de arquivo 4 ou superior e re-anexe-a explicitamente:

53 68

54```bash theme={null}69```bash theme={null}

55exec 4<&070exec 4<&0

59wait "$CHILD"74wait "$CHILD"

60```75```

61 76

~~62Não feche ou reutilize o descritor de arquivo 3 no wrapper. Redirecionar stdout e stderr do filho é aceitável.~~77Você pode redirecionar o stdout do filho. Mantenha o descritor de arquivo 3 e o stderr anexados ao runner:

79* **Descritor de arquivo 3**: transporta os sinais de atividade do filho para o runner. Não o feche nem o reutilize no wrapper.

80* **stderr**: quando o wrapper ou o filho sai com código diferente de zero, o runner publica as últimas linhas do stderr na sessão e as imprime em seu próprio log. O usuário da sessão vê essas linhas, então não imprima segredos no stderr e remova `set -x` antes de implantar o wrapper. Se você redirecionar o stderr, as sessões ainda são executadas, mas o runner relata uma falha apenas com o código de saída.

63 81

64<h3 id="pass-the-system-prompt-flags-through">82<h3 id="pass-the-system-prompt-flags-through">

65 Pass the system prompt flags through83 Pass the system prompt flags through

108 checkout126 checkout

109</h3>127</h3>

110 128

111Executado uma vez por repositório, no lugar do clone e fetch integrados do runner. Use o hook para clonar de um espelho de leitura, semear uma árvore de trabalho de um arquivo ou aplicar autenticação git por sessão. O runner define estas variáveis, e pode definir outras variáveis `CLAUDE_RUNNER_` que a tabela não lista:129Executado uma vez por repositório, no lugar do clone e fetch integrados do runner. Use o hook para clonar de um espelho de leitura que você acessa por HTTPS ou SSH, semear uma árvore de trabalho a partir de um arquivo ou aplicar autenticação git por sessão. O runner define estas variáveis, e pode definir outras variáveis `CLAUDE_RUNNER_` que a tabela não lista:

112 130

113| Variável | Descrição |131| Variável | Descrição |

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

115| `CLAUDE_RUNNER_REPO_URL` | URL do repositório para clonar, após qualquer `--git-host-rewrite` e `--git-ssh-rewrite` terem sido aplicados |133| `CLAUDE_RUNNER_REPO_URL` | URL do repositório para clonar, após qualquer `--git-host-rewrite` e `--git-ssh-rewrite` terem sido aplicados |

116| `CLAUDE_RUNNER_REPO_REF` | Revisão para fazer checkout: branch, tag ou commit SHA conforme a sessão o solicitou. Vazio significa o branch padrão do repositório. |134| `CLAUDE_RUNNER_REPO_REF` | Revisão para fazer checkout, conforme a sessão a solicitou: um branch, tag, commit SHA ou nome de referência completo como `refs/pull/<number>/head`. Vazio significa o branch padrão do repositório. |

121| `CLAUDE_RUNNER_CLIENT_PLATFORM` | A superfície do cliente que criou a sessão, como `web_claude_ai`, `desktop_app` ou `ios`. Não definido quando a sessão não tem superfície registrada ou reconhecida. |139| `CLAUDE_RUNNER_CLIENT_PLATFORM` | A superfície do cliente que criou a sessão, como `web_claude_ai`, `desktop_app` ou `ios`. Não definido quando a sessão não tem superfície registrada ou reconhecida, então referencie-a como `${CLAUDE_RUNNER_CLIENT_PLATFORM:-}` sob `set -u`. Requer Claude Code v2.1.229 ou posterior. |

123| `GIT_CONFIG_COUNT`, `GIT_CONFIG_KEY_n`, `GIT_CONFIG_VALUE_n` | Configurações git que o runner fixa para o git que seu hook executa. [Configuração do Git dentro de lifecycle hooks](#git-configuration-inside-lifecycle-hooks) as descreve. Requer Claude Code v2.1.280 ou posterior. |141| `GIT_CONFIG_COUNT`, `GIT_CONFIG_KEY_n`, `GIT_CONFIG_VALUE_n` | Configurações git que o runner fixa para o git que seu hook executa. [Configuração do Git dentro de lifecycle hooks](#git-configuration-inside-lifecycle-hooks) as descreve. Requer Claude Code v2.1.280 ou posterior. |

124 142

125O script deve deixar uma árvore de trabalho em `CLAUDE_RUNNER_CHECKOUT_PATH` com checkout na revisão solicitada. HEAD desanexado é aceitável; o runner cria o branch de trabalho da sessão em cima. O runner verifica se o caminho contém um `.git` depois; se seu hook materializa uma fonte não-git como Perforce ou um tarball desempacotado, defina `CLAUDE_RUNNER_SKIP_GIT_VERIFY=1` no ambiente do runner para pular essa verificação. Fluxos baseados em Git como criação de branch de trabalho e push de resultados requerem um checkout git, então exporte resultados de árvores não-git com um hook [`post-session`](#post-session).143O script deve deixar uma árvore de trabalho em `CLAUDE_RUNNER_CHECKOUT_PATH` com checkout na revisão solicitada. Um HEAD desanexado funciona, porque o runner cria o branch de trabalho da sessão em cima.

126 144

127O runner não passa uma credencial git para o hook. Em vez disso, emita uma credencial de clone por sessão a partir da identidade da sessão: verifique `CLAUDE_CODE_SESSION_ACCESS_TOKEN` com uma biblioteca JWT padrão contra o endpoint JWKS sob `CLAUDE_RUNNER_API_BASE_URL`, conforme descrito em [Verify the token from your service](/docs/pt/self-hosted-environments-identity#verify-the-token-from-your-service), então faça seu serviço de credencial emitir uma credencial de clone de curta duração para a identidade na reivindicação `act` do token. `CLAUDE_RUNNER_CLAUDE_BIN` não está definido no ambiente do checkout-hook, então o subcomando `decode-token` não está disponível aqui. Voltar para qualquer autenticação git que o host já tenha, como um agente SSH, credential helper ou `.netrc`, também é uma opção.145Depois que seu hook retorna, o runner verifica se `CLAUDE_RUNNER_CHECKOUT_PATH` contém um `.git`. Se seu hook materializa uma fonte não-git como Perforce ou um tarball desempacotado, defina `CLAUDE_RUNNER_SKIP_GIT_VERIFY=1` no ambiente do runner para pular essa verificação. Fluxos baseados em Git como criação de branch de trabalho e push de resultados requerem um checkout git, então exporte resultados de árvores não-git com um [hook `post-session`](#post-session).

128 146

129Quando o hook sai com código diferente de zero, ou sai com 0 sem deixar um checkout utilizável atrás, o que o runner faz depende do repositório:147<h4 id="get-git-credentials-in-the-hook">

148 Obter credenciais git no hook

149</h4>

130 150

131* **Um repositório para o qual a sessão faz push de resultados**: o runner falha a sessão, e em uma saída diferente de zero exibe a cauda do stderr do script para o usuário.151O runner não passa uma credencial git para o hook. O subcomando `decode-token` também não está disponível aqui, porque `CLAUDE_RUNNER_CLAUDE_BIN` não está definido no ambiente do checkout-hook. Em vez disso, emita uma credencial de clone por sessão a partir da identidade da sessão, ou recorra à própria autenticação git do host:

132* **Um repositório que a sessão apenas lê**, como um repositório adicionado a uma sessão em execução: o runner registra uma linha `[runner:warn]` com o detalhe da falha, publica um passo `Skipped` para a sessão, remove o que o hook deixou no caminho de checkout e continua com os repositórios restantes. Quando o runner não consegue remover o caminho imediatamente, ele tenta novamente a remoção no fim da sessão. Se pular deixa a sessão sem nenhum repositório, o runner falha a sessão mesmo assim.

133 152

134Antes da v2.1.228, o runner falhava a sessão em uma falha de hook para qualquer repositório, então um repositório somente leitura que o hook não conseguia servir falhava a sessão novamente em cada novo runner fresco em que a sessão retomava.153* **Credencial de clone por sessão**: verifique `CLAUDE_CODE_SESSION_ACCESS_TOKEN` com uma biblioteca JWT padrão contra o endpoint JWKS sob `CLAUDE_RUNNER_API_BASE_URL`, conforme descrito em [Verify the token from your service](/docs/pt/self-hosted-environments-identity#verify-the-token-from-your-service). Em seguida, faça seu serviço de credencial emitir uma credencial de clone de curta duração para a identidade na reivindicação `act` do token. Associe essa credencial a `act.sub`, e não exija `act.email`.

154* **Autenticação git do host**: use qualquer autenticação git que o host já tenha, como um agente SSH, credential helper ou `.netrc`.

135 155

136O runner remove o caminho de checkout após a sessão terminar.156<h4 id="when-the-hook-fails">

157 Quando o hook falha

158</h4>

159

160O hook falha quando sai com código diferente de zero, ou sai com 0 sem deixar um checkout utilizável para trás:

161

162* **Um repositório para o qual a sessão faz push de resultados**: o runner falha a sessão, e em uma saída diferente de zero exibe a cauda do stderr do script para o usuário.

163* **Um repositório que a sessão apenas lê**, como um repositório adicionado a uma sessão em execução: o runner registra uma linha `[runner:warn]` com o detalhe da falha, publica um passo `Skipped` para a sessão, remove o que o hook deixou no caminho de checkout e continua com os repositórios restantes. Se pular deixa a sessão sem nenhum repositório, o runner falha a sessão mesmo assim.

164

165Quando o hook é bem-sucedido, o runner remove o caminho de checkout após a sessão terminar.

137 166

138<h3 id="post-session">167<h3 id="post-session">

139 post-session168 post-session

151| `CLAUDE_RUNNER_WORKSPACE_PATHS` | Caminhos absolutos separados por dois-pontos das árvores de trabalho da sessão. Vazio para sessões sem repositório. |180| `CLAUDE_RUNNER_WORKSPACE_PATHS` | Caminhos absolutos separados por dois-pontos das árvores de trabalho da sessão. Vazio para sessões sem repositório. |

154| `CLAUDE_RUNNER_CLIENT_PLATFORM` | A superfície do cliente que criou a sessão, como `web_claude_ai`, `desktop_app` ou `ios`. Não definido quando a sessão não tem superfície registrada ou reconhecida. Requer Claude Code v2.1.229 ou posterior. |183| `CLAUDE_RUNNER_CLIENT_PLATFORM` | A superfície do cliente que criou a sessão, como `web_claude_ai`, `desktop_app` ou `ios`. Não definido quando a sessão não tem superfície registrada ou reconhecida, então referencie-a como `${CLAUDE_RUNNER_CLIENT_PLATFORM:-}` sob `set -u`. Requer Claude Code v2.1.229 ou posterior. |

156| `GIT_CONFIG_COUNT`, `GIT_CONFIG_KEY_n`, `GIT_CONFIG_VALUE_n` | Configurações git que o runner fixa para o git que seu hook executa. [Configuração do Git dentro de lifecycle hooks](#git-configuration-inside-lifecycle-hooks) as descreve. Requer Claude Code v2.1.280 ou posterior. |185| `GIT_CONFIG_COUNT`, `GIT_CONFIG_KEY_n`, `GIT_CONFIG_VALUE_n` | Configurações git que o runner fixa para o git que seu hook executa. [Configuração do Git dentro de lifecycle hooks](#git-configuration-inside-lifecycle-hooks) as descreve. Requer Claude Code v2.1.280 ou posterior. |

157 186

158`CLAUDE_RUNNER_EXIT_REASON` toma um de quatro valores:187`CLAUDE_RUNNER_EXIT_REASON` toma um de quatro valores:

159 188

160* `completed`: a sessão terminou de forma limpa. O processo Claude Code saiu normalmente, ou a sessão foi arquivada ou deletada enquanto ainda estava em execução.189* `completed`: a sessão terminou de forma limpa. O processo Claude Code saiu normalmente, ou saiu por conta própria depois que a sessão foi arquivada ou deletada.

161* `failed`: o processo Claude Code travou, ou a configuração falhou após ele ter iniciado.190* `failed`: o processo Claude Code travou, ou a configuração falhou após ele ter iniciado.

162* `interrupted`: o runner parou a sessão. Ele liberou a sessão para liberar o slot, a sessão expirou na inicialização, o servidor moveu a sessão para fora deste runner, o runner estava drenando, ou a sessão ultrapassou seu limite [`--kill-session-after-min`](/docs/pt/self-hosted-environments-reference#runner-cli-flags).191* `interrupted`: o runner parou a sessão, em um destes casos:

192 * O runner liberou a sessão para liberar o slot.

193 * A sessão atingiu o timeout na inicialização.

194 * O servidor moveu a sessão para fora deste runner.

195 * A verificação periódica do runner detectou um arquivamento ou exclusão antes de o processo sair.

196 * O runner estava drenando.

197 * A sessão ultrapassou seu limite [`--kill-session-after-min`](/docs/pt/self-hosted-environments-reference#runner-cli-flags).

163* `abandoned`: reservado para uma sessão que outro runner reivindicou. O hook não dispara atualmente nesse caso.198* `abandoned`: reservado para uma sessão que outro runner reivindicou. O hook não dispara atualmente nesse caso.

164 199

165Os [contadores de ciclo de vida da sessão](/docs/pt/self-hosted-environments-reference#session-lifecycle-counter-semantics) contam uma liberação, um timeout de inicialização e uma movimentação de servidor como `completed` em vez de `interrupted`, porque o runner devolveu o slot de forma limpa. Espere essa diferença se você comparar recibos de hook com os contadores.200Se você comparar recibos de hook com os [contadores de ciclo de vida da sessão](/docs/pt/self-hosted-environments-reference#session-lifecycle-counter-semantics), espere que alguns recibos `interrupted` contem como `completed` ali. Os contadores contam uma liberação, um timeout de inicialização, uma movimentação de servidor e um arquivamento ou exclusão que a verificação periódica do runner detectou primeiro como `completed`, porque o runner devolveu o slot de forma limpa.

166 201

167O status de saída do hook nunca afeta o resultado da sessão; uma falha é registrada e ignorada. O runner aguarda até `--post-session-hook-timeout-sec`, 60 segundos por padrão, em cada fim de sessão incluindo shutdown do runner. Este exemplo salva trabalho não confirmado para um branch de resgate:202O status de saída do hook nunca afeta o resultado da sessão; uma falha é registrada e ignorada. O runner aguarda até `--post-session-hook-timeout-sec`, 60 segundos por padrão, em cada fim de sessão incluindo shutdown do runner. Este exemplo salva trabalho não confirmado para um branch de resgate:

168 203

169```bash theme={null}204```bash theme={null}

170#!/usr/bin/env bash205#!/usr/bin/env bash

171set -u206set -u

207export GIT_ALLOW_PROTOCOL=${GIT_ALLOW_PROTOCOL:-https:http:ssh}

172IFS=':'208IFS=':'

173# -c overrides beat repo-local settings, blocking session-written fsmonitor,209# -c overrides beat repo-local settings, blocking session-written fsmonitor,

174# hook-path, and gpg-program config from executing code with the hook's210# hook-path, and gpg-program config from executing code with the hook's

175# privileges. -c commit.gpgsign=false also leaves these rescue commits211# privileges. -c commit.gpgsign=false also leaves these rescue commits

176# unsigned under --configure-git.212# unsigned under --configure-git.

177# Repo-local credential.helper and pushurl still apply, and on a runner213# Repo-local credential.helper and pushurl still apply, and on a runner

178# before v2.1.280 so does core.sshCommand; if the hook holds credentials214# before v2.1.280 so does core.sshCommand; see the note below the script

179# the session didn't, see the note below the script.215# before you give this push a credential.

180g() { git -c core.fsmonitor=false -c core.hooksPath=/dev/null \216g() { git -c core.fsmonitor=false -c core.hooksPath=/dev/null \

181 -c commit.gpgsign=false "$@"; }217 -c commit.gpgsign=false "$@"; }

182for ws in $CLAUDE_RUNNER_WORKSPACE_PATHS; do218for ws in $CLAUDE_RUNNER_WORKSPACE_PATHS; do

188done224done

189```225```

190 226

191O hook faz push com quaisquer credenciais git disponíveis em seu próprio ambiente no host do runner. Sob a [postura de sem-credenciais-na-imagem](/docs/pt/self-hosted-environments-deploy#configure-git), incluindo quando o clone integrado passa pelo proxy git Anthropic, não há nenhuma, então emita uma credencial de push de curta duração dentro do hook antes de fazer push: troque o token de sessão que o hook recebe em `CLAUDE_CODE_SESSION_ACCESS_TOKEN` com seu próprio serviço de token, verificando-o conforme [Verify session identity](/docs/pt/self-hosted-environments-identity) descreve. Quando o hook mantém uma credencial que a sessão não tinha, substitua `origin` por uma URL fornecida pelo operador e passe `-c credential.helper=` mais seu próprio helper. [Configuração do Git dentro de lifecycle hooks](#git-configuration-inside-lifecycle-hooks) descreve o que a configuração escrita pela sessão ainda pode afetar.227A linha `GIT_ALLOW_PROTOCOL` no script limita o git a remotos HTTPS, HTTP e SSH. Se o ambiente do runner já define uma lista `GIT_ALLOW_PROTOCOL` própria não vazia, o script mantém essa lista.

228

229O hook faz push com quaisquer credenciais git disponíveis em seu próprio ambiente no host do runner. Sob a [postura de sem-credenciais-na-imagem](/docs/pt/self-hosted-environments-deploy#configure-git), incluindo quando o clone integrado passa pelo proxy git Anthropic, não há nenhuma, então emita uma credencial de push de curta duração dentro do hook antes de fazer push: troque o token de sessão que o hook recebe em `CLAUDE_CODE_SESSION_ACCESS_TOKEN` com seu próprio serviço de token, verificando-o conforme [Verify session identity](/docs/pt/self-hosted-environments-identity) descreve.

230

231Trate qualquer credencial que seu hook fornece ao git como uma que uma sessão pode obter, e emita-a de modo que ela não possa fazer mais do que este push. O git em seu hook lê arquivos de configuração que uma sessão pode escrever, e um credential helper ou filter driver nomeado em um deles é executado com os privilégios do seu hook. Opções de configuração nesses arquivos também podem alterar para onde vai um push, qualquer que seja o remoto que você nomeie. Para as configurações git que o runner fixa em seu hook e as que ele deixa para esses arquivos, consulte [Configuração do Git dentro de lifecycle hooks](#git-configuration-inside-lifecycle-hooks).

192 232

193<h4 id="hook-timing-when-the-runner-releases-a-session">233<h4 id="hook-timing-when-the-runner-releases-a-session">

194 Hook timing when the runner releases a session234 Hook timing when the runner releases a session

264| `CLAUDE_RUNNER_ORDER_ID` | Chave de idempotência opaca, única por solicitação de spawn e segura para nomes de recursos Kubernetes. Use apenas o ID de ordem como sua chave de dedup do provisionador. |304| `CLAUDE_RUNNER_ORDER_ID` | Chave de idempotência opaca, única por solicitação de spawn e segura para nomes de recursos Kubernetes. Use apenas o ID de ordem como sua chave de dedup do provisionador. |

265| `CLAUDE_RUNNER_SESSION_ID` | A sessão para a qual esta solicitação é. Ela se repete em cada re-solicitação para a sessão, então use-a para logging e roteamento, não como chave de dedup. Vazio para solicitações de pré-aquecimento, que inicializam um runner em standby antes de qualquer sessão específica quando [`--min-idle`](/docs/pt/self-hosted-environments-reference#orchestrator-cli-flags) está definido, então não assuma que a variável está definida. |305| `CLAUDE_RUNNER_SESSION_ID` | A sessão para a qual esta solicitação é. Ela se repete em cada re-solicitação para a sessão, então use-a para logging e roteamento, não como chave de dedup. Vazio para solicitações de pré-aquecimento, que inicializam um runner em standby antes de qualquer sessão específica quando [`--min-idle`](/docs/pt/self-hosted-environments-reference#orchestrator-cli-flags) está definido, então não assuma que a variável está definida. |

266| `CLAUDE_RUNNER_SESSION_UUID` | O mesmo ID da sessão na forma UUID canônica. Vazio para solicitações de pré-aquecimento. |306| `CLAUDE_RUNNER_SESSION_UUID` | O mesmo ID da sessão na forma UUID canônica. Vazio para solicitações de pré-aquecimento. |

267| `CLAUDE_RUNNER_ATTEMPT` | Quantas solicitações de spawn esta sessão teve. `0` para solicitações de pré-aquecimento. |307| `CLAUDE_RUNNER_ATTEMPT` | Um contador por sessão para usar em logging. Não é uma contagem de novas tentativas nem uma contagem de solicitações. `0` para solicitações de pré-aquecimento, embora uma solicitação para uma sessão também possa carregar `0`. |

268| `CLAUDE_RUNNER_ORDER_SERVER_TIME` | Hora do servidor do cabeçalho HTTP `Date` da resposta de poll. Quando o hook verifica o `exp` do JWT da ordem de trabalho, compare contra este valor em vez do relógio local para tolerar skew. Vazio quando o gateway omitiu o cabeçalho. |308| `CLAUDE_RUNNER_ORDER_SERVER_TIME` | Hora do servidor do cabeçalho HTTP `Date` da resposta de poll. Quando o hook verifica o `exp` do JWT da ordem de trabalho, compare contra este valor em vez do relógio local para tolerar skew. Vazio quando o gateway omitiu o cabeçalho. |

270| `CLAUDE_RUNNER_ACCOUNT_ID` | ID marcado da conta que enfileirou a sessão, para roteamento por conta, quota ou chargeback. Vazio quando indisponível, e sempre vazio para sessões do canal Claude Tag, que nenhuma conta enfileira. |310| `CLAUDE_RUNNER_ACCOUNT_ID` | ID marcado da conta que enfileirou a sessão, para roteamento por conta, quota ou chargeback. Vazio quando indisponível, e sempre vazio para sessões do canal Claude Tag, que nenhuma conta enfileira. |

271| `CLAUDE_RUNNER_ACCOUNT_EMAIL` | Email da conta que enfileirou a sessão. Vazio quando indisponível. Trate o email como informação de identificação pessoal e não o registre. |311| `CLAUDE_RUNNER_ACCOUNT_EMAIL` | Email da conta que enfileirou a sessão. Vazio quando indisponível. Trate o email como informação de identificação pessoal e não o registre. |

272| `CLAUDE_RUNNER_PRIMARY_REPO_URL` | URL da primeira fonte git da sessão, para roteamento para um runner com esse repositório pré-aquecido. Vazio quando a sessão não tem fontes git. |312| `CLAUDE_RUNNER_PRIMARY_REPO_URL` | URL da primeira fonte git da sessão, para roteamento para um runner com esse repositório pré-aquecido. Vazio quando a sessão não tem fontes git. |

273| `CLAUDE_RUNNER_PRIMARY_REPO_REVISION` | Revisão da primeira fonte git da sessão: branch, SHA ou tag. Vazio quando não especificado. |313| `CLAUDE_RUNNER_PRIMARY_REPO_REVISION` | Revisão da primeira fonte git da sessão: branch, SHA, tag ou nome completo da referência. Vazio quando não especificado. |

274| `CLAUDE_RUNNER_REPO_SOURCES` | Array JSON de `{url, revision}` para todas as fontes git da sessão, para hooks que roteiam em um repositório secundário. Vazio quando não há fontes. |314| `CLAUDE_RUNNER_REPO_SOURCES` | Array JSON de `{url, revision}` para todas as fontes git da sessão, para hooks que roteiam em um repositório secundário. Vazio quando não há fontes. |

275| `CLAUDE_RUNNER_CORRELATION_ID` | O ID de correlação fornecido na criação da sessão, ecoado de volta para que o hook possa mapear esta ordem de trabalho para a solicitação que criou a sessão. Vazio quando a sessão não tem nenhum. |315| `CLAUDE_RUNNER_CORRELATION_ID` | O ID de correlação fornecido na criação da sessão, ecoado de volta para que o hook possa mapear esta ordem de trabalho para a solicitação que criou a sessão. Vazio quando a sessão não tem nenhum. |

276| `CLAUDE_RUNNER_CLIENT_PLATFORM` | A superfície do cliente que criou a sessão, como `web_claude_ai`, `desktop_app`, `ios` ou `scheduled_trigger`, para análise de adoção. Não definido quando a sessão não tem superfície registrada ou reconhecida, e para solicitações de pré-aquecimento; verifique-o com `[ -n "${CLAUDE_RUNNER_CLIENT_PLATFORM:-}" ]`, que permanece seguro sob `set -u`. |316| `CLAUDE_RUNNER_CLIENT_PLATFORM` | A superfície do cliente que criou a sessão, como `web_claude_ai`, `desktop_app`, `ios` ou `scheduled_trigger`, para análise de adoção. Não definido quando a sessão não tem superfície registrada ou reconhecida, e para solicitações de pré-aquecimento; verifique-o com `[ -n "${CLAUDE_RUNNER_CLIENT_PLATFORM:-}" ]`, que permanece seguro sob `set -u`. |

282* **Use `--capacity 1` em runners gerados**: uma ordem de trabalho vinculada a sessão registra exatamente um runner vinculado a essa sessão, então uma capacidade maior adiciona slots que nunca recebem trabalho, e o runner registra um aviso na inicialização.322* **Use `--capacity 1` em runners gerados**: uma ordem de trabalho vinculada a sessão registra exatamente um runner vinculado a essa sessão, então uma capacidade maior adiciona slots que nunca recebem trabalho, e o runner registra um aviso na inicialização.

283* **Ordens de trabalho de pré-aquecimento registram desvinculadas**: o runner em standby não está vinculado a uma sessão e reclama trabalho enfileirado como um runner de frota fixa.323* **Ordens de trabalho de pré-aquecimento registram desvinculadas**: o runner em standby não está vinculado a uma sessão e reclama trabalho enfileirado como um runner de frota fixa.

284 324

285O contrato tem quatro regras agnósticas do provisionador:325O contrato tem quatro regras, qualquer que seja a plataforma em que seu hook provisiona:

286 326

2871. **Seja idempotente em `CLAUDE_RUNNER_ORDER_ID`.** Reentrega da mesma solicitação deve gerar no máximo um runner. Derive um nome de recurso determinístico do ID de ordem e deixe sua plataforma rejeitar a duplicata. Não use `CLAUDE_RUNNER_SESSION_ID` como chave. Cada re-solicitação para uma sessão carrega o mesmo ID de sessão com um novo ID de ordem, então uma carga de trabalho nomeada ou deduplicada pelo ID de sessão é criada uma vez e nunca novamente para essa sessão.3271. **Seja idempotente em `CLAUDE_RUNNER_ORDER_ID`.** Reentrega da mesma solicitação deve gerar no máximo um runner. Derive um nome de recurso determinístico do ID de ordem e deixe sua plataforma rejeitar a duplicata. Não use `CLAUDE_RUNNER_SESSION_ID` como chave. Cada re-solicitação para uma sessão carrega o mesmo ID de sessão com um novo ID de ordem, então uma carga de trabalho nomeada ou deduplicada pelo ID de sessão é criada uma vez e nunca novamente para essa sessão.

2882. **Não tente novamente a carga de trabalho.** Um ID de ordem significa no máximo uma carga de trabalho criada. Se o runner nunca se registra, Anthropic re-solicita com um ID de ordem fresco após `--expected-spawn-seconds`.3282. **Não tente novamente a carga de trabalho.** Um ID de ordem significa no máximo uma carga de trabalho criada. Se o runner nunca se registra, Anthropic re-solicita com um ID de ordem fresco após `--expected-spawn-seconds`.

2893. **Use o contrato de código de saída.** Saída 0 significa submetido. Saída 1 significa falha retentável; a sessão recua e é re-oferecida. Saída 2 ou superior significa não-retentável; a sessão é bloqueada de gerar novamente até um [Owner](/docs/pt/cloud-environments#organization-shared-environments) selecionar **Retry** nela na aba **Activity** do ambiente. Em saída diferente de zero, a cauda do stderr do hook aparece lá como o motivo da falha, então escreva o erro acionável para stderr e nunca segredos. Para uma solicitação de pré-aquecimento não há sessão para falhar: o orquestrador registra uma saída diferente de zero localmente apenas, e o servidor re-solicita o spawn após a concessão.3293. **Use o contrato de código de saída.** Saia com o status que corresponde ao resultado:

2904. **Defina `--expected-spawn-seconds` para pelo menos seu tempo de boot p99.** Esta é a concessão no lado do servidor. Todas as réplicas do orquestrador devem usar o mesmo valor.330

331 * **Saída 0**: submetido.

332 * **Saída 1**: falha retentável. A sessão recua e é re-oferecida.

333 * **Saída 2 ou superior**: falha não-retentável. A sessão é bloqueada de gerar novamente até que um usuário envie uma nova mensagem a ela ou um [Owner](/docs/pt/cloud-environments#organization-shared-environments) selecione **Retry** nela na aba **Activity** do ambiente.

334

335 Em saída diferente de zero, a cauda do stderr do hook aparece na aba **Activity** como o motivo da falha, então escreva o erro acionável para stderr e nunca escreva segredos lá. Em um hook de shell, [mantenha falhas transitórias retentáveis](#keep-transient-failures-retryable-in-a-shell-hook).

336

337 Uma solicitação de pré-aquecimento não tem sessão para falhar: o orquestrador registra uma saída diferente de zero localmente apenas, e o servidor re-solicita o spawn após a concessão de `--expected-spawn-seconds` expirar.

3384. **Defina `--expected-spawn-seconds` para pelo menos seu tempo p99 desde a solicitação de spawn até o registro do runner.** Meça a partir do momento em que o orquestrador recebe a solicitação de spawn e inclua qualquer espera por capacidade na sua plataforma, além do tempo de boot. Este valor é a concessão no lado do servidor, e a ordem de trabalho expira com ela, então um runner cuja carga de trabalho demora mais não consegue se registrar. Todas as réplicas do orquestrador devem usar o mesmo valor.

291 339

292Tudo que o hook escreve para stdout ou stderr aparece no log do orquestrador com credenciais automaticamente redatadas. Se sessões ficarem enfileiradas, verifique o corpo `/healthz` do orquestrador para contagens de fila, então abra a aba **Activity** do seu ambiente na [página de administração **Cloud environments**](https://claude.ai/admin-settings/cloud-environments): expanda uma sessão falhada lá para seu erro de spawn e selecione **Retry** para re-solicitá-la.340Tudo que o hook escreve para stdout ou stderr aparece no log do orquestrador com credenciais automaticamente redatadas. Se sessões ficarem enfileiradas, verifique o corpo `/healthz` do orquestrador para contagens de fila, então abra a aba **Activity** do seu ambiente na [página de administração **Cloud environments**](https://claude.ai/admin-settings/cloud-environments): expanda uma sessão falhada lá para seu erro de spawn e selecione **Retry** para re-solicitá-la.

293 341

294Uma sessão que fica enfileirada sem erro de spawn na aba **Activity** pode significar que o hook está usando a chave do ID de sessão. Para confirmar, verifique se sua plataforma tem uma carga de trabalho para a primeira solicitação de spawn dessa sessão e nenhuma para as re-solicitações. Se for assim, use `CLAUDE_RUNNER_ORDER_ID` como chave da carga de trabalho.342Uma sessão que fica enfileirada sem erro de spawn na aba **Activity** pode significar que o hook está usando a chave do ID de sessão. Para confirmar, verifique se sua plataforma tem uma carga de trabalho para a primeira solicitação de spawn dessa sessão e nenhuma para as re-solicitações. Se for assim, use `CLAUDE_RUNNER_ORDER_ID` como chave da carga de trabalho.

295 343

344<h4 id="keep-transient-failures-retryable-in-a-shell-hook">

345 Mantenha falhas transitórias retentáveis em um hook de shell

346</h4>

347

348Em um hook de shell que usa `set -e`, uma falha que uma nova tentativa poderia ter resolvido pode bloquear a sessão. O hook para no comando que falhou e sai com o próprio status desse comando, e o orquestrador aplica o contrato de código de saída a esse status. Muitas falhas retornam um status de 2 ou superior, como `127` quando um comando não está instalado e `22` de `curl --fail` em um erro HTTP, então elas bloqueiam a sessão na sua primeira falha.

349

350Uma sessão que o hook já bloqueou permanece bloqueada até que um usuário envie uma nova mensagem a ela ou um [Owner](/docs/pt/cloud-environments#organization-shared-environments) selecione **Retry** nela na aba **Activity** do ambiente.

351

352Para transformar essa falha em saída 1, coloque estas linhas diretamente abaixo da linha `#!` do hook, acima de qualquer coisa que possa falhar:

353

354```bash theme={null}

355set -e

356PERMANENT=; permanent() { printf '%s\n' "$*" >&2; PERMANENT=1; exit 2; }

357trap 'rc=$?; [ "$rc" -eq 0 ] || [ -n "${PERMANENT:-}" ] || exit 1' EXIT

358```

359

360Estas linhas mudam como o restante do hook se comporta, então verifique-o quanto a cada um destes padrões depois de adicioná-las:

361

362* **`exit 2` ou superior isolado**: com o trap definido, ele se torna saída 1. Para um erro que nenhuma nova tentativa pode corrigir, chame `permanent` com o motivo, como `permanent "namespace claude-runners does not exist"`. Chame-o no shell principal, não dentro de `$( )`, `( )` ou de um pipe.

363* **`exec`**: não inicie o último comando do hook com `exec`, porque `exec` substitui o shell e o trap não é executado.

364* **Segundo trap `EXIT`**: um segundo `trap ... EXIT` substitui o primeiro, então mescle os dois em um único trap. Coloque seus comandos de limpeza diretamente após `rc=$?;` e termine cada um com `|| true;`. A limpeza então é executada tanto em caso de falha quanto de sucesso, e um comando de limpeza que falha não define o status de saída do hook. Este trap mesclado mostra o formato, com `your-cleanup-command` representando o seu próprio comando:

365

366 ```bash theme={null}

367 trap 'rc=$?; your-cleanup-command || true; [ "$rc" -eq 0 ] || [ -n "${PERMANENT:-}" ] || exit 1' EXIT

368 ```

369* **Comandos que podem falhar**: se o hook não usava `set -e` antes, agora ele para no primeiro comando que retorna diferente de zero, como uma consulta que não encontra nada ou uma submissão duplicada que sua plataforma rejeita. Se o hook age com base no resultado, faça desse comando a condição de um `if`. Se ele ignora o resultado, siga o comando com `|| true`.

370

371Para confirmar que o trap funciona, adicione uma linha diretamente abaixo da linha `trap` que chama um comando que não existe, como `no-such-command`. Execute o arquivo do hook a partir do seu shell e verifique se `echo $?` imprime `1`, depois remova a linha.

372

296<h2 id="send-model-requests-to-bedrock-or-agent-platform">373<h2 id="send-model-requests-to-bedrock-or-agent-platform">

297 Enviar requisições de modelo para Bedrock ou Agent Platform374 Enviar requisições de modelo para Bedrock ou Agent Platform

298</h2>375</h2>

381Uma sessão que envia requisições de modelo para o Amazon Bedrock ou para o Agent Platform do Google Cloud difere de uma sessão na API da Anthropic das seguintes maneiras:458Uma sessão que envia requisições de modelo para o Amazon Bedrock ou para o Agent Platform do Google Cloud difere de uma sessão na API da Anthropic das seguintes maneiras:

382 459

383* **Políticas do claude.ai**: as [configurações gerenciadas pelo servidor](/docs/pt/server-managed-settings) não chegam a essas sessões. Também não chegam as políticas da organização que um Owner define nas configurações de administração do Claude Code, portanto o Claude Code não as aplica dentro da sessão. Coloque as regras das quais você depende no [arquivo de configurações gerenciadas](/docs/pt/managed-settings#delivery-mechanisms) da imagem do runner.460* **Políticas do claude.ai**: as [configurações gerenciadas pelo servidor](/docs/pt/server-managed-settings) não chegam a essas sessões. Também não chegam as políticas da organização que um Owner define nas configurações de administração do Claude Code, portanto o Claude Code não as aplica dentro da sessão. Coloque as regras das quais você depende no [arquivo de configurações gerenciadas](/docs/pt/managed-settings#delivery-mechanisms) da imagem do runner.

461* **Skills da conta**: essas sessões não baixam as skills ativadas para a conta do claude.ai de uma pessoa. Consulte [Como a configuração de cada sessão é montada](#how-each-session’s-config-is-assembled).

384* **Arquivos**: os arquivos que as pessoas anexam a uma sessão no claude.ai ou no aplicativo móvel ou desktop não chegam a ela, e o Claude não pode enviar arquivos de volta com a [ferramenta `SendUserFile`](/docs/pt/tools-reference). Em vez disso, coloque os arquivos de entrada no repositório ou no runner.462* **Arquivos**: os arquivos que as pessoas anexam a uma sessão no claude.ai ou no aplicativo móvel ou desktop não chegam a ela, e o Claude não pode enviar arquivos de volta com a [ferramenta `SendUserFile`](/docs/pt/tools-reference). Em vez disso, coloque os arquivos de entrada no repositório ou no runner.

385* **Seleção de modelo**: o plano de controle da Anthropic envia o modelo de cada sessão e, quando uma sessão é iniciada sem um, o Claude Code usa o seu padrão para o provedor. O runner remove `ANTHROPIC_MODEL` e `ANTHROPIC_DEFAULT_MODEL` do ambiente que passa às sessões. Os exemplos das páginas dos provedores definem `ANTHROPIC_MODEL`, mas no ambiente do runner nenhuma das duas variáveis tem efeito. As variáveis por família em Fixar versões de modelo para o [Amazon Bedrock](/docs/pt/amazon-bedrock#4-pin-model-versions) e o [Agent Platform](/docs/pt/google-vertex-ai#5-pin-model-versions) chegam às sessões. Elas decidem para o que um alias como `opus` é resolvido, não para o que um ID de modelo completo é resolvido.463* **Seleção de modelo**: o plano de controle da Anthropic envia o modelo de cada sessão e, quando uma sessão é iniciada sem um, o Claude Code usa o seu padrão para o provedor. Não é possível escolher o modelo com `ANTHROPIC_MODEL` ou `ANTHROPIC_DEFAULT_MODEL` no ambiente do runner, mas você pode fixar para o que um alias é resolvido:

464 * **`ANTHROPIC_MODEL` e `ANTHROPIC_DEFAULT_MODEL`**: o runner as remove do ambiente que passa às sessões, embora os exemplos das páginas dos provedores definam `ANTHROPIC_MODEL`.

465 * **Variáveis de fixação por família**: as variáveis em Fixar versões de modelo para o [Amazon Bedrock](/docs/pt/amazon-bedrock#4-pin-model-versions) e o [Agent Platform](/docs/pt/google-vertex-ai#5-pin-model-versions) chegam, sim, às sessões. Elas decidem para o que um alias como `opus` é resolvido, não para o que um ID de modelo completo é resolvido.

386* **Modelos que a sua conta não disponibiliza**: uma sessão pode falhar em uma mensagem com um erro que nomeia o modelo. Ative os modelos que os seus desenvolvedores podem escolher, o modelo de segundo plano descrito em Fixar versões de modelo e o modelo classificador que o [modo auto](/docs/pt/permission-modes#enable-auto-mode-on-bedrock-agent-platform-or-foundry) usa. No Amazon Bedrock, permita cada um deles na sua política.466* **Modelos que a sua conta não disponibiliza**: uma sessão pode falhar em uma mensagem com um erro que nomeia o modelo. Ative os modelos que os seus desenvolvedores podem escolher, o modelo de segundo plano descrito em Fixar versões de modelo e o modelo classificador que o [modo auto](/docs/pt/permission-modes#enable-auto-mode-on-bedrock-agent-platform-or-foundry) usa. No Amazon Bedrock, permita cada um deles na sua política.

387* **Pesquisa na web e modo rápido**: a [pesquisa na web](/docs/pt/tools-reference#websearch-tool-behavior) não está disponível no Amazon Bedrock, e o [modo rápido](/docs/pt/fast-mode) não está disponível em nenhum dos dois provedores. Para outros recursos que variam por provedor, consulte [Recursos da CLI que variam por provedor](/docs/pt/feature-availability#cli-capabilities-that-vary-by-provider).467* **Pesquisa na web e modo rápido**: a [pesquisa na web](/docs/pt/tools-reference#websearch-tool-behavior) não está disponível no Amazon Bedrock, e o [modo rápido](/docs/pt/fast-mode) não está disponível em nenhum dos dois provedores. Para outros recursos que variam por provedor, consulte [Recursos da CLI que variam por provedor](/docs/pt/feature-availability#cli-capabilities-that-vary-by-provider).

388 468

411 491

412As sessões herdam o ambiente do runner, então defina [`ENABLE_TOOL_SEARCH`](/docs/pt/mcp#scale-with-mcp-tool-search) lá para controlar a busca de ferramentas MCP em todas as sessões que um runner inicia; a página de MCP aborda os valores.492As sessões herdam o ambiente do runner, então defina [`ENABLE_TOOL_SEARCH`](/docs/pt/mcp#scale-with-mcp-tool-search) lá para controlar a busca de ferramentas MCP em todas as sessões que um runner inicia; a página de MCP aborda os valores.

413 493

494<a id="connection-timing" />

495

496<h3 id="wait-for-mcp-servers-before-the-first-turn">

497 Aguardar os servidores MCP antes do primeiro turno

498</h3>

499

500Uma sessão auto-hospedada aguarda brevemente pelos servidores MCP que ainda estão se conectando, em dois pontos distintos. Um servidor que perde uma espera fica com suas ferramentas ausentes quando o primeiro turno começa, e elas ficam disponíveis mais tarde sem nenhuma ação da sua parte. As duas esperas são:

501

502* **Inicialização da sessão**: antes de a lista de ferramentas ser obtida pela primeira vez, a sessão aguarda até 5 segundos por padrão por um servidor HTTP ou SSE cuja entrada define [`alwaysLoad: true`](/docs/pt/mcp#exempt-a-server-from-deferral), ou por todos os servidores quando você define [`MCP_CONNECTION_NONBLOCKING=0`](/docs/pt/env-vars) no ambiente do runner. Caso contrário, os servidores HTTP e SSE se conectam em segundo plano. Enquanto a sessão aguarda aqui, ela demora mais para inicializar. [`MCP_CONNECT_TIMEOUT_MS`](/docs/pt/env-vars) altera o padrão de 5 segundos.

503* **Primeiro turno**: depois que a mensagem chega, o primeiro turno aguarda até 2 segundos pelos servidores stdio que ainda estão se conectando. Enquanto a sessão aguarda aqui, a primeira resposta demora mais. Para alterar a duração dessa espera, defina [`CLAUDE_CODE_MCP_STARTUP_WAIT_MS`](/docs/pt/env-vars) no ambiente do runner. Isso não altera quais servidores a espera abrange. Requer o Claude Code v2.1.274 ou posterior.

504

505O `claude mcp add` não tem uma flag `alwaysLoad`. Para definir a chave, adicione o servidor com `claude mcp add-json`, que a recebe no JSON do servidor e a grava em `.claude.json`. No seu Dockerfile:

506

507```dockerfile theme={null}

508RUN claude mcp add-json core '{"type":"http","url":"https://mcp.example.com/mcp","alwaysLoad":true}' --scope user

509```

510

511Se as ferramentas de um servidor também não aparecerem nos turnos seguintes, verifique se o servidor chegou à sessão, conforme descrito em [Servidores MCP](#mcp-servers).

512

414<h3 id="turn-off-built-in-session-tools">513<h3 id="turn-off-built-in-session-tools">

415 Desativar as ferramentas de sessão integradas514 Desativar as ferramentas de sessão integradas

416</h3>515</h3>

571 670

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

573 672

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

674

675* **Configurações de projeto**: um `.claude/settings.json` com commit no repositório se sobrepõe à linha de base de nível de usuário. Em uma sessão com vários repositórios, [no máximo o arquivo de um repositório tem efeito](#repository-settings-in-sessions-with-several-repositories).

676* **Configurações gerenciadas**: as sessões leem [`managed-settings.json`](/docs/pt/settings#where-settings-live) do caminho de sistema padrão em sua imagem do runner. Para saber se suas chaves se aplicam ao lado de [server-managed settings](/docs/pt/server-managed-settings), consulte [como Claude Code combina fontes gerenciadas](/docs/pt/managed-settings#how-claude-code-combines-managed-sources).

677

678Para a ordem em que essas fontes se aplicam, consulte [settings precedence](/docs/pt/settings#settings-precedence).

575 679

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

577 681

579* **Quem os autora**: o plano de controle popula os scripts de constantes fixas em sua própria implantação, nunca de entrada por sessão ou de terceiros.683* **Quem os autora**: o plano de controle popula os scripts de constantes fixas em sua própria implantação, nunca de entrada por sessão ou de terceiros.

580* **O que ainda os governa**: hooks entregues através de `--settings` entram na configuração de hook mesclada ordinária, não na camada gerenciada, então suas configurações gerenciadas ainda se aplicam. `disableAllHooks` os desabilita, e eles não estão entre as categorias que [`allowManagedHooksOnly`](/docs/pt/settings-reference#allowmanagedhooksonly) mantém carregadas.684* **O que ainda os governa**: hooks entregues através de `--settings` entram na configuração de hook mesclada ordinária, não na camada gerenciada, então suas configurações gerenciadas ainda se aplicam. `disableAllHooks` os desabilita, e eles não estão entre as categorias que [`allowManagedHooksOnly`](/docs/pt/settings-reference#allowmanagedhooksonly) mantém carregadas.

581 685

686Quando uma pessoa inicia sua própria sessão, o Claude Code também baixa as [skills habilitadas para sua conta claude.ai](/docs/pt/skills#skills-in-cowork-and-cloud-sessions) no diretório de configuração dessa sessão. Uma execução de [rotina](/docs/pt/routines) não recebe as skills de seu proprietário, e uma sessão que [envia requisições de modelo para Bedrock ou Agent Platform](#send-model-requests-to-bedrock-or-agent-platform) não baixa nenhuma. Para uma skill de que essas sessões precisem, faça commit dela no `.claude/skills/` do repositório ou adicione-a à sua imagem do runner.

687

582Fora das sessões do [Claude Tag](https://claude.com/docs/claude-tag/overview), uma sessão em um ambiente auto-hospedado é executada com a [memória automática](/docs/pt/memory#auto-memory) desativada por padrão. Para instruções que devem persistir entre sessões, use o `CLAUDE.md` em sua imagem do runner ou no repositório.688Fora das sessões do [Claude Tag](https://claude.com/docs/claude-tag/overview), uma sessão em um ambiente auto-hospedado é executada com a [memória automática](/docs/pt/memory#auto-memory) desativada por padrão. Para instruções que devem persistir entre sessões, use o `CLAUDE.md` em sua imagem do runner ou no repositório.

583 689

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

self-hosted-environments-deploy.md +135 −18

Details

20 20

21* **Contêineres efêmeros por sessão**: execute cada processo runner em um contêiner ou VM fresco que é destruído quando o processo sai, com `--capacity 1` e o padrão `--drain-grace-sec 0` para que cada contêiner sirva exatamente uma sessão. Em uma capacidade mais alta, ou com uma graça de drenagem positiva, um contêiner serve múltiplas sessões do mesmo [owner bloqueado](/docs/pt/self-hosted-environments#key-concepts); consulte [Ciclo de vida do Runner](/docs/pt/self-hosted-environments#runner-lifecycle). Não reutilize um sistema de arquivos entre reinicializações do runner, exceto na configuração deliberada de [checkout pré-aquecido](#reuse-a-pre-warmed-checkout), e nunca entre owners.21* **Contêineres efêmeros por sessão**: execute cada processo runner em um contêiner ou VM fresco que é destruído quando o processo sai, com `--capacity 1` e o padrão `--drain-grace-sec 0` para que cada contêiner sirva exatamente uma sessão. Em uma capacidade mais alta, ou com uma graça de drenagem positiva, um contêiner serve múltiplas sessões do mesmo [owner bloqueado](/docs/pt/self-hosted-environments#key-concepts); consulte [Ciclo de vida do Runner](/docs/pt/self-hosted-environments#runner-lifecycle). Não reutilize um sistema de arquivos entre reinicializações do runner, exceto na configuração deliberada de [checkout pré-aquecido](#reuse-a-pre-warmed-checkout), e nunca entre owners.

22 * <span id="processes-a-stopped-session-leaves" />Quando o runner interrompe uma sessão, ele não envia nenhum sinal para um processo que ainda esteja em execução depois que seu comando shell foi encerrado, como um serviço que foi daemonizado. Destruir o contêiner ou a VM encerra esse processo.22 * <span id="processes-a-stopped-session-leaves" />Quando o runner interrompe uma sessão, ele não envia nenhum sinal para um processo que ainda esteja em execução depois que seu comando shell foi encerrado, como um serviço que foi daemonizado. Destruir o contêiner ou a VM encerra esse processo.

23* **Sem credenciais amplas na imagem**: não inclua chaves SSH de longa duração, credenciais de provedor de nuvem ou tokens de acesso pessoal que concedem mais do que uma sessão precisa. Crie credenciais usadas durante uma sessão, como tokens de push ou API, por sessão a partir de seu [script wrapper](/docs/pt/self-hosted-environments-configuration#wrapper-scripts). Para o clone inicial, que acontece antes do wrapper ser executado, use um [hook de ciclo de vida `checkout`](/docs/pt/self-hosted-environments-configuration#checkout) ou [`--use-anthropic-git-proxy`](#use-the-anthropic-git-proxy); consulte [Configurar git](#configure-git).23* **Sem credenciais amplas na imagem**: não inclua chaves SSH de longa duração, credenciais de provedor de nuvem ou tokens de acesso pessoal que concedem mais do que uma sessão precisa. Crie credenciais usadas durante uma sessão, como tokens de push ou API, por sessão a partir de seu [script wrapper](/docs/pt/self-hosted-environments-configuration#wrapper-scripts). O clone inicial acontece antes do wrapper ser executado, então trate-o com um [hook de ciclo de vida `checkout`](/docs/pt/self-hosted-environments-configuration#checkout), ou com [`--use-anthropic-git-proxy`](#use-the-anthropic-git-proxy) quando todos os repositórios de uma sessão estiverem no github.com. Para ambos, consulte [Configurar git](#configure-git).

24* **Mantenha as credenciais GitHub do host longe das sessões**: Claude pode usar qualquer credencial GitHub que uma sessão consiga ler, com qualquer acesso que essa credencial conceda. Mantenha as próprias credenciais GitHub de escopo amplo do host runner fora de qualquer coisa que uma sessão possa ler. Tal credencial pode ser um token de acesso pessoal, o token que `gh auth login` salva para sua conta, ou um `GH_TOKEN` no ambiente do runner.

25 * **Com [git gerenciado pela Anthropic](#use-the-anthropic-git-proxy)**: com tal credencial, Claude acessa o GitHub diretamente em vez de passar pelo git gerenciado pela Anthropic.

26 * **Sem git gerenciado pela Anthropic**: uma credencial de clone pode permanecer na imagem se você restringir seu escopo tanto quanto [Incluir a configuração do git em sua imagem](#ship-git-config-in-your-image) descreve.

24* **Mantenha o segredo do ambiente fora dos hosts que executam sessões**: o segredo do ambiente pode registrar runners e pegar qualquer sessão enfileirada no ambiente. Em uma frota fixa, ele vive em cada host runner, onde o código de qualquer sessão pode ler o arquivo secreto. Prefira [runners sob demanda](/docs/pt/self-hosted-environments-configuration#on-demand-runners), onde o segredo fica no host do orquestrador, que nunca executa código do usuário, e cada runner recebe uma ordem de trabalho de uso único que registra exatamente um runner. Em uma frota fixa, trate o arquivo environment-secret como legível por cada sessão e gire o segredo após qualquer suspeita de comprometimento de sessão.27* **Mantenha o segredo do ambiente fora dos hosts que executam sessões**: o segredo do ambiente pode registrar runners e pegar qualquer sessão enfileirada no ambiente. Em uma frota fixa, ele vive em cada host runner, onde o código de qualquer sessão pode ler o arquivo secreto. Prefira [runners sob demanda](/docs/pt/self-hosted-environments-configuration#on-demand-runners), onde o segredo fica no host do orquestrador, que nunca executa código do usuário, e cada runner recebe uma ordem de trabalho de uso único que registra exatamente um runner. Em uma frota fixa, trate o arquivo environment-secret como legível por cada sessão e gire o segredo após qualquer suspeita de comprometimento de sessão.

25* **Saída de rede padrão-negar**: restrinja o tráfego de saída do contêiner runner e sessão no seu próprio limite de rede em cada ambiente; [Saída padrão-negar](#default-deny-egress) cobre o que permitir e por quê.28* **Saída de rede padrão-negar**: restrinja o tráfego de saída do contêiner runner e sessão no seu próprio limite de rede em cada ambiente; [Saída padrão-negar](#default-deny-egress) cobre o que permitir e por quê.

26* **IAM de host com privilégio mínimo**: a identidade de computação anexada ao host runner, como um perfil de instância ou conta de serviço de nó, deve conceder apenas o que o próprio runner precisa. As sessões devem obter suas próprias credenciais através de seu script wrapper em vez de herdar a do host.29* **IAM de host com privilégio mínimo**: a identidade de computação anexada ao host runner, como um perfil de instância ou conta de serviço de nó, deve conceder apenas o que o próprio runner precisa. As sessões devem obter suas próprias credenciais através de seu script wrapper em vez de herdar a do host.

42 O guard é executado independentemente de [`--trust-workspace`](/docs/pt/self-hosted-environments-reference#runner-cli-flags), e não cobre hooks de repositório, `.mcp.json`, ou regras Bash; consulte [Permissões e aprovação de ferramentas](/docs/pt/self-hosted-environments-configuration#permissions-and-tool-approval) para onde essas concessões pertencem.45 O guard é executado independentemente de [`--trust-workspace`](/docs/pt/self-hosted-environments-reference#runner-cli-flags), e não cobre hooks de repositório, `.mcp.json`, ou regras Bash; consulte [Permissões e aprovação de ferramentas](/docs/pt/self-hosted-environments-configuration#permissions-and-tool-approval) para onde essas concessões pertencem.

43 46

44<Note>47<Note>

45 A lista de permissões de IP de sua organização não cobre o tráfego do runner auto-hospedado por padrão. Não confie nela como um controle de rede para tráfego de runner ou sessão; aplique saída padrão-negar no seu próprio limite de rede em vez disso, e entre em contato com sua equipe de conta Anthropic se você quiser aplicação de lista de permissões de IP para sua organização.48 Se sua organização tiver a [allowlist de IP](https://support.claude.com/en/articles/13200993-restrict-access-to-claude-with-ip-allowlisting) ativada, adicione os endereços públicos de saída de seus runners e contêineres de sessão à allowlist antes de iniciá-los. Se você executar [runners sob demanda](/docs/pt/self-hosted-environments-configuration#on-demand-runners), adicione também o endereço do host do orquestrador. Não confie na allowlist como um controle de rede para tráfego de runner ou sessão. Em vez disso, aplique saída padrão-negar no seu próprio limite de rede.

46</Note>49</Note>

47 50

48<h2 id="network-requirements">51<h2 id="network-requirements">

55 58

57| :- | :- | :- |60| :- | :- | :- |

58| `api.anthropic.com` | 443, HTTPS; WSS apenas para o conector SCM | Plano de controle do runner e streaming de sessão, inferência de modelo, sinalizadores de recursos, análise de produtos, buscas de chave [JWKS](/docs/pt/self-hosted-environments-identity), assinatura de commit, o proxy git quando `--use-anthropic-git-proxy` está definido, e o túnel [conector SCM](/docs/pt/self-hosted-environments-reference#scm-connector-flags) do orquestrador quando `--scm-connector-host` está definido |61| `api.anthropic.com` | 443, HTTPS; WSS para [git gerenciado pela Anthropic](#use-the-anthropic-git-proxy) | Plano de controle do runner e streaming de sessão, inferência de modelo, sinalizadores de recursos, análise de produtos, buscas de chave [JWKS](/docs/pt/self-hosted-environments-identity), assinatura de commit e git gerenciado pela Anthropic quando `--use-anthropic-git-proxy` está definido |

59| Seu host git, como `github.com` ou seu host GitHub Enterprise | 443 ou 22 | Clonagem e push de repositórios. Não necessário se o runner usar `--use-anthropic-git-proxy`, que roteia o tráfego git através de `api.anthropic.com`. |62| Seu host git, como `github.com` ou seu host GitHub Enterprise | 443 ou 22 | Clonagem e push de repositórios em cada host git que as sessões do runner usam. Em um runner que usa [`--use-anthropic-git-proxy`](#use-the-anthropic-git-proxy), consulte [quando o caminho para `github.com` ainda é necessário](#github-com-egress-with-the-anthropic-git-proxy). |

64<span id="github-com-egress-with-the-anthropic-git-proxy" />Um runner que usa [`--use-anthropic-git-proxy`](#use-the-anthropic-git-proxy) roteia seu tráfego git de `github.com` através de `api.anthropic.com`, então ele não precisa do caminho para o host git `github.com`. Ele ainda precisa desse caminho se você definir `--push-outcome-on-release` ou fizer push a partir de um hook `post-session`.

60 65

61Se esses hosts são necessários depende de sua configuração:66Se esses hosts são necessários depende de sua configuração:

62 67

71| `browser-intake-us5-datadoghq.com` | 443 | Uploads de relatório de erro da Anthropic, enviados apenas quando [relatório de erro](/docs/pt/data-usage#telemetry-services) está habilitado para a conta da sessão. Suprimido por `DISABLE_ERROR_REPORTING=1` ou `DISABLE_TELEMETRY=1`. |76| `browser-intake-us5-datadoghq.com` | 443 | Uploads de relatório de erro da Anthropic, enviados apenas quando [relatório de erro](/docs/pt/data-usage#telemetry-services) está habilitado para a conta da sessão. Suprimido por `DISABLE_ERROR_REPORTING=1` ou `DISABLE_TELEMETRY=1`. |

72| Os endpoints do seu provedor de nuvem para requisições de modelo, consultas de modelo e renovação de credenciais, como `bedrock-runtime.us-east-1.amazonaws.com` ou `aiplatform.googleapis.com` | 443 | Apenas quando o runner [envia requisições de modelo para o Amazon Bedrock ou o Agent Platform do Google Cloud](/docs/pt/self-hosted-environments-configuration#send-model-requests-to-bedrock-or-agent-platform) |77| Os endpoints do seu provedor de nuvem para requisições de modelo, consultas de modelo e renovação de credenciais, como `bedrock-runtime.us-east-1.amazonaws.com` ou `aiplatform.googleapis.com` | 443 | Apenas quando o runner [envia requisições de modelo para o Amazon Bedrock ou o Agent Platform do Google Cloud](/docs/pt/self-hosted-environments-configuration#send-model-requests-to-bedrock-or-agent-platform) |

73 78

74O runner não alcança `statsig.anthropic.com`, `*.sentry.io`, `claude.ai`, ou `platform.claude.com`. Esses hosts aparecem em algumas listas de verificação de rede corporativa mais antigas, mas você não precisa colocá-los na lista de permissões para tráfego de runner ou sessão: as buscas de sinalizador de recurso vão para `api.anthropic.com`, e o runner se autentica com o segredo do ambiente em vez de OAuth interativo. Dois fluxos do lado do host alcançam `claude.ai`, então execute-os a partir de um host cuja saída permite, em vez de ampliar a saída do contêiner de sessão: o instalador de uma linha busca `install.sh` de `claude.ai` no tempo de instalação, e `claude auth login` interativo, que a [configuração guiada](/docs/pt/self-hosted-environments-quickstart#set-up-an-environment-and-runner), modo assinado do `doctor`, e [dispatch de CI](/docs/pt/self-hosted-environments-testing#authenticate-from-ci) usam, faz login através de `claude.ai`, `claude.com`, e `platform.claude.com`. `mcp-proxy.anthropic.com` também não é necessário: sessões auto-hospedadas não o usam, e a entrega dos conectores claude.ai de sua organização para sessões, quando habilitada para sua organização, roteia através de `api.anthropic.com`. Consulte [Servidores MCP](/docs/pt/self-hosted-environments-configuration#mcp-servers).79Você não precisa adicionar estes hosts à allowlist para tráfego de runner ou sessão:

81* **`statsig.anthropic.com`, `*.sentry.io`, `claude.ai` e `platform.claude.com`**: esses hosts aparecem em algumas listas de verificação de rede corporativa mais antigas, mas o runner não os alcança. As buscas de sinalizadores de recursos vão para `api.anthropic.com`, e o runner se autentica com o segredo do ambiente em vez de OAuth interativo.

82* **`mcp-proxy.anthropic.com`**: sessões auto-hospedadas não o usam. Quando a entrega de conectores está habilitada para sua organização, os conectores claude.ai de sua organização alcançam as sessões através de `api.anthropic.com`. Consulte [Servidores MCP](/docs/pt/self-hosted-environments-configuration#mcp-servers).

84Estes fluxos do lado do host alcançam `claude.ai`, então execute-os a partir de um host cuja saída permita isso, em vez de ampliar a saída do contêiner de sessão:

86* **O instalador de uma linha**: busca `install.sh` de `claude.ai` no tempo de instalação.

87* **`claude auth login` interativo**: faz login através de `claude.ai`, `claude.com` e `platform.claude.com`. A [configuração guiada](/docs/pt/self-hosted-environments-quickstart#run-the-guided-setup), o modo com login do `doctor` e o [dispatch de CI](/docs/pt/self-hosted-environments-testing#authenticate-from-ci) o usam. O navegador com o qual você faz login também carrega as verificações de navegador da página de login do claude.ai a partir de `hcaptcha.com`, `*.hcaptcha.com` e `challenges.cloudflare.com`.

75 88

76<h3 id="default-deny-egress">89<h3 id="default-deny-egress">

77 Saída padrão-negar90 Saída padrão-negar

127* **Deixe o runner configurar git**: inicie o runner com `--configure-git` para que ele escreva a mesma identidade e configuração de assinatura de commit que as sessões hospedadas pela Anthropic usam140* **Deixe o runner configurar git**: inicie o runner com `--configure-git` para que ele escreva a mesma identidade e configuração de assinatura de commit que as sessões hospedadas pela Anthropic usam

128* **Envie configuração git em sua imagem**: defina identidade e credenciais de push você mesmo, por exemplo para fazer commit sob sua própria identidade de bot141* **Envie configuração git em sua imagem**: defina identidade e credenciais de push você mesmo, por exemplo para fazer commit sob sua própria identidade de bot

129 142

143Para repositórios em github.com, você também pode iniciar o runner com [`--use-anthropic-git-proxy`](#use-the-anthropic-git-proxy), ou definir `CLAUDE_RUNNER_USE_GIT_PROXY=1`, para pedir que a Anthropic sirva o git para as sessões do runner.

144

130Pisos de versão Git no host runner: [`--configure-git`](#let-the-runner-configure-git) a assinatura de commit SSH requer Git 2.34 ou mais recente, [`--use-anthropic-git-proxy`](#use-the-anthropic-git-proxy) requer 2.32 ou mais recente, e retomar sessões de branches enviados por [`--push-outcome-on-release`](/docs/pt/self-hosted-environments-reference#runner-cli-flags) requer 2.29 ou mais recente. Git 2.24 é suficiente se você omitir todos os três e gerenciar a identidade git você mesmo.145Pisos de versão Git no host runner: [`--configure-git`](#let-the-runner-configure-git) a assinatura de commit SSH requer Git 2.34 ou mais recente, [`--use-anthropic-git-proxy`](#use-the-anthropic-git-proxy) requer 2.32 ou mais recente, e retomar sessões de branches enviados por [`--push-outcome-on-release`](/docs/pt/self-hosted-environments-reference#runner-cli-flags) requer 2.29 ou mais recente. Git 2.24 é suficiente se você omitir todos os três e gerenciar a identidade git você mesmo.

131 146

132<h3 id="let-the-runner-configure-git">147<h3 id="let-the-runner-configure-git">

138* `user.name = Claude` e `user.email = noreply@anthropic.com`, correspondendo às sessões hospedadas pela Anthropic153* `user.name = Claude` e `user.email = noreply@anthropic.com`, correspondendo às sessões hospedadas pela Anthropic

139* Assinatura de commit e tag em formato SSH, roteada através de um shim gerenciado pelo runner que assina cada commit através do serviço de assinatura da Anthropic usando as credenciais da própria sessão. As assinaturas são verificáveis no GitHub contra a chave de assinatura SSH publicada da Anthropic.154* Assinatura de commit e tag em formato SSH, roteada através de um shim gerenciado pelo runner que assina cada commit através do serviço de assinatura da Anthropic usando as credenciais da própria sessão. As assinaturas são verificáveis no GitHub contra a chave de assinatura SSH publicada da Anthropic.

140* `push.negotiate = true`, para que git pergunte ao seu host git quais commits ele já possui antes de empacotar um push. Requer Claude Code v2.1.257 ou posterior.155* `push.negotiate = true`, para que git pergunte ao seu host git quais commits ele já possui antes de empacotar um push. Requer Claude Code v2.1.257 ou posterior.

141* `core.hooksPath` apontando para um diretório de hooks gerenciado pelo runner. Seus hooks `commit-msg` e `prepare-commit-msg` adicionam um trailer `Co-authored-by:` para o criador da sessão a cada commit, construído a partir do email em [`CCR_SESSION_ACCOUNT_EMAIL`](/docs/pt/self-hosted-environments-configuration#wrapper-scripts) e omitido quando essa variável não está definida. Se sua imagem já define `core.hooksPath`, o runner deixa sua configuração no lugar, pula a instalação desses hooks e imprime um aviso `[runner:git]`.156* `core.hooksPath` apontando para um diretório de hooks gerenciado pelo runner. Seus hooks `commit-msg` e `prepare-commit-msg` adicionam um trailer `Co-authored-by:` para o criador da sessão a cada commit. O trailer é construído a partir do email em [`CCR_SESSION_ACCOUNT_EMAIL`](/docs/pt/self-hosted-environments-configuration#wrapper-scripts) e omitido quando essa variável não está definida. Se sua imagem já define `core.hooksPath` e o runner não usa [git gerenciada pela Anthropic](#use-the-anthropic-git-proxy), o runner mantém sua configuração, pula a instalação desses hooks e imprime um aviso `[runner:git]`.

142 157

143A assinatura de commit requer git 2.34 ou mais recente; o runner verifica na inicialização e sai com um erro se seu git for mais antigo. Este sinalizador não configura credenciais de push, que você ainda fornece na imagem.158A assinatura de commit requer git 2.34 ou mais recente; o runner verifica na inicialização e sai com um erro se seu git for mais antigo. Este sinalizador não configura credenciais de push, que você ainda fornece na imagem.

144 159

145Em um runner na v2.1.280 ou posterior, os commits que você faz a partir de um hook de ciclo de vida `checkout` ou `post-session` também são assinados como a sessão, sem o trailer `Co-authored-by:`. [Configuração git dentro de hooks de ciclo de vida](/docs/pt/self-hosted-environments-configuration#git-configuration-inside-lifecycle-hooks) descreve as configurações git que o runner fixa dentro desses hooks.160Em um runner na v2.1.280 ou posterior, os commits que você faz a partir de um hook de ciclo de vida `checkout` ou `post-session` também são assinados como a sessão, sem o trailer `Co-authored-by:`. [Configuração git dentro de hooks de ciclo de vida](/docs/pt/self-hosted-environments-configuration#git-configuration-inside-lifecycle-hooks) descreve as configurações git que o runner fixa dentro desses hooks.

146 161

162Com ou sem `--configure-git`, o Claude Code instrui o Claude a terminar suas mensagens de commit com um trailer `Claude-Session: <url>` e suas descrições de pull request com a URL da sessão. Para omitir ambos, defina [`attribution.sessionUrl`](/docs/pt/settings-reference#attribution-sessionurl) como `false` no [`~/.claude/settings.json`](/docs/pt/self-hosted-environments-configuration#how-each-session’s-config-is-assembled) do host runner e, em seguida, reinicie o runner.

163

147<h3 id="ship-git-config-in-your-image">164<h3 id="ship-git-config-in-your-image">

148 Envie configuração git em sua imagem165 Envie configuração git em sua imagem

149</h3>166</h3>

186 Use o proxy git da Anthropic203 Use o proxy git da Anthropic

187</h3>204</h3>

188 205

189Inicie o runner com `--use-anthropic-git-proxy`, ou defina `CLAUDE_RUNNER_USE_GIT_PROXY=1`, para que ele clone através do proxy git da Anthropic, autenticado com o token de curta duração da própria sessão. Para sessões de usuário comum, o proxy usa o token OAuth do GitHub ou GitHub Enterprise armazenado para o criador da sessão; para sessões de bot e agente, ele usa o token de instalação do GitHub App de sua organização. De qualquer forma, a imagem do runner não precisa de nenhuma credencial git: sem chaves SSH, sem credential helper, sem `.netrc`. Este é o mesmo caminho de autenticação que os ambientes hospedados pela Anthropic usam.206Com o proxy git da Anthropic, também chamado de git gerenciada pela Anthropic, a imagem do runner não precisa de chaves SSH, credential helper, `.netrc` ou outras credenciais git para a própria sessão. Em vez disso, o runner pede que a Anthropic sirva o git para suas sessões. Para a sessão de um usuário que a Anthropic serve, o clone do runner e os próprios fetches e pushes da sessão passam pela Anthropic, que usa o token OAuth do GitHub armazenado para o criador da sessão. [Como a Anthropic serve git para uma sessão](#how-anthropic-serves-git-for-a-session) cobre sessões de bot e agente.

207

208O proxy git fica desativado, a menos que você [o ative](#turn-the-anthropic-git-proxy-on). Um runner que alcança seu host git com suas próprias credenciais não precisa dele, e seu git funciona com qualquer host git.

209

210Em troca, o proxy git limita o que o runner suporta e muda o que ele precisa:

211

212* **Somente github.com**: a Anthropic serve uma sessão apenas quando todos os seus repositórios estão em github.com, e o proxy git ainda não suporta GitHub Enterprise Server. Em um runner com o proxy git, uma sessão com um repositório em outro host git [falha ao iniciar](#when-anthropic-doesnt-serve-a-session).

213* **Credenciais somente para os repositórios da sessão**: a Anthropic fornece credenciais git para os repositórios que fazem parte da sessão, não para outros repositórios no mesmo host git. Um submódulo privado, uma dependência que seu gerenciador de pacotes busca com git ou um marketplace de plugins em outro repositório não recebe nenhuma credencial da Anthropic. Peça às pessoas que criam sessões que [adicionem todos os repositórios](/docs/pt/web-quickstart#start-a-task) de que uma sessão precisa ao criá-la.

214* **Somente pushes de branch**: um push que exclui um branch falha, assim como um push para qualquer outro tipo de ref, como uma tag. Para saber quais branches um push pode atualizar, consulte [Proxy do GitHub](/docs/pt/cloud-environments#github-proxy).

215* **Contas do GitHub conectadas**: a pessoa que criou uma sessão de usuário deve ter conectado o GitHub em claude.ai, ou a sessão [não inicia](#creator-has-no-github-connection).

216* **`--capacity 1`**: o proxy git requer uma sessão por processo runner, então execute mais réplicas para paralelismo. [Ative o proxy git da Anthropic](#turn-the-anthropic-git-proxy-on) lista os requisitos.

217* **Configuração git global substituída**: o runner [exclui e substitui a configuração git global](#git-proxy-replaces-global-git-config) do usuário com o qual é executado. Execute-o como um usuário dedicado ou em um contêiner.

218* **Credenciais do host para pushes do host**: o push de [`--push-outcome-on-release`](/docs/pt/self-hosted-environments-reference#runner-cli-flags) do runner e qualquer push que seu [hook `post-session`](/docs/pt/self-hosted-environments-configuration#post-session) faça ainda usam as próprias credenciais git do host runner e seu [caminho de rede até `github.com`](#github-com-egress-with-the-anthropic-git-proxy). Para essas credenciais, consulte [Envie configuração git em sua imagem](#ship-git-config-in-your-image).

219* **Decisão por sessão**: a Anthropic decide, para cada sessão no runner, se serve o git dela, e uma sessão que ela não serve falha ao iniciar. [Quando as sessões falham ao iniciar em um runner com o proxy git](#when-anthropic-doesnt-serve-a-session) cobre as causas.

220

221<span id="git-proxy-replaces-global-git-config" />

222

223<Warning>

224 Com `--use-anthropic-git-proxy` definido, o runner exclui e substitui a configuração git global do usuário com o qual é executado, e não mantém nenhum backup. Ele faz isso na inicialização e antes de cada sessão. Um login ou credential helper que você mantinha ali é perdido. As configurações que [`--configure-git`](#let-the-runner-configure-git) escreve sobrevivem. Execute o runner como um usuário dedicado ou em um contêiner, nunca como seu próprio usuário.

225</Warning>

226

227Mantenha configurações git que não são secretas, como identidade e `safe.directory`, na configuração git do sistema.

228

229<h4 id="turn-the-anthropic-git-proxy-on">

230 Ative o proxy git da Anthropic

231</h4>

232

233Antes de iniciar o runner com `--use-anthropic-git-proxy`, confirme que o host runner atende a cada um destes requisitos. O runner se recusa a iniciar quando o requisito de capacidade ou de git não é atendido:

190 234

191O proxy requer `--capacity 1` porque a URL do proxy é por sessão, e git 2.32 ou mais recente porque git mais antigo ignora o mecanismo de configuração que o proxy usa para isolar sessões uma da outra. O runner se recusa a iniciar se qualquer requisito não for atendido. Como o proxy busca do lado da Anthropic, seu host git deve ser alcançável a partir da infraestrutura da Anthropic, o mesmo requisito que as sessões hospedadas pela Anthropic têm; para um host git que é apenas roteável dentro de sua rede, use um [hook de ciclo de vida `checkout`](/docs/pt/self-hosted-environments-configuration#checkout) em vez disso. Cada processo runner lida com uma sessão por vez, então execute mais réplicas para paralelismo. Quando o proxy está habilitado, `--git-host-rewrite` e `--git-ssh-rewrite` não têm efeito: a URL do proxy aponta para `api.anthropic.com`, não seu host git.235* **Claude Code v2.1.267 ou posterior**: versões anteriores aceitam a flag, mas não relatam a solicitação para que a Anthropic sirva o git nem imprimem a linha `Registering as opted in`, então a Anthropic não serve suas sessões.

236* **`--capacity 1`, o padrão**: cada processo runner lida com uma sessão por vez, então execute mais réplicas para paralelismo.

237* **Git 2.32 ou mais recente**: git mais antigo ignora a configuração git por sessão que o runner prepara para o proxy git.

192 238

193<Warning>239<Warning>

194 As receitas [Kubernetes](#kubernetes) e [Docker Compose](#docker-compose) nesta página usam `--capacity 4`. Se você adicionar `--use-anthropic-git-proxy` ou `CLAUDE_RUNNER_USE_GIT_PROXY=1` a uma delas sem alterar a capacidade para `1`, o runner sai na inicialização toda vez que seu orquestrador o reinicia. Defina `--capacity 1` e execute mais réplicas para paralelismo. [Quando o runner sai](#when-the-runner-exits) mostra a linha que o runner imprime.240 As receitas [Kubernetes](#kubernetes) e [Docker Compose](#docker-compose) nesta página usam `--capacity 4`. Se você adicionar `--use-anthropic-git-proxy` ou `CLAUDE_RUNNER_USE_GIT_PROXY=1` a uma delas sem alterar a capacidade para `1`, o runner sai na inicialização toda vez que seu orquestrador o reinicia. Defina `--capacity 1` e execute mais réplicas para paralelismo. [Quando o runner sai](#when-the-runner-exits) mostra a linha que o runner imprime.

195</Warning>241</Warning>

196 242

197O runner também relata a aceitação à Anthropic quando se registra, imprimindo `Registering as opted in to Anthropic-managed git (--use-anthropic-git-proxy)` na inicialização. Relatar a aceitação requer Claude Code v2.1.267 ou posterior, e versões anteriores aceitam o sinalizador sem relatá-lo ou imprimir essa linha. Cada sessão em um runner aceito usa a git gerenciada pela Anthropic ou a URL do proxy por sessão. Quando uma sessão usa a URL do proxy por sessão, o runner registra uma linha `[runner:warn]` dizendo isso.243Para ativar o proxy git, adicione `--use-anthropic-git-proxy` ao comando do runner ou defina `CLAUDE_RUNNER_USE_GIT_PROXY=1` no ambiente do runner. Este comando, executado em um shell no host runner, inicia o runner do [guia de início rápido](/docs/pt/self-hosted-environments-quickstart#set-up-manually) com o proxy git ativado:

244

245```bash theme={null}

246claude self-hosted-runner --environment-secret-file '/etc/claude/environment-secret' --base-dir '<writable-dir>' --use-anthropic-git-proxy

247```

248

249Na inicialização, o runner imprime `Registering as opted in to Anthropic-managed git (--use-anthropic-git-proxy)`. A Anthropic então decide, para cada sessão nesse runner, se serve o git dela. Para cada sessão que ela serve, o runner registra uma linha `[runner:session]` contendo `governed git ACTIVE`. Se, em vez disso, uma sessão falhar ao iniciar, consulte [Quando as sessões falham ao iniciar em um runner com o proxy git](#when-anthropic-doesnt-serve-a-session).

250

251<h4 id="how-anthropic-serves-git-for-a-session">

252 Como a Anthropic serve git para uma sessão

253</h4>

254

255Para uma sessão que a Anthropic serve, o clone do runner e os próprios fetches e pushes da sessão passam pela Anthropic, autenticados com o token de curta duração da própria sessão:

256

257* **Sessões de usuário**: a Anthropic usa o token OAuth do GitHub armazenado para o criador da sessão.

258* **Sessões de bot e agente**: a Anthropic usa o token de instalação do GitHub App de sua organização.

259* **Reescritas de URL**: `--git-host-rewrite` e `--git-ssh-rewrite` não têm efeito em um repositório que o proxy git serve.

260

261<h4 id="when-anthropic-doesnt-serve-a-session">

262 Quando as sessões falham ao iniciar em um runner com o proxy git

263</h4>

264

265Em um runner iniciado com `--use-anthropic-git-proxy`, uma sessão falha ao iniciar quando a Anthropic não serve o git dela. Procure no log do runner um erro git que nomeie um endereço `api.anthropic.com` contendo `/git_proxy/`.

266

267Para cada sessão, um runner no Claude Code v2.1.267 ou posterior também registra uma linha `[runner:session]` contendo `governed git ACTIVE` quando a Anthropic serve o git da sessão, ou uma linha `[runner:warn]` contendo `the server withheld Anthropic-managed git for this session` quando não serve. Encontre a linha que você está vendo entre estes casos:

268

269* **Nem `governed git ACTIVE` nem a linha `withheld`**: um runner anterior ao Claude Code v2.1.267 não registra nenhuma das linhas, e a Anthropic não serve suas sessões. Atualize o runner para a v2.1.267 ou posterior seguindo [Fixe a versão](#pin-the-version).

270* **A linha `withheld`**: a Anthropic não serviu a sessão. Um runner que funcionava antes com o proxy git pode falhar dessa forma sem nenhuma mudança do seu lado.

271 * **Um repositório não está em github.com**: uma sessão com mesmo um único repositório em outro host git, como GitHub Enterprise Server, não é servida, incluindo seus repositórios em github.com. [Desative o proxy git da Anthropic](#turn-the-anthropic-git-proxy-off) para os runners desse ambiente.

272 * **Todos os repositórios estão em github.com**: relate a falha à [sua equipe de conta da Anthropic](#report-an-issue) com o ID da sessão da linha `withheld`. A Anthropic registra o motivo do lado dela.

273* **Uma linha contendo `remote: access denied by the git proxy`**: uma sessão que a Anthropic serve ainda pode ser recusada, por exemplo quando a política da organização nega acesso git para a sessão, ou a sessão não está autorizada para o repositório. O log do runner então mostra uma linha contendo `remote: access denied by the git proxy`, e o restante dessa linha diz o motivo.

274* <span id="creator-has-no-github-connection" />**`GitHub authentication required`**: isso aparece quando o criador da sessão não tem uma conexão funcional com o GitHub em claude.ai. O clone da sessão falha, e o erro git diz `GitHub authentication required. Please reconnect your GitHub account.` Peça a essa pessoa que conecte ou reconecte o GitHub nas configurações do claude.ai.

275

276Depois de corrigir a causa, inicie novamente as sessões que falharam.

277

278<h4 id="turn-the-anthropic-git-proxy-off">

279 Desative o proxy git da Anthropic

280</h4>

281

282Se as sessões em um ambiente usam um repositório em um host git diferente de github.com, como GitHub Enterprise Server, desative `--use-anthropic-git-proxy` para os runners desse ambiente.

283

284<Steps>

285 <Step title="Remova a flag">

286 Remova `--use-anthropic-git-proxy` do comando do runner. Se você definiu `CLAUDE_RUNNER_USE_GIT_PROXY` no ambiente do runner, como em uma especificação de pod ou em um arquivo Compose, remova-a de lá. Em um shell, remova a definição dela:

287

288 ```bash theme={null}

289 unset CLAUDE_RUNNER_USE_GIT_PROXY

290 ```

291 </Step>

292

293 <Step title="Forneça credenciais git ao runner">

294 Forneça credenciais que funcionem sem um prompt para cada host git que as sessões dos runners usam, incluindo github.com. Qualquer credencial que estava na configuração git global do usuário do runner se perdeu, porque o runner excluiu essa configuração enquanto `--use-anthropic-git-proxy` estava definido. [Envie credenciais em sua imagem](#ship-git-config-in-your-image) ou use um [hook de ciclo de vida `checkout`](/docs/pt/self-hosted-environments-configuration#checkout).

295 </Step>

296

297 <Step title="Abra o caminho de rede">

298 Permita que o runner alcance cada host git que as sessões dos runners usam na porta 443 ou 22. Consulte a linha do host git em [Requisitos de rede](#network-requirements).

299 </Step>

300

301 <Step title="Reinicie os runners">

302 Reinicie os runners para que eles se registrem sem o proxy git. Em seguida, inicie novamente cada sessão que falhou.

303 </Step>

304</Steps>

198 305

199<h4 id="github-api-access-without-the-github-cli">306<h4 id="github-api-access-without-the-github-cli">

200 Acesso à API do GitHub sem o GitHub CLI307 Acesso à API do GitHub sem o GitHub CLI

266```dockerfile theme={null}373```dockerfile theme={null}

267FROM debian:bookworm-slim374FROM debian:bookworm-slim

268ARG CLAUDE_CODE_VERSION375ARG CLAUDE_CODE_VERSION

269RUN apt-get update && apt-get install -y --no-install-recommends git curl ca-certificates openssh-client \376RUN apt-get update && apt-get install -y --no-install-recommends git curl ca-certificates openssh-client jq \

270 && rm -rf /var/lib/apt/lists/*377 && rm -rf /var/lib/apt/lists/*

271RUN curl -fsSL "https://downloads.claude.ai/claude-code-releases/${CLAUDE_CODE_VERSION:?set with --build-arg CLAUDE_CODE_VERSION}/linux-x64/claude" \378RUN curl -fsSL "https://downloads.claude.ai/claude-code-releases/${CLAUDE_CODE_VERSION:?set with --build-arg CLAUDE_CODE_VERSION}/linux-x64/claude" \

272 -o /usr/local/bin/claude && chmod +x /usr/local/bin/claude379 -o /usr/local/bin/claude && chmod +x /usr/local/bin/claude

382kubectl create namespace claude-runners489kubectl create namespace claude-runners

383```490```

384 491

385Crie o Secret de suporte a partir de um arquivo local contendo o valor que você copiou na etapa [**Copy environment key**](/docs/pt/self-hosted-environments-quickstart#set-up-an-environment-and-runner) da UI de admin, para que o segredo nunca apareça no histórico do shell. Execute `(umask 077 && cat > ./environment-secret)`, cole o segredo, pressione Enter, depois Ctrl-D. Depois crie o Secret e delete o arquivo:492Crie o Secret de suporte a partir de um arquivo local contendo o valor que você copiou na etapa [**Copy environment key**](/docs/pt/self-hosted-environments-quickstart#set-up-manually) da UI de admin, para que o segredo nunca apareça no histórico do shell. Execute `(umask 077 && cat > ./environment-secret)`, cole o segredo, pressione Enter, depois Ctrl-D. Depois crie o Secret e delete o arquivo:

386 493

387```bash theme={null}494```bash theme={null}

388kubectl create secret generic claude-runner-environment-secret -n claude-runners --from-file=environment-secret=./environment-secret495kubectl create secret generic claude-runner-environment-secret -n claude-runners --from-file=environment-secret=./environment-secret

500 Reuse a pre-warmed checkout607 Reuse a pre-warmed checkout

501</h2>608</h2>

502 609

503Para repositórios grandes, o clone pode dominar a inicialização da sessão. Em `--capacity 1` sem um [hook `checkout`](/docs/pt/self-hosted-environments-configuration#checkout), o runner mantém um clone canônico por repositório em `<base-dir>/<repo-owner>/<repo>` e o reutiliza entre sessões: ele busca a ref solicitada, destaca `HEAD`, e redefine duramente para ela, o que é quase instantâneo quando pouco mudou. Para pular o clone frio, forneça o clone de uma de duas maneiras:610Para repositórios grandes, o clone pode dominar a inicialização da sessão. Para pular o clone frio, forneça você mesmo um clone no caminho onde o runner mantém o seu próprio. Sem um [hook `checkout`](/docs/pt/self-hosted-environments-configuration#checkout), o runner mantém um clone canônico por repositório em `<base-dir>/<repo-owner>/<repo>` e o reutiliza entre sessões:

611

612* **Em `--capacity 1`**: o runner busca a ref solicitada, destaca `HEAD` e redefine duramente para ela, o que é quase instantâneo quando pouco mudou.

613* **Em um `--capacity` acima de um**: o runner busca nesse clone e, em seguida, faz o checkout de um worktree separado a partir dele para cada sessão. Um clone pré-aquecido economiza o download, mas não o checkout.

614

615Forneça o clone na imagem ou em um volume persistente:

504 616

505* **Clone na imagem**: construa o clone em sua imagem de runner naquele caminho. Cada contêiner fresco então começa com o clone quente sem reutilizar um disco.617* **Clone na imagem**: construa o clone em sua imagem de runner naquele caminho. Cada contêiner fresco então começa com o clone quente sem reutilizar um disco.

506* **Clone em um volume persistente**: em runners que você pré-bloqueia para a conta de um usuário com [`--lock-to-account`](/docs/pt/self-hosted-environments-reference#runner-cli-flags), aponte `--base-dir` para um volume persistente, para que o disco apenas sirva essa conta. Um runner pré-bloqueado nunca pega sessões de canal Claude Tag, então essa opção não se aplica a runners que as servem.618* **Clone em um volume persistente**: em runners que você pré-bloqueia para a conta de um usuário com [`--lock-to-account`](/docs/pt/self-hosted-environments-reference#runner-cli-flags), aponte `--base-dir` para um volume persistente, para que o disco apenas sirva essa conta. Um runner pré-bloqueado nunca pega sessões de canal Claude Tag, então essa opção não se aplica a runners que as servem.

508O que o caminho de reutilização faz e não garante:620O que o caminho de reutilização faz e não garante:

509 621

510* **Qualquer forma de clone funciona**: um clone completo, raso, ou de um único branch no caminho é usado como está. O runner nunca passa `--depth` ao buscar em um clone existente, então um pré-aquecimento completo mantém seu histórico completo e um raso permanece raso. `CLAUDE_RUNNER_FETCH_DEPTH` (`full`, `0`, ou um número; padrão 50) controla apenas o clone frio que o runner faz quando nenhum clone existe ainda.622* **Qualquer forma de clone funciona**: um clone completo, raso, ou de um único branch no caminho é usado como está. O runner nunca passa `--depth` ao buscar em um clone existente, então um pré-aquecimento completo mantém seu histórico completo e um raso permanece raso. `CLAUDE_RUNNER_FETCH_DEPTH` (`full`, `0`, ou um número; padrão 50) controla apenas o clone frio que o runner faz quando nenhum clone existe ainda.

511* **Mudanças rastreadas redefinem, arquivos não rastreados persistem**: cada sessão começa a partir de uma redefinição dura que limpa as modificações rastreadas da sessão anterior, mas o runner nunca executa `git clean`, então arquivos não rastreados das sessões anteriores do owner bloqueado permanecem na árvore.623* **Mudanças rastreadas redefinem, arquivos não rastreados persistem**: em `--capacity 1`, cada sessão começa a partir de uma redefinição dura que limpa as modificações rastreadas da sessão anterior, mas o runner nunca executa `git clean`, então arquivos não rastreados das sessões anteriores do owner bloqueado permanecem na árvore.

512* **Diretórios por sessão também persistem**: ao lado do checkout, o runner cria entradas por sessão sob `<base-dir>/_sessions/` para cada sessão que executa. O diretório de configuração Claude da sessão contém uma cópia local da transcrição da conversa. Ao lado dele ficam os arquivos carregados da sessão, quando a sessão tem algum. O diretório da sessão também fica lá: ele contém quaisquer worktrees por sessão e checkouts do hook `checkout` enquanto a sessão é executada, e mantém tudo mais que Claude escreveu nele.624* **Diretórios por sessão também persistem**: ao lado do checkout, o runner cria entradas por sessão sob `<base-dir>/_sessions/` para cada sessão que executa. O diretório de configuração Claude da sessão contém uma cópia local da transcrição da conversa. Ao lado dele ficam os arquivos carregados da sessão, quando a sessão tem algum. O diretório da sessão também fica lá: ele contém quaisquer worktrees por sessão e checkouts do hook `checkout` enquanto a sessão é executada, e mantém tudo mais que Claude escreveu nele.

513 625

514 Por padrão, o runner deixa esses em vigor quando a sessão termina, então em um disco que sobrevive ao processo do runner eles se acumulam. Cada sessão é executada como o próprio usuário do runner, então qualquer sessão posterior que o disco servir pode lê-los. Se você manter um `--base-dir` persistente, dimensione o volume para esse crescimento. O mesmo se aplica a qualquer configuração que reinicie o runner no mesmo sistema de arquivos, incluindo a [receita Docker Compose](#docker-compose).626 Por padrão, o runner deixa esses em vigor quando a sessão termina, então em um disco que sobrevive ao processo do runner eles se acumulam. Cada sessão é executada como o próprio usuário do runner, então qualquer sessão posterior que o disco servir pode lê-los. Se você manter um `--base-dir` persistente, dimensione o volume para esse crescimento. O mesmo se aplica a qualquer configuração que reinicie o runner no mesmo sistema de arquivos, incluindo a [receita Docker Compose](#docker-compose).

522 634

523Cada processo filho Claude Code da sessão executa o próprio binário do runner, e o runner desativa auto-update dentro das sessões que gera, então cada sessão executa a versão que você instalou no host ou construiu na imagem. Uma atualização no nível do host entra em vigor na próxima vez que o runner inicia.635Cada processo filho Claude Code da sessão executa o próprio binário do runner, e o runner desativa auto-update dentro das sessões que gera, então cada sessão executa a versão que você instalou no host ou construiu na imagem. Uma atualização no nível do host entra em vigor na próxima vez que o runner inicia.

524 636

525Um modelo que suas sessões usam pode exigir uma versão mais recente do Claude Code do que aquela que executam. O servidor então rejeita solicitações para esse modelo com [Claude Code does not support this model](/docs/pt/errors#claude-code-does-not-support-this-model). Antes de fixar uma versão, verifique [as versões do Claude Code que os modelos exigem](/docs/pt/model-config#available-models) para cada modelo que suas sessões usam.637Escolha qual versão suas sessões executam e quando ela muda:

526 638

639* **Antes de fixar uma versão**: verifique [as versões do Claude Code que os modelos exigem](/docs/pt/model-config#available-models) para cada modelo que suas sessões usam. Se um modelo exigir uma versão mais recente do que aquela que suas sessões executam, o servidor rejeita requisições para esse modelo com [Claude Code does not support this model](/docs/pt/errors#claude-code-does-not-support-this-model).

527* **Para manter uma frota em uma versão**: construa a imagem com uma versão fixada, ou em um host nu instale uma versão específica e [desabilite auto-updates](/docs/pt/setup#disable-auto-updates)640* **Para manter uma frota em uma versão**: construa a imagem com uma versão fixada, ou em um host nu instale uma versão específica e [desabilite auto-updates](/docs/pt/setup#disable-auto-updates)

528* **Para atualizar**: instale a versão mais recente ou reconstrua a imagem, depois reinicie os runners641* **Para atualizar uma frota fixa**: leia as entradas do [changelog](/docs/en/changelog) entre a sua versão e a que você está instalando, depois instale a versão mais recente ou recrie a imagem e reinicie os runners

642* **Para atualizar runners sob demanda**: leia as entradas do [changelog](/docs/en/changelog) entre a sua versão e a que você está instalando, depois altere a imagem que o seu [hook `spawn-runner`](/docs/pt/self-hosted-environments-configuration#the-spawn-runner-hook) inicia. Cada novo runner recebe a nova versão. Um runner que já está em execução, incluindo um runner de reserva que [`--min-idle`](/docs/pt/self-hosted-environments-reference#orchestrator-cli-flags) iniciou, mantém sua versão até encerrar. Não o reinicie, porque sua ordem de trabalho é de uso único.

529* **Plugins**: marketplaces de plugin também não auto-atualizam; defina `FORCE_AUTOUPDATE_PLUGINS=1` no ambiente do runner para deixar plugins auto-atualizarem enquanto o binário permanece fixado643* **Plugins**: marketplaces de plugin também não auto-atualizam; defina `FORCE_AUTOUPDATE_PLUGINS=1` no ambiente do runner para deixar plugins auto-atualizarem enquanto o binário permanece fixado

530 644

531<h2 id="scale-the-fleet">645<h2 id="scale-the-fleet">

580</h3>694</h3>

581 695

582* **Sessões retomadas perdem trabalho não enviado**: um runner novo clona o repositório novamente a partir de seu branch inicial, então o trabalho que a sessão não tinha enviado se foi.696* **Sessões retomadas perdem trabalho não enviado**: um runner novo clona o repositório novamente a partir de seu branch inicial, então o trabalho que a sessão não tinha enviado se foi.

583 * **Para manter trabalho com commit**: defina [`--push-outcome-on-release`](/docs/pt/self-hosted-environments-reference#runner-cli-flags). O runner então faz um push de melhor esforço dos branches de resultado da sessão antes de liberá-la, e a sessão retomada começa a partir desses commits. Alterações sem commit ainda são perdidas.697 * **Para manter trabalho com commit**: defina [`--push-outcome-on-release`](/docs/pt/self-hosted-environments-reference#runner-cli-flags) em todos os runners do ambiente, porque um runner sem a flag retoma a sessão a partir de seu branch inicial. Um runner com a flag faz um push de melhor esforço dos branches de resultado da sessão antes de liberá-la, e a sessão retomada começa a partir desses commits. O push usa as próprias credenciais git do host do runner, inclusive em um runner que usa [git gerenciado pela Anthropic](#use-the-anthropic-git-proxy). Alterações sem commit ainda são perdidas.

698 * **Com um hook `checkout`**: repositórios obtidos por meio de um [hook de ciclo de vida `checkout`](/docs/pt/self-hosted-environments-configuration#checkout) não recebem push. Em vez disso, faça um snapshot deles a partir do [hook `post-session`](/docs/pt/self-hosted-environments-configuration#post-session).

584 * **Antes de habilitar a flag**: restrinja quem pode fazer push para refs `claude/*` no remoto de origem. Na retomada, o runner busca o branch previamente enviado sem verificar quem o enviou.699 * **Antes de habilitar a flag**: restrinja quem pode fazer push para refs `claude/*` no remoto de origem. Na retomada, o runner busca o branch previamente enviado sem verificar quem o enviou.

585* **Um repositório adicionado no meio da sessão pode falhar ao ser clonado**: Claude o clona com `git clone` via HTTPS. Em um runner sem [`--use-anthropic-git-proxy`](#use-the-anthropic-git-proxy), o clone falha com um erro de autenticação do git se nada no host puder ler o repositório. Sempre que possível, selecione cada repositório que a sessão precisa quando você a cria.700* **Um repositório adicionado no meio da sessão pode falhar ao ser clonado**: Claude o clona com `git clone` via HTTPS. Em um runner sem [`--use-anthropic-git-proxy`](#use-the-anthropic-git-proxy), o clone falha com um erro de autenticação do git se nada no host puder ler o repositório. Sempre que possível, selecione cada repositório que a sessão precisa quando você a cria.

586* **Alguns conectores não aparecem em sessões auto-hospedadas**: um conector que você ainda não conectou nas Configurações do claude.ai não está listado em uma sessão auto-hospedada, e a sessão não o solicitará para conectar. Conecte-o nas Configurações primeiro, depois inicie uma sessão fresca. Adicionar um conector a uma sessão já em execução também não torna suas ferramentas disponíveis para Claude; inicie uma sessão fresca para pegar um conector recém-adicionado.701* **Alguns conectores não aparecem em sessões auto-hospedadas**: um conector que você ainda não conectou nas Configurações do claude.ai não está listado em uma sessão auto-hospedada, e a sessão não o solicitará para conectar. Conecte-o nas Configurações primeiro, depois inicie uma sessão fresca. Adicionar um conector a uma sessão já em execução também não torna suas ferramentas disponíveis para Claude; inicie uma sessão fresca para pegar um conector recém-adicionado.

606* **Runner não aparece no ambiente**: confirme que o host pode alcançar `api.anthropic.com` via HTTPS, o segredo do ambiente está atual e o relógio do host está dentro de cinco minutos da hora real; desvios maiores causam falha na autenticação. O runner registra `[runner:fatal]` com o motivo da rejeição em caso de falha de autenticação.721* **Runner não aparece no ambiente**: confirme que o host pode alcançar `api.anthropic.com` via HTTPS, o segredo do ambiente está atual e o relógio do host está dentro de cinco minutos da hora real; desvios maiores causam falha na autenticação. O runner registra `[runner:fatal]` com o motivo da rejeição em caso de falha de autenticação.

607* **Runner sai na inicialização com `cannot create or write to base directory`**: o runner não consegue criar ou escrever em `--base-dir`, que padrão é `/workspace`. Corrija a propriedade do diretório ou aponte `--base-dir` para um caminho gravável, conforme descrito em [Keep the base directory and capacity identical across runners](#keep-the-base-directory-and-capacity-identical-across-runners). Se o runner registrar `[runner:fatal]` dizendo que a verificação do diretório base expirou, o diretório está em uma montagem NFS ou CSI travada. Verifique a saúde da montagem em vez de permissões. O runner imprime ambas essas falhas de inicialização para stderr antes de abrir `--log-file`, então procure por elas no terminal ou nos logs do contêiner da sua plataforma em vez do arquivo de log. Antes da v2.1.225, o runner não verificava o diretório base na inicialização, e essa configuração incorreta falhava nas sessões após a coleta.722* **Runner sai na inicialização com `cannot create or write to base directory`**: o runner não consegue criar ou escrever em `--base-dir`, que padrão é `/workspace`. Corrija a propriedade do diretório ou aponte `--base-dir` para um caminho gravável, conforme descrito em [Keep the base directory and capacity identical across runners](#keep-the-base-directory-and-capacity-identical-across-runners). Se o runner registrar `[runner:fatal]` dizendo que a verificação do diretório base expirou, o diretório está em uma montagem NFS ou CSI travada. Verifique a saúde da montagem em vez de permissões. O runner imprime ambas essas falhas de inicialização para stderr antes de abrir `--log-file`, então procure por elas no terminal ou nos logs do contêiner da sua plataforma em vez do arquivo de log. Antes da v2.1.225, o runner não verificava o diretório base na inicialização, e essa configuração incorreta falhava nas sessões após a coleta.

608* **Sessions stay queued**: cada runner online pode estar bloqueado para um proprietário diferente. Verifique a métrica `claude_code_self_hosted_runner_locked_account` [metric](/docs/pt/self-hosted-environments-reference#prometheus-metrics) de cada runner ou o campo `locked_account` de sua linha de log `[runner:health]` para ver quem a mantém. Ambos mostram o email do proprietário apenas depois que o runner recebeu um token de sessão com uma reivindicação `act.email`, que as sessões de um agente Claude Tag nunca fazem. Sem a reivindicação, o runner não emite nenhuma série `locked_account` e registra `locked_account=yes`, o que informa que o runner está bloqueado, mas não para qual proprietário. Adicione réplicas ou aguarde um runner existente drenar e reiniciar. Se o ambiente usar runners sob demanda, verifique o orquestrador; consulte [On-demand runners](/docs/pt/self-hosted-environments-configuration#on-demand-runners).723* **Sessions stay queued**: cada runner online pode estar bloqueado para um proprietário diferente. Verifique a métrica `claude_code_self_hosted_runner_locked_account` [metric](/docs/pt/self-hosted-environments-reference#prometheus-metrics) de cada runner ou o campo `locked_account` de sua linha de log `[runner:health]` para ver quem a mantém. Ambos mostram o email do proprietário apenas depois que o runner recebeu um token de sessão com uma reivindicação `act.email`, que as sessões de um agente Claude Tag nunca fazem. Sem a reivindicação, o runner não emite nenhuma série `locked_account` e registra `locked_account=yes`, o que informa que o runner está bloqueado, mas não para qual proprietário. Adicione réplicas ou aguarde um runner existente drenar e reiniciar. Se o ambiente usar runners sob demanda, verifique o orquestrador; consulte [On-demand runners](/docs/pt/self-hosted-environments-configuration#on-demand-runners).

609* **Sessions fail immediately after pickup**: abra a sessão em claude.ai/code para ver o erro. As causas mais comuns são [git credentials](#configure-git) ausentes na imagem do runner e ferramentas de compilação que não estão instaladas. Um diretório base não gravável interrompe o runner na inicialização em vez de falhar nas sessões. Consulte a entrada **Runner sai na inicialização com `cannot create or write to base directory`** nesta lista.724* **As sessões falham imediatamente após a coleta**: abra a sessão em claude.ai/code para ver o erro. As causas mais comuns são [credenciais git](#configure-git) ausentes na imagem do runner e ferramentas de build que não estão instaladas. Em um runner iniciado com `--use-anthropic-git-proxy`, consulte [Quando as sessões não iniciam em um runner com o proxy git](#when-anthropic-doesnt-serve-a-session). Um diretório base não gravável interrompe o runner na inicialização em vez de fazer as sessões falharem. Consulte a entrada **O runner sai na inicialização com `cannot create or write to base directory`** nesta lista.

725* **As sessões não iniciam em um runner que definiu `--use-anthropic-git-proxy`**: procure no log do runner por `access denied by the git proxy`, ou por um erro do git que mencione um endereço de `api.anthropic.com` contendo `/git_proxy/`. Para saber se a Anthropic atendeu a sessão e corrigir a causa, consulte [Quando as sessões não iniciam em um runner com o proxy git](#when-anthropic-doesnt-serve-a-session).

610* **Sessions can't reach the network through an authenticating egress proxy**: quando a fonte que você definiu com [`--proxy-authorization-command` ou `--proxy-authorization-file`](#authenticate-to-an-egress-proxy) falha, expira após 30 segundos ou produz um valor vazio, o runner responde essa conexão com `502 Bad Gateway` e registra o motivo. O runner redige o stderr do comando nesse log e nunca registra o valor do cabeçalho. Com `--proxy-authorization-command`, execute o comando você mesmo no host para confirmar que ele imprime o valor do cabeçalho inteiro em stdout. Se o runner sair na inicialização com `could not start the proxy-authorization listener`, ele não conseguiu abrir seu listener de loopback.726* **Sessions can't reach the network through an authenticating egress proxy**: quando a fonte que você definiu com [`--proxy-authorization-command` ou `--proxy-authorization-file`](#authenticate-to-an-egress-proxy) falha, expira após 30 segundos ou produz um valor vazio, o runner responde essa conexão com `502 Bad Gateway` e registra o motivo. O runner redige o stderr do comando nesse log e nunca registra o valor do cabeçalho. Com `--proxy-authorization-command`, execute o comando você mesmo no host para confirmar que ele imprime o valor do cabeçalho inteiro em stdout. Se o runner sair na inicialização com `could not start the proxy-authorization listener`, ele não conseguiu abrir seu listener de loopback.

611* **Runner logs `Poll failed` lines containing `rejecting the malformed poll response`**: o runner recebeu uma resposta de work-poll cujo corpo não é o JSON esperado da fila, na maioria das vezes porque algo entre o runner e `api.anthropic.com`, como um proxy interceptador ou um portal cativo, respondeu com sua própria página. O runner rejeita a resposta, a conta sob o tipo `transport` da métrica `claude_code_self_hosted_runner_poll_errors_total` [metric](/docs/pt/self-hosted-environments-reference#prometheus-metrics), e tenta novamente no cronograma de falha de pesquisa descrito em [Session lifecycle](/docs/pt/self-hosted-environments#session-lifecycle). O runner continua servindo suas sessões ativas. Configure o proxy para passar respostas de `api.anthropic.com` inalteradas. Antes da v2.1.246, o runner lia tal resposta como uma fila de trabalho vazia, o que poderia encerrar suas sessões ativas ou fazer com que saísse.727* **Runner logs `Poll failed` lines containing `rejecting the malformed poll response`**: o runner recebeu uma resposta de work-poll cujo corpo não é o JSON esperado da fila, na maioria das vezes porque algo entre o runner e `api.anthropic.com`, como um proxy interceptador ou um portal cativo, respondeu com sua própria página. O runner rejeita a resposta, a conta sob o tipo `transport` da métrica `claude_code_self_hosted_runner_poll_errors_total` [metric](/docs/pt/self-hosted-environments-reference#prometheus-metrics), e tenta novamente no cronograma de falha de pesquisa descrito em [Session lifecycle](/docs/pt/self-hosted-environments#session-lifecycle). O runner continua servindo suas sessões ativas. Configure o proxy para passar respostas de `api.anthropic.com` inalteradas. Antes da v2.1.246, o runner lia tal resposta como uma fila de trabalho vazia, o que poderia encerrar suas sessões ativas ou fazer com que saísse.

612* **A session's branch no longer exists on the remote**: para uma fonte git que a sessão apenas lê, o runner pula essa fonte e continua nas restantes. Para a fonte para a qual a sessão envia resultados, uma ramificação excluída, normalmente porque foi mesclada e auto-excluída, falha na sessão com um erro nomeando o repositório e a ramificação e pedindo que você restaure a ramificação e tente novamente. O runner falha na sessão com o mesmo erro quando pular deixaria sem nenhum repositório. Antes da v2.1.228, tal sessão começava em um diretório vazio.728* **A session's branch no longer exists on the remote**: para uma fonte git que a sessão apenas lê, o runner pula essa fonte e continua nas restantes. Para a fonte para a qual a sessão envia resultados, uma ramificação excluída, normalmente porque foi mesclada e auto-excluída, falha na sessão com um erro nomeando o repositório e a ramificação e pedindo que você restaure a ramificação e tente novamente. O runner falha na sessão com o mesmo erro quando pular deixaria sem nenhum repositório. Antes da v2.1.228, tal sessão começava em um diretório vazio.

616 732

617 A verificação de acesso é executada novamente cada vez que a sessão é iniciada em um runner, portanto, uma vez que a identidade git do runner tenha acesso de leitura, o próximo início clona o repositório. Antes da v2.1.274, cada uma dessas recusas falhava no início da sessão.733 A verificação de acesso é executada novamente cada vez que a sessão é iniciada em um runner, portanto, uma vez que a identidade git do runner tenha acesso de leitura, o próximo início clona o repositório. Antes da v2.1.274, cada uma dessas recusas falhava no início da sessão.

618* **Sessions take minutes to start**: o clone inicial geralmente domina. Observe a métrica `claude_code_self_hosted_runner_session_init_duration_seconds` [metric](/docs/pt/self-hosted-environments-reference#prometheus-metrics) para confirmar e corte o clone com um [pre-warmed checkout](#reuse-a-pre-warmed-checkout) ou um `CLAUDE_RUNNER_FETCH_DEPTH` menor.734* **Sessions take minutes to start**: o clone inicial geralmente domina. Observe a métrica `claude_code_self_hosted_runner_session_init_duration_seconds` [metric](/docs/pt/self-hosted-environments-reference#prometheus-metrics) para confirmar e corte o clone com um [pre-warmed checkout](#reuse-a-pre-warmed-checkout) ou um `CLAUDE_RUNNER_FETCH_DEPTH` menor.

619* **Turns fail with a 401**: cada sessão autentica chamadas de modelo com o token de curta duração [`CLAUDE_CODE_OAUTH_TOKEN`](/docs/pt/self-hosted-environments-configuration#wrapper-scripts) que o runner busca da Anthropic e rotaciona sobre o stdin da sessão. Quando uma volta termina com um 401 ou 403 da API do modelo, o runner busca um token novo e o passa para a sessão. A volta com falha não é retentada.735* **Os turnos falham com um 401**: quando um turno termina com um 401 ou 403 da API da Anthropic, o runner busca um [`CLAUDE_CODE_OAUTH_TOKEN`](/docs/pt/self-hosted-environments-configuration#wrapper-scripts) novo da Anthropic e o passa para a sessão. O turno com falha não é tentado novamente. Esse token é de curta duração, e o runner o rotaciona pelo stdin da sessão.

620 736

621 Quando uma busca falha, o runner registra uma linha `inference_token refresh failed` que diz quando tentará novamente, e continua tentando novamente enquanto a sessão estiver em execução.737 Quando uma busca falha, o runner registra uma linha `inference_token refresh failed` que diz quando tentará novamente, e continua tentando novamente enquanto a sessão estiver em execução.

622 738

637 753

638* **A normal exit**: o runner terminou suas sessões e drenagem, atingiu seu tempo de aposentadoria ou foi instruído a parar. Reinicie-o para que o ambiente tenha capacidade novamente. [Runner lifecycle](/docs/pt/self-hosted-environments#runner-lifecycle) descreve essas saídas.754* **A normal exit**: o runner terminou suas sessões e drenagem, atingiu seu tempo de aposentadoria ou foi instruído a parar. Reinicie-o para que o ambiente tenha capacidade novamente. [Runner lifecycle](/docs/pt/self-hosted-environments#runner-lifecycle) descreve essas saídas.

639* **A failed start**: o runner não consegue iniciar com a configuração ou host que foi dado, então sai segundos depois de iniciar, e sai da mesma forma toda vez que você o reinicia. Reiniciá-lo mais rápido não ajuda. Alguém precisa ler sua saída e corrigir a causa.755* **A failed start**: o runner não consegue iniciar com a configuração ou host que foi dado, então sai segundos depois de iniciar, e sai da mesma forma toda vez que você o reinicia. Reiniciá-lo mais rápido não ajuda. Alguém precisa ler sua saída e corrigir a causa.

756* **Perda de contato**: um runner que não consegue alcançar a Anthropic por mais tempo do que seu [lease](/docs/pt/self-hosted-environments#session-lifecycle), por exemplo enquanto seu host está em suspensão, pode ser removido do ambiente. Quando um runner removido se reconecta, ele sai. Seu log pode mostrar uma linha `[runner:fatal]` que contém `runner record gone server-side` ou, após uma interrupção mais longa, [`poll auth failed`](/docs/pt/self-hosted-environments-quickstart#set-up-an-environment-and-runner). O runner não se registra novamente por conta própria, então reinicie-o.

640 757

641Configure seu supervisor para reiniciar o runner sempre que sair, para aguardar mais tempo entre reinicializações quando o runner continuar saindo logo após iniciar, e para informar alguém quando isso continuar acontecendo.758Configure seu supervisor para reiniciar o runner sempre que sair, para aguardar mais tempo entre reinicializações quando o runner continuar saindo logo após iniciar, e para informar alguém quando isso continuar acontecendo.

642 759

self-hosted-environments-identity.md +3 −1

Details

195 195

196Wrappers recebem o caminho absoluto para o binário do próprio runner em `CLAUDE_RUNNER_CLAUDE_BIN`; use esse caminho em vez de um `claude` resolvido por PATH para que a decodificação seja executada no mesmo binário que o runner usa.196Wrappers recebem o caminho absoluto para o binário do próprio runner em `CLAUDE_RUNNER_CLAUDE_BIN`; use esse caminho em vez de um `claude` resolvido por PATH para que a decodificação seja executada no mesmo binário que o runner usa.

197 197

198Use `jq -re` em vez de `jq -r` para que uma declaração ausente cause uma saída diferente de zero. Com apenas `-r`, uma declaração ausente imprime a string literal `null` e sai com zero, o que silenciosamente passa um valor ruim para jusante. Passe `--no-verify` para `decode-token` apenas para inspeção offline onde o endpoint JWKS está inacessível.198Use `jq -re` em vez de `jq -r` para que uma declaração ausente cause uma saída diferente de zero. Com apenas `-r`, uma declaração ausente imprime a string literal `null` e sai com zero, o que silenciosamente passa um valor ruim para jusante.

199

200Se `decode-token` não conseguir buscar as chaves do endpoint JWKS ou não conseguir verificar o token, ele imprime o motivo em stderr, não imprime nenhuma declaração e sai com o código 1. Passe `--no-verify` para `decode-token` apenas para inspeção offline onde o endpoint JWKS está inacessível.

199 201

200<h2 id="claims-reference">202<h2 id="claims-reference">

201 Referência de declarações203 Referência de declarações

self-hosted-environments-quickstart.md +45 −7

Details

34O host do runner precisa de:34O host do runner precisa de:

35 35

36* Um host ou container Linux ou macOS com HTTPS de saída para `api.anthropic.com`, para `claude.ai` e os hosts de download para os quais ele redireciona para a etapa de instalação abaixo, e para seu host git para o clone; a [tabela de requisitos de rede](/docs/pt/self-hosted-environments-deploy#network-requirements) tem a lista completa. Windows não é suportado como host de runner; execute o runner em um container Linux. Estações de trabalho de desenvolvedores não são afetadas, pois as sessões começam a partir de claude.ai em um navegador.36* Um host ou container Linux ou macOS com HTTPS de saída para `api.anthropic.com`, para `claude.ai` e os hosts de download para os quais ele redireciona para a etapa de instalação abaixo, e para seu host git para o clone; a [tabela de requisitos de rede](/docs/pt/self-hosted-environments-deploy#network-requirements) tem a lista completa. Windows não é suportado como host de runner; execute o runner em um container Linux. Estações de trabalho de desenvolvedores não são afetadas, pois as sessões começam a partir de claude.ai em um navegador.

37* Um repositório para a sessão de teste: um público, ou um que este host já consiga clonar pela sua URL HTTPS sem que sejam solicitadas credenciais.

37* Um relógio sincronizado com a hora real, por exemplo com NTP. A autenticação falha quando o relógio está mais de cinco minutos atrasado; consulte [Troubleshooting](/docs/pt/self-hosted-environments-deploy#troubleshooting).38* Um relógio sincronizado com a hora real, por exemplo com NTP. A autenticação falha quando o relógio está mais de cinco minutos atrasado; consulte [Troubleshooting](/docs/pt/self-hosted-environments-deploy#troubleshooting).

38 39

39<h3 id="software-on-the-runner-host">40<h3 id="software-on-the-runner-host">

57 Configurar um ambiente e runner58 Configurar um ambiente e runner

58</h2>59</h2>

59 60

60Claude Code inclui uma configuração guiada: uma sessão Claude Code interativa que o orienta na criação do ambiente na interface de administração, inicia um runner local com o arquivo de segredo que você salva, confirma que o runner se registra e escreve uma folha de dicas em `./runner-setup/CHEAT-SHEET.md`. Execute-o em uma máquina onde você se conectou com `claude auth login` usando uma conta que possui uma função de Proprietário; não está disponível com chaves de API ou provedores de modelo de terceiros. Em hosts onde uma sessão interativa não é possível, use as etapas manuais abaixo. Confirme que a [verificação de versão](#software-on-the-runner-host) passou primeiro: em versões anteriores a 2.1.224, este comando inicia uma sessão Claude comum com as palavras como o prompt em vez da configuração guiada. Para iniciar a configuração guiada, execute o subcomando setup e siga os prompts:61Use a [configuração guiada](#run-the-guided-setup) ou as [etapas manuais](#set-up-manually). A configuração guiada é um único comando que inicia uma sessão interativa do Claude Code e orienta você pelo restante. Use as etapas manuais em um host onde uma sessão interativa não seja possível. Use-as também quando alguém com a função Owner tiver criado o ambiente e entregado o segredo a você, já que a configuração guiada exige login de um Owner.

63<h3 id="run-the-guided-setup">

64 Executar a configuração guiada

65</h3>

67A configuração guiada orienta você na criação do ambiente na interface de administração, inicia um runner local com o arquivo de segredo que você salva, confirma que o runner se registra e escreve uma folha de dicas em `./runner-setup/CHEAT-SHEET.md`. Antes de executá-la, confirme seu login e sua versão:

69* **Login**: execute-a em uma máquina onde você fez login com `claude auth login` usando uma conta que possui a função Owner. Com apenas uma chave de API ou um provedor de modelo de terceiros, a sessão é iniciada, mas as verificações de organização falham.

70* **Versão**: confirme que a [verificação de versão](#software-on-the-runner-host) passou. Em versões anteriores a 2.1.224, o comando setup inicia uma sessão Claude com as palavras como o prompt em vez da configuração guiada.

72Para iniciar a configuração guiada, execute o subcomando setup no seu shell e siga os prompts:

61 73

62```bash theme={null}74```bash theme={null}

63claude self-hosted-runner setup75claude self-hosted-runner setup

64```76```

65 77

~~66Para configurar manualmente:~~78A configuração não inicia uma sessão de teste por conta própria: ela pede que você inicie uma em claude.ai/code. A última etapa da configuração para o runner que ela iniciou. Se você sair da configuração antes dessa etapa, o runner continua em execução. Para continuar após a última etapa, inicie o runner novamente no seu shell com o comando em `./runner-setup/CHEAT-SHEET.md` e, em seguida, [roteie uma sessão para o ambiente](#route-a-session).

80<h3 id="set-up-manually">

81 Configurar manualmente

82</h3>

84Crie o ambiente em claude.ai, inicie o runner a partir de um terminal no host e depois retorne a claude.ai para confirmar que o runner aparece e rotear uma sessão para ele. Se alguém com a função Owner já tiver criado o ambiente e entregado o segredo a você, comece na etapa 2.

67 85

68<Steps>86<Steps>

69 <Step title="Criar um ambiente">87 <Step title="Criar um ambiente">

73 </Step>91 </Step>

74 92

75 <Step title="Iniciar um runner">93 <Step title="Iniciar um runner">

76 Crie o diretório de segredo. Esta etapa e a próxima precisam de root para o caminho `/etc/claude`; qualquer caminho que o processo runner possa ler funciona, então ajuste ambos os comandos e o valor `--environment-secret-file` juntos se você usar um diferente.94 Crie o diretório de segredo. Este comando e o próximo usam `/etc/claude`, que precisa de root, e o arquivo de segredo que eles criam é legível apenas pelo usuário que os executa. Se o runner for executado como outro usuário, ele sai com `error: Failed to read environment secret file <path> (EACCES: permission denied, open '<path>')`. Nesse caso, execute ambos os comandos como o usuário do runner, com um diretório no qual esse usuário possa escrever no lugar de `/etc/claude`, e passe o mesmo caminho para `--environment-secret-file`. Qualquer caminho que o processo do runner possa ler funciona.

77 95

78 ```bash theme={null}96 ```bash theme={null}

79 mkdir -p /etc/claude97 mkdir -p /etc/claude

89 107

90 Se o runner não conseguir criar ou escrever no caminho, ele sai na inicialização com um erro nomeando o diretório em vez de se registrar. Consulte [Troubleshooting](/docs/pt/self-hosted-environments-deploy#troubleshooting).108 Se o runner não conseguir criar ou escrever no caminho, ele sai na inicialização com um erro nomeando o diretório em vez de se registrar. Consulte [Troubleshooting](/docs/pt/self-hosted-environments-deploy#troubleshooting).

91 109

92 Depois inicie o runner com `--environment-secret-file` e `--base-dir`. O runner se registra com seu ambiente e começa a pesquisar por trabalho. Se o runner sair, reinicie-o manualmente. Implantações de produção executam o runner sob um orquestrador que reinicia runners que saíram, normalmente com um sistema de arquivos fresco por reinicialização; [Reutilizar um checkout pré-aquecido](/docs/pt/self-hosted-environments-deploy#reuse-a-pre-warmed-checkout) cobre a configuração de disco persistente suportada.110 Depois inicie o runner com `--environment-secret-file` e `--base-dir`:

93 111

94 ```bash theme={null}112 ```bash theme={null}

95 claude self-hosted-runner --environment-secret-file '/etc/claude/environment-secret' --base-dir '<writable-dir>'113 claude self-hosted-runner --environment-secret-file '/etc/claude/environment-secret' --base-dir '<writable-dir>'

96 ```114 ```

115

116 O runner registra `Registered: runner_id=<runner-id>` no log assim que se registra com seu ambiente e, em seguida, começa a pesquisar por trabalho. Se o runner sair mais tarde, reinicie-o você mesmo. Consulte [Se o runner sair](#if-the-runner-exits) para saber quando isso acontece.

97 </Step>117 </Step>

98 118

99 <Step title="Verificar se o runner aparece">119 <Step title="Verificar se o runner aparece">

100 Retorne à [página **Cloud environments**](https://claude.ai/admin-settings/cloud-environments). O status do seu ambiente muda de **Nenhum runner implantado** para **Saudável** em alguns segundos após o runner iniciar; abra o ambiente e selecione **Atividade** para ver o runner em si.120 Retorne à [página **Cloud environments**](https://claude.ai/admin-settings/cloud-environments). O status do seu ambiente muda de **Nenhum runner implantado** para **Saudável** em alguns segundos após o runner iniciar; abra o ambiente e selecione **Atividade** para ver o runner em si. Se você não tiver acesso à página de administração, a linha `Registered: runner_id=<runner-id>` no log do runner da etapa anterior fornece o mesmo sinal.

101 </Step>121 </Step>

102 122

103 <Step title="Rotear uma sessão para o ambiente">123 <Step title="Rotear uma sessão para o ambiente">

104 Inicie uma sessão em claude.ai/code e selecione seu ambiente no seletor de ambiente, onde ambientes auto-hospedados aparecem ao lado dos hospedados pela Anthropic. O runner clona com quaisquer credenciais git que o host já tenha, então escolha um repositório que este host já possa clonar, ou um público; as opções de credencial para repositórios privados em produção estão em [Configurar git](/docs/pt/self-hosted-environments-deploy#configure-git). O próximo runner disponível pega a sessão enfileirada e registra `Picked up session <session-id>` junto com sua contagem ativa e capacidade, para que você possa confirmar a partir da própria saída do runner qual host pegou a sessão. Observe a sessão funcionar e leia as respostas do Claude em [claude.ai/code](https://claude.ai/code). Se a sessão ficar enfileirada, consulte [Troubleshooting](/docs/pt/self-hosted-environments-deploy#troubleshooting).124 <span id="route-a-session" />Inicie uma sessão em claude.ai/code e selecione seu ambiente no seletor de ambiente, onde ambientes auto-hospedados aparecem ao lado dos hospedados pela Anthropic. Para o repositório, escolha o dos [pré-requisitos](#host-and-network): um repositório público ou um que este host já possa clonar. O runner clona com quaisquer credenciais git que o host já tenha.

125

126 O próximo runner disponível pega a sessão enfileirada e registra `Picked up session <session-id>` junto com sua contagem ativa e capacidade, para que você possa confirmar a partir da própria saída do runner qual host pegou a sessão. Observe a sessão funcionar e leia as respostas do Claude em [claude.ai/code](https://claude.ai/code).

127

128 Se a sessão não começar a funcionar, compare com o que você vê:

129

130 * **A sessão fica enfileirada**: consulte [Solução de problemas](/docs/pt/self-hosted-environments-deploy#troubleshooting).

131 * **A sessão falha ao iniciar com um erro do git**: o erro aparece na sessão e no log do runner. Se ele incluir `could not read Username for` do git seguido da URL do seu host git, o runner não tinha credenciais HTTPS para esse host. Consulte [Configurar git](/docs/pt/self-hosted-environments-deploy#configure-git), que também cobre as opções de credencial para repositórios privados em produção.

105 </Step>132 </Step>

106</Steps>133</Steps>

107 134

108O runner sai por design uma vez que suas sessões ativas terminam; consulte [Ciclo de vida do runner](/docs/pt/self-hosted-environments#runner-lifecycle). Para produção, implante-o sob um orquestrador que o reinicia na saída e aguarda mais tempo entre reinicializações quando o runner continua saindo logo após iniciar. Consulte [Implantar em produção](/docs/pt/self-hosted-environments-deploy) e [Quando o runner sai](/docs/pt/self-hosted-environments-deploy#when-the-runner-exits).135<h3 id="if-the-runner-exits">

136 Se o runner sair

137</h3>

138

139Se o runner sair durante este guia de início rápido, inicie-o novamente com o mesmo comando. O runner pode sair por conta própria:

140

141* **Sessões concluídas**: o log mostra `[runner:exit] account workload drained — exiting`. O runner sai por design uma vez que suas sessões ativas terminam. Consulte [Ciclo de vida do runner](/docs/pt/self-hosted-environments#runner-lifecycle).

142* **Perda de contato**: o log mostra uma linha `[runner:fatal]` com `runner record gone server-side` ou com `poll auth failed`. Se o runner perder contato com a Anthropic por um tempo, por exemplo porque o host entra em suspensão, ele pode sair quando alcançar a Anthropic novamente.

143

144Um turno concluído não encerra sua sessão de teste. Após o primeiro turno, a sessão ainda está anexada e o runner ainda está ativo, então você pode [enviar uma mensagem de acompanhamento para a sessão](#send-a-follow-up-message-to-a-running-session) sem reiniciar o runner primeiro.

145

146Para produção, implante o runner sob um orquestrador que o reinicia na saída e aguarda mais tempo entre reinicializações quando o runner continua saindo logo após iniciar. Consulte [Implantar em produção](/docs/pt/self-hosted-environments-deploy) e [Quando o runner sai](/docs/pt/self-hosted-environments-deploy#when-the-runner-exits).

109 147

110<h2 id="send-a-follow-up-message-to-a-running-session">148<h2 id="send-a-follow-up-message-to-a-running-session">

111 Enviar uma mensagem de acompanhamento para uma sessão em execução149 Enviar uma mensagem de acompanhamento para uma sessão em execução

self-hosted-environments-reference.md +26 −6

Details

52| `--release-idle-session-min <n>` | `SELF_HOSTED_RUNNER_SESSION_IDLE_MS` | `0` | Libere um slot de sessão após N minutos de inatividade uma vez que um turno termine ou a sessão aguarde a ação do usuário. Uma sessão que ainda está no meio de um turno, incluindo uma que mantém uma tarefa em segundo plano que nunca termina ou uma aprovação solicitada de dentro de uma chamada de ferramenta em execução, não conta como ociosa; emparelhe com `--kill-session-after-min` como o backstop duro. Após a tarefa em segundo plano de uma sessão terminar, o executor considera a sessão ocupada até o turno de acompanhamento que lê o resultado começar, por no máximo a janela [`SELF_HOSTED_RUNNER_BG_RESULT_GRACE_MS`](#environment-variable-only-settings). Até o executor receber um sinal de desligamento ou atingir seu tempo de aposentadoria, uma liberação que deixa o executor sem sessões ativas inicia o mesmo caminho de saída que uma drenagem normal, governada por `--drain-grace-sec`. Após um primeiro sinal que você adiou com [`--defer-shutdown-max-min`](/docs/pt/self-hosted-environments-deploy#defer-the-drain-past-the-first-signal), o executor sai assim que uma liberação o deixa sem sessões. `0` desabilita. |52| `--release-idle-session-min <n>` | `SELF_HOSTED_RUNNER_SESSION_IDLE_MS` | `0` | Libere um slot de sessão após N minutos de inatividade uma vez que um turno termine ou a sessão aguarde a ação do usuário. Uma sessão que ainda está no meio de um turno, incluindo uma que mantém uma tarefa em segundo plano que nunca termina ou uma aprovação solicitada de dentro de uma chamada de ferramenta em execução, não conta como ociosa; emparelhe com `--kill-session-after-min` como o backstop duro. Após a tarefa em segundo plano de uma sessão terminar, o executor considera a sessão ocupada até o turno de acompanhamento que lê o resultado começar, por no máximo a janela [`SELF_HOSTED_RUNNER_BG_RESULT_GRACE_MS`](#environment-variable-only-settings). Até o executor receber um sinal de desligamento ou atingir seu tempo de aposentadoria, uma liberação que deixa o executor sem sessões ativas inicia o mesmo caminho de saída que uma drenagem normal, governada por `--drain-grace-sec`. Após um primeiro sinal que você adiou com [`--defer-shutdown-max-min`](/docs/pt/self-hosted-environments-deploy#defer-the-drain-past-the-first-signal), o executor sai assim que uma liberação o deixa sem sessões. `0` desabilita. |

53| `--remove-session-state [bool]` | `SELF_HOSTED_RUNNER_REMOVE_SESSION_STATE` | desligado | Remova os diretórios por sessão de uma sessão sob `<base-dir>/_sessions/` quando a sessão terminar neste executor, seja qual for o resultado. [Reuse a pre-warmed checkout](/docs/pt/self-hosted-environments-deploy#reuse-a-pre-warmed-checkout) descreve o que eles contêm e quem pode lê-los quando permanecem. A remoção é melhor esforço: os diretórios por sessão permanecem no lugar quando o executor é morto ou atinge seu prazo de drenagem antes da limpeza ser executada. Com o sinalizador ativado, o log de depuração de uma sessão falhada ou interrompida não é mantido em disco. Requer Claude Code v2.1.268 ou posterior. |53| `--remove-session-state [bool]` | `SELF_HOSTED_RUNNER_REMOVE_SESSION_STATE` | desligado | Remova os diretórios por sessão de uma sessão sob `<base-dir>/_sessions/` quando a sessão terminar neste executor, seja qual for o resultado. [Reuse a pre-warmed checkout](/docs/pt/self-hosted-environments-deploy#reuse-a-pre-warmed-checkout) descreve o que eles contêm e quem pode lê-los quando permanecem. A remoção é melhor esforço: os diretórios por sessão permanecem no lugar quando o executor é morto ou atinge seu prazo de drenagem antes da limpeza ser executada. Com o sinalizador ativado, o log de depuração de uma sessão falhada ou interrompida não é mantido em disco. Requer Claude Code v2.1.268 ou posterior. |

54| `--retire-at <epoch-seconds>` | `SELF_HOSTED_RUNNER_RETIRE_AT` | não definido | Aposentar o executor em um timestamp Unix absoluto em segundos, para infraestrutura que mata o executor em um tempo conhecido; [Runner lifecycle](/docs/pt/self-hosted-environments#runner-lifecycle) descreve a sequência de liberação e como dimensionar a margem. Valores antes de 2001 ou após o ano 5138 são rejeitados pelo sinalizador e ignorados pela variável de ambiente. |54| `--retire-at <epoch-seconds>` | `SELF_HOSTED_RUNNER_RETIRE_AT` | não definido | Aposentar o executor em um timestamp Unix absoluto em segundos, para infraestrutura que mata o executor em um tempo conhecido; [Runner lifecycle](/docs/pt/self-hosted-environments#runner-lifecycle) descreve a sequência de liberação e como dimensionar a margem. Valores antes de 2001 ou após o ano 5138 são rejeitados pelo sinalizador e ignorados pela variável de ambiente. |

55| `--server-auto-mode-lists <mode>` | `SELF_HOSTED_RUNNER_SERVER_AUTO_MODE_LISTS` | `no-allow` | Quais das listas de regras do classificador do [modo auto](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode) que o plano de controle envia com uma sessão podem chegar a essa sessão: `all`, `no-allow` ou `none`. Consulte [Listas de regras do modo auto](#auto-mode-rule-lists) para saber o que cada valor aplica. Um valor inválido interrompe o executor na inicialização. Requer Claude Code v2.1.295 ou posterior. |

55| `--session-stop-grace-sec <n>` | `SELF_HOSTED_RUNNER_SESSION_STOP_GRACE_MS` | `5` | Quanto tempo aguardar para que o processo Claude saia limpo após uma sessão terminar, antes de forçar o encerramento. Aumente o valor se os hooks `SessionEnd` do próprio filho precisarem de mais tempo. |56| `--session-stop-grace-sec <n>` | `SELF_HOSTED_RUNNER_SESSION_STOP_GRACE_MS` | `5` | Quanto tempo aguardar para que o processo Claude saia limpo após uma sessão terminar, antes de forçar o encerramento. Aumente o valor se os hooks `SessionEnd` do próprio filho precisarem de mais tempo. |

56| `--startup-timeout-min <n>` | `SELF_HOSTED_RUNNER_STARTUP_TIMEOUT_MS` | `15` | Libere um slot de sessão se o filho não tiver sinalizado que inicializou dentro de N minutos de geração. Limpo pelo sinal de inicialização do filho no [canal de atividade](/docs/pt/self-hosted-environments-configuration#keep-stdin-and-file-descriptor-3-attached), não por saída ordinária, após o qual `--release-idle-session-min` assume. `0` desabilita. |57| `--startup-timeout-min <n>` | `SELF_HOSTED_RUNNER_STARTUP_TIMEOUT_MS` | `15` | Libere um slot de sessão se o filho não tiver sinalizado que inicializou dentro de N minutos de geração. A clonagem acontece antes da geração, então o tempo de clonagem não conta. Limpo pelo sinal de inicialização do filho no [canal de atividade](/docs/pt/self-hosted-environments-configuration#keep-stdin-and-file-descriptor-3-attached), não por saída ordinária, após o qual `--release-idle-session-min` assume. `0` desabilita. |

57| `--trust-workspace [bool]` | `SELF_HOSTED_RUNNER_TRUST_WORKSPACE` | ativado | Semeie confiança persistida para cada caminho de repositório de sessão para que `permissions.allow` e `additionalDirectories` confirmados no repo sejam honrados. Defina `false` para descartar concessões de permissão confirmadas no repo e configure regras de permissão no `settings.json` da configuração do host em vez disso; configurações `sandbox.*` confirmadas no repositório ainda se aplicam de qualquer forma, é por isso que a [proteção de configurações do repo](/docs/pt/self-hosted-environments-deploy#harden-your-deployment) as verifica independentemente deste sinalizador. |58| `--trust-workspace [bool]` | `SELF_HOSTED_RUNNER_TRUST_WORKSPACE` | ativado | Semeie confiança persistida para cada caminho de repositório de sessão para que `permissions.allow` e `additionalDirectories` confirmados no repo sejam honrados. Defina `false` para descartar concessões de permissão confirmadas no repo e configure regras de permissão no `settings.json` da configuração do host em vez disso; configurações `sandbox.*` confirmadas no repositório ainda se aplicam de qualquer forma, é por isso que a [proteção de configurações do repo](/docs/pt/self-hosted-environments-deploy#harden-your-deployment) as verifica independentemente deste sinalizador. |

58| `--use-anthropic-git-proxy` | `CLAUDE_RUNNER_USE_GIT_PROXY=1` | desligado | Clone via [proxy git da Anthropic](/docs/pt/self-hosted-environments-deploy#use-the-anthropic-git-proxy) em vez de autenticação git gerenciada pelo cliente. Requer `--capacity 1` e git 2.32 ou mais recente; o executor recusa iniciar caso contrário. Substitui os sinalizadores de reescrita. |59| `--use-anthropic-git-proxy` | `CLAUDE_RUNNER_USE_GIT_PROXY=1` | desligado | Clone repositórios no github.com via [proxy git da Anthropic](/docs/pt/self-hosted-environments-deploy#use-the-anthropic-git-proxy) em vez de autenticação git gerenciada pelo cliente. Requer `--capacity 1` e git 2.32 ou mais recente; o executor recusa iniciar caso contrário. Substitui as flags de reescrita. |

59 60

60A maioria dos sinalizadores de duração tem um máximo, escolhido para manter cada tempo limite dentro do teto do temporizador de 32 bits do tempo de execução de aproximadamente 24,85 dias. Os sinalizadores `--*-min` limitam a 10080 minutos, 7 dias; `--drain-grace-sec` a 604800 segundos, também 7 dias; e `--drain-wait-sec` a 86400 segundos, 24 horas. `--session-stop-grace-sec` e `--post-session-hook-timeout-sec` não têm limite. Exceder um limite se comporta diferentemente por superfície:61A maioria dos sinalizadores de duração tem um máximo, escolhido para manter cada tempo limite dentro do teto do temporizador de 32 bits do tempo de execução de aproximadamente 24,85 dias. Os sinalizadores `--*-min` limitam a 10080 minutos, 7 dias; `--drain-grace-sec` a 604800 segundos, também 7 dias; e `--drain-wait-sec` a 86400 segundos, 24 horas. `--session-stop-grace-sec` e `--post-session-hook-timeout-sec` não têm limite. Exceder um limite se comporta diferentemente por superfície:

61 62

62* **Sinalizador**: a inicialização falha com um erro.63* **Sinalizador**: a inicialização falha com um erro.

63* **Variável de ambiente**: o executor fixa o valor ao teto do temporizador em vez de rejeitá-lo.64* **Variável de ambiente**: o executor fixa o valor ao teto do temporizador em vez de rejeitá-lo.

64 65

66<h3 id="auto-mode-rule-lists">

67 Listas de regras do modo auto

68</h3>

70`--server-auto-mode-lists` permite que você decida quais regras do classificador do [modo auto](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode) vindas de fora do executor chegam às sessões nos seus executores. O plano de controle da Anthropic pode enviar listas de regras com uma sessão e pedir ao executor que as aplique. Algumas entradas podem ser regras que um administrador da sua organização escreveu. As listas são `environment`, `soft_deny` e `allow`:

72* **`environment`**: uma entrada pode fazer o classificador permitir mais, assim como menos.

73* **`soft_deny`**: uma entrada bloqueia uma ação, a menos que o usuário a tenha solicitado explicitamente ou uma exceção `allow` se aplique.

74* **`allow`**: as exceções às entradas `soft_deny`.

76O valor da flag escolhe quais listas o executor aplica:

78* **`no-allow`**: o padrão. Aplica `environment` e `soft_deny` e retém `allow`. Uma entrada `environment` ainda pode fazer o classificador permitir mais, então o padrão não descarta todo afrouxamento.

79* **`all`**: aplica as três listas.

80* **`none`**: não aplica nenhuma delas. Escolha `none` para descartar todo afrouxamento vindo dessas listas. Isso também remove as restrições de `soft_deny`.

82Nenhuma configuração do executor faz o plano de controle pedir ao executor que aplique as listas. Quando ele não pede, as sessões não recebem nenhuma lista, seja qual for o valor que você definir. Para ver o que aconteceu, inicie o executor com `--log-level debug`. Para cada sessão, o executor então registra em log uma linha contendo `the server asked this runner to apply`, ou uma contendo `the server did not ask this runner to apply the auto mode lists it sends`.

65<h2 id="orchestrator-cli-flags">84<h2 id="orchestrator-cli-flags">

66 Sinalizadores CLI do orquestrador85 Sinalizadores CLI do orquestrador

67</h2>86</h2>

72| :- | :- | :- |91| :- | :- | :- |

73| `--hook-concurrency <n>` | `4` | Máximo de hooks `spawn-runner` em execução em paralelo. Também limita quantas solicitações de geração são reivindicadas por pesquisa. |92| `--hook-concurrency <n>` | `4` | Máximo de hooks `spawn-runner` em execução em paralelo. Também limita quantas solicitações de geração são reivindicadas por pesquisa. |

74| `--hook-timeout <sec>` | `60` | Encerre a árvore de processos do hook após muitos segundos. O tempo limite mais sua graça de morte de 5 segundos deve ficar abaixo de `--expected-spawn-seconds`; o orquestrador impõe isso na inicialização. |93| `--hook-timeout <sec>` | `60` | Encerre a árvore de processos do hook após muitos segundos. O tempo limite mais sua graça de morte de 5 segundos deve ficar abaixo de `--expected-spawn-seconds`; o orquestrador impõe isso na inicialização. |

75| `--expected-spawn-seconds <sec>` | `120` | Tempo de inicialização p99 esperado para executores gerados, no intervalo imposto pelo servidor de 10 a 3600. Enviado em cada pesquisa como a concessão do lado do servidor; se nenhum executor se registrar antes de decorrido, a sessão é re-oferecida com um novo ID de pedido. Todas as réplicas devem compartilhar este valor. |94| `--expected-spawn-seconds <sec>` | `120` | Tempo p99 esperado desde o momento em que o orquestrador recebe uma requisição de geração até o momento em que o executor se registra, incluindo qualquer espera por capacidade na sua plataforma. O servidor impõe um intervalo de 10 a 3600. Enviado em cada pesquisa como a concessão do lado do servidor: se nenhum executor se registrar antes de decorrido, a sessão é re-oferecida com um novo ID de pedido. Todas as réplicas devem compartilhar este valor. |

76| `--min-idle <n>` | `0` | Mantenha pelo menos N slots de sessão ociosos livres gerando executores de espera de forma proativa. `0` desabilita pré-aquecimento. Emparelhe com o `--exit-if-unused-min` do executor para que executores de espera em excesso se recuperem. |95| `--min-idle <n>` | `0` | Mantenha pelo menos N slots de sessão ociosos livres gerando executores de espera de forma proativa. `0` desabilita pré-aquecimento. Emparelhe com o `--exit-if-unused-min` do executor para que executores de espera em excesso se recuperem. |

78 97

108| `SELF_HOSTED_RUNNER_POST_TURN_SETTLE_MS` | `7000` | Limite superior de quanto tempo o executor conta uma sessão como ocupada para a drenagem `--drain-wait-sec` após um turno terminar, enquanto o processo da sessão relata o fim do turno para a Anthropic. `0` ou um valor inutilizável volta ao padrão, para que a retenção não possa ser desligada. Requer Claude Code v2.1.275 ou posterior. |127| `SELF_HOSTED_RUNNER_POST_TURN_SETTLE_MS` | `7000` | Limite superior de quanto tempo o executor conta uma sessão como ocupada para a drenagem `--drain-wait-sec` após um turno terminar, enquanto o processo da sessão relata o fim do turno para a Anthropic. `0` ou um valor inutilizável volta ao padrão, para que a retenção não possa ser desligada. Requer Claude Code v2.1.275 ou posterior. |

109| `SELF_HOSTED_RUNNER_SIGKILL_GRACE_MS` | `30000` | Quanto tempo o executor aguarda o SO entregar `SIGKILL` para um filho preso em I/O não interruptível antes de sair ele mesmo. Limitado a `--post-session-hook-timeout-sec` mais 15 segundos, e 30 mais quando `--push-outcome-on-release` está definido, então o mínimo efetivo é 75 segundos nos padrões. |128| `SELF_HOSTED_RUNNER_SIGKILL_GRACE_MS` | `30000` | Quanto tempo o executor aguarda o SO entregar `SIGKILL` para um filho preso em I/O não interruptível antes de sair ele mesmo. Limitado a `--post-session-hook-timeout-sec` mais 15 segundos, e 30 mais quando `--push-outcome-on-release` está definido, então o mínimo efetivo é 75 segundos nos padrões. |

110| `CLAUDE_RUNNER_FETCH_DEPTH` | `50` | Profundidade de busca git para clones frescos. Defina um inteiro positivo, ou `full` ou `0` para uma busca completa. Repositórios já presentes no workspace mantêm sua profundidade existente. |129| `CLAUDE_RUNNER_FETCH_DEPTH` | `50` | Profundidade de busca git para clones frescos. Defina um inteiro positivo, ou `full` ou `0` para uma busca completa. Repositórios já presentes no workspace mantêm sua profundidade existente. |

130| `CLAUDE_RUNNER_FETCH_SERVER_PROGRESS_CAP_MS` | `600000` | Quanto tempo em milissegundos, por tentativa, uma busca git pode aguardar seus primeiros dados enquanto os próprios números de progresso do servidor git continuam subindo, como quando o servidor prepara o pack para um repositório grande. `0` ou `off` desativa a espera: essa busca é então interrompida após dois minutos sem dados. Qualquer outro número inteiro é limitado entre `120000` e `1800000`, de 2 a 30 minutos. Requer Claude Code v2.1.295 ou posterior. |

111| `CLAUDE_RUNNER_SKIP_GIT_VERIFY` | não definido | Quando `1`, pule a verificação de presença `.git` após um hook `checkout` ser executado. Defina isso quando seu hook materializa uma fonte não-git. |131| `CLAUDE_RUNNER_SKIP_GIT_VERIFY` | não definido | Quando `1`, pule a verificação de presença `.git` após um hook `checkout` ser executado. Defina isso quando seu hook materializa uma fonte não-git. |

113| `CLAUDE_CODE_DISABLE_ARTIFACT` | não definido | Quando `1`, desabilite a ferramenta Artifact em sessões independentemente da configuração de administrador da organização, e solte o requisito de saída `*.frame.claudeusercontent.com` |133| `CLAUDE_CODE_DISABLE_ARTIFACT` | não definido | Quando `1`, desabilite a ferramenta Artifact em sessões independentemente da configuração de administrador da organização, e solte o requisito de saída `*.frame.claudeusercontent.com` |

178| `claude_code_self_hosted_orchestrator_poll_errors_total{error_kind}` | Falhas cumulativas de PollSpawnHints por tipo: `transport`, `timeout`, `5xx`, `429` ou `4xx`. Todas as cinco séries estão presentes desde o início do processo; alerte em `rate(...[5m]) > 0`. |198| `claude_code_self_hosted_orchestrator_poll_errors_total{error_kind}` | Falhas cumulativas de PollSpawnHints por tipo: `transport`, `timeout`, `5xx`, `429` ou `4xx`. Todas as cinco séries estão presentes desde o início do processo; alerte em `rate(...[5m]) > 0`. |

180| `claude_code_self_hosted_orchestrator_queue_backing_off_sessions` | Solicitações de geração em backoff de repetição após uma falha de hook retentável |200| `claude_code_self_hosted_orchestrator_queue_backing_off_sessions` | Solicitações de geração em backoff de repetição após uma falha de hook retentável |

181| `claude_code_self_hosted_orchestrator_queue_circuit_broken_sessions` | Solicitações de geração bloqueadas até que um Owner as tente novamente na aba **Activity** do ambiente; alerte se acima de zero |201| `claude_code_self_hosted_orchestrator_queue_circuit_broken_sessions` | Sessões impedidas de serem geradas. Cada uma permanece bloqueada até que um usuário envie uma nova mensagem para ela ou um Owner a tente novamente na aba **Activity** do ambiente. A contagem pode permanecer acima de zero depois que você corrigir a causa. Alerte se acima de zero. |

182| `claude_code_self_hosted_orchestrator_pool_pending_sessions` | Total de sessões aguardando um executor para este ambiente. Agregado em toda a organização, idêntico em cada instância do orquestrador: use `MAX` em vez de `SUM` entre instâncias. |202| `claude_code_self_hosted_orchestrator_pool_pending_sessions` | Total de sessões aguardando um executor para este ambiente. Agregado em toda a organização, idêntico em cada instância do orquestrador: use `MAX` em vez de `SUM` entre instâncias. |

183| `claude_code_self_hosted_orchestrator_pool_active_sessions` | Sessões atualmente atribuídas a um executor vivo neste ambiente. Agregado em toda a organização, idêntico em cada instância do orquestrador: use `MAX` em vez de `SUM` entre instâncias. |203| `claude_code_self_hosted_orchestrator_pool_active_sessions` | Sessões atualmente atribuídas a um executor vivo neste ambiente. Agregado em toda a organização, idêntico em cada instância do orquestrador: use `MAX` em vez de `SUM` entre instâncias. |

184| `claude_code_self_hosted_orchestrator_spawn_hooks_total{result}` | Resultados cumulativos de hook `spawn-runner`: `ok`, `retryable`, `non_retryable`. Conta invocações de hook do orquestrador, não filhos de sessão que os executores geram: não comparável a `sessions_started_total`, já que capacidade acima de um, pools quentes e executores gerados novamente para a mesma sessão divergem os dois. |204| `claude_code_self_hosted_orchestrator_spawn_hooks_total{result}` | Resultados cumulativos de hook `spawn-runner`: `ok`, `retryable`, `non_retryable`. Conta invocações de hook do orquestrador, não filhos de sessão que os executores geram: não comparável a `sessions_started_total`, já que capacidade acima de um, pools quentes e executores gerados novamente para a mesma sessão divergem os dois. |

286 for: 1m306 for: 1m

287 labels: {severity: critical}307 labels: {severity: critical}

288 annotations:308 annotations:

289 summary: "{{ $value }} sessões com circuito aberto — hook spawn-runner é repetidamente não retentável; corrija a infraestrutura e tente novamente na aba Activity"309 summary: "Sessões impedidas de serem geradas: {{ $value }}. Leia o erro de cada uma na aba Activity, corrija a causa e então selecione Retry"

290 - alert: ClaudeOrchestratorPollErrors310 - alert: ClaudeOrchestratorPollErrors

291 expr: sum by (pod) (rate(claude_code_self_hosted_orchestrator_poll_errors_total[5m])) > 0311 expr: sum by (pod) (rate(claude_code_self_hosted_orchestrator_poll_errors_total[5m])) > 0

292 for: 2m312 for: 2m

321 341

322Antes da v2.1.260, o executor encerrava cada sessão que atingia seu limite `--kill-session-after-min` e a contava em `sessions_interrupted_total`.342Antes da v2.1.260, o executor encerrava cada sessão que atingia seu limite `--kill-session-after-min` e a contava em `sessions_interrupted_total`.

323 343

324O `CLAUDE_RUNNER_EXIT_REASON` do hook [`post-session`](/docs/pt/self-hosted-environments-configuration#post-session) classifica entregas limpas de forma diferente. O hook relata uma liberação, um tempo limite de inicialização e uma desatribuição do servidor como `interrupted`, porque o executor parou o filho. Esses contadores registram os mesmos eventos como `completed`, porque o slot foi devolvido limpo.344O `CLAUDE_RUNNER_EXIT_REASON` do hook [`post-session`](/docs/pt/self-hosted-environments-configuration#post-session) classifica entregas limpas de forma diferente. O hook relata estes como `interrupted`, porque o executor parou o filho: uma liberação, um tempo limite de inicialização, uma desatribuição do servidor e um arquivamento ou exclusão que a pesquisa notou primeiro. Esses contadores registram os mesmos eventos como `completed`, porque o slot foi devolvido limpo.

325 345

326Se você reconciliar recebimentos de hook contra `sessions_completed_total` diretamente, você subestima as conclusões. Use o hook para garantias por sessão e os contadores para taxas agregadas.346Se você reconciliar recebimentos de hook contra `sessions_completed_total` diretamente, você subestima as conclusões. Use o hook para garantias por sessão e os contadores para taxas agregadas.

327 347

self-hosted-environments-testing.md +14 −4

Details

87 87

88Os sinalizadores de dispatch `--environment` e `--ref` requerem Claude Code v2.1.224 ou posterior na máquina que executa o script, o mesmo piso que o próprio runner. Com o hook em vigor e um runner iniciado neste host, o script de teste:88Os sinalizadores de dispatch `--environment` e `--ref` requerem Claude Code v2.1.224 ou posterior na máquina que executa o script, o mesmo piso que o próprio runner. Com o hook em vigor e um runner iniciado neste host, o script de teste:

89 89

901. Cria uma sessão no ambiente de teste com `claude -p "<prompt>" --environment <environment-id> --output-format json`, executado a partir de um checkout de git para que a CLI possa detectar automaticamente o repositório a partir do remote `origin`. O `--ref <branch>` opcional baseia o checkout da sessão em uma ref nomeada em vez do HEAD local. O comando cria a sessão, imprime uma linha de JSON contendo `session_id` e sai sem aguardar a resposta do Claude.901. Cria uma sessão no ambiente de teste com `claude -p "<prompt>" --environment <environment-id> --output-format json`. Execute o comando a partir de um checkout de git para que a CLI possa detectar automaticamente o repositório a partir do remote `origin`. O `--ref <branch>` opcional baseia o checkout da sessão em uma ref nomeada em vez do HEAD local. O comando sai sem aguardar a resposta do Claude. O que ele imprime informa ao seu script o resultado:

91 * **Sessão criada**: uma linha de JSON como `{"ok":true,"session_id":"session_...","title":"...","url":"...","pool_id":"..."}`

92 * **Falha na criação da sessão**: a linha `{"ok":false,"error":"..."}`, e o comando sai com status 1

93 * **Alguns erros anteriores**, como sessões na nuvem indisponíveis para sua organização ou um prompt ausente: o erro no stderr sem linha de JSON, e o comando sai com status 1

912. Aguarda a resposta aparecer em `$E2E_REPLY_DIR/<session_id>.txt`, escrita pelo hook Stop no runner assim que o turno é concluído.942. Aguarda a resposta aparecer em `$E2E_REPLY_DIR/<session_id>.txt`, escrita pelo hook Stop no runner assim que o turno é concluído.

923. Envia um acompanhamento com `claude -p "<message>" --cloud <session_id> --output-format json` (consulte [Enviar uma mensagem de acompanhamento para uma sessão em execução](/docs/pt/claude-code-on-the-web#send-follow-ups-from-the-cli)), que publica um evento de usuário na sessão existente e sai.953. Envia um acompanhamento com `claude -p "<message>" --cloud <session_id> --output-format json` (consulte [Enviar uma mensagem de acompanhamento para uma sessão em execução](/docs/pt/claude-code-on-the-web#send-follow-ups-from-the-cli)), que publica um evento de usuário na sessão existente e sai.

934. Aguarda a resposta do acompanhamento da mesma forma que a etapa 2.964. Aguarda a resposta do acompanhamento da mesma forma que a etapa 2.

104 Script de exemplo107 Script de exemplo

105</h2>108</h2>

106 109

107O script abaixo executa o loop completo contra `$CLAUDE_TEST_ENVIRONMENT_ID`, o ID `ccpool_...` do seu ambiente de teste, mostrado no diálogo de detalhes do ambiente na página de administração ou retornado pela [chamada create-environment](#create-a-dedicated-test-environment), e afirma uma frase sentinela em cada resposta. Execute-o a partir de um checkout de git do repositório no qual você deseja que a sessão funcione, após iniciar um runner neste host com o hook de captura instalado e `E2E_REPLY_DIR` exportado. Primeiro, faça login com uma conta claude.ai na máquina que executa o script, conforme descrito em [Autenticar a partir de CI](#authenticate-from-ci). Sem esse login, o primeiro envio falha com um erro como `Unable to get organization UUID for cloud session creation`.110O script de exemplo é executado na mesma máquina que o executor de testes. Antes de executá-lo, prepare essa máquina:

111

112* **Checkout do repositório**: execute o script a partir de um checkout de git do repositório no qual você deseja que a sessão funcione.

113* **Runner**: inicie um runner neste host com o hook de captura instalado e `E2E_REPLY_DIR` exportado.

114* **Login**: faça login com uma conta claude.ai na máquina que executa o script, conforme descrito em [Autenticar a partir de CI](#authenticate-from-ci).

115* **ID do ambiente**: defina `CLAUDE_TEST_ENVIRONMENT_ID` como o ID `ccpool_...` do seu ambiente de teste, mostrado no diálogo de detalhes do ambiente na página de administração ou retornado pela [chamada create-environment](#create-a-dedicated-test-environment).

116

117O script abaixo executa o loop completo contra `$CLAUDE_TEST_ENVIRONMENT_ID` e afirma uma frase sentinela em cada resposta.

108 118

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

110#!/usr/bin/env bash120#!/usr/bin/env bash

152TURN1="e2e-probe-$(date +%s)-$$: say exactly 'ok: custom tools are reachable' and nothing else"162TURN1="e2e-probe-$(date +%s)-$$: say exactly 'ok: custom tools are reachable' and nothing else"

153EXPECT1="ok: custom tools are reachable"163EXPECT1="ok: custom tools are reachable"

154create_json=$(claude -p "$TURN1" --environment "$CLAUDE_TEST_ENVIRONMENT_ID" \164create_json=$(claude -p "$TURN1" --environment "$CLAUDE_TEST_ENVIRONMENT_ID" \

155 --ref "$TEST_REPO_REF" --output-format json)165 --ref "$TEST_REPO_REF" --output-format json < /dev/null)

156echo "create: $create_json"166echo "create: $create_json"

157SESSION_ID=$(jq -er '.session_id' <<<"$create_json")167SESSION_ID=$(jq -er '.session_id' <<<"$create_json")

158 168

163# 3. Post a follow-up via the CLI.173# 3. Post a follow-up via the CLI.

164TURN2="e2e-probe-followup-$(date +%s): say exactly 'ok: follow-up delivered' and nothing else"174TURN2="e2e-probe-followup-$(date +%s): say exactly 'ok: follow-up delivered' and nothing else"

165EXPECT2="ok: follow-up delivered"175EXPECT2="ok: follow-up delivered"

166followup_json=$(claude -p "$TURN2" --cloud "$SESSION_ID" --output-format json)176followup_json=$(claude -p "$TURN2" --cloud "$SESSION_ID" --output-format json < /dev/null)

167echo "followup: $followup_json"177echo "followup: $followup_json"

168jq -e '.ok == true' <<<"$followup_json" >/dev/null178jq -e '.ok == true' <<<"$followup_json" >/dev/null

169 179

sessions.md +43 −41

Details

6 6

7> Nomeie, retome, ramifique e alterne entre conversas do Claude Code. Abrange `--continue`, `--resume`, `--from-pr`, o seletor `/resume`, nomeação de sessão, exportação de transcritos e onde os transcritos são armazenados.7> Nomeie, retome, ramifique e alterne entre conversas do Claude Code. Abrange `--continue`, `--resume`, `--from-pr`, o seletor `/resume`, nomeação de sessão, exportação de transcritos e onde os transcritos são armazenados.

8 8

9Uma sessão é uma conversa salva vinculada a um diretório de projeto. Claude Code a armazena localmente conforme você trabalha, para que você possa retomar de onde parou, ramificar para tentar uma abordagem diferente ou alternar entre tarefas.9Uma [sessão](/docs/pt/glossary#session) é uma conversa salva vinculada a um diretório de projeto. Claude Code a armazena localmente conforme você trabalha, para que você possa retomar de onde parou, criar um branch para tentar uma abordagem diferente ou alternar entre tarefas.

10 10

11O [aplicativo desktop](/docs/pt/desktop#work-in-parallel-with-sessions), [claude.ai/code](/docs/pt/claude-code-on-the-web) e a [extensão VS Code](/docs/pt/vs-code#resume-past-conversations) cada um mantém sua própria lista de sessões, e o aplicativo desktop também pode [retomar uma sessão CLI](/docs/pt/desktop#coming-from-the-cli). Esta página abrange a CLI.11O [aplicativo desktop](/docs/pt/desktop#work-in-parallel-with-sessions), [claude.ai/code](/docs/pt/claude-code-on-the-web) e a [extensão VS Code](/docs/pt/vs-code#resume-past-conversations) cada um mantém sua própria lista de sessões, e o aplicativo desktop também pode [retomar uma sessão CLI](/docs/pt/desktop#coming-from-the-cli). Esta página abrange a CLI.

12 12

18 18

19| Comando | O que faz |19| Comando | O que faz |

20| :- | :- |20| :- | :- |

22| `claude --resume` | Abre o [seletor de sessão](#use-the-session-picker) |22| `claude --resume` | Abre o [seletor de sessão](#use-the-session-picker) |

23| `claude --resume <name>` | Retoma a sessão nomeada diretamente |23| `claude --resume <name>` | Retoma a sessão nomeada diretamente |

~~24| `claude --resume <transcript-path>` | Retoma a conversa armazenada no arquivo de [transcrição](#where-transcripts-are-stored) `.jsonl` nesse caminho absoluto |~~24| `claude --resume <transcript-path>` | Retoma a sessão armazenada no [arquivo de transcrição](#where-transcripts-are-stored) `.jsonl` nesse caminho absoluto |

25| `claude --from-pr <number>` | Abre o seletor de sessão filtrado para sessões vinculadas a esse pull request |25| `claude --from-pr <number>` | Abre o seletor de sessão filtrado para sessões vinculadas a esse pull request |

28Claude Code deixa as sessões criadas com [`claude -p`](/docs/pt/headless) ou o [Agent SDK](/docs/pt/agent-sdk/overview) fora do seletor de sessão e fora de `claude --continue`. Você ainda pode retomar uma passando seu ID de sessão para `claude --resume <session-id>`. Com `claude --continue`, Claude Code também pula [sessões cujo primeiro prompt foi `/loop`](#where-the-session-picker-looks). Quando você executa [`claude -p --continue`](/docs/pt/headless#continue-conversations), Claude Code inclui sessões `-p`, SDK e `/loop`.

30Você pode executar `claude --resume <session-id>` de qualquer diretório, para que possa retomar uma sessão que começou em outro lugar ou se moveu com [`/cd`](/docs/pt/commands). Claude Code procura o ID nesta ordem:

~~321. O diretório do projeto atual e seus git worktrees~~

~~332. Todos os outros projetos nesta máquina~~

35A busca entre projetos resolve o ID apenas quando exatamente um outro projeto contém uma transcrição com mensagens para ele, portanto uma duplicata copiada manualmente faz Claude Code relatar não encontrado em vez de retomar uma cópia arbitrária. Se nenhuma sessão armazenada corresponder ao ID, Claude Code relata `No conversation found with session ID: <session-id>`.

~~37Antes da v2.1.223, a busca parava no diretório do projeto atual e seus git worktrees, portanto você tinha que retomar do diretório em que a sessão trabalhou por último.~~

39`claude --continue` abre uma [sessão em background](/docs/pt/agent-view) que foi concluída, mas não uma que ainda está em execução; abrir sessões em background concluídas requer Claude Code v2.1.257 ou posterior. Se sua conversa mais recente for uma que você [moveu para o background](/docs/pt/agent-view#send-the-session-to-the-background) e ainda estiver em execução lá, Claude Code sai com `Your most recent conversation is running in the background` e o ID dessa sessão. Anexe à sessão a partir de [`claude agents`](/docs/pt/agent-view#attach-to-a-session), ou execute `claude --resume` para escolher outra.

40 27

41<h3 id="resume-a-running-background-session">28<h3 id="resume-a-running-background-session">

42 Retomar uma sessão em background em execução29 Retomar uma sessão em background em execução

64 51

65Quando Claude Code carrega uma conversa de sua transcrição, a sessão retomada restaura a conversa junto com o estado salvo nela:52Quando Claude Code carrega uma conversa de sua transcrição, a sessão retomada restaura a conversa junto com o estado salvo nela:

66 53

67* Histórico de conversa: o histórico completo, incluindo chamadas de ferramenta e resultados. Uma ferramenta que ainda estava em execução quando o processo anterior terminou, por exemplo em uma falha, não termina ou executa novamente quando você retoma. Claude vê a chamada marcada como interrompida antes de seu resultado ser registrado e é instruído a verificar se ela teve efeito antes de executá-la novamente, a menos que [`CLAUDE_CODE_RESUME_INTERRUPTED_TURN`](/docs/pt/env-vars#variables) esteja definido. Antes da v2.1.281, Claude Code descartava a chamada interrompida da conversa ou a mostrava a Claude como uma que você interrompeu.54* Histórico de conversa: o histórico completo, incluindo chamadas de ferramenta e resultados. Uma ferramenta que ainda estava em execução quando o processo anterior terminou, por exemplo em uma falha, não termina ou executa novamente quando você retoma. Claude vê a chamada marcada como interrompida antes de seu resultado ser registrado e é instruído a verificar se ela teve efeito antes de executá-la novamente, a menos que [`CLAUDE_CODE_RESUME_INTERRUPTED_TURN`](/docs/pt/env-vars#variables) esteja definido.

68* Modelo: a sessão continua no modelo que estava usando, exceto nos casos descritos em [Configurar seu modelo](/docs/pt/model-config#setting-your-model).55* Modelo: a sessão continua no modelo que estava usando, exceto nos casos descritos em [Configurar seu modelo](/docs/pt/model-config#setting-your-model).

69* Agente: uma sessão iniciada com [`--agent`](/docs/pt/sub-agents#invoke-subagents-explicitly) ou a configuração `agent` continua como esse agente, mantendo suas restrições de ferramentas e modelo. Passe `--agent` ao retomar para escolher um diferente; para o system prompt em ambos os casos, veja [Flags de system prompt em conversas retomadas](/docs/pt/cli-reference#system-prompt-flags-in-resumed-conversations). Claude Code procura o agente em dois lugares: o diretório original da sessão, desde que você tenha [confiado nesse workspace](/docs/pt/permissions#project-allow-rules-and-workspace-trust), e depois o diretório de onde você retoma, para que um agente com escopo de projeto ainda carregue quando você retoma de outro diretório. Se Claude Code não encontrar o agente em nenhum dos dois lugares, a sessão retoma com as ferramentas padrão e mostra um [aviso nomeando o agente](/docs/pt/errors#session-agent-no-longer-available).56* Agente: uma sessão iniciada com [`--agent`](/docs/pt/sub-agents#invoke-subagents-explicitly) ou a configuração `agent` continua como esse agente, mantendo suas restrições de ferramentas e modelo. Passe `--agent` ao retomar para escolher um diferente; para o system prompt em ambos os casos, veja [Flags de system prompt em conversas retomadas](/docs/pt/cli-reference#system-prompt-flags-in-resumed-conversations). Claude Code procura o agente em dois lugares: o diretório original da sessão, desde que você tenha [confiado nesse workspace](/docs/pt/permissions#project-allow-rules-and-workspace-trust), e depois o diretório de onde você retoma, para que um agente com escopo de projeto ainda carregue quando você retoma de outro diretório. Se Claude Code não encontrar o agente em nenhum dos dois lugares, a sessão retoma com as ferramentas padrão e mostra um [aviso nomeando o agente](/docs/pt/errors#session-agent-no-longer-available).

70* Modo de permissão: se você retomar de um terminal com `claude --continue`, `claude --resume <session-id>` ou `claude --resume <name>` quando o nome corresponde a uma sessão, sem `-p`, Claude Code restaura o modo de permissão em que a sessão estava, exceto nos casos em [modo de permissão ao retomar](#permission-mode-on-resume), que também cobre o seletor de sessão, `/resume` e retomar com `claude -p`. Passe `--permission-mode` ou `--dangerously-skip-permissions` para sobrescrever o modo restaurado.57* Modo de permissão: se você retomar de um terminal com `claude --continue`, `claude --resume <session-id>` ou `claude --resume <name>` quando o nome corresponde a uma sessão, sem `-p`, Claude Code restaura o modo de permissão em que a sessão estava, exceto nos casos em [modo de permissão ao retomar](#permission-mode-on-resume), que também cobre o seletor de sessão, `/resume` e retomar com `claude -p`. Passe `--permission-mode` ou `--dangerously-skip-permissions` para sobrescrever o modo restaurado.

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

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

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

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

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

88 75

76Se uma [regra de negação](/docs/pt/permissions#manage-permissions) remover a ferramenta [`ExitPlanMode`](/docs/pt/tools-reference), Claude não pode apresentar um plano para aprovação, portanto Claude Code não restaura o modo de planejamento. A sessão inicia no modo de permissão em que uma nova sessão iniciaria a partir da mesma linha de comando. Com `/resume`, a conversa continua no seu modo de permissão atual.

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

90 79

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

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

84| `plan` | Terminal, quando uma regra de negação remove `ExitPlanMode` | O modo de permissão em que uma nova sessão iniciaria |

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

110* Você não passa `--permission-mode` ou `--dangerously-skip-permissions`100* Você não passa `--permission-mode` ou `--dangerously-skip-permissions`

111* Você não passa `--fork-session`101* Você não passa `--fork-session`

112* A execução não é iniciada através de [canais](/docs/pt/channels)102* A execução não é iniciada através de [canais](/docs/pt/channels)

103* Nenhuma [regra de negação](/docs/pt/permissions#manage-permissions) remove a ferramenta `ExitPlanMode`

113 104

114<h3 id="resume-from-a-summary">105<h3 id="resume-from-a-summary">

115 Retomar de um resumo106 Retomar de um resumo

117 108

118Em um plano Pro ou Max, quando você retoma uma sessão que ficou inativa por mais de cerca de uma hora e tem mais de 100.000 tokens, Claude Code restaura a conversa e depois abre um diálogo antes de você enviar sua primeira mensagem. O [cache de prompt](/docs/pt/prompt-caching#cache-lifetime) da sessão terá expirado até então, portanto a próxima requisição processa o histórico completo uma vez, não importa qual das opções do diálogo você escolha.109Em um plano Pro ou Max, quando você retoma uma sessão que ficou inativa por mais de cerca de uma hora e tem mais de 100.000 tokens, Claude Code restaura a conversa e depois abre um diálogo antes de você enviar sua primeira mensagem. O [cache de prompt](/docs/pt/prompt-caching#cache-lifetime) da sessão terá expirado até então, portanto a próxima requisição processa o histórico completo uma vez, não importa qual das opções do diálogo você escolha.

119 110

120O diálogo oferece três maneiras de continuar a sessão. Elas diferem em quanto da conversa cada uma carrega para requisições posteriores, o que é uma troca entre manter cada detalhe e enviar menos tokens por requisição:111O diálogo oferece três maneiras de continuar a sessão:

121 112

122* **Retomar do resumo**: executa [`/compact`](/docs/pt/context-window#what-survives-compaction) imediatamente. Claude Code envia uma requisição de resumo sobre o histórico completo, depois substitui o histórico pelo resumo, suas trocas mais recentes e até cinco arquivos lidos recentemente. Requisições posteriores carregam o resumo em vez do histórico completo.113* **Retomar do resumo**: executa [`/compact`](/docs/pt/context-window#what-survives-compaction) imediatamente. Requisições posteriores carregam o resumo em vez do histórico completo.

123* **Retomar sessão completa como está**: carrega a conversa inalterada. Depois que você envia sua primeira mensagem, Claude Code reprocessa e armazena novamente em cache o histórico completo, depois o relê do cache em requisições posteriores enquanto o cache permanece aquecido.114* **Retomar sessão completa como está**: carrega a conversa inalterada.

124* **Não me pergunte novamente**: retoma a sessão completa e para de mostrar o diálogo em todas as futuras retomadas.115* **Não me pergunte novamente**: retoma a sessão completa e para de mostrar o diálogo em todas as futuras retomadas.

125 116

126Retomar como está mantém cada detalhe da conversa disponível, a um custo por requisição que escala com o tamanho da conversa. Retomar do resumo custa menos em cada requisição posterior porque carrega o resumo em vez do histórico completo, mas o que quer que o resumo deixe de fora não está mais no contexto de Claude. Veja [por que o uso sobe em uma sessão longa](/docs/pt/costs#why-usage-climbs-in-a-long-session) para saber de onde vem esse custo por requisição.117Retomar como está mantém cada detalhe da conversa disponível, a um custo por requisição que escala com o tamanho da conversa. Retomar do resumo custa menos em cada requisição posterior porque carrega o resumo em vez do histórico completo, mas o que quer que o resumo deixe de fora não está mais no contexto de Claude. Veja [por que o uso sobe em uma sessão longa](/docs/pt/costs#why-usage-climbs-in-a-long-session) para saber de onde vem esse custo por requisição.

136 127

137Use `Ctrl+W` para expandir para todos os worktrees do repositório ou `Ctrl+A` para expandir para cada projeto nesta máquina.128Use `Ctrl+W` para expandir para todos os worktrees do repositório ou `Ctrl+A` para expandir para cada projeto nesta máquina.

138 129

139Sessões cujo primeiro prompt foi um comando [`/loop`](/docs/pt/scheduled-tasks#run-a-prompt-repeatedly-with-%2Floop) não aparecem no seletor, e `claude --continue` também as pula. Executar `/loop` mais tarde em uma conversa não oculta a sessão. Antes da v2.1.211, uma execução `/loop` no início de uma conversa ocultava a sessão do seletor permanentemente.130<h4 id="/loop-p-agent-sdk-and-background-sessions">

131 `/loop`, `-p`, Agent SDK e sessões em background

132</h4>

133

134Sessões cujo primeiro prompt foi um comando [`/loop`](/docs/pt/scheduled-tasks#run-a-prompt-repeatedly-with-%2Floop) não aparecem no seletor, e `claude --continue` também as pula. Executar `/loop` mais tarde em uma conversa não oculta a sessão.

135

136Claude Code deixa as sessões criadas com [`claude -p`](/docs/pt/headless) ou o [Agent SDK](/docs/pt/agent-sdk/overview) fora do seletor de sessão e fora de `claude --continue`. Você ainda pode retomar uma passando seu ID de sessão para `claude --resume <session-id>`. Quando você executa [`claude -p --continue`](/docs/pt/headless#continue-conversations), Claude Code inclui sessões `-p`, SDK e `/loop`.

140 137

141Mover uma sessão com [`/cd`](/docs/pt/commands) a realoca para o armazenamento de projeto do novo diretório, para que apareça no seletor desse diretório depois. A partir da v2.1.196, uma sessão movida fica fora do seletor do diretório antigo mesmo após uma falha ou saída forçada. Em versões anteriores, ela também poderia reaparecer na lista do diretório antigo após uma saída que não foi limpa quando o caminho antigo continha caracteres especiais como sublinhados.138`claude --continue` abre uma [sessão em background](/docs/pt/agent-view) que foi concluída, mas não uma que ainda está em execução; abrir sessões em background concluídas requer Claude Code v2.1.257 ou posterior. Se sua conversa mais recente for uma que você [moveu para o background](/docs/pt/agent-view#send-the-session-to-the-background) e ainda estiver em execução lá, Claude Code sai com `Your most recent conversation is running in the background` e o ID dessa sessão. Anexe à sessão a partir de [`claude agents`](/docs/pt/agent-view#attach-to-a-session), ou execute `claude --resume` para escolher outra.

139

140<h4 id="sessions-in-other-worktrees-and-projects">

141 Sessões em outros worktrees e projetos

142</h4>

142 143

143Quando você seleciona uma sessão de outro worktree do mesmo repositório, Claude Code a retoma no local; quando o próprio worktree da sessão não existe mais, Claude Code [a retoma no seu diretório atual](/docs/pt/worktrees#resume-a-worktree-session). Quando você seleciona uma sessão de um projeto não relacionado, Claude Code copia um comando `cd` e de retomada para sua área de transferência em vez disso. Se o diretório desse projeto não existir mais, Claude Code retoma a sessão no seu diretório atual em vez de copiar um comando `cd` que falharia.144Quando você seleciona uma sessão de outro worktree do mesmo repositório, Claude Code a retoma no local; quando o próprio worktree da sessão não existe mais, Claude Code [a retoma no seu diretório atual](/docs/pt/worktrees#resume-a-worktree-session). Quando você seleciona uma sessão de um projeto não relacionado, Claude Code copia um comando `cd` e de retomada para sua área de transferência em vez disso. Se o diretório desse projeto não existir mais, Claude Code retoma a sessão no seu diretório atual em vez de copiar um comando `cd` que falharia.

144 145

146Mover uma sessão com [`/cd`](/docs/pt/commands) a realoca para o armazenamento de projeto do novo diretório, para que apareça no seletor desse diretório depois.

147

148<h4 id="resume-by-session-id-or-name">

149 Retomar por ID de sessão ou nome

150</h4>

151

152Você pode executar `claude --resume <session-id>` de qualquer diretório, para que possa retomar uma sessão que começou em outro lugar ou se moveu com [`/cd`](/docs/pt/commands). Claude Code procura o ID nesta ordem:

153

1541. O diretório do projeto atual e seus git worktrees

1552. Todos os outros projetos nesta máquina

156

157A busca entre projetos resolve o ID apenas quando exatamente um outro projeto contém uma transcrição com mensagens para ele, portanto uma duplicata copiada manualmente faz Claude Code relatar não encontrado em vez de retomar uma cópia arbitrária. Se nenhuma sessão armazenada corresponder ao ID, Claude Code relata `No conversation found with session ID: <session-id>`.

158

145Retomar por nome resolve no repositório atual e seus worktrees. Ambas as formas procuram por uma correspondência exata e a retomam diretamente mesmo que resida em um worktree diferente:159Retomar por nome resolve no repositório atual e seus worktrees. Ambas as formas procuram por uma correspondência exata e a retomam diretamente mesmo que resida em um worktree diferente:

146 160

166 180

167Depois que você nomeia uma sessão através de uma rota CLI ou do claude.ai, retorne a ela com `claude --resume <name>` ou `/resume <name>`; uma sessão do aplicativo desktop retoma no [aplicativo desktop](/docs/pt/desktop#work-in-parallel-with-sessions). Veja [Retomar uma sessão](#resume-a-session) para saber como a resolução de nomes se comporta entre worktrees.181Depois que você nomeia uma sessão através de uma rota CLI ou do claude.ai, retorne a ela com `claude --resume <name>` ou `/resume <name>`; uma sessão do aplicativo desktop retoma no [aplicativo desktop](/docs/pt/desktop#work-in-parallel-with-sessions). Veja [Retomar uma sessão](#resume-a-session) para saber como a resolução de nomes se comporta entre worktrees.

168 182

169Quando você inicia ou retoma uma sessão interativa com um nome que outra sessão ativa nesta máquina já usa, ou renomeia uma sessão para tal nome, Claude Code deixa o nome com a sessão que já o possui, renomeia a sua para uma variante com um sufixo de duas palavras, como `auth-refactor-graceful-unicorn`, e avisa você. Execute `/rename` com um novo nome se preferir escolher um você mesmo. Antes da v2.1.232, ambas as sessões mantinham o nome.

~~170~~

171Em três casos Claude Code não renomeia a duplicata, então você ainda pode ver duas sessões com o mesmo nome em listagens:

~~172~~

173* Não verifica títulos gerados por IA ou nomes de exibição padrão.

174* Não verifica o `--name` de uma sessão [background](/docs/pt/agent-view#from-your-shell) ou `-p` na inicialização.

175* Não consegue renomear uma sessão em uma versão anterior do Claude Code.

~~176~~

177Sessões que você não nomeia ainda recebem dois rótulos que Claude Code atribui. Apenas o título gerado funciona como um identificador de retomada:183Sessões que você não nomeia ainda recebem dois rótulos que Claude Code atribui. Apenas o título gerado funciona como um identificador de retomada:

178 184

179* Nome de exibição padrão: sessões interativas que você nunca nomeia ainda recebem um nome de exibição padrão quando iniciam. Requer Claude Code v2.1.196 ou posterior. O padrão combina o nome do diretório de trabalho com um sufixo de dois caracteres, por exemplo `my-app-3f`, e identifica a sessão em listagens de sessões em execução, como [agent view](/docs/pt/agent-view) e saída de `claude agents --json`. O padrão não é um identificador de retomada. Se você o passar para `claude --resume` ou `/resume`, Claude Code não encontra a sessão. Nomear a sessão substitui o padrão nessas listagens, e assim faz aceitar um plano.185* Nome de exibição padrão: sessões interativas que você nunca nomeia ainda recebem um nome de exibição padrão quando iniciam. Requer Claude Code v2.1.196 ou posterior. O padrão combina o nome do diretório de trabalho com um sufixo de dois caracteres, por exemplo `my-app-3f`, e identifica a sessão em listagens de sessões em execução, como [agent view](/docs/pt/agent-view) e saída de `claude agents --json`. O padrão não é um identificador de retomada. Se você o passar para `claude --resume` ou `/resume`, Claude Code não encontra a sessão.

180* Título gerado: se você não nomear uma sessão, Claude Code gera um título de sessão para ela. O título é um resumo breve do seu primeiro prompt, escrito por uma solicitação em background para o modelo pequeno/rápido, normalmente um modelo da classe Haiku. Um `claude -p` executado que você inicia diretamente de um shell ou script não recebe um.186* Título gerado: se você não nomear uma sessão, Claude Code gera um título de sessão para ela. O título é um resumo breve do seu primeiro prompt, escrito por uma solicitação em background para o modelo pequeno/rápido, normalmente um modelo da classe Haiku. Um `claude -p` executado que você inicia diretamente de um shell ou script não recebe um.

181 187

182 Aceitar um plano substitui o título do primeiro prompt por um título baseado no plano. Nomear a sessão também o substitui.188 Aceitar um plano substitui o título gerado por um título baseado no plano. Você pode passar qualquer um dos títulos para `claude --resume` ou `/resume`, e Claude Code o resolve da mesma forma que um nome que você definiu.

~~183~~

184 Você vê o título do primeiro prompt no [seletor de sessão](#use-the-session-picker) e no campo [`session_name`](/docs/pt/statusline) da statusline quando nenhum nome está definido. O título do plano aparece nos mesmos dois lugares e também nas listagens de sessões em execução, onde substitui o nome de exibição padrão.

~~185~~

186 Você pode passar qualquer um dos títulos para `claude --resume` ou `/resume`, e Claude Code o resolve da mesma forma que um nome que você definiu.

187 189

188<h2 id="use-the-session-picker">190<h2 id="use-the-session-picker">

189 Use o seletor de sessão191 Use o seletor de sessão

206| `Esc` | Sair do seletor de sessão ou modo de pesquisa |208| `Esc` | Sair do seletor de sessão ou modo de pesquisa |

207 209

208Cada linha mostra o nome da sessão se você definir um, caso contrário, o título de sessão gerado por IA, resumo da conversa ou primeiro prompt, junto com o tempo desde a última atividade, branch git e tamanho do arquivo. Expanda para todos os projetos com `Ctrl+A` para também ver o caminho do projeto de cada sessão.210Cada linha mostra o nome da sessão se você definir um, caso contrário, o título de sessão gerado por IA, resumo da conversa ou primeiro prompt, junto com o tempo desde a última atividade, branch git e tamanho do arquivo.

209 211

210As sessões criadas com `/branch` ou `--fork-session` recebem seus próprios IDs de sessão e aparecem como linhas separadas. Quando o seletor encontra mais de uma entrada para a mesma sessão, ele as agrupa sob uma única linha. Pressione `→` para expandir um grupo.212As sessões criadas com `/branch` ou `--fork-session` recebem seus próprios IDs de sessão e aparecem como linhas separadas. Quando o seletor encontra mais de uma entrada para a mesma sessão, ele as agrupa sob uma única linha. Pressione `→` para expandir um grupo.

211 213

223/branch try-streaming-approach225/branch try-streaming-approach

224```226```

225 227

226Se você omitir o nome, Claude Code nomeia o novo branch após o primeiro prompt na conversa. A partir da v2.1.198, isso também se aplica após [compaction](/docs/pt/how-claude-code-works#when-context-fills-up); versões anteriores voltavam para o nome literal `Branched conversation` em vez de procurar além do resumo de compaction para o primeiro prompt original.228Se você omitir o nome, Claude Code nomeia o novo branch com base no primeiro prompt da conversa.

227 229

228Na linha de comando, combine `--continue` ou `--resume` com `--fork-session`:230Na linha de comando, combine `--continue` ou `--resume` com `--fork-session`:

229 231

250 252

251Estes comandos controlam o que está na janela de contexto sem deixar a sessão:253Estes comandos controlam o que está na janela de contexto sem deixar a sessão:

252 254

253* **`/clear`**: comece do zero com um contexto vazio. Claude Code salva a conversa anterior; retome-a com `/resume`, ou, no mesmo processo Claude Code, a partir da [entrada de sessão anterior do menu de rewind](/docs/pt/checkpointing#rewind-past-a-cleared-conversation). Sem argumentos, a nova conversa mantém um nome que você definiu com `--name` ou `/rename`, mas não um título de sessão gerado por IA. Para nomear a conversa que você está deixando, passe o nome, como em `/clear release-prep`; a nova conversa então começa sem nome255* **`/clear`**: comece do zero com um contexto vazio. Claude Code salva a sessão anterior; retome-a com `/resume`, ou, no mesmo processo Claude Code, a partir da [entrada de sessão anterior do menu de rewind](/docs/pt/checkpointing#rewind-past-a-cleared-conversation). Sem argumentos, a nova sessão mantém um nome que você definiu com `--name` ou `/rename`, mas não um título de sessão gerado por IA. Para nomear a sessão que você está deixando, passe o nome, como em `/clear release-prep`; a nova sessão então começa sem nome

254* **`/compact [instructions]`**: substitua o histórico por um resumo, opcionalmente focado no que você especificar256* **`/compact [instructions]`**: substitua o histórico por um resumo, opcionalmente focado no que você especificar

255* **`/context`**: mostrar o que está consumindo contexto atualmente257* **`/context`**: mostrar o que está consumindo contexto atualmente

256 258

settings.md +2 −2

Details

495 495

496Antes da v2.1.211, o Claude Code mantinha o arquivo no diretório inicial. Ele ainda lê um arquivo que uma versão anterior deixou lá ao lado do arquivo raiz; onde ambos definem a mesma chave, o valor da raiz se aplica, e regras de permissão de ambos os arquivos se aplicam. O helper [`resolveSettings()`](/docs/pt/agent-sdk/typescript#resolvesettings) do Agent SDK sempre lê o arquivo do diretório inicial.496Antes da v2.1.211, o Claude Code mantinha o arquivo no diretório inicial. Ele ainda lê um arquivo que uma versão anterior deixou lá ao lado do arquivo raiz; onde ambos definem a mesma chave, o valor da raiz se aplica, e regras de permissão de ambos os arquivos se aplicam. O helper [`resolveSettings()`](/docs/pt/agent-sdk/typescript#resolvesettings) do Agent SDK sempre lê o arquivo do diretório inicial.

497 497

498O Claude Code lê o `.claude/settings.json` compartilhado do [diretório de trabalho primário](/docs/pt/permissions#working-directories) da sessão, então para usar um arquivo incluído no commit na raiz do repositório, inicie o Claude Code lá. Depois que você [mover a sessão com `/cd`](/docs/pt/permissions#move-the-session-to-another-directory), o Claude Code lê ambos os arquivos do projeto do novo diretório em vez disso, colocando o arquivo local pelas mesmas regras. Lê-los do diretório para o qual você se moveu requer Claude Code v2.1.246 ou posterior.498O Claude Code lê o `.claude/settings.json` compartilhado do [diretório de trabalho primário](/docs/pt/permissions#working-directories) da sessão, então para usar um arquivo incluído no commit na raiz do repositório, inicie o Claude Code lá. Depois que você [mover a sessão com `/cd`](/docs/pt/permissions#move-the-session-to-another-directory), o Claude Code lê ambos os arquivos do projeto do novo diretório em vez disso, colocando o arquivo local pelas mesmas regras. Lê-los do diretório para o qual você se moveu requer Claude Code v2.1.246 ou posterior. Para uma sessão de worktree que você inicia a partir do aplicativo desktop, veja [O que os worktrees compartilham com o checkout principal](/docs/pt/worktrees#what-worktrees-share-with-the-main-checkout).

499 499

500<span id="managed-settings-delivery" />500<span id="managed-settings-delivery" />

501 501

767 767

768Duas coisas mantêm uma chave em `.claude/settings.json` de se aplicar para todos que a clonam:768Duas coisas mantêm uma chave em `.claude/settings.json` de se aplicar para todos que a clonam:

769 769

770* **O Claude Code ignora a chave em um arquivo de repositório.** Procure por `User, local, or managed`, `User or managed`, `Managed` ou `Global config` na coluna Scope do [índice de configurações](/docs/pt/settings-reference#settings-index). Essas chaves nunca se aplicam do arquivo compartilhado, exceto por algumas que um arquivo de repositório ainda pode desligar. Cada uma dessas entradas diz assim em sua linha de Scope. As chaves `Global config` se aplicam apenas de `~/.claude.json`.770* **O Claude Code ignora a chave em um arquivo de repositório.** Procure por `User, local, or managed`, `User or managed`, `User`, `Managed` ou `Global config` na coluna Scope do [índice de configurações](/docs/pt/settings-reference#settings-index). Essas chaves nunca se aplicam do arquivo compartilhado, exceto por algumas que um arquivo de repositório ainda pode desligar. Cada uma dessas entradas diz assim em sua linha de Scope. As chaves `Global config` se aplicam apenas de `~/.claude.json`.

771 771

772 Dentro da chave `env`, as variáveis de exportação de telemetria nunca se aplicam do arquivo compartilhado também, exceto por alguns valores desligados; veja [Variáveis que o Claude Code ignora em `env`](/docs/pt/settings-reference#variables-claude-code-ignores-in-env).772 Dentro da chave `env`, as variáveis de exportação de telemetria nunca se aplicam do arquivo compartilhado também, exceto por alguns valores desligados; veja [Variáveis que o Claude Code ignora em `env`](/docs/pt/settings-reference#variables-claude-code-ignores-in-env).

773* **A chave espera por confiança.** As regras `permissions.allow`, `permissions.additionalDirectories`, `extraKnownMarketplaces` e a maioria dos valores [`env`](/docs/pt/settings-reference#env) se aplicam apenas depois que cada colega de equipe [confia na pasta](/docs/pt/permissions#project-allow-rules-and-workspace-trust). Até então eles ainda veem prompts e não obtêm plugins de um marketplace que o arquivo declara. As regras `deny` e `ask` se aplicam imediatamente.773* **A chave espera por confiança.** As regras `permissions.allow`, `permissions.additionalDirectories`, `extraKnownMarketplaces` e a maioria dos valores [`env`](/docs/pt/settings-reference#env) se aplicam apenas depois que cada colega de equipe [confia na pasta](/docs/pt/permissions#project-allow-rules-and-workspace-trust). Até então eles ainda veem prompts e não obtêm plugins de um marketplace que o arquivo declara. As regras `deny` e `ask` se aplicam imediatamente.

settings-reference.md +36 −13

Details

582<ReferenceFilter582<ReferenceFilter

583 noun="settings"583 noun="settings"

584 placeholder="Filter settings by key or purpose"584 placeholder="Filter settings by key or purpose"

585 facetOrder={{ scope: ["Any file", "User, local, or managed", "User or managed", "Managed", "Global config"] }}585 facetOrder={{ scope: ["Any file", "User, local, or managed", "User or managed", "User", "Managed", "Global config"] }}

586 columnHelp={{586 columnHelp={{

587topic: "The section of this page that holds the entry. Use Sort by to group the table by topic.",587topic: "The section of this page that holds the entry. Use Sort by to group the table by topic.",

588scope: "Which settings files can set the key: user (~/.claude/settings.json), project (.claude/settings.json), local (.claude/settings.local.json), or managed (deployed by your organization). Global config keys are in ~/.claude.json instead.",588scope: "Which settings files can set the key: user (~/.claude/settings.json), project (.claude/settings.json), local (.claude/settings.local.json), or managed (deployed by your organization). Global config keys are in ~/.claude.json instead.",

642| [`copyOnSelect`](#copyonselect) | Desative a cópia automática de texto que você seleciona com o mouse na [renderização em tela cheia](/docs/pt/fullscreen#use-the-mouse) e visualização de agente | Configurações de config global | Global config |642| [`copyOnSelect`](#copyonselect) | Desative a cópia automática de texto que você seleciona com o mouse na [renderização em tela cheia](/docs/pt/fullscreen#use-the-mouse) e visualização de agente | Configurações de config global | Global config |

643| [`crossSessionInbound`](#crosssessioninbound) | Escolha se Claude Code entrega [mensagens de suas outras sessões](/docs/pt/cross-session-messaging#control-inbound-messages), mostra um aviso sem entregá-las, ou as recusa | Agentes, sessões e worktrees | Any file |643| [`crossSessionInbound`](#crosssessioninbound) | Escolha se Claude Code entrega [mensagens de suas outras sessões](/docs/pt/cross-session-messaging#control-inbound-messages), mostra um aviso sem entregá-las, ou as recusa | Agentes, sessões e worktrees | Any file |

644| [`defaultShell`](#defaultshell) | Escolha se Bash ou PowerShell executa os comandos shell que você digita com o prefixo [`!`](/docs/pt/interactive-mode#shell-mode-with-prefix) | Interface e terminal | Any file |644| [`defaultShell`](#defaultshell) | Escolha se Bash ou PowerShell executa os comandos shell que você digita com o prefixo [`!`](/docs/pt/interactive-mode#shell-mode-with-prefix) | Interface e terminal | Any file |

686| [`footerLinksRegexes`](#footerlinksregexes) | Transforme IDs de issue ou review na saída em [links clicáveis](/docs/pt/statusline#clickable-links) abaixo da caixa de entrada | Interface e terminal | User or managed |686| [`footerLinksRegexes`](#footerlinksregexes) | Transforme IDs de issue ou review na saída em [links clicáveis](/docs/pt/statusline#clickable-links) abaixo da caixa de entrada | Interface e terminal | User or managed |

688| [`forceLoginMethod`](#forceloginmethod) | [Restrinja o login](/docs/pt/authentication#restrict-login-to-your-organization) a claude.ai, Claude Console, ou um [gateway de nuvem](/docs/pt/claude-apps-gateway) | Autenticação e provedores | Any file |688| [`forceLoginMethod`](#forceloginmethod) | [Restrinja o login](/docs/pt/authentication#restrict-login-to-your-organization) a claude.ai, Claude Console, ou um [gateway de nuvem](/docs/pt/claude-apps-gateway) | Autenticação e provedores | Any file |

689| [`forceLoginOrgUUID`](#forceloginorguuid) | [Fixe os logins claude.ai à sua organização](/docs/pt/authentication#restrict-login-to-your-organization); apenas uma fonte gerenciada a impõe | Autenticação e provedores | Any file |689| [`forceLoginOrgUUID`](#forceloginorguuid) | [Fixe os logins claude.ai à sua organização](/docs/pt/authentication#restrict-login-to-your-organization); apenas uma fonte gerenciada a impõe | Autenticação e provedores | Any file |

690| [`forceRemoteSettingsRefresh`](#forceremotesettingsrefresh) | Bloqueie a inicialização até que as [configurações gerenciadas por servidor](/docs/pt/server-managed-settings) sejam buscadas recentemente | Configurações empresariais e gerenciadas | Managed |690| [`forceRemoteSettingsRefresh`](#forceremotesettingsrefresh) | Bloqueie a inicialização até que as [configurações gerenciadas por servidor](/docs/pt/server-managed-settings) sejam buscadas recentemente | Configurações empresariais e gerenciadas | Managed |

836| [`wslInheritsWindowsSettings`](#wslinheritswindowssettings) | Faça WSL ler [configurações gerenciadas](/docs/pt/managed-settings) da cadeia de política do Windows | Configurações empresariais e gerenciadas | Managed |837| [`wslInheritsWindowsSettings`](#wslinheritswindowssettings) | Faça WSL ler [configurações gerenciadas](/docs/pt/managed-settings) da cadeia de política do Windows | Configurações empresariais e gerenciadas | Managed |

1763 * `"acceptEdits"`: Claude Code também executa edições de arquivo e comandos comuns do sistema de arquivos como `mkdir` e `mv` sem perguntar1764 * `"acceptEdits"`: Claude Code também executa edições de arquivo e comandos comuns do sistema de arquivos como `mkdir` e `mv` sem perguntar

1764 * `"plan"`: Claude Code lê e planeja, mas bloqueia edições até que você aprove um plano1765 * `"plan"`: Claude Code lê e planeja, mas bloqueia edições até que você aprove um plano

1765 * `"auto"`: Claude Code executa sem prompts rotineiros; antes de ações como comandos de shell e requisições de rede serem executadas, um classificador em segundo plano verifica se elas se alinham com sua solicitação1766 * `"auto"`: Claude Code executa sem prompts rotineiros; antes de ações como comandos de shell e requisições de rede serem executadas, um classificador em segundo plano verifica se elas se alinham com sua solicitação

1766 * `"dontAsk"`: Claude Code nega automaticamente cada chamada que de outra forma solicitaria; leituras, outras ações que não precisam de aprovação e ferramentas pré-aprovadas ainda são executadas1767 * `"dontAsk"`: Claude Code nega automaticamente cada chamada que de outra forma solicitaria; leituras de arquivos dentro dos seus diretórios de trabalho, outras ações que não precisam de aprovação e ferramentas pré-aprovadas ainda são executadas, exceto leituras de [caminhos de rede](/docs/pt/permissions#network-paths)

1767 * `"bypassPermissions"`: Claude Code executa tudo sem perguntar1768 * `"bypassPermissions"`: Claude Code executa tudo sem perguntar

1768 * `"manual"`: um alias para `"default"`1769 * `"manual"`: um alias para `"default"`

1769* **Padrão**: não definido1770* **Padrão**: não definido

2398 2399

2399* Uma entrada em `files` ou `envVars` que ainda tem um `path` ou `name` válido e um `mode` de `mask` ou `deny`, como uma cujo padrão `extract` não tem grupo de captura, é degradada para `mode: "deny"` com um aviso, então a credencial permanece bloqueada, não mascarada, até você corrigir a entrada. Uma entrada `files` degradada fixa [`filesystem.disabled`](/docs/pt/sandboxing#disable-filesystem-isolation) como uma entrada `deny` explícita, e o aviso observa que seu bloqueio de leitura não é imposto se configurações gerenciadas desativarem isolamento do sistema de arquivos.2400* Uma entrada em `files` ou `envVars` que ainda tem um `path` ou `name` válido e um `mode` de `mask` ou `deny`, como uma cujo padrão `extract` não tem grupo de captura, é degradada para `mode: "deny"` com um aviso, então a credencial permanece bloqueada, não mascarada, até você corrigir a entrada. Uma entrada `files` degradada fixa [`filesystem.disabled`](/docs/pt/sandboxing#disable-filesystem-isolation) como uma entrada `deny` explícita, e o aviso observa que seu bloqueio de leitura não é imposto se configurações gerenciadas desativarem isolamento do sistema de arquivos.

2400* Uma entrada com um `mode` desconhecido ou um `path` ou `name` inválido é removida.2401* Uma entrada com um `mode` desconhecido ou um `path` ou `name` inválido é removida.

2401* Cada caso avisa; se uma entrada é degradada ou removida, as entradas válidas restantes ainda são impostas, e um valor `credentials` totalmente inválido é descartado enquanto o resto de `sandbox` ainda se aplica.2402* Cada caso avisa; se uma entrada é degradada ou removida, as entradas válidas restantes ainda são impostas.

2402 2403

2403Aplica-se em v2.1.191 e posterior; antes da v2.1.221, cada entrada inválida era removida. Para as outras chaves gerenciadas com manipulação por campo, consulte [Invalid entries in managed settings](/docs/pt/managed-settings#invalid-entries-in-managed-settings).2404Aplica-se em v2.1.191 e posterior; antes da v2.1.221, cada entrada inválida era removida. Para as outras chaves gerenciadas com manipulação por campo, consulte [Invalid entries in managed settings](/docs/pt/managed-settings#invalid-entries-in-managed-settings).

2404 2405

5681 5682

5682Fora de um repositório git, um [hook `WorktreeCreate`](/docs/pt/worktrees#non-git-version-control) que falha libera o bloqueio para que a sessão possa editar o diretório de trabalho no local; essa liberação requer Claude Code v2.1.203 ou posterior.5683Fora de um repositório git, um [hook `WorktreeCreate`](/docs/pt/worktrees#non-git-version-control) que falha libera o bloqueio para que a sessão possa editar o diretório de trabalho no local; essa liberação requer Claude Code v2.1.203 ou posterior.

5683 5684

5685<h3 id="worktree-location">

5686 `worktree.location`

5687</h3>

5688

5689Escolha a pasta em uma máquina remota onde as [sessões SSH do Desktop](/docs/pt/desktop#choose-where-ssh-session-worktrees-go) criam seus worktrees, em vez de `<project-root>/.claude/worktrees/`. Apenas o aplicativo desktop lê esta chave: `--worktree`, a ferramenta `EnterWorktree`, subagentes isolados e sessões de fundo a ignoram. Requer Claude Desktop v1.44121.0 ou posterior.

5690

5691* **Escopo**: [`Usuário`](#scopes), em `~/.claude/settings.json` na máquina remota

5692* **Tipo**: string, um caminho absoluto ou um que começa com `~/`

5693* **Padrão**: não definido, portanto os worktrees ficam dentro do projeto

5694

5695Este exemplo define a pasta como `~/worktrees`:

5696

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

5698{

5699 "worktree": {

5700 "location": "~/worktrees"

5701 }

5702}

5703```

5704

5705Uma **Pasta de worktree** definida na conexão SSH no Desktop tem precedência. Se sua organização restringe quais pastas as sessões podem usar, o Desktop mantém os worktrees dentro do projeto.

5706

5684<h2 id="remote-desktop-and-notifications">5707<h2 id="remote-desktop-and-notifications">

5685 Remoto, desktop e notificações5708 Remoto, desktop e notificações

5686</h2>5709</h2>

5813 `enableArtifact`5836 `enableArtifact`

5814</h3>5837</h3>

5815 5838

5816Desative a ferramenta [Artifact](/docs/pt/artifacts), que publica a saída da sessão como uma página da web privada em claude.ai. Quando você desativa a linha **Artifacts** em `/config`, o Claude Code escreve essa chave em suas configurações de usuário, então você geralmente não a edita manualmente. Requer Claude Code v2.1.196 ou posterior.5839Desative a ferramenta [Artifact](/docs/pt/artifacts), que publica a saída da sessão como uma página da web privada em claude.ai. Quando você desativa a linha **Artifacts** em `/config`, o Claude Code escreve essa chave em suas configurações de usuário, então você geralmente não a edita manualmente.

5817 5840

5818* **Escopo**: [`Qualquer arquivo`](#scopes). Cada arquivo pode desativar a ferramenta, e nenhum pode ativá-la novamente.5841* **Escopo**: [`Qualquer arquivo`](#scopes). Cada arquivo pode desativar a ferramenta, e nenhum pode ativá-la novamente.

5819* **Tipo**: Boolean5842* **Tipo**: Boolean

5920 `sshConfigs`5943 `sshConfigs`

5921</h3>5944</h3>

5922 5945

5923Adicione conexões SSH ao menu suspenso do ambiente [Desktop](/docs/pt/desktop#pre-configure-ssh-connections-for-your-team). Administradores a usam para distribuir conexões compartilhadas para uma equipe. Conexões que você define em configurações gerenciadas aparecem como gerenciadas, então os usuários podem selecioná-las, mas não podem editá-las ou deletá-las no aplicativo.5946Adicione conexões SSH ao menu suspenso do ambiente [Desktop](/docs/pt/desktop#pre-configure-ssh-connections-for-your-team). Administradores a usam para distribuir conexões compartilhadas para uma equipe. Conexões que você define em configurações gerenciadas aparecem como gerenciadas. Os usuários podem selecioná-las e [definir sua própria **Pasta do worktree**](/docs/pt/desktop#choose-where-ssh-session-worktrees-go) para elas, mas não podem editar mais nada nem excluí-las no aplicativo.

5924 5947

5925* **Escopo**: [`Usuário ou gerenciado`](#scopes). O aplicativo desktop lê essa chave. Por padrão, ele lê as conexões gerenciadas de [uma fonte gerenciada](/docs/pt/managed-settings#how-claude-code-combines-managed-sources).5948* **Escopo**: [`Usuário ou gerenciado`](#scopes). O aplicativo desktop lê essa chave. Por padrão, ele lê as conexões gerenciadas de [uma fonte gerenciada](/docs/pt/managed-settings#how-claude-code-combines-managed-sources).

5926* **Tipo**: array de objetos, cada um com `id`, `name` e `sshHost` obrigatórios e `sshPort` e `sshIdentityFile` opcionais5949* **Tipo**: array de objetos, cada um com `id`, `name` e `sshHost` obrigatórios e `sshPort` e `sshIdentityFile` opcionais

6085 6108

6086Restrinja qual tipo de conta as pessoas podem usar para fazer login. Defina `"claudeai"` para permitir apenas contas claude.ai, `"console"` para permitir apenas contas Claude Console, ou `"gateway"` para enviar as pessoas para um [gateway na nuvem](/docs/pt/claude-apps-gateway) em vez de um login de primeira parte. Os administradores o definem em configurações gerenciadas e o emparelham com [`forceLoginOrgUUID`](#forceloginorguuid) para manter os logins claude.ai dos desenvolvedores dentro de uma organização. Se você o definir como `"claudeai"` ou `"console"` em qualquer arquivo de configurações, Claude Code também para de oferecer o [login Console sem chave](/docs/pt/authentication#sign-in-without-an-api-key) nas sessões às quais esse arquivo se aplica.6109Restrinja qual tipo de conta as pessoas podem usar para fazer login. Defina `"claudeai"` para permitir apenas contas claude.ai, `"console"` para permitir apenas contas Claude Console, ou `"gateway"` para enviar as pessoas para um [gateway na nuvem](/docs/pt/claude-apps-gateway) em vez de um login de primeira parte. Os administradores o definem em configurações gerenciadas e o emparelham com [`forceLoginOrgUUID`](#forceloginorguuid) para manter os logins claude.ai dos desenvolvedores dentro de uma organização. Se você o definir como `"claudeai"` ou `"console"` em qualquer arquivo de configurações, Claude Code também para de oferecer o [login Console sem chave](/docs/pt/authentication#sign-in-without-an-api-key) nas sessões às quais esse arquivo se aplica.

6087 6110

6088* **Escopo**: [`Qualquer arquivo`](#scopes). Claude Code honra `"gateway"` apenas de uma fonte gerenciada na máquina: `managed-settings.json`, a plist do macOS ou registro HKLM do Windows, ou um auxiliar de política. Ele trata `"gateway"` como não definido em configurações de usuário, projeto, local, HKCU e gerenciadas por servidor, a mesma regra que [`forceLoginGatewayUrl`](#forcelogingatewayurl).6111* **Escopo**: [`Qualquer arquivo`](#scopes). Claude Code honra `"gateway"` das mesmas fontes que [`forceLoginGatewayUrl`](#forcelogingatewayurl) e o trata como não definido em todos os outros lugares.

6089* **Tipo**: string, um de:6112* **Tipo**: string, um de:

6090 * `"claudeai"`: apenas contas claude.ai podem fazer login6113 * `"claudeai"`: apenas contas claude.ai podem fazer login

6091 * `"console"`: apenas contas Claude Console podem fazer login6114 * `"console"`: apenas contas Claude Console podem fazer login

6108 6131

6109Defina a URL do gateway à qual a tela `/login` Cloud gateway se conecta, para que as pessoas alcancem seu [gateway na nuvem](/docs/pt/claude-apps-gateway) sem digitar seu endereço. A tela não tem campo de URL: com esta chave definida, ela mostra a URL do seu gateway e se conecta quando a pessoa pressiona Enter; sem ela, diz a elas para entrar em contato com seu administrador de TI.6132Defina a URL do gateway à qual a tela `/login` Cloud gateway se conecta, para que as pessoas alcancem seu [gateway na nuvem](/docs/pt/claude-apps-gateway) sem digitar seu endereço. A tela não tem campo de URL: com esta chave definida, ela mostra a URL do seu gateway e se conecta quando a pessoa pressiona Enter; sem ela, diz a elas para entrar em contato com seu administrador de TI.

6110 6133

6111Ou esta chave ou `forceLoginMethod: "gateway"` torna a máquina apenas gateway, exceto para sessões que selecionam um provedor de nuvem com `CLAUDE_CODE_USE_*`. `/login` então abre na tela Cloud gateway sem seletor de método de login. Veja [A política do administrador requer um login de gateway na nuvem](/docs/pt/errors#administrator-policy-requires-a-cloud-gateway-sign-in) para o que acontece com um login de primeira parte restante ou chave de API. Defina ambas as chaves para que a tela se conecte em vez de mostrar um erro.6134Em configurações gerenciadas, ou esta chave ou `forceLoginMethod: "gateway"` torna a máquina apenas gateway, exceto para sessões que selecionam um provedor de nuvem com `CLAUDE_CODE_USE_*`. `/login` então abre na tela Cloud gateway sem seletor de método de login. Veja [A política do administrador requer um login de gateway na nuvem](/docs/pt/errors#administrator-policy-requires-a-cloud-gateway-sign-in) para o que acontece com um login de primeira parte restante ou chave de API. Defina ambas as chaves para que a tela se conecte em vez de mostrar um erro.

6112 6135

6113* **Escopo**: [`Gerenciado`](#scopes). Leia apenas de uma fonte na máquina: `managed-settings.json`, a plist do macOS ou registro HKLM do Windows, ou um auxiliar de política. Claude Code a ignora em configurações HKCU e gerenciadas por servidor.6136* **Escopo**: [`Usuário ou gerenciado`](#scopes). Lida de uma fonte gerenciada na máquina: `managed-settings.json`, a plist do macOS ou registro HKLM do Windows, ou um auxiliar de política. Em uma máquina sem nenhuma dessas, Claude Code v2.1.295 ou posterior também a lê das [configurações de usuário](/docs/pt/claude-apps-gateway#set-the-gateway-url-in-user-settings). Claude Code a ignora em configurações HKCU e gerenciadas por servidor.

6114* **Tipo**: string, uma URL completa incluindo o esquema6137* **Tipo**: string, uma URL completa incluindo o esquema

6115* **Padrão**: não definido, portanto a tela Cloud gateway mostra um erro dizendo às pessoas para entrar em contato com seu administrador de TI6138* **Padrão**: não definido, portanto a tela Cloud gateway mostra um erro dizendo às pessoas para entrar em contato com seu administrador de TI

6116 6139

6140}6163}

6141```6164```

6142 6165

6143Se uma fonte gerenciada define um array vazio, ou um valor que Claude Code não consegue analisar, Claude Code bloqueia cada login com uma mensagem de configuração incorreta.6166Se uma fonte gerenciada define um array vazio, ou um valor que não é uma string nem um array de strings, os usuários que fazem login com uma conta Anthropic não conseguem iniciar Claude Code nem concluir um login. Eles veem uma mensagem que nomeia `forceLoginOrgUUID` e lhes diz para entrar em contato com seu administrador. Um [`policyHelper`](#policyhelper) que emite um valor do tipo errado [falha em sua execução](#helper-failures) em vez disso.

6144 6167

6145Veja [Restringir login à sua organização](/docs/pt/authentication#restrict-login-to-your-organization) para como Claude Code trata logins Claude Console, os outros caminhos de login e credenciais de ambiente.6168Veja [Restringir login à sua organização](/docs/pt/authentication#restrict-login-to-your-organization) para como Claude Code trata logins Claude Console, os outros caminhos de login e credenciais de ambiente.

6146 6169

6806 `copyFullResponse`6829 `copyFullResponse`

6807</h3>6830</h3>

6808 6831

6809Faça [`/copy`](/docs/pt/commands) copiar a resposta completa toda vez, sem o seletor que ele mostra quando a resposta contém blocos de código. Selecionar **Sempre copiar resposta completa** nesse seletor define essa chave como `true`. Aparece em `/config` como **Pular o seletor /copy**.6832Faça [`/copy`](/docs/pt/commands) copiar a resposta completa toda vez, sem mostrar o seletor. Selecionar **Sempre copiar resposta completa** nesse seletor define essa chave como `true`. Aparece em `/config` como **Pular o seletor /copy**.

6810 6833

6811* **Escopo**: [`Global config`](#scopes)6834* **Escopo**: [`Global config`](#scopes)

6812* **Tipo**: Booleano6835* **Tipo**: Booleano

6813 * `true`: `/copy` copia a resposta completa sem mostrar o seletor6836 * `true`: `/copy` copia a resposta completa sem mostrar o seletor

6814 * `false`: quando a resposta contém blocos de código, `/copy` mostra um seletor onde você escolhe um bloco de código ou a resposta completa6837 * `false`: quando a resposta contém blocos de código ou citações em bloco, `/copy` mostra um seletor onde você escolhe um bloco ou a resposta completa

6815* **Padrão**: `false`6838* **Padrão**: `false`

6816 6839

6817```json ~/.claude.json theme={null}6840```json ~/.claude.json theme={null}

skills.md +74 −74

Details

192 192

193Claude Code carrega skills de projeto de `.claude/skills/` no diretório onde você o inicia e em todos os diretórios pai até a raiz do repositório, então iniciar em `packages/frontend/` ainda pega skills definidas na raiz. Quando você [move a sessão com `/cd`](/docs/pt/permissions#move-the-session-to-another-directory) na v2.1.246 ou posterior, Claude Code adiciona as skills de projeto do novo diretório.193Claude Code carrega skills de projeto de `.claude/skills/` no diretório onde você o inicia e em todos os diretórios pai até a raiz do repositório, então iniciar em `packages/frontend/` ainda pega skills definidas na raiz. Quando você [move a sessão com `/cd`](/docs/pt/permissions#move-the-session-to-another-directory) na v2.1.246 ou posterior, Claude Code adiciona as skills de projeto do novo diretório.

194 194

195Em uma sessão executada em um [git worktree](/docs/pt/worktrees) vinculado, Claude Code pesquisa diretórios pai apenas até a raiz do worktree. Na Claude Code v2.1.277 ou posterior, quando o checkout do worktree não tem um diretório `.claude/skills` em sua raiz, Claude Code carrega as skills de projeto do checkout principal. Veja [O que worktrees compartilham com o checkout principal](/docs/pt/worktrees#what-worktrees-share-with-the-main-checkout).195Em uma sessão executada em um [git worktree](/docs/pt/worktrees) vinculado que você criou com `--worktree` ou `git worktree add`, Claude Code pesquisa diretórios pai apenas até a raiz do worktree. Na Claude Code v2.1.277 ou posterior, quando o checkout do worktree não tem um diretório `.claude/skills` em sua raiz, Claude Code carrega as skills de projeto do checkout principal. Veja [O que worktrees compartilham com o checkout principal](/docs/pt/worktrees#what-worktrees-share-with-the-main-checkout).

196 196

197Skills em um diretório `.claude/skills/` abaixo de onde você iniciou não carregam na inicialização. Elas carregam na primeira vez que Claude lê ou edita um arquivo naquele subdiretório e permanecem disponíveis pelo resto da sessão. Até então, elas não aparecem no menu `/` e você não pode invocá-las por nome. Para carregá-las mais cedo, execute `/add-dir` com o caminho do subdiretório, o que requer Claude Code v2.1.257 ou posterior.197Skills em um diretório `.claude/skills/` abaixo de onde você iniciou não carregam na inicialização. Elas carregam na primeira vez que Claude lê ou edita um arquivo naquele subdiretório e permanecem disponíveis pelo resto da sessão. Até então, elas não aparecem no menu `/` e você não pode invocá-las por nome. Para carregá-las mais cedo, execute `/add-dir` com o caminho do subdiretório, o que requer Claude Code v2.1.257 ou posterior. Para uma sessão de worktree que você inicia a partir do aplicativo desktop, veja [O que worktrees compartilham com o checkout principal](/docs/pt/worktrees#what-worktrees-share-with-the-main-checkout).

198 198

199Quando o nome do diretório de uma skill aninhada corresponde ao nome de outra skill, ambas permanecem disponíveis. Com uma skill `deploy` na raiz do repositório e outra em `apps/web/.claude/skills/`:199Quando o nome do diretório de uma skill aninhada corresponde ao nome de outra skill, ambas permanecem disponíveis. Com uma skill `deploy` na raiz do repositório e outra em `apps/web/.claude/skills/`:

200 200

235 235

236Se uma skill existe apenas em `~/.claude/skills/` em sua máquina, Claude Code relata que a skill não foi encontrada quando uma [rotina](/docs/pt/routines) a invoca, porque cada execução de rotina começa como uma sessão cloud nova. Para disponibilizar uma skill pessoal nessas sessões:236Se uma skill existe apenas em `~/.claude/skills/` em sua máquina, Claude Code relata que a skill não foi encontrada quando uma [rotina](/docs/pt/routines) a invoca, porque cada execução de rotina começa como uma sessão cloud nova. Para disponibilizar uma skill pessoal nessas sessões:

237 237

238* Para sessões Cowork e cloud, habilite a skill para sua conta claude.ai.238* Para sessões Cowork e na nuvem, habilite a skill para sua conta claude.ai. [Algumas sessões em um ambiente auto-hospedado](/docs/pt/self-hosted-environments-configuration#how-each-session’s-config-is-assembled) não carregam as skills da sua conta.

239* Para sessões cloud, você pode em vez disso confirmar a skill no `.claude/skills/` do repositório. Plugins declarados no `.claude/settings.json` do repositório e plugins habilitados apenas em suas configurações de usuário [não carregam em sessões cloud](/docs/pt/cloud-environments#what-carries-over-from-your-setup).239* Para sessões cloud, você pode em vez disso confirmar a skill no `.claude/skills/` do repositório. Plugins declarados no `.claude/settings.json` do repositório e plugins habilitados apenas em suas configurações de usuário [não carregam em sessões cloud](/docs/pt/cloud-environments#what-carries-over-from-your-setup).

240 240

241[Tarefas agendadas do Desktop](/docs/pt/desktop-scheduled-tasks) executam localmente em sua máquina, então elas carregam `~/.claude/skills/`.241[Tarefas agendadas do Desktop](/docs/pt/desktop-scheduled-tasks) executam localmente em sua máquina, então elas carregam `~/.claude/skills/`.

364 Configurar skills364 Configurar skills

365</h2>365</h2>

366 366

367As skills são configuradas por meio do frontmatter YAML no topo do `SKILL.md` e do conteúdo markdown que vem em seguida.367As skills são configuradas por meio do frontmatter YAML no topo do `SKILL.md` e do conteúdo markdown que vem a seguir.

368 368

369<h3 id="types-of-skill-content">369<h3 id="types-of-skill-content">

370 Tipos de conteúdo de skill370 Tipos de conteúdo de skill

372 372

373Os arquivos de skill podem conter quaisquer instruções, mas pensar em como você deseja invocá-las ajuda a orientar o que incluir:373Os arquivos de skill podem conter quaisquer instruções, mas pensar em como você deseja invocá-las ajuda a orientar o que incluir:

374 374

375**Conteúdo de referência** adiciona conhecimento que o Claude aplica ao seu trabalho atual. Convenções, padrões, guias de estilo, conhecimento de domínio. Esse conteúdo é executado inline para que o Claude possa usá-lo junto com o contexto da sua conversa.375**Conteúdo de referência** adiciona conhecimento que Claude aplica ao seu trabalho atual. Convenções, padrões, guias de estilo, conhecimento de domínio. Esse conteúdo é executado inline para que Claude possa usá-lo junto com o contexto da sua conversa.

376 376

377```yaml theme={null}377```yaml theme={null}

378---378---

386- Include request validation386- Include request validation

387```387```

388 388

389**Conteúdo de tarefa** fornece ao Claude instruções passo a passo para uma ação específica, como implantações, commits ou geração de código. Geralmente são ações que você deseja invocar diretamente com `/skill-name` em vez de deixar o Claude decidir quando executá-las. Adicione `disable-model-invocation: true` para impedir que o Claude a acione automaticamente. O exemplo abaixo adiciona `context: fork`, que executa a skill em seu próprio contexto de subagente; consulte [Executar skills em um subagente](#run-skills-in-a-subagent).389**Conteúdo de tarefa** fornece a Claude instruções passo a passo para uma ação específica, como deploys, commits ou geração de código. Geralmente são ações que você deseja invocar diretamente com `/skill-name` em vez de deixar Claude decidir quando executá-las. Adicione `disable-model-invocation: true` para impedir que Claude a acione automaticamente. O exemplo abaixo adiciona `context: fork`, que executa a skill em seu próprio contexto de subagente; consulte [Executar skills em um subagente](#run-skills-in-a-subagent).

390 390

391```yaml theme={null}391```yaml theme={null}

392---392---

408 Referência do frontmatter408 Referência do frontmatter

409</h3>409</h3>

410 410

411Configure uma skill com o [frontmatter](/docs/pt/glossary#frontmatter) YAML entre marcadores `---` no topo do `SKILL.md` e escreva as instruções da skill em Markdown após o `---` de fechamento. Os nomes dos campos usam palavras em minúsculas separadas por hífens, exceto `when_to_use`. Um [arquivo de comando](#where-skills-live) em `.claude/commands/` aceita os mesmos campos, exceto `name` e `paths`. Este exemplo define quatro campos:411Configure uma skill com o [frontmatter](/docs/pt/glossary#frontmatter) YAML entre marcadores `---` no topo do `SKILL.md` e escreva as instruções da skill em Markdown após o `---` de fechamento. Os nomes dos campos usam palavras em minúsculas separadas por hifens, exceto `when_to_use`. Um [arquivo de comando](#where-skills-live) em `.claude/commands/` aceita os mesmos campos, exceto `name` e `paths`. Este exemplo define quatro campos:

412 412

413```yaml theme={null}413```yaml theme={null}

414---414---

421Your skill instructions here...421Your skill instructions here...

422```422```

423 423

424Todos os campos são opcionais. Apenas `description` é recomendado, para que o Claude saiba quando usar a skill. O nome de um campo deve corresponder exatamente à tabela, incluindo os hífens: o Claude Code ignora um campo que não reconhece sem relatar um erro.424Todos os campos são opcionais. Apenas `description` é recomendado para que Claude saiba quando usar a skill. O nome de um campo deve corresponder exatamente à tabela, incluindo os hifens: o Claude Code ignora um campo que não reconhece sem relatar um erro.

425 425

426O Claude Code lê o frontmatter somente quando o `---` de abertura é a primeira linha do arquivo. Caso contrário, ele trata o arquivo inteiro, incluindo os marcadores `---`, como conteúdo da skill. Se o YAML entre os marcadores não puder ser analisado, a skill ainda é carregada sem nenhum campo definido; consulte [Skill não é acionada](#skill-not-triggering) para encontrar e corrigir o erro.426O Claude Code lê o frontmatter apenas quando o `---` de abertura é a primeira linha do arquivo. Caso contrário, ele trata o arquivo inteiro, incluindo os marcadores `---`, como conteúdo da skill. Se o YAML entre os marcadores não puder ser analisado, a skill ainda será carregada sem nenhum campo definido; consulte [Skill não é acionada](#skill-not-triggering) para encontrar e corrigir o erro.

427 427

428Campos booleanos aceitam `yes`, `no`, `on`, `off`, `1` e `0` em qualquer combinação de maiúsculas e minúsculas, além de `true` e `false`. Antes da v2.1.218, o Claude Code reconhecia apenas `true` e `false`.428Os campos booleanos aceitam `yes`, `no`, `on`, `off`, `1` e `0` em qualquer combinação de maiúsculas e minúsculas, além de `true` e `false`. Antes da v2.1.218, o Claude Code reconhecia apenas `true` e `false`.

429 429

431| :- | :- | :- |431| :- | :- | :- |

432| `name` | Não | Nome do comando exibido no menu `/`. O padrão é o nome do diretório. Consulte [Como uma skill obtém seu nome de comando](#how-a-skill-gets-its-command-name) para saber como o campo interage com o nome que você digita para invocar a skill. |432| `name` | Não | Nome do comando exibido no menu `/`. O padrão é o nome do diretório. Consulte [Como uma skill obtém seu nome de comando](#how-a-skill-gets-its-command-name) para saber como o campo interage com o nome que você digita para invocar a skill. |

433| `description` | Recomendado | O que a skill faz e quando usá-la. O Claude usa isso para decidir quando aplicar a skill. Se omitido, usa a primeira linha não vazia do conteúdo markdown. Coloque o caso de uso principal primeiro: o texto combinado de `description` e `when_to_use` é truncado em 1.536 caracteres na listagem de skills para reduzir o uso de contexto. |433| `description` | Recomendado | O que a skill faz e quando usá-la. Claude usa isso para decidir quando aplicar a skill. Se omitido, usa a primeira linha não vazia do conteúdo markdown. Coloque o caso de uso principal primeiro: o texto combinado de `description` e `when_to_use` é truncado em 1.536 caracteres na listagem de skills para reduzir o uso de contexto. |

434| `when_to_use` | Não | Contexto adicional sobre quando o Claude deve invocar a skill, como frases de acionamento ou exemplos de solicitações. É anexado a `description` na listagem de skills e conta para o limite de 1.536 caracteres. |434| `when_to_use` | Não | Contexto adicional sobre quando Claude deve invocar a skill, como frases de acionamento ou exemplos de solicitações. É anexado a `description` na listagem de skills e conta para o limite de 1.536 caracteres. |

435| `argument-hint` | Não | Dica exibida durante o preenchimento automático para indicar os argumentos esperados. Exemplo: `[issue-number]` ou `[filename] [format]`. |435| `argument-hint` | Não | Dica exibida durante o preenchimento automático para indicar os argumentos esperados. Exemplo: `[issue-number]` ou `[filename] [format]`. |

436| `arguments` | Não | Argumentos posicionais nomeados para [substituição de `$name`](#available-string-substitutions) no conteúdo da skill. Aceita uma string separada por espaços ou uma lista YAML. Os nomes são mapeados para as posições dos argumentos em ordem. |436| `arguments` | Não | Argumentos posicionais nomeados para [substituição de `$name`](#available-string-substitutions) no conteúdo da skill. Aceita uma string separada por espaços ou uma lista YAML. Os nomes são mapeados para as posições dos argumentos em ordem. |

437| `disable-model-invocation` | Não | Defina como `true` para impedir que o Claude carregue esta skill automaticamente. Use para fluxos de trabalho que você deseja acionar manualmente com `/name`. Também impede que a skill seja [pré-carregada em subagentes](/docs/pt/sub-agents#preload-skills-into-subagents). A partir da v2.1.196, também impede que a skill seja executada quando uma [tarefa agendada](/docs/pt/scheduled-tasks) dispara com a skill como seu prompt. Padrão: `false`. |437| `disable-model-invocation` | Não | Defina como `true` para impedir que Claude carregue esta skill automaticamente. Use para fluxos de trabalho que você deseja acionar manualmente com `/name`. Também impede que a skill seja [pré-carregada em subagentes](/docs/pt/sub-agents#preload-skills-into-subagents) e que seja executada quando uma [tarefa agendada](/docs/pt/scheduled-tasks) é disparada com a skill como seu prompt. Padrão: `false`. |

438| `user-invocable` | Não | Defina como `false` quando apenas o Claude deve invocar a skill: o Claude Code a oculta do menu `/` e não a executa quando você digita `/name`. Use para conhecimento de fundo que os usuários não devem invocar diretamente. Padrão: `true`. |438| `user-invocable` | Não | Defina como `false` quando apenas Claude deve invocar a skill: o Claude Code a oculta do menu `/` e não a executa quando você digita `/name`. Use para conhecimento de fundo que os usuários não devem invocar diretamente. Padrão: `true`. |

439| `allowed-tools` | Não | Ferramentas que o Claude pode usar sem pedir permissão durante o turno que invoca esta skill. A concessão é removida quando você envia sua próxima mensagem. Aceita uma string separada por espaços ou vírgulas, ou uma lista YAML. Consulte [Pré-aprovar ferramentas para uma skill](#pre-approve-tools-for-a-skill). |439| `allowed-tools` | Não | Ferramentas que Claude pode usar sem pedir permissão durante o turno que invoca esta skill. A concessão é removida quando você envia sua próxima mensagem. Aceita uma string separada por espaços ou vírgulas, ou uma lista YAML. Consulte [Pré-aprovar ferramentas para uma skill](#pre-approve-tools-for-a-skill). |

440| `disallowed-tools` | Não | Ferramentas removidas do conjunto disponível do Claude enquanto esta skill está ativa. Use para skills autônomas que nunca devem chamar certas ferramentas, como `AskUserQuestion` para um loop em segundo plano. Aceita uma string separada por espaços ou vírgulas, ou uma lista YAML. A restrição é removida quando você envia sua próxima mensagem. Assim como as regras de deny, o campo não pode remover [`EndConversation`](/docs/pt/tools-reference#endconversation-tool-behavior) enquanto qualquer outra ferramenta permanecer. |440| `disallowed-tools` | Não | Ferramentas removidas do conjunto disponível para Claude enquanto esta skill está ativa. Use para skills autônomas que nunca devem chamar certas ferramentas, como `AskUserQuestion` em um loop em segundo plano. Aceita uma string separada por espaços ou vírgulas, ou uma lista YAML. A restrição é removida quando você envia sua próxima mensagem. Assim como as regras deny, o campo não pode remover [`EndConversation`](/docs/pt/tools-reference#endconversation-tool-behavior) enquanto qualquer outra ferramenta permanecer. |

441| `model` | Não | Modelo a ser usado quando esta skill está ativa. A substituição se aplica ao restante do turno atual e não é salva nas configurações. O modelo da sessão é retomado quando você envia seu próximo prompt. Aceita os mesmos valores que [`/model`](/docs/pt/model-config), ou `inherit` para manter o modelo ativo. Um valor excluído pela allowlist [`availableModels`](/docs/pt/model-config#restrict-model-selection) da sua organização não é usado, e a sessão mantém seu modelo atual. No [modo auto](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode), e no [modo de planejamento enquanto o classificador revisa comandos](/docs/pt/permission-modes#analyze-before-you-edit-with-plan-mode), um modelo que o modo auto não suporta também não é usado, e a sessão mantém seu modelo atual. Com `context: fork`, o valor define o [modelo do subagente bifurcado](#run-skills-in-a-subagent) em vez disso, e um valor excluído segue as [mesmas regras que uma substituição de modelo de subagente](/docs/pt/model-config#restrict-model-selection). |441| `model` | Não | Modelo a ser usado quando esta skill está ativa. A substituição se aplica ao restante do turno atual e não é salva nas configurações. O modelo da sessão é retomado quando você envia seu próximo prompt. Aceita os mesmos valores que [`/model`](/docs/pt/model-config), ou `inherit` para manter o modelo ativo. Um valor excluído pela allowlist [`availableModels`](/docs/pt/model-config#restrict-model-selection) da sua organização não é usado, e a sessão mantém seu modelo atual. No [modo auto](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode), e no [modo de planejamento enquanto o classificador revisa comandos](/docs/pt/permission-modes#analyze-before-you-edit-with-plan-mode), um modelo que o modo auto não suporta também não é usado, e a sessão mantém seu modelo atual. Com `context: fork`, o valor define o [modelo do subagente bifurcado](#run-skills-in-a-subagent), e um valor excluído segue as [mesmas regras de uma substituição de modelo de subagente](/docs/pt/model-config#restrict-model-selection). |

442| `effort` | Não | [Nível de esforço](/docs/pt/model-config#adjust-effort-level) quando esta skill está ativa. Sobrescreve o nível de esforço da sessão. Quando você o omite, o nível vem da [ordem de resolução de esforço](/docs/pt/model-config#adjust-effort-level). Opções: `low`, `medium`, `high`, `xhigh`, `max`; os níveis disponíveis dependem do modelo. |442| `effort` | Não | [Nível de esforço](/docs/pt/model-config#adjust-effort-level) quando esta skill está ativa. Sobrescreve o nível de esforço da sessão. Quando você o omite, o nível vem da [ordem de resolução de esforço](/docs/pt/model-config#adjust-effort-level). Opções: `low`, `medium`, `high`, `xhigh`, `max`; os níveis disponíveis dependem do modelo. |

443| `context` | Não | Defina como `fork` para executar em um contexto de subagente bifurcado. Consulte [Executar skills em um subagente](#run-skills-in-a-subagent). |443| `context` | Não | Defina como `fork` para executar em um contexto de subagente bifurcado. Consulte [Executar skills em um subagente](#run-skills-in-a-subagent). |

444| `agent` | Não | Qual tipo de subagente usar quando `context: fork` está definido. |444| `agent` | Não | Qual tipo de subagente usar quando `context: fork` está definido. |

445| `background` | Não | Aplica-se apenas com `context: fork`. Defina como `false` para aguardar o resultado do subagente bifurcado no turno que invocou a skill, em vez de [executá-lo em segundo plano](#run-skills-in-a-subagent). Padrão: `true`. Requer o Claude Code v2.1.218 ou posterior. |445| `background` | Não | Aplica-se apenas com `context: fork`. Defina como `false` para aguardar o resultado do subagente bifurcado no turno que invocou a skill, em vez de [executá-lo em segundo plano](#run-skills-in-a-subagent). Padrão: `true`. Requer o Claude Code v2.1.218 ou posterior. |

446| `hooks` | Não | Hooks que o Claude Code registra quando a skill é invocada e mantém em execução pelo restante da sessão. Consulte [Hooks em skills e agentes](/docs/pt/hooks#hooks-in-skills-and-agents) para o formato de configuração e a opção `once`. |446| `hooks` | Não | Hooks que o Claude Code registra quando a skill é invocada e mantém em execução pelo restante da sessão. Consulte [Hooks em skills e agentes](/docs/pt/hooks#hooks-in-skills-and-agents) para o formato de configuração e a opção `once`. |

447| `paths` | Não | Padrões glob que limitam quando esta skill é ativada. Aceita uma string separada por vírgulas ou uma lista YAML. Quando definido, o Claude carrega a skill automaticamente apenas ao trabalhar com arquivos que correspondem aos padrões. Usa o mesmo formato que as [regras específicas de caminho](/docs/pt/memory#path-specific-rules). |447| `paths` | Não | Padrões glob que limitam quando esta skill é ativada. Aceita uma string separada por vírgulas ou uma lista YAML. Quando definido, Claude carrega a skill automaticamente apenas ao trabalhar com arquivos que correspondem aos padrões. Usa o mesmo formato das [regras específicas de caminho](/docs/pt/memory#path-specific-rules). |

448| `shell` | Não | Shell a ser usado para blocos `` !`command` `` e ` ```! ` nesta skill. Aceita `bash` (padrão) ou `powershell`. Definir `powershell` executa comandos de shell inline via PowerShell quando a [ferramenta PowerShell](/pt/tools-reference#powershell-tool) está habilitada: ela está ativada por padrão no Windows sem Git Bash, ativada por padrão com Git Bash para contas claude.ai e Console, e requer `CLAUDE_CODE_USE_POWERSHELL_TOOL=1` em sessões do Amazon Bedrock, do Agent Platform do Google Cloud e do Microsoft Foundry, e no macOS, Linux e WSL. Defina-a como `0` para desativar a ferramenta. |448| `shell` | Não | Shell a ser usado para blocos `` !`command` `` e ` ```! ` nesta skill. Aceita `bash` (padrão) ou `powershell`. Definir `powershell` executa comandos de shell inline via PowerShell quando a [ferramenta PowerShell](/pt/tools-reference#powershell-tool) está habilitada: ela fica ativada por padrão no Windows sem Git Bash, ativada por padrão com Git Bash para contas claude.ai e Console, e requer `CLAUDE_CODE_USE_POWERSHELL_TOOL=1` em sessões do Amazon Bedrock, Agent Platform do Google Cloud e Microsoft Foundry, e no macOS, Linux e WSL. Defina como `0` para desativar a ferramenta. |

449| `metadata` | Não | Mapa YAML de formato livre para seus próprios dados de chave-valor, como campos de direitos de uso ou de catálogo, lidos por suas próprias ferramentas a partir do `SKILL.md`. O Claude Code não age sobre seu conteúdo e descarta um valor que não seja um mapa. Não reutilize nomes de campos do frontmatter, como `paths`, como chaves. |449| `metadata` | Não | Mapa YAML de formato livre para seus próprios dados de chave-valor, como campos de direitos ou catálogo, lidos pelas suas próprias ferramentas a partir do `SKILL.md`. O Claude Code não age sobre seu conteúdo e descarta um valor que não seja um mapa. Não reutilize nomes de campos do frontmatter, como `paths`, como chaves. |

450| `license` | Não | Licença que cobre a skill. Faz parte da especificação [Agent Skills](https://agentskills.io); consulte [Usar o frontmatter de skills fora do Claude Code](#using-skill-frontmatter-outside-claude-code). O Claude Code aceita o campo, mas não age sobre ele. |450| `license` | Não | Licença que abrange a skill. Faz parte da especificação [Agent Skills](https://agentskills.io); consulte [Usar o frontmatter de skills fora do Claude Code](#using-skill-frontmatter-outside-claude-code). O Claude Code aceita o campo, mas não age sobre ele. |

451| `compatibility` | Não | Requisitos de ambiente para a skill, como produtos pretendidos ou pré-requisitos de sistema, conforme definido pela especificação [Agent Skills](https://agentskills.io); consulte [Usar o frontmatter de skills fora do Claude Code](#using-skill-frontmatter-outside-claude-code). Aceita uma string de até 500 caracteres. O Claude Code aceita o campo, mas não age sobre ele. |451| `compatibility` | Não | Requisitos de ambiente para a skill, como produtos pretendidos ou pré-requisitos de sistema, conforme definido pela especificação [Agent Skills](https://agentskills.io); consulte [Usar o frontmatter de skills fora do Claude Code](#using-skill-frontmatter-outside-claude-code). Aceita uma string de até 500 caracteres. O Claude Code aceita o campo, mas não age sobre ele. |

452 452

453<h4 id="using-skill-frontmatter-outside-claude-code">453<h4 id="using-skill-frontmatter-outside-claude-code">

461| Skills do Claude Code em [qualquer nível](#where-skills-live), incluindo skills de [plugin](/docs/pt/plugins/overview) | Todos os campos da tabela acima |461| Skills do Claude Code em [qualquer nível](#where-skills-live), incluindo skills de [plugin](/docs/pt/plugins/overview) | Todos os campos da tabela acima |

462| Uploads de skills no claude.ai, a Skills API e o empacotamento com `package_skill.py` de [anthropics/skills](https://github.com/anthropics/skills) | `name`, `description`, `license`, `compatibility`, `metadata`, `allowed-tools` |462| Uploads de skills no claude.ai, a Skills API e o empacotamento com `package_skill.py` de [anthropics/skills](https://github.com/anthropics/skills) | `name`, `description`, `license`, `compatibility`, `metadata`, `allowed-tools` |

463 463

464Quando você habilita uma skill pessoal para sua conta do claude.ai, por exemplo para usá-la no [Cowork e em sessões na nuvem](#skills-in-cowork-and-cloud-sessions) e em rotinas, você a envia para o claude.ai, então as mesmas regras se aplicam.464Quando você habilita uma skill pessoal para sua conta claude.ai, por exemplo para usá-la no [Cowork e em sessões na nuvem](#skills-in-cowork-and-cloud-sessions) e em rotinas, você a envia para o claude.ai, então as mesmas regras se aplicam.

465 465

466Se você incluir qualquer campo que a especificação não permite, o empacotamento ou o upload falha com um erro fatal em vez de ignorar o campo:466Se você incluir qualquer campo que a especificação não permite, o empacotamento ou o upload falha com um erro definitivo em vez de ignorar o campo:

467 467

468```468```

469Unexpected key(s) in SKILL.md frontmatter: argument-hint. Allowed properties are: allowed-tools, compatibility, description, license, metadata, name469Unexpected key(s) in SKILL.md frontmatter: argument-hint. Allowed properties are: allowed-tools, compatibility, description, license, metadata, name

470```470```

471 471

472Restringir o frontmatter aos seis campos da especificação evita o erro de chave inesperada acima. A [especificação Agent Skills](https://agentskills.io) e os [requisitos da Skills API](https://docs.claude.com/en/api/skills-guide) definem todo o resto que esses caminhos validam. Recursos de corpo exclusivos do Claude Code, como a [injeção de contexto dinâmico](#inject-dynamic-context), não funcionam no chat do claude.ai nem pela API. O Claude Code aceita todos os seis campos, então um frontmatter que segue a especificação é carregado no Claude Code sem alterações.472Restringir o frontmatter aos seis campos da especificação evita o erro de chave inesperada acima. A [especificação Agent Skills](https://agentskills.io) e os [requisitos da Skills API](https://docs.claude.com/en/api/skills-guide) definem todo o resto que esses caminhos validam. Recursos do corpo exclusivos do Claude Code, como a [injeção de contexto dinâmico](#inject-dynamic-context), não funcionam no chat do claude.ai nem por meio da API. O Claude Code aceita todos os seis campos, então um frontmatter que segue a especificação é carregado no Claude Code sem alterações.

473 473

474<h4 id="how-a-skill-gets-its-command-name">474<h4 id="how-a-skill-gets-its-command-name">

475 Como uma skill obtém seu nome de comando475 Como uma skill obtém seu nome de comando

476</h4>476</h4>

477 477

478O comando que você digita para invocar uma skill vem do local onde o arquivo da skill está e, para diretórios de skills e skills de plugin, do campo `name` do frontmatter. Em um diretório de skills pessoal ou de projeto, `name` define o comando que o menu `/` exibe e que você digita, a menos que outro comando já use esse nome. O nome do diretório também invoca a skill. Em uma skill de plugin, `name` define o último segmento do comando, e o prefixo do plugin permanece.478O comando que você digita para invocar uma skill vem de onde o arquivo da skill está localizado e, para diretórios de skills e skills de plugin, do campo `name` do frontmatter. Em um diretório de skills pessoal ou de projeto, `name` define o comando que o menu `/` exibe e que você digita, a menos que outro comando já use esse nome. O nome do diretório também invoca a skill. Em uma skill de plugin, `name` define o último segmento do comando e o prefixo do plugin permanece.

479 479

480A tabela abaixo mostra de onde vem o nome do comando para cada estrutura:480A tabela abaixo mostra de onde vem o nome do comando para cada estrutura:

481 481

483| :- | :- | :- |483| :- | :- | :- |

484| Diretório de skill em `~/.claude/skills/` ou `.claude/skills/` | `name` do frontmatter ou o nome do diretório | `.claude/skills/deploy-staging/SKILL.md` → `/deploy-staging`, ou `/deploy` com `name: deploy` |484| Diretório de skill em `~/.claude/skills/` ou `.claude/skills/` | `name` do frontmatter ou o nome do diretório | `.claude/skills/deploy-staging/SKILL.md` → `/deploy-staging`, ou `/deploy` com `name: deploy` |

485| Diretório `.claude/skills/` [aninhado](#where-skills-live), quando o nome do diretório conflita com outra skill | Caminho do subdiretório relativo ao diretório de trabalho, seguido do nome do diretório da skill | `apps/web/.claude/skills/deploy/SKILL.md` → `/apps/web:deploy` |485| Diretório `.claude/skills/` [aninhado](#where-skills-live), quando o nome do diretório conflita com outra skill | Caminho do subdiretório relativo ao diretório de trabalho, seguido do nome do diretório da skill | `apps/web/.claude/skills/deploy/SKILL.md` → `/apps/web:deploy` |

487| Arquivo em um subdiretório de `.claude/commands/` | Caminho do subdiretório relativo a `commands/` com cada `/` substituída por `:`, seguido do nome do arquivo sem extensão | `.claude/commands/frontend/component.md` → `/frontend:component` |487| Arquivo em um subdiretório de `.claude/commands/` | Caminho do subdiretório relativo a `commands/` com cada `/` substituído por `:`, seguido do nome do arquivo sem extensão | `.claude/commands/frontend/component.md` → `/frontend:component` |

488| Subdiretório `skills/` do plugin | `name` do frontmatter ou o nome do diretório, com namespace do plugin | `my-plugin/skills/review/SKILL.md` → `/my-plugin:review`, ou `/my-plugin:fancy` com `name: fancy` |488| Subdiretório `skills/` do plugin | `name` do frontmatter ou o nome do diretório, com namespace do plugin | `my-plugin/skills/review/SKILL.md` → `/my-plugin:review`, ou `/my-plugin:fancy` com `name: fancy` |

489| `SKILL.md` na raiz do plugin | `name` do frontmatter, com o nome do diretório do plugin como fallback | `my-plugin/SKILL.md` com `name: review` → `/my-plugin:review`. Consulte [uma única skill na raiz do plugin](/docs/pt/plugins/components#skills) |489| `SKILL.md` na raiz do plugin | `name` do frontmatter, com o nome do diretório do plugin como fallback | `my-plugin/SKILL.md` com `name: review` → `/my-plugin:review`. Consulte [uma única skill na raiz do plugin](/docs/pt/plugins/components#skills) |

490| Skill [sincronizada do claude.ai](#how-synced-skills-behave) | O nome da skill na sua conta do claude.ai, prefixado com `anthropic-skills:` | Skill da conta `deploy` → `/anthropic-skills:deploy`, ou `/deploy` enquanto nenhum outro comando usar esse nome |490| Skill [sincronizada do claude.ai](#how-synced-skills-behave) | O nome da skill na sua conta claude.ai, prefixado com `anthropic-skills:` | Skill da conta `deploy` → `/anthropic-skills:deploy`, ou `/deploy` enquanto nenhum outro comando usar esse nome |

491 491

492Em uma skill de plugin, o `name` do frontmatter substitui o nome do diretório no último segmento do comando, então `my-plugin/skills/review/SKILL.md` com `name: fancy` se torna `/my-plugin:fancy`. O `/fancy` sem prefixo também invoca a skill, a menos que outro comando já use esse nome. Se o `name` que você escrever já começar com o prefixo do próprio plugin, o Claude Code não adiciona o prefixo novamente na v2.1.246 ou posterior. Por exemplo, `name: my-plugin:fancy` ainda se torna `/my-plugin:fancy`. Da v2.1.216 até a v2.1.245, o Claude Code duplicava o prefixo quando o `name` já o continha.492Em uma skill de plugin, o `name` do frontmatter substitui o nome do diretório no último segmento do comando, então `my-plugin/skills/review/SKILL.md` com `name: fancy` se torna `/my-plugin:fancy`. O `/fancy` simples também invoca a skill, a menos que outro comando já use esse nome. Se o `name` que você escrever já começar com o próprio prefixo do plugin, o Claude Code não adiciona o prefixo novamente na v2.1.246 ou posterior. Por exemplo, `name: my-plugin:fancy` ainda se torna `/my-plugin:fancy`. Da v2.1.216 até a v2.1.245, o Claude Code duplicava o prefixo quando o `name` já o continha.

493 493

494Em [sessões não interativas](/docs/pt/headless), os nomes `help` e `feedback` não são reservados para seus comandos integrados exclusivos do terminal, então uma skill de plugin com um desses nomes mantém seu comando sem prefixo ali. O nome de todos os outros comandos integrados exclusivos do terminal, como `/login`, permanece reservado, mesmo que o comando não possa ser executado nessas sessões.494Em [sessões não interativas](/docs/pt/headless), os nomes `help` e `feedback` não são reservados para seus comandos integrados exclusivos do terminal, então uma skill de plugin com um desses nomes mantém seu comando simples ali. O nome de todos os outros comandos integrados exclusivos do terminal, como `/login`, permanece reservado, mesmo que o comando não possa ser executado nessas sessões.

495 495

496Para um `SKILL.md` na raiz do plugin, não há diretório de skill de onde obter o nome, então `name` fornece todo o segmento final. Sem um campo `name`, o Claude Code recorre ao nome do diretório do plugin.496Para um `SKILL.md` na raiz do plugin, não há diretório de skill de onde obter o nome, então `name` fornece todo o segmento final. Sem um campo `name`, o Claude Code recorre ao nome do diretório do plugin.

497 497

505| :- | :- |505| :- | :- |

506| `$ARGUMENTS` | Todos os argumentos passados ao invocar a skill. Quando nenhum placeholder recebe um argumento, o Claude Code os anexa como `ARGUMENTS: <value>`. Consulte [Passar argumentos para skills](#pass-arguments-to-skills). |506| `$ARGUMENTS` | Todos os argumentos passados ao invocar a skill. Quando nenhum placeholder recebe um argumento, o Claude Code os anexa como `ARGUMENTS: <value>`. Consulte [Passar argumentos para skills](#pass-arguments-to-skills). |

507| `$ARGUMENTS[N]` | Acessa um argumento específico pelo índice baseado em 0, como `$ARGUMENTS[0]` para o primeiro argumento. |507| `$ARGUMENTS[N]` | Acessa um argumento específico pelo índice baseado em 0, como `$ARGUMENTS[0]` para o primeiro argumento. |

508| `$N` | Forma abreviada de `$ARGUMENTS[N]`, como `$0` para o primeiro argumento ou `$1` para o segundo. |508| `$N` | Abreviação de `$ARGUMENTS[N]`, como `$0` para o primeiro argumento ou `$1` para o segundo. |

509| `$name` | Argumento nomeado declarado na lista [`arguments`](#frontmatter-reference) do frontmatter. Os nomes são mapeados para as posições em ordem, então com `arguments: [issue, branch]` o placeholder `$issue` se expande para o primeiro argumento e `$branch` para o segundo. |509| `$name` | Argumento nomeado declarado na lista [`arguments`](#frontmatter-reference) do frontmatter. Os nomes são mapeados para posições em ordem, então com `arguments: [issue, branch]` o placeholder `$issue` se expande para o primeiro argumento e `$branch` para o segundo. |

510| `${CLAUDE_SESSION_ID}` | O ID da sessão atual. Útil para logs, para criar arquivos específicos da sessão ou para correlacionar a saída da skill com sessões. |510| `${CLAUDE_SESSION_ID}` | O ID da sessão atual. Útil para log, criação de arquivos específicos da sessão ou correlação da saída da skill com sessões. |

511| `${CLAUDE_EFFORT}` | O nível de esforço atual: `low`, `medium`, `high`, `xhigh` ou `max`. Use isso para adaptar as instruções da skill à configuração de esforço ativa. |511| `${CLAUDE_EFFORT}` | O nível de esforço atual: `low`, `medium`, `high`, `xhigh` ou `max`. Use isso para adaptar as instruções da skill à configuração de esforço ativa. |

512| `${CLAUDE_SKILL_DIR}` | O diretório que contém o arquivo `SKILL.md` da skill. Para skills de plugin, é o subdiretório da skill dentro do plugin, não a raiz do plugin. Use isso em comandos de injeção bash para referenciar scripts ou arquivos incluídos com a skill, independentemente do diretório de trabalho atual. |512| `${CLAUDE_SKILL_DIR}` | O diretório que contém o arquivo `SKILL.md` da skill. Para skills de plugin, este é o subdiretório da skill dentro do plugin, não a raiz do plugin. Use isso em comandos de injeção bash para referenciar scripts ou arquivos incluídos com a skill, independentemente do diretório de trabalho atual. |

513| `${CLAUDE_PROJECT_DIR}` | O diretório raiz do projeto. É o mesmo caminho que os [hooks](/docs/pt/hooks#reference-scripts-by-path) e os servidores MCP recebem como `CLAUDE_PROJECT_DIR`. Use isso para referenciar scripts ou arquivos locais do projeto, como `${CLAUDE_PROJECT_DIR}/.claude/hooks/helper.sh`, independentemente de onde a skill está instalada. |513| `${CLAUDE_PROJECT_DIR}` | O diretório raiz do projeto. Este é o mesmo caminho que [hooks](/docs/pt/hooks#reference-scripts-by-path) e servidores MCP recebem como `CLAUDE_PROJECT_DIR`. Use isso para referenciar scripts ou arquivos locais do projeto, como `${CLAUDE_PROJECT_DIR}/.claude/hooks/helper.sh`, independentemente de onde a skill está instalada. |

514| `${CLAUDE_PLUGIN_ROOT}` | O diretório de instalação do plugin. Substituído apenas em skills de plugin. Use isso para referenciar scripts ou arquivos incluídos em qualquer lugar do plugin, incluindo recursos compartilhados entre as skills do plugin. Consulte [variáveis de ambiente de plugins](/docs/pt/plugins/manifest-reference#environment-variables). |514| `${CLAUDE_PLUGIN_ROOT}` | O diretório de instalação do plugin. Substituído apenas em skills de plugin. Use isso para referenciar scripts ou arquivos incluídos em qualquer lugar do plugin, incluindo recursos compartilhados entre as skills do plugin. Consulte [variáveis de ambiente de plugin](/docs/pt/plugins/manifest-reference#environment-variables). |

515| `${CLAUDE_PLUGIN_DATA}` | O [diretório de dados persistentes](/docs/pt/plugins/components#path-variables-and-persistent-data) do plugin, que sobrevive às atualizações do plugin. Substituído apenas em skills de plugin. Use isso para referenciar dependências instaladas, arquivos gerados ou caches que precisam sobreviver a uma atualização. |515| `${CLAUDE_PLUGIN_DATA}` | O [diretório de dados persistentes](/docs/pt/plugins/components#path-variables-and-persistent-data) do plugin, que sobrevive às atualizações do plugin. Substituído apenas em skills de plugin. Use isso para referenciar dependências instaladas, arquivos gerados ou caches que devem sobreviver a uma atualização. |

516 516

517O Claude Code substitui `${CLAUDE_SKILL_DIR}` e `${CLAUDE_PROJECT_DIR}` em dois lugares: no conteúdo markdown da skill e nas regras de Bash do frontmatter [`allowed-tools`](#frontmatter-reference). Em uma skill de plugin, o Claude Code substitui `${CLAUDE_PLUGIN_ROOT}` e `${CLAUDE_PLUGIN_DATA}` nos mesmos dois lugares. Usar a mesma variável em ambos os lugares permite que uma skill execute um script incluído sem um prompt de permissão. A skill a seguir mostra o padrão:517O Claude Code substitui `${CLAUDE_SKILL_DIR}` e `${CLAUDE_PROJECT_DIR}` em dois lugares: no conteúdo markdown da skill e nas regras de Bash no frontmatter [`allowed-tools`](#frontmatter-reference). Em uma skill de plugin, o Claude Code substitui `${CLAUDE_PLUGIN_ROOT}` e `${CLAUDE_PLUGIN_DATA}` nos mesmos dois lugares. Usar a mesma variável em ambos os lugares permite que uma skill execute um script incluído sem um prompt de permissão. A skill a seguir mostra o padrão:

518 518

519```yaml theme={null}519```yaml theme={null}

520---520---

526Run `${CLAUDE_SKILL_DIR}/scripts/render.sh <csv-file>` to render the chart.526Run `${CLAUDE_SKILL_DIR}/scripts/render.sh <csv-file>` to render the chart.

527```527```

528 528

529Se essa skill estiver instalada em `~/.claude/skills/render-chart/`, ambas as ocorrências de `${CLAUDE_SKILL_DIR}` se expandem para esse diretório. A regra de `allowed-tools` então corresponde exatamente ao comando que o corpo da skill instrui o Claude a executar, então o script é executado sem solicitar confirmação.529Se esta skill estiver instalada em `~/.claude/skills/render-chart/`, ambas as ocorrências de `${CLAUDE_SKILL_DIR}` se expandem para esse diretório. A regra `allowed-tools` então corresponde exatamente ao comando que o corpo da skill instrui Claude a executar, então o script é executado sem pedir confirmação.

530 530

531A substituição de `${CLAUDE_PROJECT_DIR}` requer o Claude Code v2.1.196 ou posterior.531Os argumentos indexados usam aspas no estilo do shell, então coloque valores com várias palavras entre aspas para passá-los como um único argumento. Por exemplo, `/my-skill "hello world" second` faz `$0` se expandir para `hello world` e `$1` para `second`. O placeholder `$ARGUMENTS` sempre se expande para a string completa de argumentos conforme digitada.

~~532~~

533Os argumentos indexados usam aspas no estilo do shell, então coloque valores com várias palavras entre aspas para passá-los como um único argumento. Por exemplo, `/my-skill "hello world" second` faz `$0` se expandir para `hello world` e `$1` para `second`. O placeholder `$ARGUMENTS` sempre se expande para a string completa de argumentos como foi digitada.

534 532

535Um placeholder indexado sem argumento correspondente, como `$2` quando apenas um argumento foi passado, permanece inalterado no conteúdo. Um placeholder nomeado do frontmatter [`arguments`](#frontmatter-reference) sem argumento correspondente se expande para uma string vazia.533Um placeholder indexado sem argumento correspondente, como `$2` quando apenas um argumento foi passado, permanece inalterado no conteúdo. Um placeholder nomeado do frontmatter [`arguments`](#frontmatter-reference) sem argumento correspondente se expande para uma string vazia.

536 534

537Se você passar um valor de argumento que contenha texto como `$1` ou `$ARGUMENTS`, o Claude Code o insere como texto literal e não o expande. Por exemplo, se o corpo de uma skill contém `Summarize $0` e você executa `/summarize "$ARGUMENTS from yesterday"`, o Claude recebe `Summarize $ARGUMENTS from yesterday`. O Claude Code ainda substitui variáveis `${CLAUDE_*}`, como `${CLAUDE_SKILL_DIR}`, depois de inserir os argumentos.535Se você passar um valor de argumento que contenha texto como `$1` ou `$ARGUMENTS`, o Claude Code o insere como texto literal e não o expande. Por exemplo, se o corpo de uma skill contiver `Summarize $0` e você executar `/summarize "$ARGUMENTS from yesterday"`, Claude recebe `Summarize $ARGUMENTS from yesterday`. O Claude Code ainda substitui variáveis `${CLAUDE_*}`, como `${CLAUDE_SKILL_DIR}`, depois de inserir os argumentos.

538 536

539Para incluir um `$` literal antes de um dígito, de `ARGUMENTS` ou de um nome de argumento declarado, como `$1.00` em texto corrido, escape-o com uma barra invertida: `\$1.00`. Uma barra invertida antes de qualquer outro `$` permanece inalterada. Apenas uma única barra invertida imediatamente antes do token o escapa. Uma barra invertida duplicada, como `\\$1`, mantém ambas as barras invertidas, e `$1` ainda se expande para o valor do argumento. O escape com barra invertida abrange apenas esses placeholders de argumentos. Uma barra invertida não impede a substituição de uma variável `${CLAUDE_*}` onde a variável se aplica.537Para incluir um `$` literal antes de um dígito, de `ARGUMENTS` ou de um nome de argumento declarado, como `$1.00` em prosa, escape-o com uma barra invertida: `\$1.00`. Uma barra invertida antes de qualquer outro `$` permanece inalterada. Apenas uma única barra invertida diretamente antes do token o escapa. Uma barra invertida dupla, como `\\$1`, mantém ambas as barras invertidas no lugar, e `$1` ainda se expande para o valor do argumento. O escape com barra invertida abrange apenas esses placeholders de argumentos. Uma barra invertida não impede a substituição de uma variável `${CLAUDE_*}` onde a variável se aplica.

540 538

541**Exemplo usando substituições:**539**Exemplo usando substituições:**

542 540

555 Adicionar arquivos de suporte553 Adicionar arquivos de suporte

556</h3>554</h3>

557 555

558As skills podem incluir vários arquivos em seu diretório. Isso mantém o `SKILL.md` focado no essencial, ao mesmo tempo que permite ao Claude acessar material de referência detalhado apenas quando necessário. Documentos de referência grandes, especificações de API ou coleções de exemplos não precisam ser carregados no contexto toda vez que a skill é executada.556As skills podem incluir vários arquivos em seu diretório. Isso mantém o `SKILL.md` focado no essencial, permitindo que Claude acesse material de referência detalhado apenas quando necessário. Documentos de referência grandes, especificações de API ou coleções de exemplos não precisam ser carregados no contexto toda vez que a skill é executada.

559 557

560```text theme={null}558```text theme={null}

561my-skill/559my-skill/

566 └── helper.py (utility script - executed, not loaded)564 └── helper.py (utility script - executed, not loaded)

567```565```

568 566

569Referencie os arquivos de suporte a partir do `SKILL.md` para que o Claude saiba o que cada arquivo contém e quando carregá-lo:567Referencie os arquivos de suporte a partir do `SKILL.md` para que Claude saiba o que cada arquivo contém e quando carregá-lo:

570 568

571```markdown theme={null}569```markdown theme={null}

572## Additional resources570## Additional resources

575- For usage examples, see [examples.md](examples.md)573- For usage examples, see [examples.md](examples.md)

576```574```

577 575

578<Tip>Mantenha o `SKILL.md` com menos de 500 linhas. Mova o material de referência detalhado para arquivos separados.</Tip>576<Tip>Mantenha o `SKILL.md` com menos de 500 linhas. Mova material de referência detalhado para arquivos separados.</Tip>

579 577

580<h3 id="control-who-invokes-a-skill">578<h3 id="control-who-invokes-a-skill">

581 Controlar quem invoca uma skill579 Controlar quem invoca uma skill

582</h3>580</h3>

583 581

584Por padrão, tanto você quanto o Claude podem invocar qualquer skill. Você pode digitar `/skill-name` para invocá-la diretamente, e o Claude pode carregá-la automaticamente quando for relevante para sua conversa. Dois campos do frontmatter permitem restringir isso:582Por padrão, tanto você quanto Claude podem invocar qualquer skill. Você pode digitar `/skill-name` para invocá-la diretamente, e Claude pode carregá-la automaticamente quando for relevante para sua conversa. Dois campos do frontmatter permitem restringir isso:

585 583

586* **`disable-model-invocation: true`**: o Claude não pode invocar a skill por conta própria. Use isso para fluxos de trabalho com efeitos colaterais ou cujo momento você deseja controlar, como `/commit`, `/deploy` ou `/send-slack-message`. Você não quer que o Claude decida fazer deploy porque seu código parece pronto.584* **`disable-model-invocation: true`**: Claude não pode invocar a skill por conta própria. Use isso para fluxos de trabalho com efeitos colaterais ou cujo momento você deseja controlar, como `/commit`, `/deploy` ou `/send-slack-message`. Você não quer que Claude decida fazer deploy porque seu código parece pronto.

587 585

588* **`user-invocable: false`**: apenas o Claude pode invocar a skill. Use isso para conhecimento de fundo que não é acionável como comando. Uma skill `legacy-system-context` explica como um sistema antigo funciona. O Claude deve saber disso quando for relevante, mas `/legacy-system-context` não é uma ação significativa para os usuários executarem.586* **`user-invocable: false`**: Apenas Claude pode invocar a skill. Use isso para conhecimento de fundo que não é acionável como comando. Uma skill `legacy-system-context` explica como um sistema antigo funciona. Claude deve saber disso quando relevante, mas `/legacy-system-context` não é uma ação significativa para os usuários executarem.

589 587

590Este exemplo cria uma skill de deploy. Se você definir `disable-model-invocation: true`, o Claude não poderá executar a skill automaticamente:588Este exemplo cria uma skill de deploy. Se você definir `disable-model-invocation: true`, Claude não pode executar a skill automaticamente:

591 589

592```yaml theme={null}590```yaml theme={null}

593---591---

6044. Verify the deployment succeeded6024. Verify the deployment succeeded

605```603```

606 604

607Se o Claude tentar mesmo assim, o Claude Code bloqueia a chamada e o instrui a não reproduzir as etapas de deploy de outra forma, então espere que o Claude sugira que você mesmo execute `/deploy`.605Se Claude tentar mesmo assim, o Claude Code bloqueia a chamada e o instrui a não reproduzir as etapas de deploy de outra forma, então espere que Claude sugira que você mesmo execute `/deploy`.

608 606

609Veja como os dois campos afetam a invocação e o carregamento no contexto:607Veja como os dois campos afetam a invocação e o carregamento no contexto:

610 608

612| :- | :- | :- | :- |610| :- | :- | :- | :- |

613| (padrão) | Sim | Sim | Descrição sempre no contexto, skill completa carregada quando invocada |611| (padrão) | Sim | Sim | Descrição sempre no contexto, skill completa é carregada quando invocada |

615| `user-invocable: false` | Não | Sim | Descrição sempre no contexto, skill completa carregada quando invocada |613| `user-invocable: false` | Não | Sim | Descrição sempre no contexto, skill completa é carregada quando invocada |

616 614

617<Note>615<Note>

618 Em uma sessão normal, as descrições das skills são carregadas no contexto para que o Claude saiba o que está disponível, mas o conteúdo completo da skill só é carregado quando invocado. [Subagentes com skills pré-carregadas](/docs/pt/sub-agents#preload-skills-into-subagents) funcionam de forma diferente: o conteúdo completo da skill é injetado na inicialização.616 Em uma sessão normal, as descrições das skills são carregadas no contexto para que Claude saiba o que está disponível, mas o conteúdo completo da skill só é carregado quando invocada. [Subagentes com skills pré-carregadas](/docs/pt/sub-agents#preload-skills-into-subagents) funcionam de forma diferente: o conteúdo completo da skill é injetado na inicialização.

619</Note>617</Note>

620 618

621<h4 id="where-you-write-the-skill’s-name">619<h4 id="where-you-write-the-skill’s-name">

622 Onde você escreve o nome da skill620 Onde você escreve o nome da skill

623</h4>621</h4>

624 622

625Para executar uma skill diretamente, coloque seu nome no início da mensagem. Após texto simples, o nome dá ao Claude permissão para executar a skill, mas não a executa:623Para executar uma skill diretamente, coloque o nome dela no início da sua mensagem. Após texto simples, o nome dá a Claude permissão para executar a skill, mas não a executa:

626 624

628| :- | :- | :- |626| :- | :- | :- |

630| Após texto simples, como uma palavra separada sem pontuação anexada | `go ahead and /deploy to staging` | Nada é executado diretamente. O nome conta como sua permissão para aquela mensagem: o Claude pode executar a skill enquanto responde e avalia pela sua redação se você pediu isso |628| Após texto simples, como uma palavra separada sem pontuação anexada | `go ahead and /deploy to staging` | Nada é executado diretamente. O nome conta como sua permissão para aquela mensagem: Claude pode executar a skill enquanto responde e julga, pelas suas palavras, se você pediu isso |

631 629

632Para escrever sobre a skill sem permitir uma execução, omita a barra.630Para escrever sobre a skill sem permitir uma execução, omita a barra.

633 631

635 Ciclo de vida do conteúdo da skill633 Ciclo de vida do conteúdo da skill

636</h3>634</h3>

637 635

638Quando você ou o Claude invocam uma skill, o conteúdo renderizado do `SKILL.md` entra na conversa como uma única mensagem e permanece ali nos turnos seguintes. Essa persistência se aplica às instruções da skill, não às suas permissões: uma concessão de [`allowed-tools`](#pre-approve-tools-for-a-skill) é removida quando você envia sua próxima mensagem. O Claude Code não relê o arquivo da skill em turnos posteriores, então escreva as orientações que devem valer durante toda uma tarefa como instruções permanentes, e não como etapas únicas.636Quando você ou Claude invocam uma skill, o conteúdo renderizado do `SKILL.md` entra na conversa como uma única mensagem e permanece ali nos turnos seguintes. Essa persistência se aplica às instruções da skill, não às suas permissões: uma concessão de [`allowed-tools`](#pre-approve-tools-for-a-skill) é removida quando você envia sua próxima mensagem. O Claude Code não relê o arquivo da skill nos turnos seguintes, então escreva orientações que devem valer durante toda uma tarefa como instruções permanentes, e não como etapas únicas.

639 637

640Quando o Claude reinvoca uma skill cujo conteúdo renderizado é idêntico à cópia já presente no contexto, o Claude Code adiciona uma breve nota de que a skill já está carregada, em vez de uma segunda cópia do conteúdo. Quando o conteúdo renderizado é diferente, porque os argumentos mudaram ou um comando de [contexto dinâmico](#inject-dynamic-context) produziu uma nova saída, o Claude Code anexa o conteúdo completo novamente.638Quando Claude invoca novamente uma skill cujo conteúdo renderizado é idêntico à cópia já presente no contexto, o Claude Code adiciona uma breve nota de que a skill já está carregada, em vez de uma segunda cópia do conteúdo. Quando o conteúdo renderizado é diferente, porque os argumentos mudaram ou um comando de [contexto dinâmico](#inject-dynamic-context) produziu uma nova saída, o Claude Code anexa o conteúdo completo novamente.

641 639

642A [compactação automática](/docs/pt/how-claude-code-works#when-context-fills-up) mantém as skills invocadas dentro de um orçamento de tokens. Quando a conversa é resumida para liberar contexto, o Claude Code reanexa a invocação mais recente de cada skill após o resumo, mantendo os primeiros 5.000 tokens de cada uma. As skills reanexadas compartilham um orçamento combinado de 25.000 tokens. O Claude Code preenche esse orçamento começando pela skill invocada mais recentemente, então skills mais antigas podem ser descartadas por completo após a compactação se você tiver invocado muitas em uma sessão.640A [compactação automática](/docs/pt/how-claude-code-works#when-context-fills-up) mantém as skills invocadas dentro de um orçamento de tokens. Quando a conversa é resumida para liberar contexto, o Claude Code anexa novamente a invocação mais recente de cada skill após o resumo, mantendo os primeiros 5.000 tokens de cada uma. As skills anexadas novamente compartilham um orçamento combinado de 25.000 tokens. O Claude Code preenche esse orçamento a partir da skill invocada mais recentemente, então skills mais antigas podem ser descartadas por completo após a compactação se você tiver invocado muitas em uma sessão.

643 641

644Se o Claude parar de seguir uma skill no meio de uma sessão, consulte [O Claude para de seguir uma skill](#claude-stops-following-a-skill).642Se Claude parar de seguir uma skill no meio de uma sessão, consulte [Claude para de seguir uma skill](#claude-stops-following-a-skill).

645 643

646<h3 id="pre-approve-tools-for-a-skill">644<h3 id="pre-approve-tools-for-a-skill">

647 Pré-aprovar ferramentas para uma skill645 Pré-aprovar ferramentas para uma skill

648</h3>646</h3>

649 647

650O campo `allowed-tools` concede permissão para as ferramentas listadas durante o turno que invoca a skill, para que o Claude possa usá-las sem solicitar sua aprovação. A concessão é removida quando você envia sua próxima mensagem, mesmo que o conteúdo da skill [permaneça no contexto](#skill-content-lifecycle); invocar a skill novamente a reaplica para aquele turno. Ele não restringe quais ferramentas estão disponíveis: todas as ferramentas continuam podendo ser chamadas, e suas [configurações de permissão](/docs/pt/permissions) ainda regem as ferramentas que não estão listadas. Para pré-aprovar ferramentas para a sessão inteira em vez de um único turno, adicione regras de allow a essas configurações de permissão.648O campo `allowed-tools` concede permissão para as ferramentas listadas durante o turno que invoca a skill, para que Claude possa usá-las sem solicitar sua aprovação. A concessão é removida quando você envia sua próxima mensagem, mesmo que o conteúdo da skill [permaneça no contexto](#skill-content-lifecycle); invocar a skill novamente a reaplica para aquele turno. Ele não restringe quais ferramentas estão disponíveis: todas as ferramentas continuam podendo ser chamadas, e suas [configurações de permissão](/docs/pt/permissions) ainda regem as ferramentas que não estão listadas. Para pré-aprovar ferramentas para a sessão inteira em vez de um único turno, adicione regras allow a essas configurações de permissão.

651 649

652A confiança no workspace não restringe este campo. O Claude Code aplica o `allowed-tools` de uma skill de projeto mesmo em uma execução com `-p` em uma pasta na qual você nunca confiou. Uma skill pode conceder a si mesma amplo acesso a ferramentas, então revise o `allowed-tools` das skills incluídas em um repositório antes de executar o Claude Code nele. Para desconsiderar o campo em skills de repositório em toda a sua organização, consulte [Quando apenas regras de permissão gerenciadas se aplicam](#when-only-managed-permission-rules-apply).650A confiança do workspace não restringe este campo. O Claude Code aplica o `allowed-tools` de uma skill de projeto mesmo em uma execução `-p` em uma pasta na qual você nunca confiou. Uma skill pode conceder a si mesma amplo acesso a ferramentas, então revise o `allowed-tools` das skills incluídas em um repositório antes de executar o Claude Code ali. Para desconsiderar o campo em skills de repositório em toda a sua organização, consulte [Quando apenas regras de permissão gerenciadas se aplicam](#when-only-managed-permission-rules-apply).

653 651

654Esta skill permite que o Claude execute comandos git sem aprovação a cada uso sempre que você a invocar:652Esta skill permite que Claude execute comandos git sem aprovação a cada uso sempre que você a invoca:

655 653

656```yaml theme={null}654```yaml theme={null}

657---655---

662---660---

663```661```

664 662

665Para remover ferramentas do conjunto disponível do Claude enquanto uma skill está ativa, liste-as em `disallowed-tools` no frontmatter da skill. A restrição é removida quando você envia sua próxima mensagem. Assim como as regras de deny, o campo não pode remover [`EndConversation`](/docs/pt/tools-reference#endconversation-tool-behavior) enquanto qualquer outra ferramenta permanecer. Para bloquear ferramentas em todas as skills e prompts, adicione regras de deny nas suas [configurações de permissão](/docs/pt/permissions).663Para remover ferramentas do conjunto disponível para Claude enquanto uma skill está ativa, liste-as em `disallowed-tools` no frontmatter da skill. A restrição é removida quando você envia sua próxima mensagem. Assim como as regras deny, o campo não pode remover [`EndConversation`](/docs/pt/tools-reference#endconversation-tool-behavior) enquanto qualquer outra ferramenta permanecer. Para bloquear ferramentas em todas as skills e prompts, adicione regras deny nas suas [configurações de permissão](/docs/pt/permissions).

666 664

667<h4 id="when-only-managed-permission-rules-apply">665<h4 id="when-only-managed-permission-rules-apply">

668 Quando apenas regras de permissão gerenciadas se aplicam666 Quando apenas regras de permissão gerenciadas se aplicam

670 668

671Quando sua organização define `allowManagedPermissionRulesOnly` nas configurações gerenciadas, o Claude Code ignora `allowed-tools` em skills de projeto e pessoais e nas [outras origens listadas na entrada da configuração](/docs/pt/settings-reference#allowmanagedpermissionrulesonly). Isso requer o Claude Code v2.1.282 ou posterior.669Quando sua organização define `allowManagedPermissionRulesOnly` nas configurações gerenciadas, o Claude Code ignora `allowed-tools` em skills de projeto e pessoais e nas [outras origens listadas na entrada da configuração](/docs/pt/settings-reference#allowmanagedpermissionrulesonly). Isso requer o Claude Code v2.1.282 ou posterior.

672 670

673As ferramentas que uma skill afetada lista passam, em vez disso, pelas regras gerenciadas da sua organização e pelo prompt de permissão normal. Execute `/status` para listar cada skill cujo `allowed-tools` o Claude Code ignorou até o momento na sessão. Um comando injetado na skill que nenhuma regra gerenciada permite segue as [Verificações de permissão em comandos injetados](#permission-checks-on-injected-commands).671As ferramentas que uma skill afetada lista passam pelas regras gerenciadas da sua organização e pelo prompt de permissão normal. Execute `/status` para listar cada skill cujo `allowed-tools` o Claude Code ignorou até o momento na sessão. Um comando injetado na skill que nenhuma regra gerenciada permite segue as [Verificações de permissão em comandos injetados](#permission-checks-on-injected-commands).

674 672

675<h3 id="pass-arguments-to-skills">673<h3 id="pass-arguments-to-skills">

676 Passar argumentos para skills674 Passar argumentos para skills

677</h3>675</h3>

678 676

679Tanto você quanto o Claude podem passar argumentos ao invocar uma skill. Os argumentos ficam disponíveis por meio do placeholder `$ARGUMENTS`.677Tanto você quanto Claude podem passar argumentos ao invocar uma skill. Os argumentos ficam disponíveis por meio do placeholder `$ARGUMENTS`.

680 678

681Esta skill corrige uma issue do GitHub pelo número. O placeholder `$ARGUMENTS` é substituído pelo que vier após o nome da skill:679Esta skill corrige uma issue do GitHub pelo número. O placeholder `$ARGUMENTS` é substituído pelo que vier após o nome da skill:

682 680

6965. Create a commit6945. Create a commit

697```695```

698 696

699Quando você executa `/fix-issue 123`, o Claude recebe "Fix GitHub issue 123 following our coding standards..."697Quando você executa `/fix-issue 123`, Claude recebe "Fix GitHub issue 123 following our coding standards..."

700 698

701Se você invocar uma skill com argumentos, mas nenhum placeholder no conteúdo da skill receber um, o Claude Code anexa `ARGUMENTS: <your input>` ao final do conteúdo da skill para que o Claude ainda veja o que você digitou. Um placeholder é `$ARGUMENTS`, uma forma indexada como `$1` ou um argumento nomeado. Um placeholder indexado sem argumento na sua posição permanece como texto literal e não conta como tendo recebido um. Um placeholder nomeado conta mesmo quando sua posição não tem argumento, porque ele se expande para uma string vazia.699Se você invocar uma skill com argumentos, mas nenhum placeholder no conteúdo da skill receber um, o Claude Code anexa `ARGUMENTS: <your input>` ao final do conteúdo da skill para que Claude ainda veja o que você digitou. Um placeholder é `$ARGUMENTS`, uma forma indexada como `$1` ou um argumento nomeado. Um placeholder indexado sem argumento em sua posição permanece como texto literal e não conta como tendo recebido um. Um placeholder nomeado conta mesmo quando sua posição não tem argumento, porque ele se expande para uma string vazia.

702 700

703Você também pode empilhar várias skills no início de uma mensagem. Digitar `/write-tests /fix-issue 123` carrega ambas as skills e passa o texto final `123` como `$ARGUMENTS` para cada uma delas.701Você também pode empilhar várias skills no início de uma mensagem. Digitar `/write-tests /fix-issue 123` carrega ambas as skills e passa o texto final `123` como `$ARGUMENTS` para cada uma delas.

704 702

705O Claude Code expande a primeira skill mais até cinco outras empilhadas depois dela. A expansão para no primeiro token que não seja uma skill inline invocável pelo usuário, então uma skill que é executada como um [subagente bifurcado](#run-skills-in-a-subagent), como [`/code-review`](/docs/pt/code-review#review-a-diff-locally), ou uma cujos argumentos podem começar com um comando de barra, como `/loop`, também encerra a sequência ali. Esse token e tudo o que vem depois dele se tornam o texto de argumentos para todas as skills expandidas. `/code-review` é executado como um subagente bifurcado a partir da v2.1.218; em versões anteriores, ele era executado inline e empilhado.703O Claude Code expande a primeira skill mais até cinco outras empilhadas depois dela. A expansão para no primeiro token que não seja uma skill inline invocável pelo usuário, então uma skill que é executada como um [subagente bifurcado](#run-skills-in-a-subagent), como [`/code-review`](/docs/pt/code-review#review-a-diff-locally), ou uma cujos argumentos possam começar com um comando de barra, como `/loop`, também encerra a sequência ali. Esse token e tudo o que vem depois dele se tornam o texto de argumento para cada skill expandida. `/code-review` é executada como um subagente bifurcado a partir da v2.1.218; em versões anteriores, ela era executada inline e empilhada.

706 704

707Para acessar argumentos individuais pela posição, use `$ARGUMENTS[N]` ou a forma mais curta `$N`:705Para acessar argumentos individuais por posição, use `$ARGUMENTS[N]` ou a forma mais curta `$N`:

708 706

709```yaml theme={null}707```yaml theme={null}

710---708---

716Preserve all existing behavior and tests.714Preserve all existing behavior and tests.

717```715```

718 716

719Executar `/migrate-component SearchBar JavaScript TypeScript` substitui `$ARGUMENTS[0]` por `SearchBar`, `$ARGUMENTS[1]` por `JavaScript` e `$ARGUMENTS[2]` por `TypeScript`. A mesma skill usando a forma abreviada `$N`:717Executar `/migrate-component SearchBar JavaScript TypeScript` substitui `$ARGUMENTS[0]` por `SearchBar`, `$ARGUMENTS[1]` por `JavaScript` e `$ARGUMENTS[2]` por `TypeScript`. A mesma skill usando a abreviação `$N`:

720 718

721```yaml theme={null}719```yaml theme={null}

722---720---

843* Quando você invoca uma skill bifurcada enquanto uma invocação anterior da mesma skill ainda está em execução841* Quando você invoca uma skill bifurcada enquanto uma invocação anterior da mesma skill ainda está em execução

844* Quando uma [scheduled task](/docs/pt/scheduled-tasks) dispara com a skill como seu prompt842* Quando uma [scheduled task](/docs/pt/scheduled-tasks) dispara com a skill como seu prompt

845 843

844Quando um agente em um [fluxo de trabalho dinâmico](/docs/pt/workflows) invoca uma skill bifurcada, esse agente espera e recebe o resultado, mesmo quando a skill não define `background: false`. Antes da v2.1.295, Claude Code não esperava nesse caso, e quando a skill era executada em segundo plano, seu resultado chegava à sua conversa principal em vez de chegar a esse agente.

845

846Um fork em background também é executado com o [conjunto de ferramentas mais estreito que se aplica a subagentes em background](/docs/pt/sub-agents#run-subagents-in-foreground-or-background): o subagente da skill é um tipo de agente regular, então a isenção para subagentes que bifurcam a conversa não o cobre. Se as etapas de sua skill dependem de uma ferramenta fora desse conjunto, defina `background: false` para manter o conjunto completo de ferramentas.846Um fork em background também é executado com o [conjunto de ferramentas mais estreito que se aplica a subagentes em background](/docs/pt/sub-agents#run-subagents-in-foreground-or-background): o subagente da skill é um tipo de agente regular, então a isenção para subagentes que bifurcam a conversa não o cobre. Se as etapas de sua skill dependem de uma ferramenta fora desse conjunto, defina `background: false` para manter o conjunto completo de ferramentas.

847 847

848Uma skill bifurcada que é executada em background aplica suas edições fora dos [checkpoints](/docs/pt/checkpointing) de sua sessão, então `/rewind` não as desfaz; use git para revertê-las.848Uma skill bifurcada que é executada em background aplica suas edições fora dos [checkpoints](/docs/pt/checkpointing) de sua sessão, então `/rewind` não as desfaz; use git para revertê-las.

sub-agents.md +3 −5

Details

386* **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](/docs/pt/model-config#extended-context) da conversa principal.386* **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](/docs/pt/model-config#extended-context) da conversa principal.

387* **O Claude Code não consegue identificar a família do modelo da conversa principal, em [um provedor diferente da API da Anthropic](/docs/pt/third-party-integrations)**: isso pode acontecer com um [ARN de perfil de inferência de aplicação](/docs/pt/amazon-bedrock#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`](/docs/pt/model-config#environment-variables), pois `opus` então resolve para o modelo que você definiu.387* **O Claude Code não consegue identificar a família do modelo da conversa principal, em [um provedor diferente da API da Anthropic](/docs/pt/third-party-integrations)**: isso pode acontecer com um [ARN de perfil de inferência de aplicação](/docs/pt/amazon-bedrock#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`](/docs/pt/model-config#environment-variables), pois `opus` então resolve para o modelo que você definiu.

388 388

389Um 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.389Um 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.

390 390

391Definir `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).391Definir `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).

392 392

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

394 394

395Definir a variável como `inherit` é o mesmo que deixá-la sem definição. Antes da v2.1.196, esse valor forçava os subagentes a usar o modelo da conversa principal e ignorava as outras fontes.

~~396~~

397O Claude Code verifica os valores do parâmetro por invocação, do frontmatter e da variável de ambiente em relação à allowlist [`availableModels`](/docs/pt/model-config#restrict-model-selection) da sua organização. Para um valor bloqueado, ele substitui por outro modelo:395O Claude Code verifica os valores do parâmetro por invocação, do frontmatter e da variável de ambiente em relação à allowlist [`availableModels`](/docs/pt/model-config#restrict-model-selection) da sua organização. Para um valor bloqueado, ele substitui por outro modelo:

398 396

399* 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](/docs/pt/model-config#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.397* 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](/docs/pt/model-config#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.

621| `acceptEdits` | Aceita automaticamente edições de arquivos e comandos comuns do sistema de arquivos para caminhos no diretório de trabalho ou em `additionalDirectories` |619| `acceptEdits` | Aceita automaticamente edições de arquivos e comandos comuns do sistema de arquivos para caminhos no diretório de trabalho ou em `additionalDirectories` |

622| `auto` | [Modo auto](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode): um classificador em segundo plano revisa comandos e gravações em diretórios protegidos |620| `auto` | [Modo auto](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode): um classificador em segundo plano revisa comandos e gravações em diretórios protegidos |

623| `dontAsk` | Nega automaticamente os prompts de permissão. Ferramentas explicitamente permitidas ainda funcionam; `AskUserQuestion`, ferramentas MCP marcadas com [`requiresUserInteraction`](/docs/pt/mcp#require-approval-for-a-specific-tool) e ferramentas de conectores que [sua organização definiu como `ask`](/docs/pt/mcp#organization-controls-on-connector-tools) em sessões onde essa configuração chega ao Claude Code são negadas mesmo que você as tenha permitido |621| `dontAsk` | Nega automaticamente os prompts de permissão. Ferramentas explicitamente permitidas ainda funcionam; `AskUserQuestion`, ferramentas MCP marcadas com [`requiresUserInteraction`](/docs/pt/mcp#require-approval-for-a-specific-tool), [leituras de caminhos de rede](/docs/pt/permissions#network-paths) e ferramentas de conectores que [sua organização definiu como `ask`](/docs/pt/mcp#organization-controls-on-connector-tools) em sessões onde essa configuração chega ao Claude Code são negadas mesmo que você as tenha permitido |

624| `bypassPermissions` | [Ignora os prompts de permissão](/docs/pt/permission-modes#skip-all-checks-with-bypasspermissions-mode). Um subagente é executado neste modo somente quando a conversa principal também está |622| `bypassPermissions` | [Ignora os prompts de permissão](/docs/pt/permission-modes#skip-all-checks-with-bypasspermissions-mode). Um subagente é executado neste modo somente quando a conversa principal também está |

626 624

1150* **System prompt**: o próprio prompt do agente mais detalhes de ambiente que Claude Code acrescenta, não o system prompt do Claude Code. Subagentes personalizados definem o seu no [corpo markdown](#write-subagent-files) ou campo `prompt`. Agentes integrados têm prompts predefinidos.1148* **System prompt**: o próprio prompt do agente mais detalhes de ambiente que Claude Code acrescenta, não o system prompt do Claude Code. Subagentes personalizados definem o seu no [corpo markdown](#write-subagent-files) ou campo `prompt`. Agentes integrados têm prompts predefinidos.

1151* **Mensagem de tarefa**: o prompt de delegação que Claude escreve quando passa o trabalho.1149* **Mensagem de tarefa**: o prompt de delegação que Claude escreve quando passa o trabalho.

1152* **Arquivos CLAUDE.md**: cada nível da [hierarquia CLAUDE.md](/docs/pt/memory#how-claude-md-files-load) que a conversa principal carrega, incluindo `~/.claude/CLAUDE.md`, regras do projeto, `CLAUDE.local.md`, arquivos de política gerenciada e qualquer arquivo [`AGENTS.md`](/docs/pt/memory#agents-md) carregado como instruções do projeto. Os agentes Explore e Plan integrados pulam isso. Um subagente cuja definição define [`omitClaudeMd`](#supported-frontmatter-fields) carrega apenas os arquivos de política gerenciada, ou nenhum quando a definição vem de [configurações gerenciadas](#choose-the-subagent-scope).1150* **Arquivos CLAUDE.md**: cada nível da [hierarquia CLAUDE.md](/docs/pt/memory#how-claude-md-files-load) que a conversa principal carrega, incluindo `~/.claude/CLAUDE.md`, regras do projeto, `CLAUDE.local.md`, arquivos de política gerenciada e qualquer arquivo [`AGENTS.md`](/docs/pt/memory#agents-md) carregado como instruções do projeto. Os agentes Explore e Plan integrados pulam isso. Um subagente cuja definição define [`omitClaudeMd`](#supported-frontmatter-fields) carrega apenas os arquivos de política gerenciada, ou nenhum quando a definição vem de [configurações gerenciadas](#choose-the-subagent-scope).

1153* **Status Git**: um snapshot que Claude Code lê do seu repositório quando o subagente é iniciado. Ausente fora de um repositório Git ou sempre que o snapshot estiver desativado; consulte [`includeGitInstructions`](/docs/pt/settings-reference#includegitinstructions). Explore e Plan o pulam de qualquer forma.1151* **Status Git**: um snapshot que Claude Code lê do seu repositório quando o subagente é iniciado. Para um subagente em [seu próprio worktree](/docs/pt/worktrees#isolate-subagents-with-worktrees) desse repositório, o snapshot mostra o branch, o status e os commits recentes do worktree. Ausente fora de um repositório Git ou sempre que o snapshot estiver desativado; consulte [`includeGitInstructions`](/docs/pt/settings-reference#includegitinstructions). Explore e Plan o pulam de qualquer forma.

1154* **Skills pré-carregadas**: conteúdo completo de qualquer skill nomeada no campo [`skills`](#preload-skills-into-subagents) do agente. Agentes integrados não pré-carregam skills.1152* **Skills pré-carregadas**: conteúdo completo de qualquer skill nomeada no campo [`skills`](#preload-skills-into-subagents) do agente. Agentes integrados não pré-carregam skills.

1155* **Roster de irmãos**: um [lembrete do sistema](/docs/pt/glossary#system-reminder) listando `main` e cada outro agente nomeado na sessão, cada um um valor `to` válido para [`SendMessage`](#resume-subagents). Requer Claude Code v2.1.206 ou posterior. O roster aparece apenas quando as ferramentas do subagente incluem `SendMessage` e pelo menos um outro agente tem um nome, seja Claude o nomeou ao gerá-lo ou ele é executado como um colega de [equipe de agentes](/docs/pt/agent-teams). É um snapshot tirado quando o subagente começa, então agentes nomeados depois não aparecem.1153* **Roster de irmãos**: um [lembrete do sistema](/docs/pt/glossary#system-reminder) listando `main` e cada outro agente nomeado na sessão, cada um um valor `to` válido para [`SendMessage`](#resume-subagents). Requer Claude Code v2.1.206 ou posterior. O roster aparece apenas quando as ferramentas do subagente incluem `SendMessage` e pelo menos um outro agente tem um nome, seja Claude o nomeou ao gerá-lo ou ele é executado como um colega de [equipe de agentes](/docs/pt/agent-teams). É um snapshot tirado quando o subagente começa, então agentes nomeados depois não aparecem.

1156 1154

terminal-config.md +13 −0

Details

122}122}

123```123```

124 124

125<h2 id="see-session-status-in-your-terminal">

126 Ver o status da sessão no seu terminal

127</h2>

128

129Se o seu terminal implementa o OSC 7501 Program Status Protocol, ele pode mostrar se cada sessão interativa do Claude Code está trabalhando, aguardando você ou concluída, o que ajuda quando você executa tarefas longas ou várias sessões ao mesmo tempo. Não há nada para ativar no Claude Code. Para descobrir se o seu terminal implementa o protocolo e onde ele mostra o status, consulte a documentação dele.

130

131Se ele implementa e você não vê nenhum status para uma sessão, verifique cada uma destas causas:

132

133* **Versão do Claude Code**: o relato de status requer o Claude Code v2.1.295 ou posterior. Execute `claude --version` no seu shell para verificar.

134* **tmux**: dentro do tmux, o Claude Code verifica o suporte no tmux em vez de no seu terminal, e [`allow-passthrough`](#configure-tmux) não tem efeito sobre isso. Inicie a sessão fora do tmux.

135* **Sessão em segundo plano**: uma [sessão em segundo plano](/docs/pt/agent-view) não relata seu status ao seu terminal, mesmo enquanto você está conectado a ela. A visualização de agentes mostra o status dela em vez disso.

136* **[`CLAUDE_CODE_DISABLE_TERMINAL_TITLE`](/docs/pt/env-vars#variables)**: se você definir essa variável como `1`, o Claude Code não verifica o suporte nem relata o status. Remova a definição dela.

137

125<h2 id="configure-tmux">138<h2 id="configure-tmux">

126 Configurar tmux139 Configurar tmux

127</h2>140</h2>

tools-reference.md +32 −11

Details

279 279

280A ferramenta Edit realiza substituição exata de strings. Ela recebe uma `old_string` e uma `new_string` e substitui a primeira pela segunda. Ela não usa regex ou correspondência aproximada.280A ferramenta Edit realiza substituição exata de strings. Ela recebe uma `old_string` e uma `new_string` e substitui a primeira pela segunda. Ela não usa regex ou correspondência aproximada.

281 281

282Três verificações devem passar para que uma edição seja aplicada. Antes de qualquer uma delas, um caminho correspondido por uma [regra de negação `Read`](/docs/pt/permissions#tool-specific-permission-rules) é recusado, incluindo a criação de um novo arquivo lá. A recusa requer Claude Code v2.1.208 ou posterior.282Estas verificações devem passar para que uma edição seja aplicada. Antes de qualquer uma delas, um caminho correspondido por uma [regra de negação `Read`](/docs/pt/permissions#tool-specific-permission-rules) é recusado, incluindo a criação de um novo arquivo lá. A recusa requer Claude Code v2.1.208 ou posterior.

283 283

284* **Read-before-edit**: Claude lê o arquivo na conversa atual antes de editá-lo, e uma leitura interrompida com um aviso [`PARTIAL view`](#read-tool-behavior) não conta. Claude Opus 4.6, Claude Haiku 4.5 e modelos mais antigos sempre exigem a leitura. Modelos mais novos podem editar um arquivo não lido quando a leitura não precisaria de um prompt de permissão e a ferramenta Read está disponível.284* **Read-before-edit**: Claude lê o arquivo na conversa atual antes de editá-lo, e uma leitura interrompida com um aviso [`PARTIAL view`](#large-files) não conta. Claude Opus 4.6, Claude Haiku 4.5 e modelos mais antigos sempre exigem a leitura. Modelos mais novos podem editar um arquivo não lido quando a leitura não precisaria de um prompt de permissão e a ferramenta Read está disponível.

285* **Match**: `old_string` deve aparecer no arquivo exatamente como escrito. Uma única diferença de caractere de espaço em branco ou indentação é suficiente para não corresponder.285* **Match**: `old_string` deve aparecer no arquivo exatamente como escrito. Uma única diferença de caractere de espaço em branco ou indentação é suficiente para não corresponder.

286* **Uniqueness**: `old_string` deve aparecer exatamente uma vez. Quando aparece mais de uma vez, Claude fornece uma string mais longa com contexto circundante suficiente para identificar uma ocorrência, ou define `replace_all: true` para substituir todas elas.286* **Uniqueness**: `old_string` deve aparecer exatamente uma vez. Quando aparece mais de uma vez, Claude fornece uma string mais longa com contexto circundante suficiente para identificar uma ocorrência, ou define `replace_all: true` para substituir todas elas.

287 287

288Um arquivo que mudou no disco depois que Claude o leu pela última vez ainda pode ser editado quando `old_string` corresponde ao conteúdo atual exatamente e sem ambiguidade e Claude Code pode ler o arquivo sem solicitar. Corresponder contra o conteúdo atual do arquivo mantém isso seguro, e o resultado observa que o arquivo contém outras alterações para que Claude o releia antes de edições que dependem do conteúdo circundante. Em qualquer outro caso, como uma `old_string` desatualizada ou uma que corresponde mais de uma vez sem `replace_all`, Claude lê o arquivo novamente antes de editar. O tratamento relaxado de arquivos não lidos e alterados requer Claude Code v2.1.208 ou posterior; antes disso, Claude Code recusava qualquer edição em um arquivo que não havia lido na conversa ou que mudou no disco após a leitura.288Um arquivo que mudou no disco depois que Claude o leu pela última vez ainda pode ser editado quando `old_string` corresponde ao conteúdo atual exatamente e sem ambiguidade e Claude Code pode ler o arquivo sem solicitar. Corresponder contra o conteúdo atual do arquivo mantém isso seguro, e o resultado observa que o arquivo contém outras alterações para que Claude o releia antes de edições que dependem do conteúdo circundante. Em qualquer outro caso, como uma `old_string` desatualizada ou uma que corresponde mais de uma vez sem `replace_all`, Claude lê o arquivo novamente antes de editar. O tratamento relaxado de arquivos não lidos e alterados requer Claude Code v2.1.208 ou posterior; antes disso, Claude Code recusava qualquer edição em um arquivo que não havia lido na conversa ou que mudou no disco após a leitura.

289 289

290Visualizar um arquivo com Bash também satisfaz o requisito read-before-edit quando o comando é `cat`, `nl`, `bat`, `batcat`, `head`, `tail`, `sed -n 'X,Yp'`, `grep`, `egrep`, `fgrep`, ou `rg` em um único arquivo sem pipes ou redirecionamentos. Saída com pipe e outros comandos Bash não contam para a verificação read-before-edit.290Claude também pode editar um arquivo sem um Read separado depois de visualizá-lo com um comando Bash como `cat` ou `grep`. Esses comandos são `cat`, `nl`, `bat`, `batcat`, `head`, `tail`, `sed -n 'X,Yp'`, `grep`, `egrep`, `fgrep` e `rg`, cada um executado em um único arquivo sem pipes ou redirecionamentos. Uma busca que não exibe nenhuma correspondência não conta como leitura, nem qualquer comando fora desta lista.

291 291

292Quando Claude visualiza um arquivo dessa forma, Claude Code também carrega qualquer [`CLAUDE.md` de subdiretório](/docs/pt/memory#how-claude-md-files-load) e [regras com escopo de caminho](/docs/pt/memory#path-specific-rules) que se aplicam a esse arquivo. Consulte [Regras de permissão Read e Edit](/docs/pt/permissions#read-and-edit) para saber quais comandos Bash suas regras de negação `Read` e `Edit` cobrem.292Quando Claude visualiza um arquivo dessa forma, Claude Code também carrega qualquer [`CLAUDE.md` de subdiretório](/docs/pt/memory#how-claude-md-files-load) e [regras com escopo de caminho](/docs/pt/memory#path-specific-rules) que se aplicam a esse arquivo. Consulte [Regras de permissão Read e Edit](/docs/pt/permissions#read-and-edit) para saber quais comandos Bash suas regras de negação `Read` e `Edit` cobrem.

293 293

294<h3 id="non-utf-8-files">

295 Arquivos não UTF-8

296</h3>

297

298Claude não pode usar [NotebookEdit](#notebookedit-tool-behavior) em um arquivo que não seja UTF-8 válido. O mesmo vale para Edit, a menos que o arquivo comece com uma marca de ordem de bytes UTF-16 little-endian. Quando Claude tenta, a ferramenta recusa a alteração e deixa o arquivo intacto. Os arquivos recusados incluem texto não ASCII salvo em uma codificação legada como Windows-1252 ou Shift-JIS, arquivos binários e UTF-8 com uma sequência de bytes inválida.

299

300As ferramentas recusam porque salvam o arquivo inteiro de volta como UTF-8, o que substituiria cada byte que não conseguem decodificar pelo caractere de substituição `U+FFFD`. Em vez disso, o [erro que Claude recebe](/docs/pt/errors#file-is-not-valid-utf-8) instrui a fazer a alteração com um comando de shell que mantém a codificação do arquivo, ou a perguntar a você sobre convertê-lo para UTF-8 primeiro.

301

302Claude ainda pode substituir esse arquivo com Write, a menos que o novo conteúdo contenha `U+FFFD`, o caractere que Read mostra a Claude no lugar de bytes que não consegue decodificar. Essa proteção impede que Claude grave de volta o texto corrompido que leu. Quando Write substitui o arquivo, ele salva o novo conteúdo como UTF-8, de modo que a codificação original do arquivo é perdida.

303

294<h2 id="endconversation-tool-behavior">304<h2 id="endconversation-tool-behavior">

295 Comportamento da ferramenta EndConversation305 Comportamento da ferramenta EndConversation

296</h2>306</h2>

455* `insert`: adiciona uma nova célula após a alvo. Sem `cell_id`, a nova célula vai no início do notebook. Requer `cell_type` definido como `code` ou `markdown`.465* `insert`: adiciona uma nova célula após a alvo. Sem `cell_id`, a nova célula vai no início do notebook. Requer `cell_type` definido como `code` ou `markdown`.

456* `delete`: remove a célula alvo.466* `delete`: remove a célula alvo.

457 467

468NotebookEdit recusa um arquivo de notebook que não seja decodificado como UTF-8, sob a [mesma regra que Edit](#non-utf-8-files), e não grava nada.

469

458Regras de permissão usam o formato de caminho `Edit(...)`. Uma regra como `Edit(notebooks/**)` cobre chamadas NotebookEdit em arquivos nesse diretório.470Regras de permissão usam o formato de caminho `Edit(...)`. Uma regra como `Edit(notebooks/**)` cobre chamadas NotebookEdit em arquivos nesse diretório.

459 471

460<h2 id="powershell-tool">472<h2 id="powershell-tool">

514* `"shell": "powershell"` em [hooks de comando](/docs/pt/hooks#command-hook-fields) individuais: executa esse hook no PowerShell. Os hooks iniciam PowerShell diretamente, portanto isso funciona independentemente de `CLAUDE_CODE_USE_POWERSHELL_TOOL`.526* `"shell": "powershell"` em [hooks de comando](/docs/pt/hooks#command-hook-fields) individuais: executa esse hook no PowerShell. Os hooks iniciam PowerShell diretamente, portanto isso funciona independentemente de `CLAUDE_CODE_USE_POWERSHELL_TOOL`.

515* `shell: powershell` em [frontmatter de skill](/docs/pt/skills#frontmatter-reference): executa blocos `` !`command` `` no PowerShell. Requer que a ferramenta PowerShell esteja ativada.527* `shell: powershell` em [frontmatter de skill](/docs/pt/skills#frontmatter-reference): executa blocos `` !`command` `` no PowerShell. Requer que a ferramenta PowerShell esteja ativada.

516 528

517O mesmo comportamento de redefinição de diretório de trabalho da sessão principal descrito na seção da ferramenta Bash se aplica aos comandos PowerShell, incluindo a variável de ambiente `CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR`.529Os comandos PowerShell seguem o [mesmo comportamento de redefinição de diretório de trabalho da sessão principal](#what-persists-between-commands) que os comandos Bash, incluindo a variável de ambiente `CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR`.

530

531Os comandos PowerShell também recebem as variáveis que os hooks persistem através de `CLAUDE_ENV_FILE`, nas condições descritas em [Variáveis persistidas em comandos PowerShell](/docs/pt/hooks#persisted-variables-in-powershell-commands). Requer Claude Code v2.1.296 ou posterior.

518 532

519O código de saída 1 de `grep`, `rg`, `egrep`, `fgrep`, `findstr` e `git grep` significa nenhuma correspondência. O código de saída 1 de `git diff` significa que existem diferenças. Nenhum resultado é relatado ao Claude como uma falha de comando. Para `robocopy`, códigos de saída de 0 a 7 são resultados informativos, como arquivos copiados ou arquivos extras detectados. Códigos de saída de 8 ou superior contam como falhas.533O código de saída 1 de `grep`, `rg`, `egrep`, `fgrep`, `findstr` e `git grep` significa nenhuma correspondência. O código de saída 1 de `git diff` significa que existem diferenças. Nenhum resultado é relatado ao Claude como uma falha de comando. Para `robocopy`, códigos de saída de 0 a 7 são resultados informativos, como arquivos copiados ou arquivos extras detectados. Códigos de saída de 8 ou superior contam como falhas.

520 534

547 561

548A ferramenta Read recebe um caminho de arquivo e retorna o conteúdo com números de linha. Claude é instruído a sempre passar caminhos absolutos.562A ferramenta Read recebe um caminho de arquivo e retorna o conteúdo com números de linha. Claude é instruído a sempre passar caminhos absolutos.

549 563

550Por padrão, Read retorna o arquivo desde o início. Quando uma leitura de arquivo inteiro excede o limite de tokens, Read retorna a primeira página com um aviso de `PARTIAL view` que informa a Claude quanto do arquivo foi recebido e como ler mais com `offset` e `limit`. Uma leitura que passa um `offset` ou `limit` explícito e ainda assim excede o limite de tokens retorna um erro.

~~551~~

552Uma leitura com um `limit` explícito para assim que as linhas selecionadas excedem o que o limite de tokens poderia caber e retorna um erro sem carregar o resto do intervalo. O erro informa a Claude para usar um `limit` menor, ou para procurar conteúdo específico com [Grep](#grep-tool-behavior) em vez disso quando uma única linha é tão grande. Antes da v2.1.208, Claude Code carregava todo o intervalo na memória antes de rejeitá-lo, então ler um arquivo com uma única linha extremamente longa poderia fazer com que ficasse sem memória.

~~553~~

554Ler um arquivo vazio retorna um aviso de que o arquivo existe mas seu conteúdo está vazio, e um `offset` além da última linha retorna um aviso informando a contagem de linhas do arquivo. Antes da v2.1.208, ler um arquivo vazio retornava o aviso past-the-end em vez disso.564Ler um arquivo vazio retorna um aviso de que o arquivo existe mas seu conteúdo está vazio, e um `offset` além da última linha retorna um aviso informando a contagem de linhas do arquivo. Antes da v2.1.208, ler um arquivo vazio retornava o aviso past-the-end em vez disso.

555 565

556Read lida com vários tipos de arquivo além de texto simples:566Read lida com vários tipos de arquivo além de texto simples:

557 567

558* **Imagens**: PNG, JPG e outros formatos de imagem são retornados como conteúdo visual que Claude pode ver, não como bytes brutos. Claude Code redimensiona e recompacta imagens grandes para se adequarem aos limites de tamanho de imagem do modelo antes de enviá-las, então Claude pode ver uma versão reduzida de uma captura de tela grande. Uma imagem que ainda é maior que 500KB após esse redimensionamento é re-codificada como JPEG com qualidade reduzida com suas dimensões de pixel inalteradas. Se Claude perder detalhes de nível de pixel fino em uma imagem grande, peça-lhe para cortar a região de interesse primeiro, por exemplo com ImageMagick via Bash.568* **Imagens**: PNG, JPG e outros formatos de imagem são retornados como conteúdo visual que Claude pode ver, não como bytes brutos. Claude Code redimensiona e recompacta imagens grandes para se adequarem aos limites de tamanho de imagem do modelo antes de enviá-las, então Claude pode ver uma versão reduzida de uma captura de tela grande. Uma imagem que ainda é maior que 500KB após esse redimensionamento é re-codificada como JPEG com qualidade reduzida com suas dimensões de pixel inalteradas. Se Claude perder detalhes de nível de pixel fino em uma imagem grande, peça-lhe para cortar a região de interesse primeiro, por exemplo com ImageMagick via Bash.

559* **PDFs**: Claude lê arquivos `.pdf` curtos por inteiro. Para PDFs com mais de 10 páginas, ele lê em intervalos com um parâmetro `pages`, como `"1-5"`, até 20 páginas por vez. Leituras de intervalo de páginas renderizam páginas com `pdftoppm` do poppler-utils, então instale-o com `brew install poppler` no macOS ou `apt-get install poppler-utils` no Debian e Ubuntu. No Windows e outras plataformas, instale uma compilação do poppler que coloque `pdftoppm` no seu `PATH`. Sem ele, uma leitura de intervalo de páginas falha com `pdftoppm is not installed`.569* **PDFs**: Claude lê arquivos `.pdf` curtos por inteiro. Para PDFs com mais de 10 páginas, ele lê em intervalos com um parâmetro `pages`, como `"1-5"`, até 20 páginas por vez. Leituras de intervalo de páginas renderizam páginas com `pdftoppm` do poppler-utils, então instale-o com `brew install poppler` no macOS ou `apt-get install poppler-utils` no Debian e Ubuntu. No Windows e outras plataformas, instale uma compilação do poppler que coloque `pdftoppm` no seu `PATH`. Sem ele, uma leitura de intervalo de páginas falha com `pdftoppm is not installed`.

560* **Notebooks Jupyter**: arquivos `.ipynb` retornam todas as células com suas saídas, incluindo código, markdown e visualizações. Claude Code recusa-se a ler um arquivo de notebook com mais de 100 MB; o erro informa a Claude como ler uma porção do notebook em vez disso, como uma fatia de células, com um comando shell.570* **Notebooks Jupyter**: arquivos `.ipynb` retornam todas as células com suas saídas, incluindo código, markdown e visualizações. Um notebook cujas células somam mais de 256 KB, ou mais do que o [limite de tokens](#large-files), retorna um erro em vez disso. Claude Code recusa-se a ler um arquivo de notebook com mais de 100 MB; o erro informa a Claude como ler uma porção do notebook em vez disso, como uma fatia de células, com um comando shell.

561 571

562Read apenas lê arquivos, não diretórios. Claude lista o conteúdo do diretório com um comando shell como `ls`.572Read apenas lê arquivos, não diretórios. Claude lista o conteúdo do diretório com um comando shell como `ls`.

563 573

574<h3 id="large-files">

575 Arquivos grandes

576</h3>

577

578Claude pode ler um arquivo de texto maior do que uma única chamada de Read retorna. Por padrão, uma chamada retorna no máximo 25.000 tokens, ou o valor que você definir em [`CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS`](/docs/pt/env-vars), e recusa um arquivo inteiro com mais de 256 KB, então Claude lê um arquivo maior em páginas com `offset` e `limit`. No Claude Code v2.1.296 ou posterior, ele pode, em vez disso, ler o arquivo inteiro, ou um intervalo longo de linhas, em uma única chamada definindo `allow_large: true` quando precisar, por exemplo porque você pediu o arquivo inteiro. Essa leitura é dimensionada de acordo com o espaço restante na [janela de contexto](/docs/pt/context-window) da sessão em vez dos limites padrão. Imagens, PDFs e notebooks mantêm seus limites.

579

580O que Claude recebe quando uma leitura ultrapassa os limites padrão:

581

582* **Arquivo inteiro acima do limite de tokens**: a primeira página do arquivo, com um aviso de `PARTIAL view` informando quanto do arquivo foi recebido e como ler mais com `offset` e `limit`

583* **Arquivo inteiro acima de 256 KB, ou uma leitura com `offset` ou `limit` acima do limite de tokens**: um erro informando para ler uma porção com `offset` e `limit`, ou para procurar conteúdo específico com [Grep](#grep-tool-behavior) em vez disso

584

564<h2 id="sendfeedback-tool-behavior">585<h2 id="sendfeedback-tool-behavior">

565 Comportamento da ferramenta SendFeedback586 Comportamento da ferramenta SendFeedback

566</h2>587</h2>

734 Comportamento da ferramenta Write755 Comportamento da ferramenta Write

735</h2>756</h2>

736 757

737A ferramenta Write cria um novo arquivo ou sobrescreve um existente com o conteúdo completo fornecido. Ela não anexa ou mescla.758A ferramenta Write cria um novo arquivo ou sobrescreve um existente com o conteúdo completo fornecido. Ela não anexa ou mescla. A Write também sobrescreve um arquivo existente cujos bytes não podem ser decodificados e salva o novo conteúdo como UTF-8, conforme descrito em [arquivos não UTF-8](#non-utf-8-files).

738 759

739Se Claude deve ler um arquivo existente na conversa atual antes de sobrescrevê-lo depende do modelo e do arquivo:760Se Claude deve ler um arquivo existente na conversa atual antes de sobrescrevê-lo depende do modelo e do arquivo:

740 761

741* Claude Opus 4.6, Claude Haiku 4.5 e modelos mais antigos sempre exigem a leitura, portanto uma Write para um arquivo existente não lido falha com um erro.762* Claude Opus 4.6, Claude Haiku 4.5 e modelos mais antigos sempre exigem a leitura, portanto uma Write para um arquivo existente não lido falha com um erro.

742* Modelos mais novos podem sobrescrever um arquivo que nunca leram nesta sessão sob as mesmas condições que [read-before-edit](#edit-tool-behavior): lê-lo não precisaria de um prompt de permissão e a ferramenta Read está disponível.763* Modelos mais novos podem sobrescrever um arquivo que nunca leram nesta sessão sob as mesmas condições que [read-before-edit](#edit-tool-behavior): lê-lo não precisaria de um prompt de permissão e a ferramenta Read está disponível.

743* Notebooks Jupyter e arquivos que Claude leu apenas parcialmente com um aviso [`PARTIAL view`](#read-tool-behavior) exigem a leitura em todos os modelos.764* Notebooks Jupyter e arquivos que Claude leu apenas parcialmente com um [aviso `PARTIAL view`](#large-files) exigem a leitura em todos os modelos.

744 765

745Esta restrição não se aplica a novos arquivos. Antes da v2.1.228, todos os modelos exigiam a leitura antes de sobrescrever um arquivo existente.766Esta restrição não se aplica a novos arquivos. Antes da v2.1.228, todos os modelos exigiam a leitura antes de sobrescrever um arquivo existente.

746 767

troubleshoot-install.md +1 −1

Details

1212Se você vir `API Error: 403 Request not allowed` após fazer login:1212Se você vir `API Error: 403 Request not allowed` após fazer login:

1213 1213

1214* **Usuários Claude Pro/Max**: verifique se sua assinatura está ativa em [claude.ai/settings](https://claude.ai/settings)1214* **Usuários Claude Pro/Max**: verifique se sua assinatura está ativa em [claude.ai/settings](https://claude.ai/settings)

1215* **Usuários do Anthropic Console**: confirme que sua conta tem a função "Claude Code" ou "Developer". Os administradores atribuem isso no Anthropic Console em Settings → Members.1215* **Usuários do Anthropic Console**: confirme que sua conta tem a função "Claude Code" ou "Developer". Os administradores atribuem isso na página Members do Console em [platform.claude.com/settings/members](https://platform.claude.com/settings/members).

1216* **Atrás de um proxy**: proxies corporativos podem interferir com requisições de API. Consulte [network configuration](/docs/pt/network-config) para configuração de proxy.1216* **Atrás de um proxy**: proxies corporativos podem interferir com requisições de API. Consulte [network configuration](/docs/pt/network-config) para configuração de proxy.

1217 1217

1218<h3 id="claude-code-access-has-not-been-granted-for-this-account">1218<h3 id="claude-code-access-has-not-been-granted-for-this-account">

vs-code.md +3 −2

Details

237 237

238To restore an archived session, expand **Archived sessions** and click **Unarchive session**. To restore every archived session at once, hover over the **Archived sessions** header in the sessions list in the Activity Bar and click its unarchive icon, which requires Claude Code v2.1.277 or later. Before v2.1.257, the action was **Delete session**, which hid a session with no way to restore it. Sessions you deleted then appear under **Archived sessions** after you upgrade.238To restore an archived session, expand **Archived sessions** and click **Unarchive session**. To restore every archived session at once, hover over the **Archived sessions** header in the sessions list in the Activity Bar and click its unarchive icon, which requires Claude Code v2.1.277 or later. Before v2.1.257, the action was **Delete session**, which hid a session with no way to restore it. Sessions you deleted then appear under **Archived sessions** after you upgrade.

239 239

240When the conversation you resume ended in plan mode, Claude Code restores plan mode. Requires Claude Code v2.1.246 or later. Claude Code doesn't restore it in two cases:240Quando a conversa que você retoma terminou no modo de planejamento, o Claude Code restaura o modo de planejamento. Requer Claude Code v2.1.246 ou posterior. O Claude Code não o restaura nestes casos:

241 241

242* The extension [chooses the starting permission mode](/docs/pt/permission-modes#switch-permission-modes) from `claudeCode.initialPermissionMode` or a pick that carries over from an earlier conversation242* The extension [chooses the starting permission mode](/docs/pt/permission-modes#switch-permission-modes) from `claudeCode.initialPermissionMode` or a pick that carries over from an earlier conversation

243* You have `claudeCode.claudeProcessWrapper` configured243* You have `claudeCode.claudeProcessWrapper` configured

244* Uma [regra de negação](/docs/pt/permissions#manage-permissions) remove a ferramenta [`ExitPlanMode`](/docs/pt/tools-reference)

244 245

245<h3 id="resume-cloud-sessions-from-claude-ai">246<h3 id="resume-cloud-sessions-from-claude-ai">

246 Resume cloud sessions from Claude.ai247 Resume cloud sessions from Claude.ai

479 480

480Claude abre novas abas para tarefas do navegador e compartilha o estado de login do seu navegador, para que possa acessar qualquer site em que você já esteja conectado.481Claude abre novas abas para tarefas do navegador e compartilha o estado de login do seu navegador, para que possa acessar qualquer site em que você já esteja conectado.

481 482

482Para que cada sessão se conecte ao seu navegador assim que iniciar, sem digitar `@browser`, consulte [Ativar o Chrome por padrão](/docs/pt/chrome#enable-chrome-by-default). Para quando o Claude Code pedir sua confirmação antes de uma ação do navegador em uma sessão conectada dessa forma, consulte [Prompts de permissão em sessões do VS Code](/docs/pt/chrome#permission-prompts-in-vs-code-sessions).483Para que cada sessão se conecte ao seu navegador assim que iniciar, sem digitar `@browser`, consulte [Ativar o Chrome por padrão](/docs/pt/chrome#enable-chrome-by-default). Para quando o Claude Code pedir sua confirmação antes de uma ação do navegador, consulte [Prompts de permissão em sessões do VS Code](/docs/pt/chrome#permission-prompts-in-vs-code-sessions).

483 484

484Para instruções de configuração, a lista completa de recursos e solução de problemas, consulte [Use Claude Code with Chrome](/docs/pt/chrome).485Para instruções de configuração, a lista completa de recursos e solução de problemas, consulte [Use Claude Code with Chrome](/docs/pt/chrome).

485 486

workflows.md +1 −1

Details

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

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

513 513

514Quando a [`availableModels` allowlist](/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](/docs/pt/sub-agents#choose-a-model). A visualização de progresso da execução em [`/workflows`](#watch-the-run) mostra um aviso nomeando tanto o modelo solicitado quanto o substituído.514Quando a [`availableModels` allowlist](/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](/docs/pt/sub-agents#choose-a-model).

515 515

516<h3 id="set-a-size-guideline">516<h3 id="set-a-size-guideline">

517 Defina uma diretriz de tamanho517 Defina uma diretriz de tamanho

worktrees.md +3 −1

Details

268 268

269 A mesma leitura abrange `.claude/agents` e `.claude/commands`. Para skills, a leitura requer Claude Code v2.1.277 ou posterior.269 A mesma leitura abrange `.claude/agents` e `.claude/commands`. Para skills, a leitura requer Claude Code v2.1.277 ou posterior.

270 270

271Todos esses se aplicam se você criar a worktree com `--worktree`, com `git worktree add`, ou através do [aplicativo desktop](/docs/pt/desktop#work-in-parallel-with-sessions).271Todos esses se aplicam quer você crie o worktree com `--worktree` ou com `git worktree add`.

272

273Em uma sessão de worktree que você inicia a partir do [aplicativo desktop](/docs/pt/desktop#work-in-parallel-with-sessions), Claude Code lê a configuração do projeto, como opções de configuração, hooks, skills, agentes, comandos e servidores do [`.mcp.json`](/docs/pt/mcp#project-scope), a partir da raiz do checkout principal em vez do worktree. Os comandos de hook são executados nessa raiz, e `${CLAUDE_PROJECT_DIR}` aponta para ela. Para acessar os arquivos em que Claude está trabalhando, leia o caminho do worktree a partir do [campo de entrada `cwd`](/docs/pt/hooks#common-input-fields) do hook. Os arquivos `CLAUDE.md` e `.claude/rules/` continuam sendo carregados a partir do worktree.

272 274

273<h2 id="manage-worktrees-manually">275<h2 id="manage-worktrees-manually">

274 Gerencie worktrees manualmente276 Gerencie worktrees manualmente

Documentation 2026-10-09 23:02 UTC to 2026-10-10 21:01 UTC