SpyBara
Go Premium

Documentation 2026-10-24 22:59 UTC to 2026-10-25 23:58 UTC

57 files changed +630 −135. View all changes and history on the product overview
2026
Fri 30 23:01 Thu 29 23:57 Wed 28 23:57 Tue 27 22:59 Mon 26 22:57 Sun 25 23:58 Sat 24 22:59 Fri 23 22:59 Thu 22 22:58 Wed 21 23:02 Tue 20 23:00 Mon 19 23:58 Sat 17 23:57 Fri 16 22:59 Thu 15 23:58 Wed 14 22:58 Tue 13 23:57 Sun 11 23:57 Sat 10 23:01 Fri 9 23:02 Thu 8 22:58 Wed 7 23:59 Tue 6 23:59 Mon 5 23:58 Sun 4 23:58 Sat 3 23:57 Fri 2 22:59 Thu 1 23:59
Details

324 * A chamada foi única, portanto, nenhum resultado anterior existe.324 * A chamada foi única, portanto, nenhum resultado anterior existe.

325 * O travamento aconteceu na primeira rodada.325 * O travamento aconteceu na primeira rodada.

326 * A rodada antes do travamento foi o `/clear` em si, portanto, seu resultado cobre apenas a redefinição.326 * A rodada antes do travamento foi o `/clear` em si, portanto, seu resultado cobre apenas a redefinição.

3272. Some o `usage` nas mensagens do assistente em vez disso, contando cada resposta da API uma vez, como o exemplo [Track per-step usage](#track-per-step-usage) faz. No modo de entrada única, some todas elas; no modo de entrada de transmissão, some as que chegaram após o último resultado. Isso fornece os tokens de entrada e cache do loop principal. O uso de subagentos não é recuperável dessa forma, e nem são tokens de saída ou custo em USD, porque [o `output_tokens` por etapa é um espaço reservado](#read-output-tokens-from-the-result-message).3272. Some o `usage` nas mensagens do assistente em vez disso, contando cada resposta da API uma vez, como o exemplo [Rastrear uso por etapa](#track-per-step-usage) faz. No modo de entrada única, some todas elas; no modo de entrada de transmissão, some as que chegaram após o último resultado. Isso fornece os tokens de entrada e cache do loop principal. O uso de subagentos não é recuperável dessa forma, e nem são tokens de saída ou custo em USD, porque [o `output_tokens` por etapa é um espaço reservado](#read-output-tokens-from-the-result-message).

328 328 

329### Rastrear tokens de cache329### Rastrear tokens de cache

330 330 

Details

771 771 

772Quando um callback excede seu timeout, Claude Code o cancela e descarta sua saída, e a sessão continua em vez de travar. O que acontece a seguir depende do evento:772Quando um callback excede seu timeout, Claude Code o cancela e descarta sua saída, e a sessão continua em vez de travar. O que acontece a seguir depende do evento:

773 773 

774* `PreToolUse`: Claude Code bloqueia a chamada de ferramenta. Em seu lugar, Claude recebe um resultado de ferramenta informando que o hook não respondeu antes de seu timeout, e o turno continua. Antes da v2.1.210, Claude Code relatava o timeout a Claude como uma rejeição do usuário, o que fazia sessões autônomas pararem e aguardarem entrada.774* `PreToolUse`: Claude Code bloqueia a chamada de ferramenta. Se todos os outros hooks não retornaram nada ou retornaram apenas uma decisão `allow`, o resultado da ferramenta informa a Claude que o hook não respondeu antes de seu timeout, e o turno continua. Se outro de seus hooks já negou a chamada, sua negação ainda chega a Claude: o resultado da ferramenta inclui o motivo desse hook, e o texto do timeout pode vir em seguida.

775 

776 Antes da v2.1.210, Claude Code relatava o timeout a Claude como uma rejeição do usuário, o que fazia sessões autônomas pararem e aguardarem entrada.

775* `PostToolUse` e `PostToolUseFailure`: Claude Code mantém o resultado da ferramenta e o turno continua.777* `PostToolUse` e `PostToolUseFailure`: Claude Code mantém o resultado da ferramenta e o turno continua.

776* `UserPromptSubmit` e [`UserPromptExpansion`](https://code.claude.com/docs/pt/hooks#userpromptexpansion): Claude Code bloqueia o prompt com uma mensagem nomeando o hook e o timeout, e a sessão continua. Antes da v2.1.208, Claude Code terminava a consulta com `error_during_execution` quando um callback nesses eventos expirava.778* `UserPromptSubmit` e [`UserPromptExpansion`](https://code.claude.com/docs/pt/hooks#userpromptexpansion): Claude Code bloqueia o prompt com uma mensagem nomeando o hook e o timeout, e a sessão continua. Antes da v2.1.208, Claude Code terminava a consulta com `error_during_execution` quando um callback nesses eventos expirava.

777* `Stop` e `SubagentStop`: o callback com timeout conta como retornando nenhuma decisão. O agente ou subagente para como se esse callback o tivesse permitido, e uma decisão de seus outros hooks no evento ainda se aplica. Antes do Claude Code v2.1.273, um callback `Stop` ou `SubagentStop` com timeout contava como uma execução de hook falhada, e Claude Code descartava as decisões de seus outros hooks no evento.779* `Stop` e `SubagentStop`: o callback com timeout conta como retornando nenhuma decisão. O agente ou subagente para como se esse callback o tivesse permitido, e uma decisão de seus outros hooks no evento ainda se aplica. Antes do Claude Code v2.1.273, um callback `Stop` ou `SubagentStop` com timeout contava como uma execução de hook falhada, e Claude Code descartava as decisões de seus outros hooks no evento.

Details

872| Propriedade | Tipo | Padrão | Descrição |872| Propriedade | Tipo | Padrão | Descrição |

873| :- | :- | :- | :- |873| :- | :- | :- | :- |

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

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

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

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

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

Details

309| `options.dir` | `string` | `undefined` | Diretório do projeto para encontrar a sessão. Quando omitido, pesquisa todos os projetos |309| `options.dir` | `string` | `undefined` | Diretório do projeto para encontrar a sessão. Quando omitido, pesquisa todos os projetos |

310| `options.limit` | `number` | `undefined` | Número máximo de mensagens a retornar |310| `options.limit` | `number` | `undefined` | Número máximo de mensagens a retornar |

311| `options.offset` | `number` | `undefined` | Número de mensagens a pular do início |311| `options.offset` | `number` | `undefined` | Número de mensagens a pular do início |

312| `options.includeSystemMessages` | `boolean` | `false` | Quando `true`, também retorna mensagens de sistema, como limites de compactação, junto com as mensagens de usuário e assistente |

312 313 

313#### Tipo de retorno: `SessionMessage`314#### Tipo de retorno: `SessionMessage`

314 315 

315| Propriedade | Tipo | Descrição |316| Propriedade | Tipo | Descrição |

316| :- | :- | :- |317| :- | :- | :- |

317| `type` | `"user" \| "assistant"` | Papel da mensagem |318| `type` | `"user" \| "assistant" \| "system"` | Papel da mensagem. `"system"` aparece apenas quando `options.includeSystemMessages` é `true` |

318| `uuid` | `string` | Identificador único de mensagem |319| `uuid` | `string` | Identificador único de mensagem |

319| `session_id` | `string` | Sessão a que esta mensagem pertence |320| `session_id` | `string` | Sessão a que esta mensagem pertence |

320| `message` | `unknown` | Payload de mensagem bruta da transcrição |321| `message` | `unknown` | Payload de mensagem bruta da transcrição |


632 }): Promise<SDKControlReloadPluginsResponse>;633 }): Promise<SDKControlReloadPluginsResponse>;

633 reloadSkills(): Promise<SDKControlReloadSkillsResponse>;634 reloadSkills(): Promise<SDKControlReloadSkillsResponse>;

634 reloadOutputStyles(): Promise<SDKControlReloadOutputStylesResponse>;635 reloadOutputStyles(): Promise<SDKControlReloadOutputStylesResponse>;

636 seedReadState(path: string, mtime: number): Promise<void>;

635 accountInfo(): Promise<AccountInfo>;637 accountInfo(): Promise<AccountInfo>;

636 reconnectMcpServer(serverName: string): Promise<void>;638 reconnectMcpServer(serverName: string): Promise<void>;

637 toggleMcpServer(serverName: string, enabled: boolean): Promise<void>;639 toggleMcpServer(serverName: string, enabled: boolean): Promise<void>;

638 setMcpServers(servers: Record<string, McpServerConfig>): Promise<McpSetServersResult>;640 setMcpServers(servers: Record<string, McpServerConfig>): Promise<McpSetServersResult>;

641 setMcpPermissionModeOverride(

642 serverName: string,

643 mode: 'default' | 'auto' | null

644 ): Promise<{ warning?: string }>;

639 readMcpResource(serverName: string, uri: string): Promise<SDKControlMcpReadResourceResponse>;645 readMcpResource(serverName: string, uri: string): Promise<SDKControlMcpReadResourceResponse>;

640 streamInput(stream: AsyncIterable<SDKUserMessage>): Promise<void>;646 streamInput(stream: AsyncIterable<SDKUserMessage>): Promise<void>;

641 stopTask(taskId: string): Promise<void>;647 stopTask(taskId: string): Promise<void>;

648 backgroundTasks(toolUseId?: string): Promise<boolean>;

642 close(): void;649 close(): void;

643}650}

644```651```


665| `reloadPlugins(options?)` | Recarrega os plugins do disco, para que plugins que você instala ou edita no meio da sessão cheguem à sessão em execução. É resolvido com um [`SDKControlReloadPluginsResponse`](#sdkcontrolreloadpluginsresponse) listando os comandos, subagentes, plugins e o status dos servidores MCP da sessão. Requer o Agent SDK v0.2.85 ou posterior. A [opção `holdOnCacheImpact`](#sdkcontrolreloadpluginsresponse) requer o Agent SDK v0.3.268 ou posterior |672| `reloadPlugins(options?)` | Recarrega os plugins do disco, para que plugins que você instala ou edita no meio da sessão cheguem à sessão em execução. É resolvido com um [`SDKControlReloadPluginsResponse`](#sdkcontrolreloadpluginsresponse) listando os comandos, subagentes, plugins e o status dos servidores MCP da sessão. Requer o Agent SDK v0.2.85 ou posterior. A [opção `holdOnCacheImpact`](#sdkcontrolreloadpluginsresponse) requer o Agent SDK v0.3.268 ou posterior |

666| `reloadSkills()` | Recarrega as skills do disco, para que skills que você adiciona ou edita no meio da sessão fiquem disponíveis para a sessão em execução. É resolvido com um [`SDKControlReloadSkillsResponse`](#sdkcontrolreloadskillsresponse) listando as skills disponíveis após o recarregamento. Requer o Agent SDK v0.3.163 ou posterior |673| `reloadSkills()` | Recarrega as skills do disco, para que skills que você adiciona ou edita no meio da sessão fiquem disponíveis para a sessão em execução. É resolvido com um [`SDKControlReloadSkillsResponse`](#sdkcontrolreloadskillsresponse) listando as skills disponíveis após o recarregamento. Requer o Agent SDK v0.3.163 ou posterior |

667| `reloadOutputStyles()` | Relê os [estilos de saída](https://code.claude.com/docs/pt/output-styles.md) do disco, para que um arquivo de estilo que você adiciona ou edita no meio da sessão fique disponível para a sessão em execução. É resolvido com um [`SDKControlReloadOutputStylesResponse`](#sdkcontrolreloadoutputstylesresponse) listando os nomes de estilos disponíveis após o recarregamento. Requer o Agent SDK v0.3.261 ou posterior |674| `reloadOutputStyles()` | Relê os [estilos de saída](https://code.claude.com/docs/pt/output-styles.md) do disco, para que um arquivo de estilo que você adiciona ou edita no meio da sessão fique disponível para a sessão em execução. É resolvido com um [`SDKControlReloadOutputStylesResponse`](#sdkcontrolreloadoutputstylesresponse) listando os nomes de estilos disponíveis após o recarregamento. Requer o Agent SDK v0.3.261 ou posterior |

675| `seedReadState(path, mtime)` | Marca um arquivo como já lido para que um Edit posterior não falhe com `File has not been read yet`. Consulte [`seedReadState()`](#seedreadstate). Requer o TypeScript SDK v0.2.83 ou posterior |

668| `accountInfo()` | Retorna as informações da conta |676| `accountInfo()` | Retorna as informações da conta |

669| `reconnectMcpServer(serverName)` | Reconecta um servidor MCP pelo nome. Se o nome também corresponder a uma entrada em um arquivo de configurações como `.mcp.json` ou `~/.claude.json`, o Claude Code reconecta o servidor que você configurou por meio de [`mcpServers`](#options) ou `setMcpServers()`, não a entrada do arquivo de configurações. Essa ordem de resolução requer Claude Code v2.1.257 ou posterior |677| `reconnectMcpServer(serverName)` | Reconecta um servidor MCP pelo nome. Se o nome também corresponder a uma entrada em um arquivo de configurações como `.mcp.json` ou `~/.claude.json`, o Claude Code reconecta o servidor que você configurou por meio de [`mcpServers`](#options) ou `setMcpServers()`, não a entrada do arquivo de configurações. Essa ordem de resolução requer Claude Code v2.1.257 ou posterior |

670| `toggleMcpServer(serverName, enabled)` | Habilita ou desabilita um servidor MCP pelo nome, com a mesma resolução de nomes que `reconnectMcpServer()`. Desabilitar um servidor o desconecta e remove suas ferramentas. Consulte [`toggleMcpServer()`](#togglemcpserver) para ver a versão do Claude Code necessária para cada tipo de servidor |678| `toggleMcpServer(serverName, enabled)` | Habilita ou desabilita um servidor MCP pelo nome, com a mesma resolução de nomes que `reconnectMcpServer()`. Desabilitar um servidor o desconecta e remove suas ferramentas. Consulte [`toggleMcpServer()`](#togglemcpserver) para ver a versão do Claude Code necessária para cada tipo de servidor |

671| `setMcpServers(servers)` | Substitui os servidores MCP que este método gerencia: servidores adicionados por meio dele e [servidores SDK em processo](#createsdkmcpserver). É resolvido com um [`McpSetServersResult`](#mcpsetserversresult) indicando quais servidores foram adicionados e removidos, e quaisquer erros; essa seção informa quais outros servidores permanecem conectados |679| `setMcpServers(servers)` | Substitui os servidores MCP que este método gerencia: servidores adicionados por meio dele e [servidores SDK em processo](#createsdkmcpserver). É resolvido com um [`McpSetServersResult`](#mcpsetserversresult) indicando quais servidores foram adicionados e removidos, e quaisquer erros; essa seção informa quais outros servidores permanecem conectados |

680| `setMcpPermissionModeOverride(serverName, mode)` | Sobrescreve o modo de permissão das ferramentas de um servidor MCP com um modo mais restritivo que o da sessão, ou limpa essa substituição com `null`. Disponível apenas no modo de entrada por streaming. Consulte [`setMcpPermissionModeOverride()`](#setmcppermissionmodeoverride). Requer o TypeScript SDK v0.3.187 ou posterior |

672| `readMcpResource(serverName, uri)` | *Alpha.* Lê um recurso `ui://` do MCP Apps de um servidor MCP conectado para que sua aplicação possa renderizar o widget de uma ferramenta. É resolvido com um [`SDKControlMcpReadResourceResponse`](#sdkcontrolmcpreadresourceresponse). Requer o TypeScript Agent SDK v0.3.280 ou posterior |681| `readMcpResource(serverName, uri)` | *Alpha.* Lê um recurso `ui://` do MCP Apps de um servidor MCP conectado para que sua aplicação possa renderizar o widget de uma ferramenta. É resolvido com um [`SDKControlMcpReadResourceResponse`](#sdkcontrolmcpreadresourceresponse). Requer o TypeScript Agent SDK v0.3.280 ou posterior |

673| `streamInput(stream)` | Transmite mensagens de entrada para a query em conversas com vários turnos |682| `streamInput(stream)` | Transmite mensagens de entrada para a query em conversas com vários turnos |

674| `stopTask(taskId)` | Interrompe uma tarefa em segundo plano em execução pelo ID |683| `stopTask(taskId)` | Interrompe uma tarefa em segundo plano em execução pelo ID |

684| `backgroundTasks(toolUseId?)` | Move para segundo plano os comandos Bash e subagentes em execução que o turno está aguardando, o mesmo que pressionar Ctrl+B no terminal interativo. Consulte [`backgroundTasks()`](#backgroundtasks). Requer o TypeScript SDK v0.2.139 ou posterior |

675| `close()` | Fecha a query e encerra o processo subjacente. Encerra a query à força e limpa todos os recursos |685| `close()` | Fecha a query e encerra o processo subjacente. Encerra a query à força e limpa todos os recursos |

676 686 

687#### `setMcpPermissionModeOverride()`

688 

689Sobrescreve o modo de permissão das ferramentas de um servidor MCP com um modo mais restritivo que o da sessão, ou limpa essa substituição com `null`. Use-o quando uma sessão é executada em um modo que ignora prompts por ação, mas as ferramentas de um servidor ainda devem ser revisadas. Requer o TypeScript SDK v0.3.187 ou posterior.

690 

691Passe um de três valores como `mode`:

692 

693* `'default'`: o Claude Code avalia as chamadas de ferramenta desse servidor como o [modo Manual](https://code.claude.com/docs/pt/permission-modes.md#available-modes) faz.

694* `'auto'`: o Claude Code encaminha as chamadas de ferramenta desse servidor pelo classificador do [modo auto](https://code.claude.com/docs/pt/permission-modes.md#eliminate-prompts-with-auto-mode). O Claude Code rejeita esse valor quando o classificador não está disponível para a sessão.

695* `null`: limpa a substituição.

696 

697A substituição só tem efeito enquanto a sessão está em um modo que ignora prompts por ação: `bypassPermissions` ou `auto`. Em qualquer outro modo da sessão, o Claude Code ignora a substituição, de modo que ela nunca pode ampliar o que a sessão permite.

698 

699A promise resolve com `{ warning }` quando ainda não se conhece nenhum servidor com esse nome. O Claude Code armazena a substituição mesmo assim e a aplica assim que um servidor com exatamente esse nome se conecta, então o aviso é uma verificação de erro de digitação, não uma falha.

700 

701Disponível apenas no modo de entrada por streaming, a mesma restrição de `setModel()` e `setPermissionMode()`.

702 

703#### `seedReadState()`

704 

705Marca um arquivo como já lido para que um Edit posterior não falhe com `File has not been read yet`. Use-o quando seu aplicativo tiver descartado um resultado anterior de `Read` do contexto da conversa e Claude for editar esse arquivo em seguida. Requer o TypeScript SDK v0.2.83 ou posterior.

706 

707Passe `mtime` como o horário de modificação do arquivo no momento dessa leitura anterior, em milissegundos inteiros desde a epoch, por exemplo `Math.floor(stat.mtimeMs)`. Se o arquivo em disco tiver sido alterado após esse horário, o Claude Code não faz a marcação.

708 

709A promise resolve independentemente de o arquivo ter sido marcado ou não, então uma promise resolvida não indica qual dos casos ocorreu.

710 

711#### `backgroundTasks()`

712 

713Move para segundo plano os comandos Bash e subagentes em execução que o turno está aguardando, o mesmo que pressionar Ctrl+B no terminal interativo. Passe o `toolUseId` de uma chamada de ferramenta para mover para segundo plano apenas o comando Bash ou subagente que essa chamada iniciou, ou omita-o para mover para segundo plano todas as tarefas em primeiro plano. Requer o TypeScript SDK v0.2.139 ou posterior.

714 

715Cada chamada de ferramenta movida para segundo plano retorna imediatamente para Claude com um resultado de execução em segundo plano, o turno continua e o Claude Code emite um [`SDKTaskNotificationMessage`](#sdktasknotificationmessage) quando a tarefa termina.

716 

717Em uma sessão em que tarefas em segundo plano estão habilitadas, a promise resolve para um booleano:

718 

719* **`true`**: uma tarefa foi movida para segundo plano, ou você omitiu `toolUseId`.

720* **`false`**: o `toolUseId` que você passou não correspondeu a nenhuma tarefa em primeiro plano.

721 

722Se as tarefas em segundo plano estiverem desabilitadas para a sessão, como com [`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS`](https://code.claude.com/docs/pt/env-vars), a promise é rejeitada e nada é movido para segundo plano.

723 

677#### `applyFlagSettings()`724#### `applyFlagSettings()`

678 725 

679Altera [configurações](https://code.claude.com/docs/pt/settings.md) em uma sessão em execução sem reiniciar a query. Use-o quando uma configuração que não tem um setter dedicado precisar mudar no meio da sessão, como restringir `permissions` depois que o agente lê uma entrada não confiável. `setModel()` e `setPermissionMode()` são setters dedicados para essas duas chaves; `applyFlagSettings()` é a forma geral que aceita qualquer subconjunto das chaves de configuração, e passar `model` aqui se comporta da mesma forma que `setModel()`.726Altera [configurações](https://code.claude.com/docs/pt/settings.md) em uma sessão em execução sem reiniciar a query. Use-o quando uma configuração que não tem um setter dedicado precisar mudar no meio da sessão, como restringir `permissions` depois que o agente lê uma entrada não confiável. `setModel()` e `setPermissionMode()` são setters dedicados para essas duas chaves; `applyFlagSettings()` é a forma geral que aceita qualquer subconjunto das chaves de configuração, e passar `model` aqui se comporta da mesma forma que `setModel()`.


1472 | SDKPermissionDeniedMessage1519 | SDKPermissionDeniedMessage

1473 | SDKPromptSuggestionMessage1520 | SDKPromptSuggestionMessage

1474 | SDKAPIRetryMessage1521 | SDKAPIRetryMessage

1522 | SDKControlRequestProgressMessage

1523 | SDKModelRefusalFallbackMessage

1524 | SDKModelRefusalNoFallbackMessage

1475 | SDKMirrorErrorMessage1525 | SDKMirrorErrorMessage

1476 | SDKInformationalMessage1526 | SDKInformationalMessage

1477 | SDKConversationResetMessage;1527 | SDKConversationResetMessage;

1478```1528```

1479 1529 

1530Três mensagens nesta união informam o progresso de requisições de controle e recusas do modelo. Cada uma tem `type: "system"`, então diferencie-as pelo `subtype` listado com cada uma:

1531 

1532* `SDKControlRequestProgressMessage`, `subtype: "control_request_progress"`: informa o progresso de uma requisição de controle de longa duração que seu cliente enviou. `request_id` associa a mensagem a essa requisição, e `status` é `"started"` ou `"api_retry"`. Requer Agent SDK v0.3.203 ou posterior.

1533* `SDKModelRefusalFallbackMessage`, `subtype: "model_refusal_fallback"`: emitida quando o modelo encerra o stream com uma recusa e o turno é tentado novamente em um modelo de fallback. Contém `original_model` e `fallback_model`. Requer Agent SDK v0.3.170 ou posterior.

1534* `SDKModelRefusalNoFallbackMessage`, `subtype: "model_refusal_no_fallback"`: emitida quando o modelo encerra o stream com uma recusa e nenhuma nova tentativa é executada, por exemplo porque nenhum modelo de fallback está configurado. Contém `original_model`. Requer Agent SDK v0.3.193 ou posterior.

1535 

1480### `SDKAssistantMessage`1536### `SDKAssistantMessage`

1481 1537 

1482Mensagem de resposta do assistente.1538Mensagem de resposta do assistente.


1636 stop_reason: string | null;1692 stop_reason: string | null;

1637 ttft_ms?: number;1693 ttft_ms?: number;

1638 ttft_stream_ms?: number;1694 ttft_stream_ms?: number;

1695 time_to_request_ms?: number;

1639 user_message_uuid?: string;1696 user_message_uuid?: string;

1640 user_message_uuids?: string[];1697 user_message_uuids?: string[];

1641 resume_reason?: string;1698 resume_reason?: string;


1701* `api_error_status`: o código de status HTTP do erro de API que encerrou a conversa. Ausente ou `null` quando o turno terminou sem um erro de API.1758* `api_error_status`: o código de status HTTP do erro de API que encerrou a conversa. Ausente ou `null` quando o turno terminou sem um erro de API.

1702* `ttft_ms`: tempo até o primeiro token em milissegundos, medido quando a primeira mensagem completa do assistente chega. Presente apenas no braço de sucesso.1759* `ttft_ms`: tempo até o primeiro token em milissegundos, medido quando a primeira mensagem completa do assistente chega. Presente apenas no braço de sucesso.

1703* `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.1760* `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.

1761* `time_to_request_ms`: tempo em milissegundos desde o início do turno até o Claude Code enviar a requisição à API. Presente apenas no ramo de sucesso. Requer Claude Code v2.1.162 ou posterior.

1704* `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.1762* `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.

1705* `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).1763* `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).

1706* `resume_reason`: por que este turno continua um que uma reinicialização interrompeu. Presente em ambos os ramos. Consulte [`resume_reason`](#resume_reason).1764* `resume_reason`: por que este turno continua um que uma reinicialização interrompeu. Presente em ambos os ramos. Consulte [`resume_reason`](#resume_reason).


1772* Turnos que não respondem a nenhuma mensagem sua, ou respondem a uma mensagem que você enviou sem um `uuid`1830* Turnos que não respondem a nenhuma mensagem sua, ou respondem a uma mensagem que você enviou sem um `uuid`

1773* Resultados que não respondem a nenhuma mensagem que você enviou, como o resultado zerado após uma falha de processo de trabalho1831* Resultados que não respondem a nenhuma mensagem que você enviou, como o resultado zerado após uma falha de processo de trabalho

1774 1832 

1833Quando um hook [`UserPromptSubmit`](https://code.claude.com/docs/pt/hooks#userpromptsubmit) bloqueia uma mensagem que inicia seu próprio turno, ou a interrompe com `continue: false`, você ainda recebe um resultado para essa mensagem. É um resultado de sucesso com `is_error: false` e `num_turns: 0`, seu `result` é a [mensagem de bloqueio](https://code.claude.com/docs/pt/hooks.md#what-a-blocked-prompt-leaves-behind) ou a [mensagem de interrupção](https://code.claude.com/docs/pt/hooks.md#json-output), e ele ecoa o `uuid` da mensagem segundo as mesmas regras de qualquer outro resultado. O resultado não tem `terminal_reason`, e nada nele além do texto de `result` indica que um hook encerrou o turno. Uma mensagem que um hook bloqueia enquanto outro turno está em execução pode não receber resultado: consulte [`user_message_uuids`](#user_message_uuids).

1834 

1775#### `user_message_uuids`1835#### `user_message_uuids`

1776 1836 

1777Os `uuid`s de cada mensagem que você enviou que Claude Code respondeu neste turno. Quando você envia várias mensagens próximas, Claude Code pode mesclá-las em um turno, e `user_message_uuid` então nomeia apenas a última delas. Para corresponder a resposta a qualquer uma das mensagens mescladas, procure o `uuid` dessa mensagem em qualquer lugar desta lista. Requer Agent SDK v0.3.259 ou posterior.1837Os `uuid`s de cada mensagem que você enviou que Claude Code respondeu neste turno. Quando você envia várias mensagens próximas, Claude Code pode mesclá-las em um turno, e `user_message_uuid` então nomeia apenas a última delas. Para corresponder a resposta a qualquer uma das mensagens mescladas, procure o `uuid` dessa mensagem em qualquer lugar desta lista. Requer Agent SDK v0.3.259 ou posterior.

1778 1838 

1779Claude Code define a lista junto com `user_message_uuid` em cada quadro de resposta que carrega esse campo e no resultado. Para o conjunto completo de quadros do turno que ecoam o `uuid` da mensagem respondida, e a versão que cada um requer, consulte [`user_message_uuid`](#user_message_uuid). A lista sempre contém `user_message_uuid` e contém no máximo 64 entradas.1839Claude Code define a lista junto com `user_message_uuid` em cada quadro de resposta que carrega esse campo e no resultado. Para o conjunto completo de quadros do turno que ecoam o `uuid` da mensagem respondida, e a versão que cada um requer, consulte [`user_message_uuid`](#user_message_uuid). A lista sempre contém `user_message_uuid` e contém no máximo 64 entradas.

1780 1840 

1781Quando Claude Code capta uma mensagem regular que você enviou enquanto um turno estava em execução, ele adiciona o `uuid` dessa mensagem à lista do resultado.1841Quando o Claude Code capta uma mensagem regular que você enviou enquanto um turno estava em execução, ele adiciona o `uuid` dessa mensagem à lista do resultado. Quando um hook [`UserPromptSubmit`](https://code.claude.com/docs/pt/hooks#userpromptsubmit) bloqueia a mensagem na captação, o Claude Code a descarta: a mensagem nunca chega ao Claude e não é mantida para um turno posterior. Você não recebe nenhum resultado para ela, e seu `uuid` não aparece na lista de nenhum resultado. Se um hook puder bloquear mensagens, defina um timeout na espera por um resultado que liste uma mensagem que você enviou enquanto um turno estava em execução.

1842 

1843Isso vale quando a saída do hook é apenas um bloqueio. Se a saída definir `continue: false`, mesmo ao lado de `decision: "block"`, ou se o hook for um hook de prompt que responde [`ok: false`](https://code.claude.com/docs/pt/hooks#response-schema) sem `continueOnBlock: true`, o Claude Code interrompe a mensagem em vez de descartá-la. A mensagem aguarda seu próprio turno, você recebe um resultado para ela e seu texto permanece na conversa, então o Claude a vê no próximo turno.

1782 1844 

1783Quando uma primeira resposta ou resultado carrega `user_message_uuid` sem a lista, veio de uma versão anterior de Claude Code, portanto recorra ao campo único.1845Quando uma primeira resposta ou resultado carrega `user_message_uuid` sem a lista, veio de uma versão anterior de Claude Code, portanto recorra ao campo único.

1784 1846 

channels.md +1 −1

Details

271 271 

272A mensagem chega em sua sessão Claude Code. O terminal a mostra como uma linha de canal de entrada como `← fakechat · web: what's in my working directory?`, enquanto o modelo a recebe como um evento `<channel source="plugin:fakechat:fakechat">`, usando o nome do servidor com escopo do plugin. Claude a lê, faz o trabalho e chama a ferramenta `reply` do fakechat. Se Claude Code solicitar permissão para a primeira resposta, aprove-a. A resposta aparece na interface de chat.272A mensagem chega em sua sessão Claude Code. O terminal a mostra como uma linha de canal de entrada como `← fakechat · web: what's in my working directory?`, enquanto o modelo a recebe como um evento `<channel source="plugin:fakechat:fakechat">`, usando o nome do servidor com escopo do plugin. Claude a lê, faz o trabalho e chama a ferramenta `reply` do fakechat. Se Claude Code solicitar permissão para a primeira resposta, aprove-a. A resposta aparece na interface de chat.

273 273 

274Se Claude atingir um prompt de permissão enquanto você está longe do terminal, a sessão pausa até que você responda. Os servidores de canal que declaram a [capacidade de retransmissão de permissão](https://code.claude.com/docs/pt/channels-reference.md#relay-permission-prompts) podem encaminhar esses prompts para você para que você possa aprovar ou negar remotamente. Para uso sem supervisão, [`--dangerously-skip-permissions`](https://code.claude.com/docs/pt/permission-modes#skip-all-checks-with-bypasspermissions-mode) ignora a maioria dos prompts, mas use apenas em ambientes em que você confia. Mesmo assim, o [modo actions no auto-aprova](https://code.claude.com/docs/pt/permission-modes.md#actions-no-mode-auto-approves) ainda se aplica.274Se Claude atingir um prompt de permissão enquanto você está longe do terminal, a sessão pausa até que você responda. Os servidores de canal que declaram a [capacidade de retransmissão de permissão](https://code.claude.com/docs/pt/channels-reference.md#relay-permission-prompts) podem encaminhar esses prompts para você para que você possa aprovar ou negar remotamente. Para uso sem supervisão, [`--dangerously-skip-permissions`](https://code.claude.com/docs/pt/permission-modes#skip-all-checks-with-bypasspermissions-mode) ignora a maioria dos prompts, mas use apenas em ambientes em que você confia. Mesmo assim, as [ações que nenhum modo aprova automaticamente](https://code.claude.com/docs/pt/permission-modes.md#actions-no-mode-auto-approves) ainda se aplicam.

275 275 

276Quando você executa canais em modo não interativo com `-p`, ferramentas que precisam de entrada de terminal, como perguntas de múltipla escolha e aprovação de modo de plano, são desabilitadas para que a sessão nunca fique travada aguardando entrada.276Quando você executa canais em modo não interativo com `-p`, ferramentas que precisam de entrada de terminal, como perguntas de múltipla escolha e aprovação de modo de plano, são desabilitadas para que a sessão nunca fique travada aguardando entrada.

277 277 

Details

525 params: z.object({525 params: z.object({

526 request_id: z.string(), // cinco letras minúsculas, inclua verbatim em seu prompt526 request_id: z.string(), // cinco letras minúsculas, inclua verbatim em seu prompt

527 tool_name: z.string(), // ex: "Bash", "Write"527 tool_name: z.string(), // ex: "Bash", "Write"

528 description: z.string(), // resumo do que esta chamada faz. Trate como não confiável.528 description: z.string(), // resumo desta chamada. Trate como não confiável.

529 input_preview: z.string(), // args da ferramenta como texto em forma de JSON. Trate como não confiável.529 input_preview: z.string(), // args da ferramenta como texto em forma de JSON. Trate como não confiável.

530 }),530 }),

531})531})


582}582}

583```583```

584 584 

585Uma resposta remota que não corresponde exatamente ao formato esperado falha de uma de duas maneiras, e em ambos os casos o diálogo do terminal local permanece aberto:585Se uma resposta remota não tiver efeito e o diálogo do terminal local permanecer aberto, verifique estas causas:

586 586 

587* **Formato diferente**: a regex do seu manipulador de entrada falha em corresponder, então texto como `approve it` ou `yes` sem um ID cai como uma mensagem normal para Claude.587* **O formato está errado**: a regex do seu manipulador de entrada falha em corresponder, então texto como `approve it` ou `yes` sem um ID cai como uma mensagem normal para Claude.

588* **Formato correto, ID errado**: seu servidor emite um veredicto, mas Claude Code não encontra nenhuma solicitação aberta com esse ID e o descarta silenciosamente.588* **O ID está errado**: seu servidor emite um veredicto, mas Claude Code não encontra nenhuma solicitação aberta com esse ID e o descarta silenciosamente.

589* **O ID foi usado por um prompt anterior**: seu servidor emite um veredicto com o ID da solicitação, mas um prompt anterior na sessão tinha o mesmo ID. Quando um ID se repete, Claude Code descarta qualquer veredicto de canal que o carregue, para que uma resposta destinada a um prompt não possa aprovar o outro. Um ID é composto por cinco letras aleatórias, então uma repetição é rara. Responda no terminal em vez disso.

589 590 

590### Exemplo completo591### Exemplo completo

591 592 

Details

90 90 

91### Mensagens enviadas no meio do turno não checkpointed91### Mensagens enviadas no meio do turno não checkpointed

92 92 

93No menu de rewind, uma mensagem que você [digitou enquanto Claude ainda estava trabalhando](https://code.claude.com/docs/pt/interactive-mode.md#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.93No menu de rewind, uma mensagem que você [digitou enquanto Claude ainda estava trabalhando](https://code.claude.com/docs/pt/interactive-mode.md#queue-messages-while-claude-works) pode ser marcada como **No code restore**. A mensagem marcada não tem um [checkpoint](#how-checkpoints-work) próprio.

94 94 

95Você 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.95Para desfazer as edições de arquivo que Claude fez depois dessa mensagem, 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.

96 96 

97### Caminhos symlinked e hard-linked não restaurados97### Caminhos symlinked e hard-linked não restaurados

98 98 

Details

98 98 

99Os avisos e a porcentagem vêm dos cabeçalhos `anthropic-ratelimit-unified-*`, que o gateway adiciona a cada resposta bem-sucedida de `/v1/messages` para um desenvolvedor que tem um limite. Os cabeçalhos sempre descrevem o limite próprio do desenvolvedor: o gateway remove os cabeçalhos de rate limit do provedor upstream, que descrevem sua cota compartilhada, e nunca os encaminha.99Os avisos e a porcentagem vêm dos cabeçalhos `anthropic-ratelimit-unified-*`, que o gateway adiciona a cada resposta bem-sucedida de `/v1/messages` para um desenvolvedor que tem um limite. Os cabeçalhos sempre descrevem o limite próprio do desenvolvedor: o gateway remove os cabeçalhos de rate limit do provedor upstream, que descrevem sua cota compartilhada, e nunca os encaminha.

100 100 

101O gasto que um desenvolvedor vê é a própria [estimativa](#how-requests-are-priced) do gateway, o mesmo valor com o qual ele aplica o limite, e não um valor da fatura do seu provedor. Claude Code lê os valores em dólar com uma requisição separada ao gateway. Se você definir `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` nas máquinas dos desenvolvedores, como [Postura de conformidade](https://code.claude.com/docs/pt/claude-apps-gateway-deploy.md#compliance-posture) sugere, Claude Code pula essa requisição. Com essa variável definida, ou com um servidor do gateway anterior a v2.1.284, a barra e a linha de status mostram apenas a porcentagem.101O gasto que um desenvolvedor vê é a própria [estimativa](#how-requests-are-priced) do gateway, o mesmo valor com o qual ele aplica o limite. Não é um valor da fatura do seu provedor. Claude Code lê os valores em dólar com uma requisição separada ao gateway, que ele envia mesmo se você definir `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` nas máquinas dos desenvolvedores. Antes da v2.1.295, Claude Code pulava essa requisição quando a variável estava definida, e `/usage` e a linha de status mostravam a porcentagem e a data de redefinição, sem valores em dólar.

102 102 

103## Referência da API de administrador103## Referência da API de administrador

104 104 

Details

18 18 

19* **Navegador**: [claude.ai/code](https://claude.ai/code), também chamado Claude Code na web19* **Navegador**: [claude.ai/code](https://claude.ai/code), também chamado Claude Code na web

20* **Móvel**: a aba **Code** no [aplicativo Claude](https://code.claude.com/docs/pt/mobile.md)20* **Móvel**: a aba **Code** no [aplicativo Claude](https://code.claude.com/docs/pt/mobile.md)

21* **Aplicativo desktop**: selecione **Cloud** em vez de **Local** quando você [inicia uma sessão](https://code.claude.com/docs/pt/desktop.md#run-long-running-tasks-in-the-cloud)21* **Aplicativo desktop**: selecione um ambiente em **Cloud** no seletor de ambiente quando você [inicia uma sessão](https://code.claude.com/docs/pt/desktop.md#run-long-running-tasks-in-the-cloud)

22* **Terminal**: [`claude --cloud`](#from-terminal-to-cloud)22* **Terminal**: [`claude --cloud`](#from-terminal-to-cloud)

23* **Tarefas agendadas na nuvem**: [execuções agendadas e acionadas](https://code.claude.com/docs/pt/routines.md) cada uma é executada como uma sessão na nuvem23* **Tarefas agendadas na nuvem**: [execuções agendadas e acionadas](https://code.claude.com/docs/pt/routines.md) cada uma é executada como uma sessão na nuvem

24 24 


247 247 

248### Revisar alterações248### Revisar alterações

249 249 

250Cada sessão mostra um indicador de diff com linhas adicionadas e removidas, como `+42 -18`. Selecione-o para abrir a visualização de diff, deixe comentários inline em linhas específicas e envie-os para Claude com sua próxima mensagem.250Depois que Claude envia suas alterações para um branch, o cartão **Changes** no painel ao lado do chat mostra as linhas adicionadas e removidas, como `+42 -18`. Clique nas contagens de linhas no cartão **Changes** para abrir a visualização de diff.

251 251 

252A visualização de diff compara as alterações da sessão em relação ao seu branch base por padrão. Para comparar com qualquer outro branch no repositório, selecione **Compare against** e escolha um.252* Você também pode clicar em **Changes** na barra de título da sessão ou no menu **⋮** da barra.

253* Para mostrar o painel quando ele estiver oculto, clique no ícone **Show session rail** na barra de título da sessão ou no menu **⋮** da barra.

254 

255Na visualização de diff, você pode comentar em linhas e comparar com outro branch:

256 

257* **Comentar**: deixe comentários inline em linhas específicas e, em seguida, envie os comentários para Claude com sua próxima mensagem

258* **Comparar**: a visualização de diff compara as alterações da sessão em relação ao seu branch base por padrão. Para comparar com qualquer outro branch no repositório, selecione **Compare against** e escolha um

253 259 

254Claude Code calcula esses diffs a partir do conteúdo bruto do blob git, portanto os drivers de diff e filtros `textconv` configurados no repositório não se aplicam.260Claude Code calcula esses diffs a partir do conteúdo bruto do blob git, portanto os drivers de diff e filtros `textconv` configurados no repositório não se aplicam.

255 261 


313 319 

314### Arquivar sessões320### Arquivar sessões

315 321 

316Você pode arquivar sessões para manter sua lista de sessões organizada. As sessões arquivadas ficam ocultas da lista de sessões padrão, mas podem ser visualizadas filtrando por sessões arquivadas.322Arquive uma sessão para removê-la da lista de sessões da barra lateral. Para arquivar uma, passe o mouse sobre ela na barra lateral, abra seu menu **⋯** e selecione **Archive**.

317 323 

318Para arquivar uma sessão, passe o mouse sobre a sessão na barra lateral e selecione o ícone de arquivo.324#### Encontrar uma sessão arquivada

325 

326Para ver suas sessões arquivadas, acesse [claude.ai/code/sessions](https://claude.ai/code/sessions) e abra a aba **Archived**. Para colocar uma de volta na lista de sessões da barra lateral, passe o mouse sobre ela nessa aba, abra seu menu **⋮** e selecione **Unarchive**.

319 327 

320### Excluir sessões328### Excluir sessões

321 329 

322Excluir uma sessão remove permanentemente a sessão e seus dados. Esta ação não pode ser desfeita. Você pode excluir uma sessão de duas maneiras:330Excluir uma sessão remove permanentemente a sessão e seus dados. Esta ação não pode ser desfeita. Exclua uma sessão pela barra lateral, pelo menu da sessão ou pela aba **Archived**, se você já a tiver arquivado:

323 331 

324* **Na barra lateral**: filtre por sessões arquivadas, passe o mouse sobre a sessão que deseja excluir e selecione o ícone de exclusão332* **Na barra lateral**: passe o mouse sobre a sessão, abra seu menu **⋯** e selecione **Delete**

325* **No menu da sessão**: abra uma sessão, selecione o menu suspenso ao lado do título da sessão e selecione **Delete**333* **No menu da sessão**: abra uma sessão, selecione o menu suspenso ao lado do título da sessão e selecione **Delete**

334* **Na aba Archived**: passe o mouse sobre a sessão na [aba **Archived**](#find-an-archived-session), abra seu menu **⋮** e selecione **Delete**

326 335 

327Você será solicitado a confirmar antes de uma sessão ser excluída.336Você será solicitado a confirmar antes de uma sessão ser excluída.

328 337 


336 345 

337Existem algumas maneiras de ativar auto-fix dependendo de onde o PR veio e qual dispositivo você está usando:346Existem algumas maneiras de ativar auto-fix dependendo de onde o PR veio e qual dispositivo você está usando:

338 347 

339* **PRs criados em uma sessão na nuvem**: abra a sessão em claude.ai/code, abra a barra de status de CI e selecione **Auto-fix**348* **PRs criados em uma sessão na nuvem**: abra a sessão em claude.ai/code e encontre o pull request no [card **Changes**](#review-changes). Abra o menu **⋮** ao lado do título do pull request e ative **Auto-fix**

340* **A partir do seu terminal**: execute [`/autofix-pr`](https://code.claude.com/docs/pt/commands) enquanto estiver na branch do PR. Claude Code detecta o PR aberto com `gh`, gera uma sessão na nuvem e ativa auto-fix em uma etapa349* **A partir do seu terminal**: execute [`/autofix-pr`](https://code.claude.com/docs/pt/commands) enquanto estiver na branch do PR. Claude Code detecta o PR aberto com `gh`, gera uma sessão na nuvem e ativa auto-fix em uma etapa

341* **A partir do aplicativo móvel**: diga a Claude para corrigir automaticamente o PR, por exemplo "watch this PR and fix any CI failures or review comments"350* **A partir do aplicativo móvel**: diga a Claude para corrigir automaticamente o PR, por exemplo "watch this PR and fix any CI failures or review comments"

342* **Qualquer PR existente**: cole a URL do PR em uma sessão e diga a Claude para corrigir automaticamente351* **Qualquer PR existente**: cole a URL do PR em uma sessão e diga a Claude para corrigir automaticamente

343 352 

344Auto-fix é um toggle por PR. Para parar de monitorar, abra a barra de status de CI na sessão em claude.ai/code e desmarque o toggle **Auto-fix**, ou diga a Claude para parar de observar o PR.353Para parar de monitorar, desative **Auto-fix** no menu **⋮** do pull request no [card **Changes**](#review-changes) da sessão, ou diga a Claude para parar de observar o PR.

345 354 

346### Como Claude responde à atividade de PR355### Como Claude responde à atividade de PR

347 356 


381* Tente novamente após um minuto, já que a capacidade é provisionada sob demanda390* Tente novamente após um minuto, já que a capacidade é provisionada sob demanda

382* Confirme que sua conexão GitHub pode acessar o repositório seguindo [No repositories appear after connecting GitHub](https://code.claude.com/docs/pt/web-quickstart.md#no-repositories-appear-after-connecting-github)391* Confirme que sua conexão GitHub pode acessar o repositório seguindo [No repositories appear after connecting GitHub](https://code.claude.com/docs/pt/web-quickstart.md#no-repositories-appear-after-connecting-github)

383 392 

393### Your new session couldn't start

394 

395Seu prompt está de volta na caixa de onde você o enviou.

396 

397* **Conexão perdida**: verifique sua conexão com a internet e qualquer VPN ou proxy que você use, depois envie seu prompt novamente

398* **Erro do servidor**: aguarde um momento, depois envie seu prompt novamente. Se o aviso reaparecer, verifique [status.claude.com](https://status.claude.com)

399 

400### Can't rewind to this message

401 

402**Rewind to here** falha com este erro em qualquer mensagem, exceto a mais recente, quando sua sessão é executada em um [runner auto-hospedado](https://code.claude.com/docs/pt/self-hosted-environments) com Claude Code anterior à v2.1.246. Peça a quem gerencia os runners da sua organização para [atualizá-los](https://code.claude.com/docs/pt/self-hosted-environments-deploy.md#pin-the-version).

403 

384### Unable to get organization UUID404### Unable to get organization UUID

385 405 

386`claude --cloud` e `claude --teleport` requerem entrada com uma conta claude.ai. Se você autenticar com uma chave de API, ou se seus detalhes de conta armazenados estiverem obsoletos, você verá uma destas mensagens:406`claude --cloud` e `claude --teleport` requerem entrada com uma conta claude.ai. Se você autenticar com uma chave de API, ou se seus detalhes de conta armazenados estiverem obsoletos, você verá uma destas mensagens:

Details

111 111 

112O projeto agora está listado em **Projects** na barra lateral, e sua conversa está aberta. [Seu primeiro lote](#your-first-batch) cobre o que configurar antes de enviar trabalho a ele.112O projeto agora está listado em **Projects** na barra lateral, e sua conversa está aberta. [Seu primeiro lote](#your-first-batch) cobre o que configurar antes de enviar trabalho a ele.

113 113 

114### Iniciar a partir de uma sessão em nuvem existente114### Iniciar a partir de uma sessão existente

115 115 

116Se uma sessão na nuvem que você mesmo iniciou está fazendo trabalho que pertence a um projeto, abra o menu dela na barra lateral e escolha **Move to project**, depois escolha no submenu:116Se uma sessão na nuvem que você mesmo iniciou está fazendo trabalho que pertence a um projeto, abra o menu dela na barra lateral e escolha **Move to project**, depois escolha no submenu:

117 117 


120 120 

121Um banner **Set up project** também pode aparecer acima da caixa de mensagem de uma sessão na nuvem. Se você usá-lo em vez de **Continue as new project**, o resultado é o mesmo, exceto que o turno em execução da sessão para assim que o projeto abre.121Um banner **Set up project** também pode aparecer acima da caixa de mensagem de uma sessão na nuvem. Se você usá-lo em vez de **Continue as new project**, o resultado é o mesmo, exceto que o turno em execução da sessão para assim que o projeto abre.

122 122 

123Uma sessão local não tem essas opções. Para continuar seu trabalho em um projeto, descreva o trabalho na conversa do projeto, ou faça push de sua branch, adicione esse repositório ao projeto e nomeie a branch na tarefa.123Uma sessão na sua própria máquina recebe o mesmo menu da barra lateral em claude.ai/code assim que você a conecta por meio do [Remote Control](https://code.claude.com/docs/pt/remote-control.md#start-a-remote-control-session). A partir de um projeto, Claude não consegue ler a transcrição de uma sessão que se conectou enquanto [**Require trusted devices**](https://code.claude.com/docs/pt/remote-control.md#trusted-devices) estava ativado para sua conta. Se essa configuração estiver desativada:

124 

1251. Se a sessão ainda não estiver conectada, execute `/remote-control` nela. Se ela se conectou enquanto essa configuração estava ativada, desconecte-a e conecte-a novamente primeiro.

1262. Em um navegador, encontre a linha da sessão na barra lateral em [claude.ai/code](https://claude.ai/code), abra o menu dela e escolha no mesmo submenu.

127 

128Se **Require trusted devices** estiver ativado, ou se você não usar o Remote Control, descreva o trabalho você mesmo na conversa do projeto. Ou faça push do branch da sessão, adicione o repositório dela ao projeto e informe a Claude o nome do branch.

124 129 

125### Configurar acesso ao GitHub130### Configurar acesso ao GitHub

126 131 


425* **Sessões na nuvem**: cada thread é uma [sessão na nuvem](https://code.claude.com/docs/pt/claude-code-on-the-web.md), a menos que você peça a Claude para executá-la na sua máquina. De qualquer forma, Claude inicia e rastreia em vez de você. Você também pode trazer o trabalho de uma sessão na nuvem que você mesmo iniciou para um projeto: escolha [**Move to project**](#start-from-an-existing-cloud-session) no menu da barra lateral dessa sessão.430* **Sessões na nuvem**: cada thread é uma [sessão na nuvem](https://code.claude.com/docs/pt/claude-code-on-the-web.md), a menos que você peça a Claude para executá-la na sua máquina. De qualquer forma, Claude inicia e rastreia em vez de você. Você também pode trazer o trabalho de uma sessão na nuvem que você mesmo iniciou para um projeto: escolha [**Move to project**](#start-from-an-existing-cloud-session) no menu da barra lateral dessa sessão.

426* **Tarefas agendadas**: quando você pede trabalho agendado em um projeto, Claude cria uma [tarefa agendada na nuvem](https://code.claude.com/docs/pt/routines.md) que é executada como threads nesse projeto e aparece em sua aba **Scheduled tasks**. Tarefas agendadas que você cria fora de um projeto continuam funcionando por conta própria.431* **Tarefas agendadas**: quando você pede trabalho agendado em um projeto, Claude cria uma [tarefa agendada na nuvem](https://code.claude.com/docs/pt/routines.md) que é executada como threads nesse projeto e aparece em sua aba **Scheduled tasks**. Tarefas agendadas que você cria fora de um projeto continuam funcionando por conta própria.

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

428* **Sessões locais e agent view**: uma sessão que você inicia na sua máquina em seu terminal, IDE ou no ambiente local do aplicativo desktop não pode ser adicionada a um projeto. [Agent view](https://code.claude.com/docs/pt/agent-view.md) é uma tela para rastrear várias sessões locais lado a lado, e você ainda inicia cada uma e dá sua tarefa a ela mesmo.433* **Sessões locais e agent view**: uma sessão que você mesmo inicia em seu terminal, IDE ou no ambiente local do aplicativo desktop fica fora dos seus projetos, embora você possa [trazer o trabalho dela para um deles](#start-from-an-existing-cloud-session). [Agent view](https://code.claude.com/docs/pt/agent-view.md) é uma tela para rastrear várias sessões locais lado a lado, e você ainda inicia cada uma e dá sua tarefa a ela mesmo.

429* **Worktrees**: um [worktree](https://code.claude.com/docs/pt/worktrees.md) dá a cada sessão local sua própria cópia de trabalho de um repositório. As threads na nuvem não precisam deles: cada uma clona seus repositórios em seu próprio sandbox na nuvem e trabalha em seu próprio branch.434* **Worktrees**: um [worktree](https://code.claude.com/docs/pt/worktrees.md) dá a cada sessão local sua própria cópia de trabalho de um repositório. As threads na nuvem não precisam deles: cada uma clona seus repositórios em seu próprio sandbox na nuvem e trabalha em seu próprio branch.

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

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


437 442 

438* Projects estão disponíveis em claude.ai/code, no aplicativo desktop e no aplicativo móvel Claude, não no CLI do terminal, na extensão VS Code ou no plugin JetBrains, e não através de Amazon Bedrock, Agent Platform do Google Cloud ou Microsoft Foundry.443* Projects estão disponíveis em claude.ai/code, no aplicativo desktop e no aplicativo móvel Claude, não no CLI do terminal, na extensão VS Code ou no plugin JetBrains, e não através de Amazon Bedrock, Agent Platform do Google Cloud ou Microsoft Foundry.

439* As threads do projeto são [sessões em nuvem](https://code.claude.com/docs/pt/claude-code-on-the-web.md), ou sessões em sua própria máquina através de [Remote Control](https://code.claude.com/docs/pt/remote-control.md), com Anthropic como provedor de modelo em ambos os casos. [Segurança](https://code.claude.com/docs/pt/security.md) e [Uso de dados](https://code.claude.com/docs/pt/data-usage.md) cobrem como as sessões em nuvem são isoladas e o que é retido, e [Conexão e segurança](https://code.claude.com/docs/pt/remote-control.md#connection-and-security) cobre como uma thread em sua máquina se conecta e o que é armazenado.444* As threads do projeto são [sessões em nuvem](https://code.claude.com/docs/pt/claude-code-on-the-web.md), ou sessões em sua própria máquina através de [Remote Control](https://code.claude.com/docs/pt/remote-control.md), com Anthropic como provedor de modelo em ambos os casos. [Segurança](https://code.claude.com/docs/pt/security.md) e [Uso de dados](https://code.claude.com/docs/pt/data-usage.md) cobrem como as sessões em nuvem são isoladas e o que é retido, e [Conexão e segurança](https://code.claude.com/docs/pt/remote-control.md#connection-and-security) cobre como uma thread em sua máquina se conecta e o que é armazenado.

440* Você não pode adicionar uma sessão que iniciou você mesmo em sua máquina a um projeto. Um projeto alcança sua máquina apenas [executando uma thread lá através de Remote Control](#run-a-thread-on-your-own-computer), e essa seção lista o que é necessário.445* Você não pode adicionar a um projeto uma sessão que você mesmo iniciou em sua máquina, embora possa [trazer o trabalho dela para um projeto](#start-from-an-existing-cloud-session). Um projeto alcança sua máquina [executando uma thread lá através de Remote Control](#run-a-thread-on-your-own-computer), e essa seção lista o que é necessário.

441* O sandbox de uma thread em nuvem pausa entre voltas e retoma quando a thread continua. Se o sandbox não puder ser retomado, a thread continua de um clone fresco, então mudanças não confirmadas podem ser perdidas. Em tarefas longas, peça a Claude para confirmar e enviar trabalho em progresso.446* O sandbox de uma thread em nuvem pausa entre voltas e retoma quando a thread continua. Se o sandbox não puder ser retomado, a thread continua de um clone fresco, então mudanças não confirmadas podem ser perdidas. Em tarefas longas, peça a Claude para confirmar e enviar trabalho em progresso.

442* Um projeto pertence a um usuário. Você não pode compartilhar um projeto ou suas threads com outro usuário, e transcrições de thread não têm a opção de compartilhamento que outras sessões em nuvem têm. Não há controles de nível de organização para projetos durante o beta.447* Um projeto pertence a um usuário. Você não pode compartilhar um projeto ou suas threads com outro usuário, e transcrições de thread não têm a opção de compartilhamento que outras sessões em nuvem têm. Não há controles de nível de organização para projetos durante o beta.

443* Uma thread pertence ao único project que a iniciou. Você não pode mover ou copiar uma thread para outro project, ou movê-la para ficar sozinha. [**Move to project**](#start-from-an-existing-cloud-session) vai apenas na outra direção: traz o trabalho de uma sessão em nuvem para um project. Você não pode mesclar dois projects em um.448* Uma thread pertence ao único project que a iniciou. Você não pode mover ou copiar uma thread para outro project, ou movê-la para ficar sozinha. [**Move to project**](#start-from-an-existing-cloud-session) vai apenas na outra direção: traz o trabalho de uma sessão em nuvem para um project. Você não pode mesclar dois projects em um.

code-review.md +1 −1

Details

67 67 

68* **Descobertas**: comentários inline nas linhas em questão, com um resumo no corpo da revisão68* **Descobertas**: comentários inline nas linhas em questão, com um resumo no corpo da revisão

69* **Uma execução de verificação**: chamada **Claude Code Review**, com as descobertas listadas em seus [detalhes](https://code.claude.com/docs/pt/code-review-pull-requests.md#check-run-output). A execução de verificação não é concluída como falha.69* **Uma execução de verificação**: chamada **Claude Code Review**, com as descobertas listadas em seus [detalhes](https://code.claude.com/docs/pt/code-review-pull-requests.md#check-run-output). A execução de verificação não é concluída como falha.

70* **Quando não encontra nada**: o título da execução de verificação diz **Code review found no issues**, e Claude publica a mesma nota curta no pull request70* **Uma nota no lugar das descobertas**: publicada quando o título da execução de verificação diz **Code review found no issues**

71 71 

72Code Review escolhe os modelos Claude em que as revisões são executadas, e suas configurações de administrador não oferecem escolha de modelo. Para tornar as revisões mais ou menos minuciosas, altere o [nível de revisão](#review-levels).72Code Review escolhe os modelos Claude em que as revisões são executadas, e suas configurações de administrador não oferecem escolha de modelo. Para tornar as revisões mais ou menos minuciosas, altere o [nível de revisão](#review-levels).

73 73 

Details

152 152 

153### O que uma revisão posterior abrange153### O que uma revisão posterior abrange

154 154 

155Uma revisão posterior que começa por conta própria, como após um push, concentra-se no que mudou desde a última revisão e publica menos nits e descobertas pré-existentes. O resumo dela contabiliza o que foi deixado de fora, em uma linha que termina com "found and not posted" ou "outside the scope of this re-review and not posted."155Uma revisão posterior que começa por conta própria, como após um push, concentra-se no que mudou desde a última revisão e publica menos [nits e descobertas pré-existentes](#severity-levels). Para ver se ela deixou descobertas de fora por esse motivo, procure no corpo da revisão uma frase que as contabiliza:

156 

157* **Descobertas em código que não mudou desde a última revisão**: a frase termina com "outside the scope of this re-review and not posted"

158* **Nits e descobertas pré-existentes**: a frase termina com "found and not posted"

156 159 

157Para obter uma revisão que não deixe nenhuma dessas de fora, comente [`@claude review`](#comment-commands). Ela abrange todo o pull request novamente.160Para obter uma revisão que não deixe nenhuma dessas de fora, comente [`@claude review`](#comment-commands). Ela abrange todo o pull request novamente.

158 161 

Details

15| Título da check run | O que significa | O que fazer |15| Título da check run | O que significa | O que fazer |

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

17| **Code review queued...** ou **Code review in progress...** | A revisão ainda não terminou | Aguarde o título mudar |17| **Code review queued...** ou **Code review in progress...** | A revisão ainda não terminou | Aguarde o título mudar |

18| **Code review found no issues** | A revisão terminou e não encontrou nada a sinalizar | Nada |18| **Code review found no issues** | A revisão terminou e não publicou nenhum achado | Se esta não for a primeira revisão do pull request, procure no corpo da revisão uma contagem de [achados que a revisão deixou de fora](https://code.claude.com/docs/pt/code-review-pull-requests.md#what-a-later-review-covers). Caso contrário, nada |

19| Um título informando que foram encontrados problemas | A revisão terminou com achados | Se você não os vê no diff, consulte [Encontre problemas que não aparecem como comentários inline](#find-issues-that-aren’t-showing-as-inline-comments) |19| Um título informando que foram encontrados problemas | A revisão terminou com achados | Se você não os vê no diff, consulte [Encontre problemas que não aparecem como comentários inline](#find-issues-that-aren’t-showing-as-inline-comments) |

20| **Code review skipped — no new changes** | Uma revisão automática não foi executada no seu push mais recente | Para obter uma revisão mesmo assim, comente `@claude review` |20| **Code review skipped — no new changes** | Uma revisão automática não foi executada no seu push mais recente | Para obter uma revisão mesmo assim, comente `@claude review` |

21| **Code review not repeated — earlier findings still open** | Uma revisão automática não foi executada no seu push mais recente, e achados Important da revisão anterior ainda estão em aberto | Faça push de uma correção ou, para obter uma revisão mesmo assim, comente `@claude review`. Consulte [Quando um push mantém o resultado anterior](https://code.claude.com/docs/pt/code-review-pull-requests.md#when-a-push-keeps-the-earlier-result) |21| **Code review not repeated — earlier findings still open** | Uma revisão automática não foi executada no seu push mais recente, e achados Important da revisão anterior ainda estão em aberto | Faça push de uma correção ou, para obter uma revisão mesmo assim, comente `@claude review`. Consulte [Quando um push mantém o resultado anterior](https://code.claude.com/docs/pt/code-review-pull-requests.md#when-a-push-keeps-the-earlier-result) |

desktop.md +48 −17

Details

223 223 

224#### Ocultar ou mostrar o painel de detalhes da sessão224#### Ocultar ou mostrar o painel de detalhes da sessão

225 225 

226Para ocultar ou mostrar o painel, clique em **Hide session rail** ou **Show session rail** na barra de título da sessão, ou no menu **⋮** da barra quando a janela for estreita. Se você ainda não vir o painel, [verifique qual layout da aba Code você tem](#check-which-layout-you-have).226Para ocultar ou mostrar o painel, clique em **Hide session rail** ou **Show session rail** na barra de título da sessão, ou no menu **⋮** da barra. Se você ainda não vir o painel, [verifique qual layout da aba Code você tem](#check-which-layout-you-have).

227 227 

228### Executar comandos no terminal228### Executar comandos no terminal

229 229 


984 984 

985* **Sistema**: um processador x86\_64 ou arm64. A máquina também precisa atender aos [requisitos de sistema](https://code.claude.com/docs/pt/setup.md#system-requirements) do Claude Code. No Linux, o Claude Code precisa de glibc 2.17 ou posterior, ou musl. Para ver qual a máquina tem, execute `ldd --version` nela. Em uma distribuição baseada em musl, como o Alpine Linux, instale também os [pacotes de que o Claude Code precisa](https://code.claude.com/docs/pt/setup.md#alpine-linux-and-musl-based-distributions).985* **Sistema**: um processador x86\_64 ou arm64. A máquina também precisa atender aos [requisitos de sistema](https://code.claude.com/docs/pt/setup.md#system-requirements) do Claude Code. No Linux, o Claude Code precisa de glibc 2.17 ou posterior, ou musl. Para ver qual a máquina tem, execute `ldd --version` nela. Em uma distribuição baseada em musl, como o Alpine Linux, instale também os [pacotes de que o Claude Code precisa](https://code.claude.com/docs/pt/setup.md#alpine-linux-and-musl-based-distributions).

986* **SFTP**: o servidor SSH precisa oferecer o subsistema SFTP, que uma linha `Subsystem sftp` no `sshd_config` dele ativa. Para verificar, conecte-se ao mesmo host e porta com `sftp` em um terminal no seu computador. Um servidor funcionando mostra o prompt `sftp>`.986* **SFTP**: o servidor SSH precisa oferecer o subsistema SFTP, que uma linha `Subsystem sftp` no `sshd_config` dele ativa. Para verificar, conecte-se ao mesmo host e porta com `sftp` em um terminal no seu computador. Um servidor funcionando mostra o prompt `sftp>`.

987* **Sessões por conexão**: o Desktop no macOS e no Linux abre várias sessões em uma única conexão SSH. Se o `sshd_config` do servidor definir `MaxSessions 1`, aumente o valor, por exemplo para o padrão do OpenSSH, que é 10.987* **`MaxSessions 1` no servidor**: para se conectar a um servidor cujo `sshd_config` define `MaxSessions 1`, faça uma destas coisas:

988 * **Seu computador executa macOS ou Linux**: atualize para o Claude Desktop v3.1623.0 ou posterior

989 * **Seu computador executa Windows**: certifique-se de que o Desktop [se conecta pelo cliente OpenSSH](#use-your-ssh-configuration), porque o cliente SSH integrado do Desktop não consegue se conectar a esse servidor

990 * **Você pode alterar o servidor**: aumente `MaxSessions`, por exemplo para o padrão do OpenSSH, que é 10

991* **Logins com `MaxSessions 1`**: use um login que funcione sem prompt, como uma chave que seu agente SSH mantém. O Desktop faz login pelo menos duas vezes cada vez que se conecta ou reconecta. Espere pelo menos mais um login para cada aba do [terminal](#run-commands-in-the-terminal) e para cada sessão do Desktop em que você executa comandos que começam com `!`. Não espere nenhum para comandos que Claude executa.

992* **Códigos de uso único com `MaxSessions 1`**: se cada login solicitar algo, como códigos de uso único, os comandos `!` falham. Execute esses comandos em uma aba do terminal, que solicita no próprio painel.

988* **Pasta de instalação**: o Desktop instala um programa auxiliar e o Claude Code em `~/.claude/remote/` no seu diretório pessoal. Ele os executa a partir dali, portanto essa pasta não pode estar em um sistema de arquivos montado com `noexec`. Reserve cerca de 1 GB de espaço em disco no diretório pessoal de cada usuário que se conecta. Para saber o que essa pasta contém, consulte [Arquivos e processos na máquina remota](#files-and-processes-on-the-remote-machine).993* **Pasta de instalação**: o Desktop instala um programa auxiliar e o Claude Code em `~/.claude/remote/` no seu diretório pessoal. Ele os executa a partir dali, portanto essa pasta não pode estar em um sistema de arquivos montado com `noexec`. Reserve cerca de 1 GB de espaço em disco no diretório pessoal de cada usuário que se conecta. Para saber o que essa pasta contém, consulte [Arquivos e processos na máquina remota](#files-and-processes-on-the-remote-machine).

989* **Shell**: o shell definido para sua conta na máquina remota precisa executar comandos enviados via SSH, como fazem o Bash, o Zsh e o `sh`994* **Shell**: o shell definido para sua conta na máquina remota precisa executar comandos enviados via SSH, como fazem o Bash, o Zsh e o `sh`

990* **Rede**: o Claude Code é executado na máquina remota e faz suas requisições de rede a partir dali, portanto a máquina precisa do [acesso à rede que o Claude Code exige](https://code.claude.com/docs/pt/network-config.md#network-access-requirements). Se a máquina não conseguir baixar o Claude Code, o Desktop o baixa no seu computador e o envia. As outras requisições do Claude Code ainda saem da máquina remota. Em uma máquina remota Linux, se essas requisições precisarem de um proxy, [defina-o para sessões SSH](#set-a-proxy-or-a-ca-certificate-for-ssh-sessions).995* **Rede**: o Claude Code é executado na máquina remota e faz suas requisições de rede a partir dali, portanto a máquina precisa do [acesso à rede que o Claude Code exige](https://code.claude.com/docs/pt/network-config.md#network-access-requirements). Se a máquina não conseguir baixar o Claude Code, o Desktop o baixa no seu computador e o envia. As outras requisições do Claude Code ainda saem da máquina remota. Em uma máquina remota Linux, se essas requisições precisarem de um proxy, [defina-o para sessões SSH](#set-a-proxy-or-a-ca-certificate-for-ssh-sessions).


993 998 

994Se uma máquina remota Linux acessa a internet por meio de um proxy ou precisa de um certificado de CA, adicione as [variáveis de proxy e de CA](https://code.claude.com/docs/pt/network-config.md) em `env` no `~/.claude/settings.json` dessa máquina. Adicione-as mesmo que você já as exporte em `~/.profile`, `~/.bash_profile`, `~/.zprofile` ou `~/.zshrc` nessa máquina.999Se uma máquina remota Linux acessa a internet por meio de um proxy ou precisa de um certificado de CA, adicione as [variáveis de proxy e de CA](https://code.claude.com/docs/pt/network-config.md) em `env` no `~/.claude/settings.json` dessa máquina. Adicione-as mesmo que você já as exporte em `~/.profile`, `~/.bash_profile`, `~/.zprofile` ou `~/.zshrc` nessa máquina.

995 1000 

996Uma sessão SSH não as obtém desses arquivos, mesmo quando o `claude` em um terminal nessa máquina as obtém. A sessão pode então travar, ou mostrar **The connection from … to the API failed** ou **Authentication failed**, e fazer login novamente não ajuda.1001Em uma sessão SSH, o Claude Code não recebe as variáveis desses arquivos, mesmo quando `claude` em um terminal nessa máquina recebe. A sessão pode então travar ou mostrar **The connection from … to the API failed** ou **Authentication failed**, e fazer login novamente não ajuda.

997 1002 

998**1. Adicione as variáveis**1003**1. Adicione as variáveis**

999 1004 


1028 1033 

1029Reinicie a máquina remota, ou saia do Desktop e encerre os processos do auxiliar, como nas duas primeiras etapas para [remover o auxiliar](#files-and-processes-on-the-remote-machine). Faça isso quando nenhuma tarefa estiver em execução, porque qualquer uma das opções interrompe o trabalho de Claude.1034Reinicie a máquina remota, ou saia do Desktop e encerre os processos do auxiliar, como nas duas primeiras etapas para [remover o auxiliar](#files-and-processes-on-the-remote-machine). Faça isso quando nenhuma tarefa estiver em execução, porque qualquer uma das opções interrompe o trabalho de Claude.

1030 1035 

1031#### Usar sua configuração SSH no macOS e no Linux1036#### Usar sua configuração SSH

1032 1037 

1033No macOS e no Linux, o Desktop se conecta executando o cliente OpenSSH no seu computador, portanto ele usa seu `~/.ssh/config`. Conectar-se por meio do cliente OpenSSH requer o Claude Desktop v1.37937.0 ou posterior. Insira um nome de `Host` desse arquivo no campo **SSH host** para usar as configurações da entrada correspondente, como `HostName`, `User`, `IdentityFile`, `CertificateFile`, `ProxyJump` e `ProxyCommand`.1038Você pode usar sua configuração SSH no macOS, Linux e Windows quando o Desktop se conecta pelo cliente OpenSSH no seu computador:

1039 

1040* **macOS e Linux**: o Desktop se conecta executando o cliente OpenSSH no seu computador, então ele usa o seu `~/.ssh/config`. Conectar-se pelo cliente OpenSSH requer o Claude Desktop v1.37937.0 ou posterior.

1041* **Windows**: quando o Desktop se conecta pelo cliente OpenSSH, ele usa o seu `%USERPROFILE%\.ssh\config`. Se você usa uma conta Claude em vez de um provedor terceirizado, conectar-se pelo cliente OpenSSH requer todos estes itens:

1042 

1043 * Claude Desktop v2.2553.0 ou posterior. Para descobrir sua versão, consulte [Verificar sua versão](#check-your-version).

1044 * OpenSSH 9.4 ou posterior da Microsoft

1045 * Desktop instalado com os botões de download no topo desta página, porque o Desktop da Microsoft Store não se conecta pelo cliente OpenSSH

1046 

1047 Se você não puder atender a esses requisitos, ou se usar um provedor terceirizado, consulte [Conectar no Windows sem o cliente OpenSSH](#connect-on-windows-without-the-openssh-client).

1048 

1049Com o cliente OpenSSH, insira um nome de `Host` do seu arquivo de configuração no campo **SSH host**. O Desktop então usa as configurações dessa entrada `Host`, como `HostName`, `User`, `IdentityFile`, `CertificateFile`, `ProxyJump` e `ProxyCommand`.

1034 1050 

1035Antes de adicionar a conexão, verifique o cliente e a entrada em um terminal no seu computador:1051Antes de adicionar a conexão, verifique o cliente e a entrada em um terminal no seu computador:

1036 1052 

1037* **Versão do cliente**: execute `ssh -V`. O cliente precisa ser o OpenSSH 7.6 ou posterior.1053* **Versão do cliente no macOS e Linux**: execute `ssh -V`. O cliente precisa ser OpenSSH 7.6 ou posterior.

1038* **Entrada**: execute `ssh` com o nome do `Host`, como `ssh devbox`. Se isso falhar, corrija a entrada primeiro.1054* **Versão do cliente no Windows**: o Desktop tenta primeiro o `ssh` no seu `PATH`, então execute `ssh -V`. O cliente é aprovado se a saída mostrar `OpenSSH_for_Windows_` e 9.4 ou posterior. Se não for aprovado, verifique as duas pastas que o Desktop tenta em seguida: execute `.\ssh.exe -V` em `C:\Windows\System32\OpenSSH` e depois em `C:\Program Files\OpenSSH`.

1055* **Nenhum cliente aprovado no Windows**: adicione o recurso opcional **OpenSSH Client** no Windows e instale as atualizações pendentes do Windows, ou instale o [build mais recente da Microsoft](https://learn.microsoft.com/en-us/troubleshoot/windows-server/system-management-components/upgrade-in-box-openssh-to-latest-openssh-release). Depois feche e reabra o Desktop. Para ver se o Desktop encontrou um cliente OpenSSH utilizável, procure em [`ssh.log`](#get-desktops-logs-for-an-ssh-problem) por `Windows OpenSSH client:` e uma versão, ou por `no usable Windows OpenSSH client`.

1056* **Entrada**: no Windows, use o cliente que foi aprovado na verificação de versão. Execute `ssh` com o nome do `Host`, como `ssh devbox`. Se isso falhar, corrija a entrada primeiro.

1039 1057 

1040Você pode deixar os campos **SSH port** e **SSH key (optional)** vazios. Se você preencher um deles, o Desktop o usa junto com a entrada:1058Você pode deixar os campos **SSH port** e **SSH key (optional)** vazios. Se você preencher um deles, o Desktop o usa junto com a entrada:

1041 1059 

1042* **SSH port**: um valor aqui sobrescreve o `Port` da entrada1060* **SSH port**: um valor aqui sobrescreve o `Port` da entrada

1043* **SSH key (optional)**: o Desktop oferece o arquivo de chave que você escolher, além do `IdentityFile` da entrada e das chaves no seu agente SSH1061* **SSH key (optional)**: com o cliente OpenSSH, o Desktop oferece o arquivo de chave que você escolher, além do `IdentityFile` da entrada e das chaves no seu agente SSH. No Windows, escolha uma chave no formato OpenSSH, porque o `ssh` não lê um arquivo `.ppk` do PuTTY.

1062 

1063##### Conectar no Windows sem o cliente OpenSSH

1064 

1065No Windows, você se conecta pelo cliente SSH integrado do Desktop se seu computador não atender aos [requisitos para o cliente OpenSSH](#use-your-ssh-configuration). Com um provedor terceirizado, você se conecta pelo cliente integrado por padrão, e seu administrador pode alterar isso. Para a configuração, consulte [SSH remote sessions in Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/ssh-remote-sessions).

1066 

1067Com o cliente integrado, você ainda pode inserir um nome de `Host` da sua configuração SSH no campo **SSH host** se o seu `PATH` tiver um comando `ssh`, com estes limites:

1068 

1069* **Configurações da entrada**: o Desktop usa `HostName`, `User`, `Port` e `IdentityFile`. Ele também usa `ProxyCommand` se houver um shell `sh` no seu `PATH`.

1070* **SSH key (optional)**: deixe este campo vazio para manter o `IdentityFile` da entrada, porque um arquivo de chave que você escolher aqui substitui o `IdentityFile`

1071* **`CertificateFile` e `ProxyJump`**: o Desktop ignora `CertificateFile`, e a conexão falha se a entrada definir `ProxyJump`. Para usar qualquer uma dessas configurações, [conecte-se pelo cliente OpenSSH](#use-your-ssh-configuration).

1044 1072 

1045##### Acessar uma máquina atrás de um jump host1073##### Acessar uma máquina atrás de um jump host

1046 1074 


1095 1123 

1096##### Usar variáveis do seu shell em um `ProxyCommand`1124##### Usar variáveis do seu shell em um `ProxyCommand`

1097 1125 

1098Para usar uma variável de ambiente sua em um comando `ProxyCommand` ou `Match exec`, exporte-a em um arquivo de inicialização do shell, como `~/.zshrc`, depois saia do Desktop e abra-o novamente. Quando o Desktop é iniciado, ele lê o que seu shell de login exporta e mantém esses valores até você sair.1126No macOS e Linux, para usar uma variável de ambiente sua em um comando `ProxyCommand` ou `Match exec`, exporte-a em um arquivo de inicialização do shell, como `~/.zshrc`. Depois feche e reabra o Desktop. Quando o Desktop é iniciado, ele lê o que seu shell de login exporta e mantém esses valores até você fechá-lo.

1099 1127 

1100Isso requer o Claude Desktop v2.37337.0 ou posterior e um comando `env` que aceite `-0`, o que você pode verificar executando `env -0` em um terminal no seu computador.1128Isso requer o Claude Desktop v2.37337.0 ou posterior e um comando `env` que aceite `-0`, o que você pode verificar executando `env -0` em um terminal no seu computador.

1101 1129 


1103>1131>

1104> Se o seu shell define credenciais temporárias da AWS, [forneça um perfil à AWS CLI](#use-aws-credentials-in-a-proxycommand) em vez de exportar variáveis `AWS_*`.1132> Se o seu shell define credenciais temporárias da AWS, [forneça um perfil à AWS CLI](#use-aws-credentials-in-a-proxycommand) em vez de exportar variáveis `AWS_*`.

1105 1133 

1106##### Usar credenciais da AWS em um `ProxyCommand`1134##### Usar credenciais da AWS em um `ProxyCommand` no macOS e Linux

1107 1135 

1108Se você define credenciais temporárias da AWS em um arquivo de inicialização do shell, um `ProxyCommand` que executa a AWS CLI pode se conectar em um terminal e falhar no Desktop. Quando seu shell exporta `AWS_SESSION_TOKEN`, `AWS_SECURITY_TOKEN` ou `AWS_CREDENTIAL_EXPIRATION`, o `ssh` e seu `ProxyCommand` no Desktop não recebem as credenciais da AWS do shell, nem `AWS_REGION` ou `AWS_PROFILE`.1136Se você define credenciais temporárias da AWS em um arquivo de inicialização do shell, um `ProxyCommand` que executa a AWS CLI pode se conectar em um terminal e falhar no Desktop. Quando seu shell exporta `AWS_SESSION_TOKEN`, `AWS_SECURITY_TOKEN` ou `AWS_CREDENTIAL_EXPIRATION`, o `ssh` e seu `ProxyCommand` no Desktop não recebem as credenciais da AWS do shell, nem `AWS_REGION` ou `AWS_PROFILE`.

1109 1137 


1242 1270 

1243##### Preparar uma tarefa longa1271##### Preparar uma tarefa longa

1244 1272 

1245* **Atualize primeiro**: atualize o Desktop antes de iniciar uma tarefa longa. No macOS e no Windows, o Desktop pode reiniciar sozinho para instalar uma atualização que baixou. Essa reinicialização aguarda enquanto Claude está trabalhando em uma tarefa SSH. No macOS com uma conta Claude, por padrão a reinicialização pode acontecer mesmo assim depois que a atualização tiver aguardado 72 horas.1273* **Atualize primeiro**: atualize o Desktop antes de iniciar uma tarefa longa. No macOS e Windows, o Desktop pode reiniciar sozinho para instalar uma atualização que baixou. Essa reinicialização aguarda enquanto Claude está trabalhando em uma tarefa SSH. Por padrão, depois que a atualização aguardar 72 horas, a reinicialização pode acontecer durante a tarefa se o Desktop conseguir [se reconectar à tarefa depois](#reopen-a-session-after-you-quit-desktop).

1246* **Não saia no Windows, ou antes da v2.42304.0 com um provedor terceirizado**: nesses casos, ao sair você perde a tarefa em execução, então deixe o Desktop aberto durante a tarefa. Em qualquer outro caso, veja [o que você recupera](#reopen-a-session-after-you-quit-desktop) antes de sair.1274* **Verifique antes de fechar**: você nem sempre recupera a tarefa em execução depois de um fechamento ou reinicialização, por exemplo após algumas atualizações do Desktop. Para os casos, consulte [Reabrir uma sessão depois de fechar o Desktop](#reopen-a-session-after-you-quit-desktop).

1275* **Em uma versão mais antiga, deixe o Desktop aberto**: no Windows com o Claude Desktop anterior à v3.1623.0, você não recupera a tarefa em execução depois que o Desktop fecha ou reinicia. O mesmo acontece com um provedor terceirizado no macOS ou Linux antes da v2.42304.0. Em ambos os casos, deixe o Desktop aberto durante a tarefa. Para descobrir sua versão, consulte [Verificar sua versão](#check-your-version).

1247* **Reduza as solicitações**: escolha um modo de permissão, regras ou hooks que [façam a tarefa aguardar por você com menos frequência](#handle-requests-that-arrive-while-you-are-away)1276* **Reduza as solicitações**: escolha um modo de permissão, regras ou hooks que [façam a tarefa aguardar por você com menos frequência](#handle-requests-that-arrive-while-you-are-away)

1248* **Verifique o jump host**: se seu jump host pede um login, por exemplo um push para um telefone, mude para um login que funcione sem prompt. Caso contrário, o Desktop pode enviar outro push cada vez que tentar se reconectar.1277* **Verifique o jump host**: se seu jump host pede um login, por exemplo um push para um telefone, mude para um login que funcione sem prompt. Caso contrário, o Desktop pode enviar outro push cada vez que tentar se reconectar.

1249* **Teste a máquina remota**: inicie uma tarefa curta, saia do Desktop enquanto a tarefa ainda está em execução e abra a sessão novamente bem depois de a tarefa dever ter terminado. Se a tarefa não estiver concluída e a sessão não mostrar nenhum erro de autenticação, verifique na máquina remota [o que pode encerrar uma tarefa](#limits-while-desktop-is-disconnected).1278* **Teste a máquina remota**: inicie uma tarefa curta, saia do Desktop enquanto a tarefa ainda está em execução e abra a sessão novamente bem depois de a tarefa dever ter terminado. Se a tarefa não estiver concluída e a sessão não mostrar nenhum erro de autenticação, verifique na máquina remota [o que pode encerrar uma tarefa](#limits-while-desktop-is-disconnected).


1320 1349 

1321Depois que você sai do Desktop, a tarefa continua em execução na máquina remota, mas para quando a sessão é aberta novamente, a menos que o Desktop consiga se reconectar ao processo dela. Enquanto o Desktop está fechado, a tarefa é executada até terminar, precisar de você ou atingir um dos [limites](#limits-while-desktop-is-disconnected).1350Depois que você sai do Desktop, a tarefa continua em execução na máquina remota, mas para quando a sessão é aberta novamente, a menos que o Desktop consiga se reconectar ao processo dela. Enquanto o Desktop está fechado, a tarefa é executada até terminar, precisar de você ou atingir um dos [limites](#limits-while-desktop-is-disconnected).

1322 1351 

1323* **Desktop no Windows**: você não recupera a tarefa em execução, porque o Desktop nunca se reconecta depois de sair. Inicie o Desktop novamente somente quando esperar que a tarefa esteja concluída, porque a sessão pode ser aberta quando o Desktop é iniciado.1352* **Desktop no Windows, tarefa iniciada em uma versão anterior à v3.1623.0**: você não recupera a tarefa, mesmo que o Desktop tenha sido atualizado desde então. Inicie o Desktop novamente somente quando esperar que a tarefa esteja concluída, porque a sessão pode abrir quando o Desktop é iniciado, e a tarefa para quando a sessão abre. Se você não souber em qual versão iniciou a tarefa, também espere até achar que ela está concluída.

1324* **Provedor terceirizado, tarefa de uma versão anterior**: se você iniciou a tarefa em uma versão do Desktop anterior à v2.42304.0, também não a recupera no macOS nem no Linux. Inicie o Desktop novamente somente quando esperar que a tarefa esteja concluída.1353* **Provedor terceirizado no macOS ou Linux, tarefa iniciada em uma versão anterior à v2.42304.0**: você não recupera a tarefa. Inicie o Desktop novamente somente quando esperar que a tarefa esteja concluída.

1325* **Qualquer outra tarefa, com o Desktop no macOS ou no Linux**: inicie o Desktop e abra a sessão, e a tarefa continua se o Desktop se reconectar. Ele nem sempre consegue se reconectar, por exemplo após algumas atualizações do Desktop, então [atualize antes de uma tarefa longa](#prepare-a-long-task).1354* **Qualquer outra tarefa**: inicie o Desktop e abra a sessão, e a tarefa continua se o Desktop se reconectar. Ele nem sempre consegue se reconectar, por exemplo após algumas atualizações do Desktop, então [atualize antes de uma tarefa longa](#prepare-a-long-task).

1326 1355 

1327Quando o Desktop não consegue se reconectar, você também perde qualquer aprovação ou pergunta que estava aguardando por você. Se a tarefa não continuar sozinha, envie uma mensagem, e o Claude continua a partir do histórico salvo da conversa.1356Quando a tarefa para, a sessão pode mostrar `Restarting Claude Code on <host>…` enquanto o Desktop inicia um novo processo. Você também perde qualquer aprovação ou pergunta que estava aguardando por você. Se Claude não continuar sozinho, envie uma mensagem, e Claude continua a partir do histórico salvo da conversa.

1328 1357 

1329Para implantações de terceiros, consulte [SSH remote sessions in Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/ssh-remote-sessions).1358Para implantações de terceiros, consulte [SSH remote sessions in Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/ssh-remote-sessions).

1330 1359 


1411 1440 

1412Para descobrir quem se conectou a uma máquina remota, leia o log do servidor SSH nessa máquina, onde um login do Desktop se parece com um de um terminal. Com o Desktop no macOS ou no Linux, espere uma entrada cada vez que o Desktop se conecta, e não uma para cada sessão.1441Para descobrir quem se conectou a uma máquina remota, leia o log do servidor SSH nessa máquina, onde um login do Desktop se parece com um de um terminal. Com o Desktop no macOS ou no Linux, espere uma entrada cada vez que o Desktop se conecta, e não uma para cada sessão.

1413 1442 

1443Se o servidor define `MaxSessions 1`, espere pelo menos duas entradas cada vez que o Desktop se conecta ou reconecta. Espere pelo menos mais uma para cada aba de terminal e para cada sessão do Desktop em que você executa comandos que começam com `!`.

1444 

1414Você não encontrará as conexões SSH do Desktop nas [métricas e eventos](https://code.claude.com/docs/pt/monitoring-usage.md#available-metrics-and-events) do Claude Code. Para descobrir a partir deles em qual máquina remota uma sessão SSH executou, consulte [Atribuir telemetria a sessões SSH do Desktop](https://code.claude.com/docs/pt/monitoring-usage.md#attribute-telemetry-to-desktop-ssh-sessions). Para o registro do próprio Desktop sobre suas conexões, consulte [Obter os logs do Desktop para um problema de SSH](#get-desktops-logs-for-an-ssh-problem).1445Você não encontrará as conexões SSH do Desktop nas [métricas e eventos](https://code.claude.com/docs/pt/monitoring-usage.md#available-metrics-and-events) do Claude Code. Para descobrir a partir deles em qual máquina remota uma sessão SSH executou, consulte [Atribuir telemetria a sessões SSH do Desktop](https://code.claude.com/docs/pt/monitoring-usage.md#attribute-telemetry-to-desktop-ssh-sessions). Para o registro do próprio Desktop sobre suas conexões, consulte [Obter os logs do Desktop para um problema de SSH](#get-desktops-logs-for-an-ssh-problem).

1415 1446 

1416#### Conexões que fecham antes do login1447#### Conexões que fecham antes do login


2112| - | - | - |2143| - | - | - |

2113| `<host>'s SSH server has SFTP turned off` | `[SFTP_UNAVAILABLE]` | Ative o SFTP no `sshd_config` do servidor, conforme descrito em [requisitos da máquina remota](#remote-machine-requirements-for-ssh-sessions) |2144| `<host>'s SSH server has SFTP turned off` | `[SFTP_UNAVAILABLE]` | Ative o SFTP no `sshd_config` do servidor, conforme descrito em [requisitos da máquina remota](#remote-machine-requirements-for-ssh-sessions) |

2114| `SFTP doesn't start on <host>` | `[SFTP_NOT_STARTED]` | Conecte-se ao mesmo host com `sftp` em um terminal no seu computador para ver o que o impede e, em seguida, verifique as configurações e os arquivos que a mensagem do Desktop menciona |2145| `SFTP doesn't start on <host>` | `[SFTP_NOT_STARTED]` | Conecte-se ao mesmo host com `sftp` em um terminal no seu computador para ver o que o impede e, em seguida, verifique as configurações e os arquivos que a mensagem do Desktop menciona |

2115| `<host> allows too few SSH sessions per connection` | `[SESSION_LIMIT]` | Aumente `MaxSessions` no `sshd_config` do servidor, por exemplo para o padrão do OpenSSH, que é 10 |2146| `<host> allows too few SSH sessions per connection` | `[SESSION_LIMIT]` | Atualize para o Claude Desktop v3.1623.0 ou posterior, ou aumente `MaxSessions` no `sshd_config` do servidor, por exemplo para o padrão do OpenSSH, que é 10 |

2116| `<host> is out of disk space` | `[ENOSPC]` ou `[EDQUOT]` | Libere espaço ou cota na máquina remota, no seu diretório pessoal ou em `/tmp` |2147| `<host> is out of disk space` | `[ENOSPC]` ou `[EDQUOT]` | Libere espaço ou cota na máquina remota, no seu diretório pessoal ou em `/tmp` |

2117| `Free up disk space on this computer` | `[ENOSPC]` ou `[EDQUOT]`, em uma mensagem que começa com `Couldn't prepare the deploy locally` | Libere espaço no seu computador |2148| `Free up disk space on this computer` | `[ENOSPC]` ou `[EDQUOT]`, em uma mensagem que começa com `Couldn't prepare the deploy locally` | Libere espaço no seu computador |

2118| `Claude Code won't start on <host>` | `[CLI_UNRESPONSIVE]` | Aguarde um minuto e tente novamente. Se continuar falhando, execute na máquina remota o comando que a mensagem menciona para ver se o Claude Code responde lá. |2149| `Claude Code won't start on <host>` | `[CLI_UNRESPONSIVE]` | Aguarde um minuto e tente novamente. Se continuar falhando, execute na máquina remota o comando que a mensagem menciona para ver se o Claude Code responde lá. |

errors.md +2 −0

Details

327| `Cannot read this as an image: <path> is a pipe or a device` | [Tool errors](#file-is-too-large-to-read-as-an-image) |327| `Cannot read this as an image: <path> is a pipe or a device` | [Tool errors](#file-is-too-large-to-read-as-an-image) |

328| `subagent_type is required: the general-purpose agent is not available in this session` | [Tool errors](#subagent-type-is-required) |328| `subagent_type is required: the general-purpose agent is not available in this session` | [Tool errors](#subagent-type-is-required) |

329| `Error: this write left the memory index at MEMORY.md at ..., over its ... read limit` | [Tool errors](#memory-index-is-over-its-read-limit) |329| `Error: this write left the memory index at MEMORY.md at ..., over its ... read limit` | [Tool errors](#memory-index-is-over-its-read-limit) |

330| `Sandbox is required but failed to initialize: <reason>` | [Solução de problemas de sandboxing](https://code.claude.com/docs/pt/sandboxing.md#commands-refused-with-sandbox-is-required) |

331| `Sandbox is required (sandbox.failIfUnavailable) and stopped being available in this session: <reason>` | [Solução de problemas de sandboxing](https://code.claude.com/docs/pt/sandboxing.md#commands-refused-with-sandbox-is-required) |

330| `pkill: refusing to run` | [Tool errors](#pkill-pattern-matches-the-claude-code-process) |332| `pkill: refusing to run` | [Tool errors](#pkill-pattern-matches-the-claude-code-process) |

331| `Failed to write to <name>'s inbox — nothing was sent` | [Tool errors](#failed-to-write-to-a-teammate-inbox) |333| `Failed to write to <name>'s inbox — nothing was sent` | [Tool errors](#failed-to-write-to-a-teammate-inbox) |

332| `Failed to write the plan approval request to the lead's inbox — plan not submitted` | [Tool errors](#failed-to-write-to-a-teammate-inbox) |334| `Failed to write the plan approval request to the lead's inbox — plan not submitted` | [Tool errors](#failed-to-write-to-a-teammate-inbox) |

fast-mode.md +2 −2

Details

80 80 

81O preço do modo rápido é fixo em toda a janela de contexto de 1M token. Para a taxa padrão do Opus para comparar, consulte a [referência de preços do Claude](https://platform.claude.com/docs/pt/about-claude/pricing).81O preço do modo rápido é fixo em toda a janela de contexto de 1M token. Para a taxa padrão do Opus para comparar, consulte a [referência de preços do Claude](https://platform.claude.com/docs/pt/about-claude/pricing).

82 82 

83A primeira vez que você ativa o modo rápido em uma conversa, você paga o preço total do token de entrada não armazenado em cache do modo rápido para todo o contexto da conversa. Quanto mais profundo você estiver em uma conversa, mais isso custa, portanto a cobrança é menor quando você ativa o modo rápido no início. O custo se aplica uma vez por conversa, portanto desativar e ativar o modo rápido novamente mais tarde não o repete. Para o mecanismo, consulte [como o modo rápido interage com o cache de prompt](https://code.claude.com/docs/pt/prompt-caching.md#turning-on-fast-mode).83A primeira vez que você ativa o modo rápido em uma conversa, você paga o preço total do token de entrada não armazenado em cache do modo rápido para todo o contexto da conversa. Quanto mais profundo você estiver em uma conversa, mais isso custa, portanto a cobrança é menor quando você ativa o modo rápido no início. O modo rápido e a velocidade padrão mantêm [caches separados](https://code.claude.com/docs/pt/prompt-caching.md#turning-on-fast-mode), portanto cada alternância posterior lê parte ou toda a conversa novamente sem cache.

84 84 

85### Veja onde o gasto do modo rápido aparece85### Veja onde o gasto do modo rápido aparece

86 86 


167 167 

168Atrás de um gateway, verifique estas configurações, nas quais Claude Code não envia a verificação de disponibilidade e não tem nenhuma verificação bem-sucedida anterior em cache:168Atrás de um gateway, verifique estas configurações, nas quais Claude Code não envia a verificação de disponibilidade e não tem nenhuma verificação bem-sucedida anterior em cache:

169 169 

170* Você aponta `ANTHROPIC_BASE_URL` para seu gateway e define [`ANTHROPIC_API_KEY`](https://code.claude.com/docs/pt/llm-gateway-connect#set-the-base-url-and-credential) como uma chave emitida pelo gateway que não está no formato de uma chave de API Anthropic. Claude Code não envia essa chave para `api.anthropic.com`.170* Você aponta `ANTHROPIC_BASE_URL` para seu gateway e define [`ANTHROPIC_API_KEY`](https://code.claude.com/docs/pt/llm-gateway-connect#set-the-base-url-and-credential) como uma chave emitida pelo gateway que não está no formato de uma chave de API Anthropic.

171* Você define [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](https://code.claude.com/docs/pt/env-vars), então Claude Code pula a verificação.171* Você define [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](https://code.claude.com/docs/pt/env-vars), então Claude Code pula a verificação.

172 172 

173Para restaurar o modo rápido em qualquer uma dessas configurações, defina `CLAUDE_CODE_SKIP_FAST_MODE_NETWORK_ERRORS=1`.173Para restaurar o modo rápido em qualquer uma dessas configurações, defina `CLAUDE_CODE_SKIP_FAST_MODE_NETWORK_ERRORS=1`.

Details

262 262 

263**Custo de contexto:** Baixo até ser usado. Skills apenas de usuário têm custo zero até invocação.263**Custo de contexto:** Baixo até ser usado. Skills apenas de usuário têm custo zero até invocação.

264 264 

265**Em subagents:** Skills funcionam diferentemente em subagents. Em vez de carregamento sob demanda, skills listadas no campo `skills` do subagent são totalmente pré-carregadas em seu contexto no lançamento. Subagents ainda podem descobrir e invocar skills de projeto, usuário e plugin não listadas através da ferramenta Skill.265**Em subagents:** O conteúdo completo das skills listadas no campo `skills` de um subagent [carrega em seu contexto no lançamento](https://code.claude.com/docs/pt/sub-agents.md#preload-skills-into-subagents), em vez de sob demanda. Subagents ainda podem descobrir e invocar skills de projeto, usuário e plugin não listadas através da ferramenta Skill.

266 266 

267> [!TIP]267> [!TIP]

268>268>

glossary.md +2 −2

Details

120 120 

121### Compaction121### Compaction

122 122 

123Sumarização automática de sua conversa quando a [context window](#context-window) se aproxima de seu limite. Saídas de tool mais antigas são limpas primeiro, depois a conversa é sumarizada. CLAUDE.md na raiz do projeto e auto memory sobrevivem a compaction e recarregam do disco; instruções dadas apenas em conversa podem ser perdidas. Execute `/compact` para disparar manualmente, opcionalmente com um foco como `/compact focus on the API changes`.123Sumarização automática de sua conversa quando a [janela de contexto](#context-window) se aproxima de seu limite. CLAUDE.md na raiz do projeto e a memória automática sobrevivem à compactação, mas instruções dadas apenas na conversa podem não sobreviver. Execute `/compact` para disparar manualmente, opcionalmente com um foco como `/compact focus on the API changes`.

124 124 

125Saiba mais: [What survives compaction](https://code.claude.com/docs/pt/context-window.md#what-survives-compaction) · [When context fills up](https://code.claude.com/docs/pt/how-claude-code-works.md#when-context-fills-up)125Saiba mais: [O que sobrevive à compactação](https://code.claude.com/docs/pt/context-window.md#what-survives-compaction) · [Quando o contexto se enche](https://code.claude.com/docs/pt/how-claude-code-works.md#when-context-fills-up) · [Quando o Claude Code compacta uma conversa que você deixa ociosa](https://code.claude.com/docs/pt/settings-reference.md#idlecompaction)

126 126 

127### Connector127### Connector

128 128 

hooks.md +15 −5

Details

1426 1426 

1427Os hooks Setup não podem bloquear; a execução continua com qualquer código de saída. Em todos os códigos de saída, o Claude Code descarta os [campos de saída JSON](#json-output) de um hook Setup, como `systemMessage`, `continue` e `hookSpecificOutput.additionalContext`. Com `-p`, o stdout, o stderr e o código de saída de um hook Setup aparecem na saída da execução somente como [eventos `hook_response`](https://code.claude.com/docs/pt/headless#read-session-metadata) quando você inicia com `--output-format stream-json --verbose`.1427Os hooks Setup não podem bloquear; a execução continua com qualquer código de saída. Em todos os códigos de saída, o Claude Code descarta os [campos de saída JSON](#json-output) de um hook Setup, como `systemMessage`, `continue` e `hookSpecificOutput.additionalContext`. Com `-p`, o stdout, o stderr e o código de saída de um hook Setup aparecem na saída da execução somente como [eventos `hook_response`](https://code.claude.com/docs/pt/headless#read-session-metadata) quando você inicia com `--output-format stream-json --verbose`.

1428 1428 

1429Os hooks Setup têm acesso a `CLAUDE_ENV_FILE`. As variáveis gravadas nesse arquivo persistem nos comandos Bash subsequentes da sessão, como nos [hooks SessionStart](#persist-environment-variables). Somente hooks `type: "command"` são executados no `Setup`. Um hook `type: "mcp_tool"` no `Setup` é sempre ignorado, conforme descrito em [Campos de hook de ferramenta MCP](#mcp-tool-hook-fields).1429Os hooks Setup têm acesso a `CLAUDE_ENV_FILE`. Se o seu hook gravar variáveis nesse arquivo, elas persistem nos comandos Bash subsequentes da sessão, como nos [hooks SessionStart](#persist-environment-variables). Somente hooks `type: "command"` são executados no `Setup`. Um hook `type: "mcp_tool"` no `Setup` é sempre ignorado, conforme descrito em [Campos de hook de ferramenta MCP](#mcp-tool-hook-fields).

1430 1430 

1431### InstructionsLoaded1431### InstructionsLoaded

1432 1432 


1483 1483 

1484Um [hook de callback do Agent SDK](https://code.claude.com/docs/pt/agent-sdk/hooks.md) em `UserPromptSubmit` que atinge seu timeout bloqueia o prompt com uma mensagem indicando o hook e o timeout, porque um callback ali pode estar atuando como um controle de política que não deve falhar de forma permissiva. A sessão continua.1484Um [hook de callback do Agent SDK](https://code.claude.com/docs/pt/agent-sdk/hooks.md) em `UserPromptSubmit` que atinge seu timeout bloqueia o prompt com uma mensagem indicando o hook e o timeout, porque um callback ali pode estar atuando como um controle de política que não deve falhar de forma permissiva. A sessão continua.

1485 1485 

1486#### `Esc` durante uma verificação de prompt

1487 

1488Se você pressionar `Esc` ou interromper a sessão enquanto os hooks ainda estão verificando um prompt, a verificação para e o prompt não chega ao Claude. O texto que você digitou no terminal retorna à entrada do prompt, e os hooks o verificam novamente quando você o reenviar.

1489 

1490Um hook pode bloquear o prompt no mesmo momento em que você interrompe. O prompt então permanece bloqueado: você vê a [mensagem de bloqueio](#what-a-blocked-prompt-leaves-behind) desse hook, e o texto não retorna à entrada.

1491 

1486#### Entrada do UserPromptSubmit1492#### Entrada do UserPromptSubmit

1487 1493 

1488Além dos [campos de entrada comuns](#common-input-fields), os hooks UserPromptSubmit recebem o campo `prompt` contendo o texto enviado. Conteúdo colado que foi recolhido em um marcador `[Pasted text #N]` chega expandido no lugar. Em sessões em que o Claude Code [marca texto colado para o Claude](https://code.claude.com/docs/pt/terminal-config.md#how-claude-treats-pasted-text), esse conteúdo expandido fica entre uma linha `<pasted_content id="…">` e uma linha `</pasted_content id="…">`, portanto leve essas linhas em conta se o seu hook analisar o prompt.1494Além dos [campos de entrada comuns](#common-input-fields), os hooks UserPromptSubmit recebem o campo `prompt` contendo o texto enviado. Conteúdo colado que foi recolhido em um marcador `[Pasted text #N]` chega expandido no lugar. Em sessões em que o Claude Code [marca texto colado para o Claude](https://code.claude.com/docs/pt/terminal-config.md#how-claude-treats-pasted-text), esse conteúdo expandido fica entre uma linha `<pasted_content id="…">` e uma linha `</pasted_content id="…">`, portanto leve essas linhas em conta se o seu hook analisar o prompt.


1741 1747 

1742Use o [controle de decisão do PreToolUse](#pretooluse-decision-control) para permitir, negar, perguntar ou adiar a chamada de ferramenta.1748Use o [controle de decisão do PreToolUse](#pretooluse-decision-control) para permitir, negar, perguntar ou adiar a chamada de ferramenta.

1743 1749 

1744Um [hook de callback do Agent SDK](https://code.claude.com/docs/pt/agent-sdk/hooks.md) em `PreToolUse` que excede seu timeout bloqueia a chamada de ferramenta, e o Claude recebe um resultado de erro indicando o timeout.1750Um [hook de callback do Agent SDK](https://code.claude.com/docs/pt/agent-sdk/hooks.md#hook-timeout) em `PreToolUse` que excede seu timeout bloqueia a chamada de ferramenta.

1745 1751 

1746#### Entrada do PreToolUse1752#### Entrada do PreToolUse

1747 1753 


2970 2976 

2971É executado quando um comando de shell na conversa principal altera o diretório de trabalho, por exemplo quando o Claude executa um comando `cd`. Use-o para reagir a mudanças de diretório: recarregar variáveis de ambiente, ativar toolchains específicas do projeto ou executar scripts de configuração automaticamente. Combina com [FileChanged](#filechanged) para ferramentas como o [direnv](https://direnv.net/), que gerenciam o ambiente por diretório.2977É executado quando um comando de shell na conversa principal altera o diretório de trabalho, por exemplo quando o Claude executa um comando `cd`. Use-o para reagir a mudanças de diretório: recarregar variáveis de ambiente, ativar toolchains específicas do projeto ou executar scripts de configuração automaticamente. Combina com [FileChanged](#filechanged) para ferramentas como o [direnv](https://direnv.net/), que gerenciam o ambiente por diretório.

2972 2978 

2973Os hooks CwdChanged têm acesso a [`CLAUDE_ENV_FILE`](#persist-environment-variables). As variáveis gravadas nesse arquivo persistem nos comandos Bash subsequentes até o próximo evento CwdChanged, quando o Claude Code as limpa.2979Hooks CwdChanged têm acesso a [`CLAUDE_ENV_FILE`](#persist-environment-variables). Se seu hook gravar variáveis nesse arquivo, elas persistem nos comandos Bash subsequentes até o próximo evento CwdChanged, quando o Claude Code as limpa.

2974 2980 

2975O CwdChanged não suporta matchers e é disparado em todas as ocorrências.2981O CwdChanged não suporta matchers e é disparado em todas as ocorrências.

2976 2982 


3135* O Claude Code isola uma [sessão em segundo plano](https://code.claude.com/docs/pt/agent-view.md#how-file-edits-are-isolated) em seu próprio worktree3141* O Claude Code isola uma [sessão em segundo plano](https://code.claude.com/docs/pt/agent-view.md#how-file-edits-are-isolated) em seu próprio worktree

3136* [`claude remote-control`](https://code.claude.com/docs/pt/remote-control#start-a-remote-control-session) no modo `worktree` inicia uma sessão em seu próprio worktree3142* [`claude remote-control`](https://code.claude.com/docs/pt/remote-control#start-a-remote-control-session) no modo `worktree` inicia uma sessão em seu próprio worktree

3137 3143 

3138Quando o Claude executa `git worktree add` por meio da ferramenta Bash em vez de chamar `EnterWorktree`, o seu hook WorktreeCreate não é executado. Para inspecionar ou bloquear esse comando, adicione um hook [`PreToolUse`](#pretooluse) com o matcher `Bash`.3144Um hook WorktreeCreate não é executado para um worktree que o Claude adiciona via Bash, e o hook de um plugin não é executado para aquele criado quando você inicia com `--worktree` e [`--tmux`](https://code.claude.com/docs/pt/cli-reference#cli-flags):

3145 

3146* **`git worktree add` via Bash**: para inspecionar ou bloquear esse comando, adicione um hook [`PreToolUse`](#pretooluse) com o matcher `Bash`.

3147* **`--worktree` com `--tmux`**: o Claude Code cria o worktree antes de carregar os plugins, então um hook WorktreeCreate de um plugin não é executado. Para que seu hook seja executado com ambas as flags, defina-o em um [arquivo de configurações](#configuration). Antes da v2.1.300, o hook WorktreeCreate de um plugin também não era executado apenas com `--worktree`.

3139 3148 

3140Por padrão, o Claude Code cria a cópia de trabalho isolada com `git worktree`. Configurar um hook WorktreeCreate substitui esse comportamento padrão do git, permitindo que você use um sistema de controle de versão diferente, como SVN, Perforce ou Mercurial.3149Por padrão, o Claude Code cria a cópia de trabalho isolada com `git worktree`. Configurar um hook WorktreeCreate substitui esse comportamento padrão do git, permitindo que você use um sistema de controle de versão diferente, como SVN, Perforce ou Mercurial.

3141 3150 


4077 4086 

4078Quando um hook assíncrono dispara, Claude Code inicia o processo do hook e imediatamente continua sem esperar que termine. O hook recebe a mesma entrada JSON via stdin que um hook síncrono.4087Quando um hook assíncrono dispara, Claude Code inicia o processo do hook e imediatamente continua sem esperar que termine. O hook recebe a mesma entrada JSON via stdin que um hook síncrono.

4079 4088 

4080Apó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ê.4089Apó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, exceto para [saída repetida de `SessionStart`](#limitations). Diferentemente de um `systemMessage` de hook síncrono, nenhum dos dois campos é mostrado para você.

4081 4090 

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

4083 4092 


4145 4154 

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

4147* Cada execução cria um processo em background separado.4156* Cada execução cria um processo em background separado.

4157* Um hook `SessionStart` assíncrono é executado toda vez que o evento dispara. Claude Code ignora a saída do hook quando o texto de `additionalContext` e `systemMessage` corresponde ao que Claude recebeu por último desse hook, a menos que um hook `SessionStart` síncrono tenha adicionado outro texto desde então. Claude Code entrega o texto quando ele muda, e novamente na próxima vez que o hook for executado após uma compactação ou `/clear`. Antes da v2.1.295, Claude Code adicionava o mesmo texto à conversa novamente a cada retomada.

4148 4158 

4149## Considerações de segurança4159## Considerações de segurança

4150 4160 

hooks-guide.md +1 −1

Details

954* Hooks `PostToolUse` não podem desfazer ações já que a ferramenta já foi executada.954* Hooks `PostToolUse` não podem desfazer ações já que a ferramenta já foi executada.

955* Hooks [`PermissionRequest`](https://code.claude.com/docs/pt/hooks#permissionrequest) disparam quando Claude Code está prestes a pedir permissão a você, ou quando, caso contrário, negaria automaticamente uma chamada que não pode pedir confirmação. Em [modo não interativo](https://code.claude.com/docs/pt/headless.md) com a flag `-p`, eles ainda são executados fora do [modo `dontAsk`](https://code.claude.com/docs/pt/permission-modes#allow-only-pre-approved-tools-with-dontask-mode), e uma chamada sobre a qual nenhum hook decide e que nada mais pode responder é negada.955* Hooks [`PermissionRequest`](https://code.claude.com/docs/pt/hooks#permissionrequest) disparam quando Claude Code está prestes a pedir permissão a você, ou quando, caso contrário, negaria automaticamente uma chamada que não pode pedir confirmação. Em [modo não interativo](https://code.claude.com/docs/pt/headless.md) com a flag `-p`, eles ainda são executados fora do [modo `dontAsk`](https://code.claude.com/docs/pt/permission-modes#allow-only-pre-approved-tools-with-dontask-mode), e uma chamada sobre a qual nenhum hook decide e que nada mais pode responder é negada.

956* Hooks `Stop` disparam sempre que Claude termina de responder, não apenas na conclusão de tarefas. Eles não disparam em interrupções do usuário. Erros de API disparam [StopFailure](https://code.claude.com/docs/pt/hooks.md#stopfailure) em vez disso.956* Hooks `Stop` disparam sempre que Claude termina de responder, não apenas na conclusão de tarefas. Eles não disparam em interrupções do usuário. Erros de API disparam [StopFailure](https://code.claude.com/docs/pt/hooks.md#stopfailure) em vez disso.

957* Quando múltiplos hooks `PreToolUse` retornam [`updatedInput`](https://code.claude.com/docs/pt/hooks#pretooluse) para reescrever argumentos de uma ferramenta, o último a terminar vence. Como hooks executam em paralelo, a ordem é não-determinística. Evite ter mais de um hook modificando a entrada da mesma ferramenta.957* Quando múltiplos hooks `PreToolUse` retornam [`updatedInput`](https://code.claude.com/docs/pt/hooks#pretooluse) para reescrever a entrada de uma ferramenta, Claude Code não mescla as reescritas nem garante com qual reescrita a ferramenta será executada. Evite ter mais de um hook reescrevendo a entrada da mesma ferramenta.

958 958 

959### Hooks e modos de permissão959### Hooks e modos de permissão

960 960 

Details

131 131 

132#### Quando o contexto se enche132#### Quando o contexto se enche

133 133 

134Claude Code gerencia o contexto automaticamente conforme você se aproxima do limite. Ele limpa saídas de ferramentas mais antigas primeiro, depois resume a conversa se necessário. Suas solicitações e trechos de código-chave são preservados; instruções detalhadas do início da conversa podem ser perdidas. Coloque regras persistentes em CLAUDE.md em vez de confiar no histórico de conversa.134Claude Code gerencia o contexto automaticamente conforme você se aproxima do limite. Ele compacta a conversa em um resumo. O resumo mantém suas solicitações e trechos de código-chave, mas instruções detalhadas do início da conversa podem ser perdidas. Coloque regras persistentes em CLAUDE.md em vez de confiar no histórico de conversa.

135 135 

136Para controlar o que é preservado durante a compactação, adicione uma seção "Compact Instructions" a CLAUDE.md ou execute `/compact` com um foco (como `/compact focus on the API changes`).136Para controlar o que é preservado durante a compactação, adicione uma seção "Compact Instructions" a CLAUDE.md ou execute `/compact` com um foco (como `/compact focus on the API changes`).

137 137 

Details

659 659 

660Para reatribuir as teclas que rolam a lista de arquivos ou alteram a comparação, consulte [Ações do painel de diff](https://code.claude.com/docs/pt/keybindings.md#diff-panel-actions).660Para reatribuir as teclas que rolam a lista de arquivos ou alteram a comparação, consulte [Ações do painel de diff](https://code.claude.com/docs/pt/keybindings.md#diff-panel-actions).

661 661 

662Durante um merge, rebase, cherry-pick ou revert não concluído, o painel continua mostrando as alterações que leu do git por último, para que não se encha com as alterações recebidas da operação. Ele se atualiza na primeira atualização após o término da operação, por exemplo, quando Claude editar um arquivo novamente.

663 

662### Caixa de diálogo de diff664### Caixa de diálogo de diff

663 665 

664A caixa de diálogo de diff abre como um bloco com borda acima do prompt e lista seus arquivos alterados com suas contagens de linhas adicionadas e removidas. Ela os compara com `HEAD`, ou com o que você [escolheu por último no painel de diff](#diff-panel) para este repositório.666A caixa de diálogo de diff abre como um bloco com borda acima do prompt e lista seus arquivos alterados com suas contagens de linhas adicionadas e removidas. Ela os compara com `HEAD`, ou com o que você [escolheu por último no painel de diff](#diff-panel) para este repositório.

keybindings.md +4 −4

Details

678 678 

679## Interação com modo vim679## Interação com modo vim

680 680 

681Quando o modo vim está ativado via `/config` → Editor mode, atalhos de teclado e modo vim operam independentemente:681Quando você ativa o modo vim com a configuração Editor mode em `/config`, atalhos de teclado e modo vim operam independentemente:

682 682 

683* **Modo vim** manipula entrada no nível de entrada de texto (movimento do cursor, modos, motions)683* **Modo vim** manipula entrada no nível de entrada de texto: movimento do cursor, modos e motions

684* **Atalhos de teclado** manipulam ações no nível de componente (alternar tarefas, enviar, etc.)684* **Atalhos de teclado** manipulam ações no nível de componente, como alternar tarefas ou enviar uma mensagem

685* A tecla Escape no modo vim muda INSERT para NORMAL; ela não dispara `chat:cancel`685* A tecla Escape no modo vim muda do modo INSERT para o modo NORMAL; ela não dispara `chat:cancel`

686* A maioria dos atalhos Ctrl+key passam pelo modo vim para o sistema de atalhos de teclado686* A maioria dos atalhos Ctrl+key passam pelo modo vim para o sistema de atalhos de teclado

687* As chaves vim não são remapeáveis através do arquivo de atalhos de teclado. Para mapear uma sequência de dois-key no modo INSERT como `jj` para Escape, use a configuração [`vimInsertModeRemaps`](https://code.claude.com/docs/pt/interactive-mode#remap-insert-mode-key-sequences)687* As chaves vim não são remapeáveis através do arquivo de atalhos de teclado. Para mapear uma sequência de dois-key no modo INSERT como `jj` para Escape, use a configuração [`vimInsertModeRemaps`](https://code.claude.com/docs/pt/interactive-mode#remap-insert-mode-key-sequences)

688* No modo NORMAL do vim, `?` mostra o menu de ajuda (comportamento vim)688* No modo NORMAL do vim, `?` mostra o menu de ajuda (comportamento vim)

Details

306 306 

307## Adicione skills por diretório307## Adicione skills por diretório

308 308 

309Qualquer subdiretório pode definir [skills](https://code.claude.com/docs/pt/skills.md) escopo para sua própria pilha. Uma skill carrega sob demanda quando Claude determina que é relevante, então ferramentas específicas da API não consomem contexto durante trabalho frontend.309Qualquer subdiretório pode definir [skills](https://code.claude.com/docs/pt/skills.md) com escopo restrito à sua própria pilha. Uma skill carrega sob demanda quando Claude determina que é relevante.

310 310 

311As skills vivem sob `.claude/skills/` dentro do diretório. Confirme-as ao lado do código dessa área para que qualquer um que clone o repositório as obtenha. Em um monorepo isso pode ser um conjunto de skills por pacote. Em uma grande base de código de árvore única é um conjunto por subsistema como `src/db/.claude/skills/`.311As skills vivem sob `.claude/skills/` dentro do diretório. Confirme-as ao lado do código dessa área para que qualquer um que clone o repositório as obtenha. Em um monorepo isso pode ser um conjunto de skills por pacote. Em uma grande base de código de árvore única é um conjunto por subsistema como `src/db/.claude/skills/`.

312 312 


347- Mock de serviços externos em `src/__tests__/mocks/`347- Mock de serviços externos em `src/__tests__/mocks/`

348```348```

349 349 

350Um subdiretório diferente mantém diferentes skills da mesma maneira: `packages/web/.claude/skills/component-patterns/` descreve as convenções de componente do frontend em vez de teste. Quando Claude trabalha em um arquivo em `packages/api/`, ele carrega a skill api-testing. Quando trabalha em `packages/web/`, carrega component-patterns em vez disso. As skills de nenhum diretório carregam durante as tarefas do outro.350Um subdiretório diferente mantém diferentes skills da mesma maneira: `packages/web/.claude/skills/component-patterns/` descreve as convenções de componente do frontend em vez de teste. Quando Claude trabalha em um arquivo em `packages/api/`, ele carrega a skill api-testing. Quando trabalha em `packages/web/`, carrega component-patterns.

351 351 

352Você também pode restringir uma skill por padrão de arquivo em vez de por localização. O [campo frontmatter `paths`](https://code.claude.com/docs/pt/skills#frontmatter-reference) aceita padrões glob, e Claude carrega a skill automaticamente apenas quando trabalha com arquivos correspondentes. Use isso para uma skill que vive no `.claude/skills/` da raiz do repositório mas se aplica apenas a certos arquivos, como uma skill de migração de banco de dados restrita a `**/migrations/**`.352Você também pode restringir uma skill por padrão de arquivo em vez de por localização. O [campo frontmatter `paths`](https://code.claude.com/docs/pt/skills#frontmatter-reference) aceita padrões glob, e Claude carrega a skill automaticamente apenas quando trabalha com arquivos correspondentes. Use isso para uma skill que vive no `.claude/skills/` da raiz do repositório mas se aplica apenas a certos arquivos, como uma skill de migração de banco de dados restrita a `**/migrations/**`.

353 353 

Details

520| Erros `400` em cada solicitação, nas próprias palavras do gateway rejeitando um tipo de ferramenta não reconhecido, como `Input tag 'advisor_20260301'`, em Claude Code v2.1.275 | Em um lançamento gradual nessa versão, as solicitações carregam uma entrada de [ferramenta advisor](https://code.claude.com/docs/pt/advisor.md) mesmo com o advisor desativado. A API Anthropic aceita, mas um gateway ou upstream que valida tipos de ferramenta rejeita toda a solicitação; um que [encaminha campos de corpo de solicitação inalterados](https://code.claude.com/docs/pt/llm-gateway-protocol.md#forward-as-open-lists) passa sem ser afetado. A entrada é uma declaração que não carrega conteúdo de conversa | Atualize para v2.1.276 ou posterior, que não envia a entrada atrás de um gateway `ANTHROPIC_BASE_URL` a menos que você ative o advisor. Em v2.1.275, defina [`CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1`](https://code.claude.com/docs/pt/env-vars), que remove a entrada das solicitações |520| Erros `400` em cada solicitação, nas próprias palavras do gateway rejeitando um tipo de ferramenta não reconhecido, como `Input tag 'advisor_20260301'`, em Claude Code v2.1.275 | Em um lançamento gradual nessa versão, as solicitações carregam uma entrada de [ferramenta advisor](https://code.claude.com/docs/pt/advisor.md) mesmo com o advisor desativado. A API Anthropic aceita, mas um gateway ou upstream que valida tipos de ferramenta rejeita toda a solicitação; um que [encaminha campos de corpo de solicitação inalterados](https://code.claude.com/docs/pt/llm-gateway-protocol.md#forward-as-open-lists) passa sem ser afetado. A entrada é uma declaração que não carrega conteúdo de conversa | Atualize para v2.1.276 ou posterior, que não envia a entrada atrás de um gateway `ANTHROPIC_BASE_URL` a menos que você ative o advisor. Em v2.1.275, defina [`CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1`](https://code.claude.com/docs/pt/env-vars), que remove a entrada das solicitações |

521| Modelos faltando do seletor `/model` | Nomes de modelo de gateway não estão na lista integrada de Claude Code, ou Claude Code está mostrando um lineup [`modelPicker`](https://code.claude.com/docs/pt/settings-reference#modelpicker) que substitui as opções integradas | Ative [descoberta de modelo de gateway](#add-gateway-models-to-the-model-picker) ou adicione nomes com as variáveis de [configuração de modelo](https://code.claude.com/docs/pt/model-config.md). Se Claude Code mostrar um lineup `modelPicker` substituto, adicione os modelos de gateway a ele, ou peça ao seu administrador para adicioná-los quando as configurações gerenciadas o fornecerem |521| Modelos faltando do seletor `/model` | Nomes de modelo de gateway não estão na lista integrada de Claude Code, ou Claude Code está mostrando um lineup [`modelPicker`](https://code.claude.com/docs/pt/settings-reference#modelpicker) que substitui as opções integradas | Ative [descoberta de modelo de gateway](#add-gateway-models-to-the-model-picker) ou adicione nomes com as variáveis de [configuração de modelo](https://code.claude.com/docs/pt/model-config.md). Se Claude Code mostrar um lineup `modelPicker` substituto, adicione os modelos de gateway a ele, ou peça ao seu administrador para adicioná-los quando as configurações gerenciadas o fornecerem |

522| `/fast` relata `Fast mode unavailable due to network connectivity issues` enquanto as requisições de inferência funcionam | A verificação de disponibilidade do [modo rápido](https://code.claude.com/docs/pt/fast-mode.md) vai diretamente para `api.anthropic.com` e não segue `ANTHROPIC_BASE_URL`, portanto a saída direta bloqueada falha na verificação | Adicione `api.anthropic.com` à allowlist se a saída estiver bloqueada, ou defina uma variável de skip. Consulte [usar modo rápido atrás de proxies e gateways LLM](https://code.claude.com/docs/pt/fast-mode.md#use-fast-mode-behind-proxies-and-llm-gateways) |522| `/fast` relata `Fast mode unavailable due to network connectivity issues` enquanto as requisições de inferência funcionam | A verificação de disponibilidade do [modo rápido](https://code.claude.com/docs/pt/fast-mode.md) vai diretamente para `api.anthropic.com` e não segue `ANTHROPIC_BASE_URL`, portanto a saída direta bloqueada falha na verificação | Adicione `api.anthropic.com` à allowlist se a saída estiver bloqueada, ou defina uma variável de skip. Consulte [usar modo rápido atrás de proxies e gateways LLM](https://code.claude.com/docs/pt/fast-mode.md#use-fast-mode-behind-proxies-and-llm-gateways) |

523| `/fast` relata `Fast mode is currently unavailable` em uma sessão que se autentica com uma chave emitida pelo gateway em `ANTHROPIC_API_KEY` | Enquanto `ANTHROPIC_BASE_URL` aponta para seu gateway, Claude Code não envia para `api.anthropic.com` uma chave que não esteja no formato de uma chave de API Anthropic. A verificação de disponibilidade do [modo rápido](https://code.claude.com/docs/pt/fast-mode.md) então não é enviada e, sem uma verificação anterior bem-sucedida em cache, Claude Code trata o modo rápido como indisponível | Defina `CLAUDE_CODE_SKIP_FAST_MODE_NETWORK_ERRORS=1`; consulte [usar modo rápido atrás de proxies e gateways LLM](https://code.claude.com/docs/pt/fast-mode.md#use-fast-mode-behind-proxies-and-llm-gateways) |523| `/fast` relata `Fast mode is currently unavailable` em uma sessão que se autentica com uma chave emitida pelo gateway em `ANTHROPIC_API_KEY` | Enquanto `ANTHROPIC_BASE_URL` aponta para seu gateway e a chave não está no formato de uma chave de API Anthropic, Claude Code não envia a verificação de disponibilidade do [modo rápido](https://code.claude.com/docs/pt/fast-mode.md). Sem uma verificação anterior bem-sucedida em cache, ele trata o modo rápido como indisponível | Defina `CLAUDE_CODE_SKIP_FAST_MODE_NETWORK_ERRORS=1`; consulte [usar modo rápido atrás de proxies e gateways LLM](https://code.claude.com/docs/pt/fast-mode.md#use-fast-mode-behind-proxies-and-llm-gateways) |

524| `/fast` relata `Fast mode has been disabled by your organization` em uma sessão autenticada com `ANTHROPIC_AUTH_TOKEN`, mesmo que a organização tenha modo rápido ativado | A verificação de disponibilidade requer um login claude.ai ou uma chave de API; com apenas um token de portador, Claude Code trata o modo rápido como desativado sem enviar a verificação | Defina `CLAUDE_CODE_SKIP_FAST_MODE_ORG_CHECK=1`; consulte [usar modo rápido atrás de proxies e gateways LLM](https://code.claude.com/docs/pt/fast-mode.md#use-fast-mode-behind-proxies-and-llm-gateways) |524| `/fast` relata `Fast mode has been disabled by your organization` em uma sessão autenticada com `ANTHROPIC_AUTH_TOKEN`, mesmo que a organização tenha modo rápido ativado | A verificação de disponibilidade requer um login claude.ai ou uma chave de API; com apenas um token de portador, Claude Code trata o modo rápido como desativado sem enviar a verificação | Defina `CLAUDE_CODE_SKIP_FAST_MODE_ORG_CHECK=1`; consulte [usar modo rápido atrás de proxies e gateways LLM](https://code.claude.com/docs/pt/fast-mode.md#use-fast-mode-behind-proxies-and-llm-gateways) |

525| Claude Code pede para você fazer login mesmo que o [teste curl](#verify-the-connection) tenha sucesso | O CLI não tem credencial própria: uma URL base alcançável não é uma, e em uma sessão interativa um bloco `env` no `.claude/settings.json` ou `.claude/settings.local.json` de um projeto se aplica apenas após o assistente de primeira execução e [prompt de confiança](https://code.claude.com/docs/pt/permissions.md#what-runs-before-you-trust-a-folder) | Defina `ANTHROPIC_AUTH_TOKEN` em algum lugar que Claude Code leia antes da configuração de primeira execução: uma exportação de shell, o bloco `env` em `~/.claude/settings.json` ou configurações gerenciadas |525| Claude Code pede para você fazer login mesmo que o [teste curl](#verify-the-connection) tenha sucesso | O CLI não tem credencial própria: uma URL base alcançável não é uma, e em uma sessão interativa um bloco `env` no `.claude/settings.json` ou `.claude/settings.local.json` de um projeto se aplica apenas após o assistente de primeira execução e [prompt de confiança](https://code.claude.com/docs/pt/permissions.md#what-runs-before-you-trust-a-folder) | Defina `ANTHROPIC_AUTH_TOKEN` em algum lugar que Claude Code leia antes da configuração de primeira execução: uma exportação de shell, o bloco `env` em `~/.claude/settings.json` ou configurações gerenciadas |

526| `ANTHROPIC_API_KEY` está definido mas ignorado, sem prompt | A chave precisa de uma aprovação única em sessões interativas, e uma chave previamente recusada é ignorada sem perguntar novamente | Ative-a em `/config` com a opção `Use custom API key` |526| `ANTHROPIC_API_KEY` está definido mas ignorado, sem prompt | A chave precisa de uma aprovação única em sessões interativas, e uma chave previamente recusada é ignorada sem perguntar novamente | Ative-a em `/config` com a opção `Use custom API key` |

Details

148| :- | :- |148| :- | :- |

149| `x-claude-code-request-class` | Que tipo de solicitação é esta: `main` para uma volta da conversa principal, `subagent` para uma volta de um [subagente](https://code.claude.com/docs/pt/sub-agents.md), `workflow` para um agente executando dentro de um workflow, `compaction` para a solicitação de resumo que compacta uma conversa, ou `auxiliary` para solicitações laterais como títulos de sessão, classificadores e resumos. Enviado em cada solicitação |149| `x-claude-code-request-class` | Que tipo de solicitação é esta: `main` para uma volta da conversa principal, `subagent` para uma volta de um [subagente](https://code.claude.com/docs/pt/sub-agents.md), `workflow` para um agente executando dentro de um workflow, `compaction` para a solicitação de resumo que compacta uma conversa, ou `auxiliary` para solicitações laterais como títulos de sessão, classificadores e resumos. Enviado em cada solicitação |

150| `x-claude-code-agent-type` | O tipo de subagente que emitiu a solicitação: um nome de tipo de agente integrado como `Explore`, `Plan` ou `general-purpose`, ou `custom` para um agente definido pelo usuário, `teammate` para um membro da [equipe de agentes](https://code.claude.com/docs/pt/agent-teams.md) executando no processo do líder, ou `fork` para um [fork](https://code.claude.com/docs/pt/sub-agents.md#fork-the-current-conversation). Presente apenas nas próprias voltas de um subagente; solicitações de compactação ou laterais de um subagente mantêm o ID do agente mas não carregam tipo. Um nome de agente escolhido pelo usuário nunca é enviado |150| `x-claude-code-agent-type` | O tipo de subagente que emitiu a solicitação: um nome de tipo de agente integrado como `Explore`, `Plan` ou `general-purpose`, ou `custom` para um agente definido pelo usuário, `teammate` para um membro da [equipe de agentes](https://code.claude.com/docs/pt/agent-teams.md) executando no processo do líder, ou `fork` para um [fork](https://code.claude.com/docs/pt/sub-agents.md#fork-the-current-conversation). Presente apenas nas próprias voltas de um subagente; solicitações de compactação ou laterais de um subagente mantêm o ID do agente mas não carregam tipo. Um nome de agente escolhido pelo usuário nunca é enviado |

151| `x-claude-code-compaction` | Presente na requisição que resume a conversa durante uma [compactação](https://code.claude.com/docs/pt/prompt-caching.md#compacting-the-conversation). O valor diz o que a acionou: `auto` quando a janela de contexto se aproximava da capacidade, `manual` para `/compact`, ou `reactive` quando a API rejeitou uma requisição como muito longa. O valor também é `auto` para [compactação por inatividade](https://code.claude.com/docs/pt/settings-reference.md#idlecompaction). Ausente em todas as outras requisições |151| `x-claude-code-compaction` | Presente na requisição que resume a conversa durante uma [compactação](https://code.claude.com/docs/pt/prompt-caching.md#compacting-the-conversation). O valor diz o que a acionou: `auto` quando a janela de contexto se aproximava da capacidade, `manual` para `/compact`, ou `reactive` quando a API rejeitou uma requisição como muito longa. O valor também é `auto` para [compactação por inatividade](https://code.claude.com/docs/pt/settings-reference.md#idlecompaction) em uma sessão interativa de terminal. Ausente em todas as outras requisições, incluindo uma que escreve um resumo em segundo plano antes de uma compactação |

152| `x-claude-code-context-compacted` | Presente uma vez, na primeira solicitação de conversa principal após uma compactação, com os mesmos valores que `x-claude-code-compaction`. O prefixo de conversa antes desta solicitação não é mais usado, então um cache com chave nele pode ser descartado |152| `x-claude-code-context-compacted` | Presente uma vez, na primeira solicitação de conversa principal após uma compactação, com os mesmos valores que `x-claude-code-compaction`. O prefixo de conversa antes desta solicitação não é mais usado, então um cache com chave nele pode ser descartado |

153| `x-claude-code-prev-tool-durations` | Tempo de execução medido das chamadas de ferramenta cujos resultados esta solicitação carrega, como `<name>=<ms>;<name>=<ms>`, por exemplo `Bash=742;Read=9`. Enviado na próxima solicitação da mesma conversa após um lote de chamadas de ferramenta, da sessão principal ou de um subagente |153| `x-claude-code-prev-tool-durations` | Tempo de execução medido das chamadas de ferramenta cujos resultados esta solicitação carrega, como `<name>=<ms>;<name>=<ms>`, por exemplo `Bash=742;Read=9`. Enviado na próxima solicitação da mesma conversa após um lote de chamadas de ferramenta, da sessão principal ou de um subagente |

154| `x-claude-code-prompt-id` | UUID aleatório que identifica o prompt do usuário que uma solicitação serve. Solicitações servindo um prompt compartilham o valor, incluindo as voltas de subagentes que o prompt iniciou. Solicitações não atribuídas a um prompt o omitem. Use-o para agrupar as solicitações de uma sessão por prompt. Requer Claude Code v2.1.283 ou posterior |154| `x-claude-code-prompt-id` | UUID aleatório que identifica o prompt do usuário que uma solicitação serve. Solicitações servindo um prompt compartilham o valor, incluindo as voltas de subagentes que o prompt iniciou. Solicitações não atribuídas a um prompt o omitem. Use-o para agrupar as solicitações de uma sessão por prompt. Requer Claude Code v2.1.283 ou posterior |


238* Quando o upstream rejeita apenas o marcador `cache_control` em uma mensagem de sistema no meio da conversa, Claude Code mantém as mensagens de sistema e tenta novamente uma vez com o marcador movido. O marcador vai na última entrada em `messages` que não é uma mensagem de sistema, nessa nova tentativa e em requisições posteriores até Claude Code sair238* Quando o upstream rejeita apenas o marcador `cache_control` em uma mensagem de sistema no meio da conversa, Claude Code mantém as mensagens de sistema e tenta novamente uma vez com o marcador movido. O marcador vai na última entrada em `messages` que não é uma mensagem de sistema, nessa nova tentativa e em requisições posteriores até Claude Code sair

239* Quando o upstream rejeita uma [assinatura de pensamento](https://platform.claude.com/docs/en/build-with-claude/extended-thinking), incluindo com um `400` cuja mensagem diz que o bloco está `bound to a different conversation`, Claude Code remove blocos de pensamento anteriores da solicitação, tenta novamente, e os mantém fora de cada solicitação posterior. Novas respostas ainda incluem pensamento239* Quando o upstream rejeita uma [assinatura de pensamento](https://platform.claude.com/docs/en/build-with-claude/extended-thinking), incluindo com um `400` cuja mensagem diz que o bloco está `bound to a different conversation`, Claude Code remove blocos de pensamento anteriores da solicitação, tenta novamente, e os mantém fora de cada solicitação posterior. Novas respostas ainda incluem pensamento

240* Quando o gateway ou seu upstream rejeita a entrada da [ferramenta advisor](https://code.claude.com/docs/pt/advisor.md) em `tools` como um tipo de ferramenta não reconhecido, Claude Code tenta novamente a solicitação uma vez sem essa entrada e seu valor `anthropic-beta`. Solicitações posteriores para essa URL base deixam o advisor de fora até Claude Code sair, e `/advisor` fica indisponível para o desenvolvedor por esse tempo. Claude Code reconhece essa rejeição por uma resposta `400` ou `422` cuja mensagem nomeia o tipo de ferramenta após `Input tag`, como `Input tag 'advisor_20260301'`. Antes da v2.1.280, Claude Code não tentava novamente essa rejeição240* Quando o gateway ou seu upstream rejeita a entrada da [ferramenta advisor](https://code.claude.com/docs/pt/advisor.md) em `tools` como um tipo de ferramenta não reconhecido, Claude Code tenta novamente a solicitação uma vez sem essa entrada e seu valor `anthropic-beta`. Solicitações posteriores para essa URL base deixam o advisor de fora até Claude Code sair, e `/advisor` fica indisponível para o desenvolvedor por esse tempo. Claude Code reconhece essa rejeição por uma resposta `400` ou `422` cuja mensagem nomeia o tipo de ferramenta após `Input tag`, como `Input tag 'advisor_20260301'`. Antes da v2.1.280, Claude Code não tentava novamente essa rejeição

241* Quando o upstream rejeita `output_config.effort`, Claude Code tenta novamente a solicitação sem esforço e o deixa de fora de solicitações posteriores para esse modelo até Claude Code sair. Claude Code reconhece essa rejeição por um `400` cuja mensagem nomeia `output_config.effort` junto com `Extra inputs are not permitted`, ou diz que o modelo não suporta o parâmetro de esforço241* Quando o upstream rejeita `output_config.effort` ou seu valor `anthropic-beta`, Claude Code tenta novamente e não adiciona nenhum dos dois às requisições para esse modelo até Claude Code sair. Seu gateway não precisa de nenhuma alteração se encaminhar o `400` do upstream sem modificações e a mensagem:

242 * Nomear `output_config.effort` junto com `Extra inputs are not permitted`

243 * Disser que o modelo não suporta o parâmetro de esforço

244 * Começar com `Unexpected value(s)` e listar `effort-2025-11-24` para o header `anthropic-beta`. Requer v2.1.310 ou posterior. Desenvolvedores cujo [`ANTHROPIC_BETAS`](https://code.claude.com/docs/pt/env-vars) lista o valor continuam enviando-o e recebendo o `400`, então peça a eles que removam essa entrada

242* Quando o upstream rejeita o campo `context_management` ou seu valor `anthropic-beta`, o gateway vê a requisição mais uma vez sem eles. Se o gateway os vir novamente em uma requisição posterior e o upstream os rejeitar novamente, a mesma nova tentativa acontece. Claude Code reconhece essa rejeição por sua mensagem, por exemplo uma que contenha `context_management: Extra inputs are not permitted`. Antes da v2.1.304, Claude Code não tentava novamente essa rejeição245* Quando o upstream rejeita o campo `context_management` ou seu valor `anthropic-beta`, o gateway vê a requisição mais uma vez sem eles. Se o gateway os vir novamente em uma requisição posterior e o upstream os rejeitar novamente, a mesma nova tentativa acontece. Claude Code reconhece essa rejeição por sua mensagem, por exemplo uma que contenha `context_management: Extra inputs are not permitted`. Antes da v2.1.304, Claude Code não tentava novamente essa rejeição

243* Quando o upstream rejeita um campo de ferramenta beta diferente de `defer_loading`, como `strict`, o `400` chega ao desenvolvedor. Antes disso, o gateway pode ver a requisição novamente [sem os campos de busca de ferramentas](#retry-without-tool-search). Para deixar de enviar esses campos, peça aos desenvolvedores que definam [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`](#disable-pre-release-capabilities)246* Quando o upstream rejeita um campo de ferramenta beta diferente de `defer_loading`, como `strict`, o `400` chega ao desenvolvedor. Antes disso, o gateway pode ver a requisição novamente [sem os campos de busca de ferramentas](#retry-without-tool-search). Para deixar de enviar esses campos, peça aos desenvolvedores que definam [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`](#disable-pre-release-capabilities)

244 247 

Details

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

471 471 

472* **Você o definiu no computador que executa o Desktop**: o Desktop não passa para a sessão SSH um valor que você define ali472* **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

473* **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.473* **Você o exportou em `/etc/profile` ou em outro arquivo que somente shells de login leem**: o nome chega quando você executa `claude` a partir de um shell de login, mas não em uma sessão SSH do Desktop. O Desktop não inicia o Claude Code por meio de um shell de login. Em vez disso, defina a variável em `env` no [arquivo de configurações gerenciadas](https://code.claude.com/docs/pt/desktop.md#managed-settings) na máquina remota.

474* **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).474* **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).

475* **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](https://code.claude.com/docs/pt/settings-reference.md#how-env-values-interact-with-your-shell). O [log de depuração](https://code.claude.com/docs/pt/debug-your-config.md) 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.475* **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](https://code.claude.com/docs/pt/settings-reference.md#how-env-values-interact-with-your-shell). O [log de depuração](https://code.claude.com/docs/pt/debug-your-config.md) 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.

476 476 


1403* `pre_tokens`: Contagem aproximada de tokens antes da compactação1403* `pre_tokens`: Contagem aproximada de tokens antes da compactação

1404* `post_tokens`: Contagem aproximada de tokens após a compactação1404* `post_tokens`: Contagem aproximada de tokens após a compactação

1405* `error`: Mensagem de erro quando a compactação falhou1405* `error`: Mensagem de erro quando a compactação falhou

1406* `precompute_reuse`: Definido somente quando `trigger` é `"manual"` ou para uma [compactação por inatividade](https://code.claude.com/docs/pt/settings-reference.md#idlecompaction), que reporta `trigger` como `"auto"`. A compactação automática pode preparar um resumo em segundo plano antes que a janela de contexto fique cheia, e este atributo registra se a compactação reutilizou esse resumo preparado. `"hit"` significa que ele foi reutilizado; `"miss_custom_instructions"`, `"miss_hook"` e `"miss_not_ready"` indicam o motivo pelo qual um novo resumo foi calculado em vez disso1406* `precompute_reuse`: Definido apenas quando `trigger` é `"manual"`, ou quando `trigger` é `"auto"` para uma [compactação por inatividade](https://code.claude.com/docs/pt/settings-reference.md#idlecompaction) em uma sessão interativa no terminal. A compactação automática pode preparar um resumo em segundo plano antes que a janela de contexto se encha, e este atributo registra se a compactação reutilizou esse resumo preparado. `"hit"` significa que ele foi reutilizado; `"miss_custom_instructions"`, `"miss_hook"` e `"miss_not_ready"` indicam o motivo pelo qual um novo resumo foi calculado em vez disso

1407 1407 

1408#### Evento de subagente concluído1408#### Evento de subagente concluído

1409 1409 

Details

248 248 

249**Web and mobile**249**Web and mobile**

250 250 

251Em [claude.ai/code](https://claude.ai/code), use o dropdown de modo ao lado da caixa de prompt. No aplicativo móvel, toque no botão **+** na caixa de prompt e depois em **Permission**. Sessões na nuvem e sessões de Remote Control oferecem modos de permissão diferentes:251Em [claude.ai/code](https://claude.ai/code), use o dropdown de modo na linha abaixo da caixa de prompt. No aplicativo móvel, toque no botão **+** na caixa de prompt e depois em **Permission**. Sessões na nuvem e sessões de Remote Control oferecem modos de permissão diferentes:

252 252 

253* **[Sessões na nuvem](https://code.claude.com/docs/pt/claude-code-on-the-web.md)**: Accept edits, Plan e Auto. Accept edits corresponde ao modo `default`: sessões na nuvem pré-aprovam edições de arquivo independentemente do modo, então o dropdown mostra Accept edits em vez de Manual. Sessões na nuvem ainda honram `defaultMode: "acceptEdits"` de configurações. O modo Auto aparece apenas quando sua organização o permite e o modelo selecionado o suporta. Bypass permissions não está disponível.253* **[Sessões na nuvem](https://code.claude.com/docs/pt/claude-code-on-the-web.md)**: Accept edits, Plan e Auto. Accept edits corresponde ao modo `default`: sessões na nuvem pré-aprovam edições de arquivo independentemente do modo, então o dropdown mostra Accept edits em vez de Manual. Sessões na nuvem ainda honram `defaultMode: "acceptEdits"` de configurações. O modo Auto aparece apenas quando sua organização o permite e o modelo selecionado o suporta. Bypass permissions não está disponível.

254* **[Sessões de Remote Control](https://code.claude.com/docs/pt/remote-control.md)** em sua máquina local: Manual, Accept edits, Plan e Auto para uma sessão que você mesmo iniciou, e você não pode selecionar Bypass permissions do aplicativo. Para usar Auto, a sessão precisa atender aos [requisitos de disponibilidade](#eliminate-prompts-with-auto-mode) do modo auto. Para um thread de projeto executado em seu computador, veja [Execute um thread em seu próprio computador](https://code.claude.com/docs/pt/claude-projects.md#run-a-thread-on-your-own-computer).254* **[Sessões de Remote Control](https://code.claude.com/docs/pt/remote-control.md)** em sua máquina local: Manual, Accept edits, Plan e Auto para uma sessão que você mesmo iniciou, e você não pode selecionar Bypass permissions do aplicativo. Para usar Auto, a sessão precisa atender aos [requisitos de disponibilidade](#eliminate-prompts-with-auto-mode) do modo auto. Para um thread de projeto executado em seu computador, veja [Execute um thread em seu próprio computador](https://code.claude.com/docs/pt/claude-projects.md#run-a-thread-on-your-own-computer).

permissions.md +1 −1

Details

79| `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` |79| `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` |

80| `plan` | Claude lê arquivos e executa comandos shell somente leitura para explorar, mas não edita seus arquivos de origem; com [modo automático](https://code.claude.com/docs/pt/permission-modes.md#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 |80| `plan` | Claude lê arquivos e executa comandos shell somente leitura para explorar, mas não edita seus arquivos de origem; com [modo automático](https://code.claude.com/docs/pt/permission-modes.md#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 |

81| `auto` | Executa sem prompts rotineiros; antes de ações como comandos shell e solicitações de rede serem executadas, um [classificador](https://code.claude.com/docs/pt/permission-modes.md#eliminate-prompts-with-auto-mode) em segundo plano verifica se elas se alinham com sua solicitação |81| `auto` | Executa sem prompts rotineiros; antes de ações como comandos shell e solicitações de rede serem executadas, um [classificador](https://code.claude.com/docs/pt/permission-modes.md#eliminate-prompts-with-auto-mode) em segundo plano verifica se elas se alinham com sua solicitação |

82| `dontAsk` | Nega automaticamente toda chamada que de outra forma solicitaria permissão, embora um [mod](https://code.claude.com/docs/pt/plugins/mods/overview.md) que você instalou ainda possa aprovar algumas dessas chamadas. 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`](https://code.claude.com/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`](https://code.claude.com/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 |82| `dontAsk` | Nega automaticamente toda chamada que de outra forma solicitaria permissão, embora um [mod](https://code.claude.com/docs/pt/plugins/mods/overview.md) que você instalou ainda possa aprovar algumas dessas chamadas. 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`](https://code.claude.com/docs/pt/mcp#require-approval-for-a-specific-tool), [leituras de caminhos de rede](#network-paths) e ferramentas de conector [que sua organização definiu como `ask`](https://code.claude.com/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 |

83| `bypassPermissions` | Ignora prompts de permissão, exceto pelas [ações que nenhum modo aprova automaticamente](https://code.claude.com/docs/pt/permission-modes.md#actions-no-mode-auto-approves) |83| `bypassPermissions` | Ignora prompts de permissão, exceto pelas [ações que nenhum modo aprova automaticamente](https://code.claude.com/docs/pt/permission-modes.md#actions-no-mode-auto-approves) |

84 84 

85> [!WARNING]85> [!WARNING]

Details

584 584 

585O comando de um monitor é limitado em onde inicia e o que pode referenciar:585O comando de um monitor é limitado em onde inicia e o que pode referenciar:

586 586 

587* **Apenas sessões interativas**: monitores de plugin iniciam em uma sessão interativa e nunca em modo não interativo com a flag `-p`. Eles também não iniciam em sessões em que o provedor de API ou as configurações de telemetria tornam a [ferramenta Monitor](https://code.claude.com/docs/pt/tools-reference.md#monitor-tool) indisponível587* **Sessões interativas**: monitores de plugin não iniciam em modo não interativo com a flag `-p`

588* **Versão mínima**: no Amazon Bedrock, Claude Platform on AWS, Agent Platform do Google Cloud ou Microsoft Foundry, ou com `DISABLE_TELEMETRY` ou `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` definida, os monitores requerem Claude Code v2.1.310 ou posterior. O requisito se aplica quando a [busca de feature flags](https://code.claude.com/docs/pt/env-vars.md#features-that-need-feature-flag-fetching) está desativada

588* **Sem configuração do usuário**: `command` obtém as [variáveis de caminho](#path-variables-and-persistent-data) e `${ENV_VAR}` do ambiente, mas nunca `${user_config.*}`. Um monitor que referencia um não inicia, e processos de monitor não recebem `CLAUDE_PLUGIN_OPTION_<KEY>` também589* **Sem configuração do usuário**: `command` obtém as [variáveis de caminho](#path-variables-and-persistent-data) e `${ENV_VAR}` do ambiente, mas nunca `${user_config.*}`. Um monitor que referencia um não inicia, e processos de monitor não recebem `CLAUDE_PLUGIN_OPTION_<KEY>` também

589* **Desabilitação no meio da sessão**: se você desabilitar um plugin no meio da sessão, Claude Code não para monitores que já estão em execução. Eles param quando a sessão termina590* **Desabilitação no meio da sessão**: se você desabilitar um plugin no meio da sessão, Claude Code não para monitores que já estão em execução. Eles param quando a sessão termina

590 591 


647 648 

648No caminho do diretório de dados, `<id>` é o identificador do plugin com cada caractere diferente de letras, dígitos, `_` e `-` substituído por `-`, então `my-plugin@my-marketplace` se torna `my-plugin-my-marketplace`.649No caminho do diretório de dados, `<id>` é o identificador do plugin com cada caractere diferente de letras, dígitos, `_` e `-` substituído por `-`, então `my-plugin@my-marketplace` se torna `my-plugin-my-marketplace`.

649 650 

650No Windows, os caminhos substituídos usam barras para frente para que um shell não leia barras invertidas como escapes.651No Windows, a maioria dos caminhos substituídos usa barras para frente, como em `C:/Users/you/...`. Eles mantêm suas barras invertidas nativas em um [hook no formato exec](https://code.claude.com/docs/pt/hooks.md#exec-form-and-shell-form) e em um hook que é executado pelo PowerShell, que é o shell padrão no Windows quando o Git Bash não está instalado.

651 652 

652### Instalar dependências no diretório de dados653### Instalar dependências no diretório de dados

653 654 

Details

148 148 

149Quando os dois nomes diferem e alguém instala pelo nome do manifesto, Claude Code relata `Plugin "<manifest-name>" not found in marketplace "<marketplace>"`. Mantenha os dois nomes iguais. Para mais sobre como Claude Code usa os dois nomes, veja [Referência de carregamento de plugin](https://code.claude.com/docs/pt/plugins/loading.md#find-where-a-plugin-came-from).149Quando os dois nomes diferem e alguém instala pelo nome do manifesto, Claude Code relata `Plugin "<manifest-name>" not found in marketplace "<marketplace>"`. Mantenha os dois nomes iguais. Para mais sobre como Claude Code usa os dois nomes, veja [Referência de carregamento de plugin](https://code.claude.com/docs/pt/plugins/loading.md#find-where-a-plugin-came-from).

150 150 

151### Manter submódulos não utilizados fora do clone

152 

153Quando alguém adiciona seu marketplace, Claude Code clona o repositório e busca apenas os submódulos git que contêm arquivos de plugin. Requer Claude Code v2.1.295 ou posterior.

154 

155Você decide quais submódulos Claude Code busca pelo local onde coloca cada plugin:

156 

157* **Um plugin em um subdiretório**: Claude Code busca os submódulos dentro do diretório do plugin e um submódulo que o contenha. Coloque um submódulo de que seu plugin precisa dentro do diretório do plugin, e mantenha um de que ele não precisa fora dele

158* **Um plugin na raiz do marketplace**: Claude Code busca todos os submódulos do repositório assim que um dos arquivos do plugin se refere a um caminho dentro de qualquer um deles. Se seu repositório tiver um submódulo grande que apenas o seu build usa, mova o plugin para um subdiretório

159 

160Se um plugin na raiz executa um arquivo de um submódulo, escreva o caminho do arquivo por extenso na configuração de hook ou de servidor do plugin, como `${CLAUDE_PLUGIN_ROOT}/vendor/tool/run.sh`. Claude Code lê esses caminhos para descobrir se o plugin precisa dos submódulos. Ele não consegue ver um caminho que um script constrói enquanto é executado.

161 

162Para a regra completa, veja [Submódulos Git no repositório do marketplace](https://code.claude.com/docs/pt/plugins/marketplace-reference.md#git-submodules-in-the-marketplace-repository).

163 

151## Escolher uma source de plugin164## Escolher uma source de plugin

152 165 

153Cada entrada de plugin em `marketplace.json` tem uma `source` que diz ao Claude Code onde buscar esse plugin. Escolha a source por onde os arquivos do plugin são armazenados. A tabela lista as sources que a maioria dos proprietários de marketplace usam.166Cada entrada de plugin em `marketplace.json` tem uma `source` que diz ao Claude Code onde buscar esse plugin. Escolha a source por onde os arquivos do plugin são armazenados. A tabela lista as sources que a maioria dos proprietários de marketplace usam.

Details

111Diga aos usuários o que cada protocolo precisa em sua máquina:111Diga aos usuários o que cada protocolo precisa em sua máquina:

112 112 

113* **SSH**: a chave deve funcionar sem um prompt de passphrase, por exemplo porque está carregada em `ssh-agent`. O host já deve estar em `known_hosts`.113* **SSH**: a chave deve funcionar sem um prompt de passphrase, por exemplo porque está carregada em `ssh-agent`. O host já deve estar em `known_hosts`.

114* **HTTPS**: Claude Code deixa o helper de credencial git do usuário ativado, mas proíbe-o de solicitar. Uma credencial que o helper já armazena funciona; uma que ele teria que pedir falha. No GitHub, `gh auth login` seguido de `gh auth setup-git` armazena uma.114* **HTTPS**: Claude Code deixa o helper de credencial git do usuário ativado, mas proíbe-o de solicitar, e não executa programas askpass, como um definido em `GIT_ASKPASS`. Uma credencial que o helper já armazena funciona; uma que ele teria que pedir falha. No GitHub, `gh auth login` seguido de `gh auth setup-git` armazena uma.

115 115 

116Para um host GitHub Enterprise Server, os usuários precisam de acesso git a esse host a partir de sua máquina. Veja [Plugin marketplaces on GHES](https://code.claude.com/docs/pt/github-enterprise-server.md#plugin-marketplaces-on-ghes) para o que cada superfície Claude Code precisa para alcançar um marketplace hospedado em GHES.116Para um host GitHub Enterprise Server, os usuários precisam de acesso git a esse host a partir de sua máquina. Veja [Plugin marketplaces on GHES](https://code.claude.com/docs/pt/github-enterprise-server.md#plugin-marketplaces-on-ghes) para o que cada superfície Claude Code precisa para alcançar um marketplace hospedado em GHES.

117 117 

Details

238 238 

239Um marketplace privado é um em um repositório que você precisa de credenciais para clonar, no GitHub ou em qualquer outro host git. Você o adiciona com o mesmo comando `/plugin marketplace add` ou `claude plugin marketplace add` que um público. O Claude Code o clona com as credenciais git já em sua máquina e nunca solicita, então cada forma de conexão tem um requisito:239Um marketplace privado é um em um repositório que você precisa de credenciais para clonar, no GitHub ou em qualquer outro host git. Você o adiciona com o mesmo comando `/plugin marketplace add` ou `claude plugin marketplace add` que um público. O Claude Code o clona com as credenciais git já em sua máquina e nunca solicita, então cada forma de conexão tem um requisito:

240 240 

241* **HTTPS**: seus ajudantes de credencial git se aplicam, então o acesso que você configurou com `gh auth login`, o Keychain do macOS ou `git-credential-store` funciona. Prompts interativos são suprimidos, então um host que você nunca autenticou falha em vez de pedir uma senha.241* **HTTPS**: seus ajudantes de credencial git se aplicam, então o acesso que você configurou com `gh auth login`, o Keychain do macOS ou `git-credential-store` funciona. Os prompts e os programas askpass do Git ficam desativados, incluindo um definido em `GIT_ASKPASS`, então o clone falha em vez de solicitar quando o git precisaria pedir uma credencial.

242* **SSH**: o host já deve estar em seu arquivo `known_hosts` e a chave deve funcionar sem um prompt de frase-passe. Se sua configuração git nomeia um programa SSH em `GIT_SSH_COMMAND`, `GIT_SSH` ou `core.sshCommand` da sua configuração git, o Claude Code executa esse programa.242* **SSH**: o host já deve estar em seu arquivo `known_hosts` e a chave deve funcionar sem um prompt de frase-passe. Se sua configuração git nomeia um programa SSH em `GIT_SSH_COMMAND`, `GIT_SSH` ou `core.sshCommand` da sua configuração git, o Claude Code executa esse programa.

243* **Atalho GitHub `owner/repo`**: o Claude Code verifica se sua chave SSH autentica em `github.com`, depois clona sobre SSH se fizer e sobre HTTPS se não fizer. Defina [`CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1`](https://code.claude.com/docs/pt/env-vars#variables) para pular essa verificação e sempre clonar sobre HTTPS.243* **Atalho GitHub `owner/repo`**: o Claude Code verifica se sua chave SSH autentica em `github.com`, depois clona sobre SSH se fizer e sobre HTTPS se não fizer. Defina [`CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1`](https://code.claude.com/docs/pt/env-vars#variables) para pular essa verificação e sempre clonar sobre HTTPS.

244 244 

Details

41* **Um marketplace que configurações declaram mas `known_marketplaces.json` não tem**: Claude Code o clona, depois recarrega plugins e baixa plugins habilitados que ainda não estão em cache41* **Um marketplace que configurações declaram mas `known_marketplaces.json` não tem**: Claude Code o clona, depois recarrega plugins e baixa plugins habilitados que ainda não estão em cache

42* **Um marketplace declarado cuja fonte mudou em configurações**: Claude Code o busca novamente da nova fonte e mostra `Plugins changed. Run /reload-plugins to activate.`42* **Um marketplace declarado cuja fonte mudou em configurações**: Claude Code o busca novamente da nova fonte e mostra `Plugins changed. Run /reload-plugins to activate.`

43 43 

44Um plugin habilitado que nenhum caminho buscou e que não tem diretório de cache utilizável mostra `Plugin "<name>" not cached at <path>` na aba **Errors** do `/plugin`, e `claude plugin list` adiciona `— run /plugin to refresh` à mesma linha. Para a correção, veja [`Plugin "<name>" not cached at <path>`](https://code.claude.com/docs/pt/plugins/troubleshooting#plugin-not-cached-at).44Um plugin habilitado que nenhum caminho buscou e que não tem diretório de cache utilizável mostra `Plugin "<name>" not cached at <path>` na aba **Errors** do `/plugin`. Para a correção, veja [`Plugin "<name>" not cached at <path>`](https://code.claude.com/docs/pt/plugins/troubleshooting#plugin-not-cached-at).

45 45 

46## Encontrar de onde um plugin veio46## Encontrar de onde um plugin veio

47 47 

Details

155| `workflows` | Caminho, ou array de caminhos | Arquivos de [Workflow](https://code.claude.com/docs/pt/workflows.md#distribute-a-workflow-in-a-plugin) `.js` ou diretórios. Substitui o scan padrão `workflows/` |155| `workflows` | Caminho, ou array de caminhos | Arquivos de [Workflow](https://code.claude.com/docs/pt/workflows.md#distribute-a-workflow-in-a-plugin) `.js` ou diretórios. Substitui o scan padrão `workflows/` |

156| `experimental` | Object | Contêiner para `themes`, `monitors` e `evals`, cuja forma de manifesto ainda pode mudar |156| `experimental` | Object | Contêiner para `themes`, `monitors` e `evals`, cuja forma de manifesto ainda pode mudar |

157| `experimental.themes` | Caminho, ou array de caminhos | Arquivos de tema ou diretórios. Substitui o scan padrão `themes/`. Uma chave `themes` de nível superior ainda carrega, com um aviso `claude plugin validate` |157| `experimental.themes` | Caminho, ou array de caminhos | Arquivos de tema ou diretórios. Substitui o scan padrão `themes/`. Uma chave `themes` de nível superior ainda carrega, com um aviso `claude plugin validate` |

158| [`experimental.monitors`](#monitors) | Caminho, ou array inline | Um arquivo `.json` contendo o array de monitors, ou o próprio array. Padrão é `monitors/monitors.json`. Uma chave `monitors` de nível superior ainda carrega, com um aviso `claude plugin validate`. Monitors executam apenas em sessões interativas, e não no Amazon Bedrock, Agent Platform do Google Cloud ou Microsoft Foundry |158| [`experimental.monitors`](#monitors) | Caminho, ou array inline | Um arquivo `.json` contendo o array de monitors, ou o próprio array. Padrão é `monitors/monitors.json`. Uma chave `monitors` de nível superior ainda carrega, com um aviso `claude plugin validate`. Monitors [não iniciam com a flag `-p`](https://code.claude.com/docs/pt/plugins/components#monitors) |

159| `experimental.evals` | Caminho, ou array de caminhos | Diretório que contém os [casos de eval](https://code.claude.com/docs/pt/plugin-evals.md#use-a-different-eval-directory) do plugin quando não é o padrão `evals/`. `claude plugin eval --eval-dir` o substitui |159| `experimental.evals` | Caminho, ou array de caminhos | Diretório que contém os [casos de eval](https://code.claude.com/docs/pt/plugin-evals.md#use-a-different-eval-directory) do plugin quando não é o padrão `evals/`. `claude plugin eval --eval-dir` o substitui |

160 160 

161Na coluna Tipo, um caminho é uma string relativa à raiz do plugin, como `"./custom/commands"`.161Na coluna Tipo, um caminho é uma string relativa à raiz do plugin, como `"./custom/commands"`.


606}606}

607```607```

608 608 

609No Windows, os caminhos substituídos usam barras para frente para que um shell não leia barras invertidas como escapes.609No Windows, a maioria dos caminhos substituídos usa barras para frente, como em `C:/Users/you/...`. Eles mantêm suas barras invertidas nativas em um [hook em forma exec](https://code.claude.com/docs/pt/hooks.md#exec-form-and-shell-form) e em um hook que é executado através do PowerShell, que é o shell padrão no Windows quando o Git Bash não está instalado.

610 610 

611## Layout padrão611## Layout padrão

612 612 

Details

172* **`url`**: Claude Code busca apenas `marketplace.json`, então caminhos relativos não podem se resolver. Dê a cada plugin uma origem de objeto em vez disso, como `github` ou `git-subdir`.172* **`url`**: Claude Code busca apenas `marketplace.json`, então caminhos relativos não podem se resolver. Dê a cada plugin uma origem de objeto em vez disso, como `github` ou `git-subdir`.

173* **`settings`**: caminhos relativos são rejeitados imediatamente.173* **`settings`**: caminhos relativos são rejeitados imediatamente.

174 174 

175#### Git submodules in the marketplace repository

176 

177Quando Claude Code clona um repositório de marketplace, ele busca apenas os submódulos git que contêm arquivos de plugin. Requer Claude Code v2.1.295 ou posterior.

178 

179Versões anteriores buscam todos os submódulos, incluindo os aninhados. Se o repositório tiver um submódulo grande, Claude Code pode então ultrapassar o [timeout de clone](https://code.claude.com/docs/pt/plugins/troubleshooting.md#git-clone-timed-out-after-120s) enquanto o busca.

180 

181Para um plugin em um subdiretório, como `./plugins/formatter`, Claude Code busca um submódulo nestes casos:

182 

183* **O plugin está dentro do submódulo**: o submódulo é o diretório do plugin ou um diretório acima dele

184* **O submódulo está dentro do plugin**: o submódulo está em qualquer lugar sob o diretório do plugin

185* **Um link simbólico aponta para dentro do submódulo**: um link com commit no repositório tem seu destino no submódulo

186 

187Um plugin na raiz do marketplace, com `"source": "./"`, recebe todos os submódulos do repositório ou nenhum deles. Claude Code busca todos os submódulos quando um destes aponta para dentro de qualquer submódulo:

188 

189* **Um diretório de componente**: um diretório na raiz que contém componentes do plugin, como `skills/`, `hooks/` ou `bin/`

190* **Um caminho na configuração do plugin**: um caminho na entrada de marketplace do plugin, em seu `plugin.json` ou em um arquivo de configuração como `.mcp.json` ou `hooks/hooks.json`

191* **Um link simbólico**: um link com commit no repositório

192* **Texto nos arquivos do plugin**: o caminho de um submódulo, como `vendor/tool`, escrito em um arquivo de configuração ou em um arquivo sob um diretório de componente

193 

194Quando nenhum deles aponta, Claude Code não busca nenhum submódulo para esse plugin. Um repositório que é ao mesmo tempo um projeto e um plugin frequentemente tem submódulos que apenas o build do projeto usa, e essa regra os deixa de fora.

195 

196Claude Code também busca todos os submódulos quando não consegue determinar quais contêm arquivos de plugin, como:

197 

198* **Um `SKILL.md` na raiz**: o repositório inteiro é então o diretório de uma skill

199* **Um arquivo que Claude Code não consegue ler**: o arquivo do marketplace, um dos arquivos de configuração do plugin ou `.gitmodules`

200 

201Se você adicionar um marketplace com `--sparse`, ou se sua origem definir `sparsePaths`, Claude Code faz checkout apenas dos diretórios nomeados ali e não busca nenhum submódulo. Versões anteriores fazem o mesmo.

202 

203Para manter fora do clone um submódulo que seus plugins não usam, veja [Keep unused submodules out of the clone](https://code.claude.com/docs/pt/plugins/create-marketplace.md#keep-unused-submodules-out-of-the-clone).

204 

175#### Bare names under pluginRoot205#### Bare names under pluginRoot

176 206 

177Um nome simples é um único nome de diretório sem `/`, como `"formatter"`. Para escrever nomes simples em vez de caminhos `./`, defina [`metadata.pluginRoot`](#top-level-fields) para o diretório que eles se resolvem sob. Com `"pluginRoot": "./plugins"`, `"source": "formatter"` se resolve para `./plugins/formatter`. Requer Claude Code v2.1.239 ou posterior.207Um nome simples é um único nome de diretório sem `/`, como `"formatter"`. Para escrever nomes simples em vez de caminhos `./`, defina [`metadata.pluginRoot`](#top-level-fields) para o diretório que eles se resolvem sob. Com `"pluginRoot": "./plugins"`, `"source": "formatter"` se resolve para `./plugins/formatter`. Requer Claude Code v2.1.239 ou posterior.

Details

313 313 

314#### O que as chamadas recusadas retornam314#### O que as chamadas recusadas retornam

315 315 

316Nos resultados, `<reason>` representa `the session was stopped and nobody has sent input since`:316Nos resultados, `<reason>` representa o motivo pelo qual a chamada foi recusada. Após uma interrupção, esse motivo é `the session was stopped and nobody has sent input since`. Para outros motivos, consulte [Chamadas recusadas em execuções `claude -p` e sessões do Agent SDK](#calls-refused-in-non-interactive-runs).

317 317 

318| Algumas chamadas recusadas | Resultado até a próxima entrada do usuário |318| Algumas chamadas recusadas | Resultado |

319| :- | :- |319| :- | :- |

320| `$.prompt.submit` | Resolve com `{ drop: '<reason>' }` e não enfileira nenhum prompt |320| `$.prompt.submit` | Resolve com `{ drop: '<reason>' }` e não enfileira nenhum prompt |

321| `$.command.run` | Rejeita com um erro cuja mensagem termina com `<reason>` |321| `$.command.run` | Rejeita com um erro cuja mensagem termina com `<reason>` |


324| `$.session.send` para um colega de uma [equipe de agentes](https://code.claude.com/docs/pt/agent-teams.md) | Resolve com `{ isDelivered: false, reason: 'Teammate "<name>" was not messaged: <reason>.' }`, onde `<name>` é o nome do colega |324| `$.session.send` para um colega de uma [equipe de agentes](https://code.claude.com/docs/pt/agent-teams.md) | Resolve com `{ isDelivered: false, reason: 'Teammate "<name>" was not messaged: <reason>.' }`, onde `<name>` é o nome do colega |

325| [`$.tool.call`](https://code.claude.com/docs/pt/plugins/mods/reference#mods-api-methods) de Bash com `run_in_background: true`, Monitor ou CronCreate | Resolve com `{ deny: '<tool> was not run: it starts background work, a schedule or a goal, and <reason>' }`, onde `<tool>` é o nome da ferramenta |325| [`$.tool.call`](https://code.claude.com/docs/pt/plugins/mods/reference#mods-api-methods) de Bash com `run_in_background: true`, Monitor ou CronCreate | Resolve com `{ deny: '<tool> was not run: it starts background work, a schedule or a goal, and <reason>' }`, onde `<tool>` é o nome da ferramenta |

326 326 

327Junto com esses resultados de `$.session.send` e `$.tool.call`, o usuário pode ver o [toast `Stopped:`](https://code.claude.com/docs/pt/plugins/mods/troubleshoot#stopped-type-a-message-to-continue).327Quando uma dessas chamadas `$.session.send` ou `$.tool.call` é recusada após uma interrupção em uma sessão interativa, o usuário pode ver o [toast `Stopped:`](https://code.claude.com/docs/pt/plugins/mods/troubleshoot#stopped-type-a-message-to-continue).

328 328 

329#### Trabalho que seu mod iniciou antes da interrupção329#### Trabalho que seu mod iniciou antes da interrupção

330 330 


341 341 

342Quando um trabalho agendado vence ou um monitor gera um evento antes da próxima entrada do usuário, o usuário pode ver o [toast `Stopped:`](https://code.claude.com/docs/pt/plugins/mods/troubleshoot#stopped-type-a-message-to-continue).342Quando um trabalho agendado vence ou um monitor gera um evento antes da próxima entrada do usuário, o usuário pode ver o [toast `Stopped:`](https://code.claude.com/docs/pt/plugins/mods/troubleshoot#stopped-type-a-message-to-continue).

343 343 

344### Chamadas recusadas em execuções `claude -p` e sessões do Agent SDK

345 

346Em uma execução `claude -p` ou em uma sessão do [Agent SDK](https://code.claude.com/docs/pt/agent-sdk/overview.md), um resultado como `{ drop: 'the run reached its --max-turns limit' }` significa que a execução recusou a chamada do seu mod.

347 

348Um `$.prompt.submit` recusado resolve com `{ drop: '<reason>' }`. Outras chamadas recusadas, como `$.command.run` e `$.agent.spawn`, fornecem os resultados mostrados em [O que as chamadas recusadas retornam](#what-refused-calls-return), com o motivo no lugar de `<reason>`. Encontre seu `<reason>` abaixo para saber o que fazer:

349 

350* **`the run reached its --max-turns limit`**: os turnos dos prompts do seu mod e dos subagentes que ele cria contam para [`--max-turns`](https://code.claude.com/docs/pt/cli-reference#cli-flags) ou para o [limite de turnos](https://code.claude.com/docs/pt/agent-sdk/configuration.md#limit-turns-and-spend) do Agent SDK. Para ter mais turnos, inicie a execução com um limite maior. Se não puder, faça seu mod parar de fazer a chamada recusada. Se a execução receber outro prompt do usuário ou do aplicativo do SDK, a contagem de turnos é reiniciada e a execução volta a aceitar chamadas.

351* **`the run is past its --max-budget-usd limit`**: inicie a execução com um `--max-budget-usd` maior ou aumente o [limite de gastos](https://code.claude.com/docs/pt/agent-sdk/configuration.md#limit-turns-and-spend) do Agent SDK. Se não puder, faça seu mod parar de fazer a chamada recusada. O limite se aplica ao custo total da execução até o momento. Esse total continua se acumulando quando a execução recebe outro prompt, então uma nova tentativa retorna o mesmo motivo.

352* **`the host has ended its input`**: por exemplo, o aplicativo do SDK encerrou sua [entrada por streaming](https://code.claude.com/docs/pt/agent-sdk/streaming-vs-single-mode.md), ou o stdin foi fechado em uma execução iniciada com [`--input-format stream-json`](https://code.claude.com/docs/pt/cli-reference#cli-flags). A execução está terminando e não aceita mais entradas, então uma nova tentativa retorna o mesmo motivo. Faça seu mod parar de fazer a chamada recusada. Se você mesmo inicia a execução, da próxima vez mantenha essa entrada aberta até que seu mod não tenha mais chamadas a fazer.

353* **`the session was stopped and nobody has sent input since`**: a execução foi [interrompida](#calls-and-background-work-after-the-user-interrupts-a-turn), por exemplo com o [`interrupt()`](https://code.claude.com/docs/pt/agent-sdk/typescript#query-object) do Agent SDK. Para fazer a chamada novamente após a próxima mensagem do usuário ou do aplicativo do SDK, siga [Tente novamente uma chamada recusada ou descartada](#retry-a-refused-or-dropped-call).

354 

355### Uma execução `claude -p` com seu mod nunca termina

356 

357Se seu mod envia um prompt ao final de cada turno, cada prompt inicia outro turno. Sem [`--max-turns`](https://code.claude.com/docs/pt/cli-reference#cli-flags) ou `--max-budget-usd`, uma execução `claude -p` que carrega o mod continua até que você mesmo a interrompa.

358 

359Para que a execução termine sozinha, adicione qualquer uma das flags ao comando no seu shell. Se outras pessoas iniciam a execução, faça seu mod parar de enviar prompts quando seu trabalho estiver concluído. Este comando adiciona `--max-turns`:

360 

361```bash theme={null}

362claude -p "find the TODOs" --max-turns 5

363```

364 

365Quando a execução atinge esse limite, o próximo prompt do mod é [recusado](#calls-refused-in-non-interactive-runs) em vez de iniciar um turno, e a execução termina.

366 

367Se a execução ainda ultrapassar o limite, execute `claude --version` no seu shell e [atualize o Claude Code](https://code.claude.com/docs/pt/setup.md#update-claude-code) se a sua versão for anterior à v2.1.304. Os prompts do mod são recusados no limite a partir da v2.1.299. Se seu mod cria subagentes, os turnos deles contam para `--max-turns` a partir da v2.1.304.

368 

344## Envie e receba mensagens entre sessões369## Envie e receba mensagens entre sessões

345 370 

346Um mod pode enviar uma mensagem em texto simples para outra de suas sessões, para um dos subagentes desta sessão ou para um colega de equipe em sua [equipe de agentes](https://code.claude.com/docs/pt/agent-teams.md). Ele também pode observar as mensagens que chegam e saem.371Um mod pode enviar uma mensagem em texto simples para outra de suas sessões, para um dos subagentes desta sessão ou para um colega de equipe em sua [equipe de agentes](https://code.claude.com/docs/pt/agent-teams.md). Ele também pode observar as mensagens que chegam e saem.


390| `$.http` | `fetch(url, init)` sobre `http` ou `https`. Ele resolve para `{ status, ok, headers, text }` uma vez que o corpo é lido. |415| `$.http` | `fetch(url, init)` sobre `http` ou `https`. Ele resolve para `{ status, ok, headers, text }` uma vez que o corpo é lido. |

391| `$.store` | Um armazenamento de chave-valor JSON do seu próprio plugin, mantido entre sessões |416| `$.store` | Um armazenamento de chave-valor JSON do seu próprio plugin, mantido entre sessões |

392| `$.env` | `get` e `set` variáveis de ambiente. Escreva o nome como uma string literal. |417| `$.env` | `get` e `set` variáveis de ambiente. Escreva o nome como uma string literal. |

393| `$.settings` | `read` o que os arquivos de configurações e a política gerenciada contêm |418| `$.settings` | `read()` resolve para todas as configurações, mescladas em um único objeto. Com `{ source }` ou `{ key }`, ele resolve, em vez disso, para [as configurações de uma fonte ou o valor de uma chave](#read-one-source-or-one-key). |

394| `$.session` | `messages()` retorna a transcrição como uma lista de `{ role, text, toolUses }`. Também o diretório de trabalho, modelo e mais. [`usage()`](https://code.claude.com/docs/pt/plugins/mods/reference#mods-api-methods) retorna o uso da janela de contexto e limites de plano. |419| `$.session` | `messages()` retorna a transcrição como uma lista de `{ role, text, toolUses }`. Também o diretório de trabalho, modelo e mais. [`usage()`](https://code.claude.com/docs/pt/plugins/mods/reference#mods-api-methods) retorna o uso da janela de contexto e limites de plano. |

395| `$.mcp` | `call` uma ferramenta em um servidor MCP conectado |420| `$.mcp` | `call` uma ferramenta em um servidor MCP conectado |

396 421 


408* **`$.process.spawn started, and a plugin withheld its result:`**: o mod que recusou não havia lido a saída do comando até o fim. Claude Code interrompe o comando se ele ainda estiver em execução.433* **`$.process.spawn started, and a plugin withheld its result:`**: o mod que recusou não havia lido a saída do comando até o fim. Claude Code interrompe o comando se ele ainda estiver em execução.

409* **`$.process.spawn ran, and a plugin withheld its result:`**: o mod que recusou havia lido a saída do comando até o fim, então o comando já havia saído434* **`$.process.spawn ran, and a plugin withheld its result:`**: o mod que recusou havia lido a saída do comando até o fim, então o comando já havia saído

410 435 

436### Leia todas as configurações, uma fonte ou uma chave

437 

438`$.settings.read()` resolve para um objeto que contém as configurações de todas as fontes em uso, mescladas por [precedência](https://code.claude.com/docs/pt/settings.md#settings-precedence). Passe `{ source }` para ler uma única fonte, `{ key }` para ler uma única chave, ou ambos:

439 

440| Chamada | Resolve para |

441| :- | :- |

442| `$.settings.read()` | As configurações mescladas como um único objeto. Suas chaves de nível superior são as de um arquivo `settings.json`, como `permissions` e `hooks`. |

443| `$.settings.read({ source: 'policy' })` | As configurações dessa única fonte como um objeto, ou `{}` quando essa fonte não contém configurações |

444| `$.settings.read({ key: 'spinnerTipsEnabled' })` | O valor dessa chave nas configurações mescladas, ou `undefined` quando a chave não está definida |

445| `$.settings.read({ key: 'spinnerTipsEnabled', source: 'user' })` | O valor dessa chave nessa única fonte, ou `undefined` quando essa fonte não a define |

446 

447Para `source`, passe o nome da fonte de configurações a ser lida:

448 

449* **`user`**: `~/.claude/settings.json`

450* **`project`**: `.claude/settings.json`

451* **`local`**: `.claude/settings.local.json`

452* **`flag`**: o que você passa com `--settings` e as configurações inline do SDK

453* **`policy`**: [configurações gerenciadas](https://code.claude.com/docs/pt/managed-settings.md#how-claude-code-combines-managed-sources)

454 

455Para `key`, passe o nome exato de uma chave de nível superior, não um caminho com pontos dentro de um objeto aninhado. O argumento `key` requer Claude Code v2.1.304 ou posterior.

456 

411## Próximas etapas457## Próximas etapas

412 458 

413* [React to events](https://code.claude.com/docs/pt/plugins/mods/events.md): hook tool calls, prompts, and turns459* [React to events](https://code.claude.com/docs/pt/plugins/mods/events.md): hook tool calls, prompts, and turns

Details

46 46 

47**4. Experimente o mod**47**4. Experimente o mod**

48 48 

49Use o que você pediu. Para o prompt de exemplo, o nome do branch atual aparece acima da caixa de prompt. Se o mod não fizer o que você queria, diga ao Claude o que mudar. O mod recarrega no final de cada rodada que altera seus arquivos, então você pode tentar a mudança assim que Claude terminar.49Use o que você pediu. Para o prompt de exemplo, o nome do branch atual aparece acima da caixa de prompt. Se o mod não fizer o que você queria, diga ao Claude o que mudar. O mod recarrega no final de cada turno que altera seus arquivos, então você pode tentar a mudança assim que Claude terminar.

50 

51Se uma linha da transcrição que começa com o nome do mod disser que a [mudança não foi carregada](https://code.claude.com/docs/pt/plugins/mods/troubleshoot.md#this-mods-change-didnt-load), cole essa linha na sua próxima mensagem quando pedir uma correção ao Claude. Claude não vê a linha a menos que você a cole.

50 52 

51### Use o mod em outras sessões53### Use o mod em outras sessões

52 54 

Details

93 93 

94## Fazer hook no que o Claude está fazendo94## Fazer hook no que o Claude está fazendo

95 95 

96Trate estes eventos para ver ou alterar uma chamada de ferramenta, um prompt ou um turno enquanto acontecem. Para cada evento e o que um hook pode retornar, consulte a [referência de eventos](https://code.claude.com/docs/pt/plugins/mods/reference.md#events).96Trate estes eventos para ver ou alterar uma chamada de ferramenta, um prompt, um turno ou uma leitura de configurações enquanto acontecem. Para cada evento e o que um hook pode retornar, consulte a [referência de eventos](https://code.claude.com/docs/pt/plugins/mods/reference.md#events).

97 97 

98### Proteger ou alterar uma chamada de ferramenta98### Proteger ou alterar uma chamada de ferramenta

99 99 


115 115 

116Quando o Claude tenta `git push --force`, o comando não é executado e nenhum prompt de permissão aparece, porque o hook nunca chama `next`. O Claude lê o texto de `deny` como o resultado da ferramenta, então escreva-o como uma instrução sobre a qual o Claude possa agir. Todos os outros comandos Bash são executados como seriam sem o mod.116Quando o Claude tenta `git push --force`, o comando não é executado e nenhum prompt de permissão aparece, porque o hook nunca chama `next`. O Claude lê o texto de `deny` como o resultado da ferramenta, então escreva-o como uma instrução sobre a qual o Claude possa agir. Todos os outros comandos Bash são executados como seriam sem o mod.

117 117 

118Se este hook lançar um erro ou exceder o tempo limite, o Claude Code o ignora e o comando prossegue como prosseguiria sem o mod. Para recusar o comando nesse caso, [adicione um handler `.catch`](#handle-a-hook-that-fails) ao hook.

119 

118Para agir depois que uma ferramenta foi executada, use `await next(e)`, faça seu trabalho e retorne o que `next` lhe deu. Este hook registra em log cada arquivo `.mdx` que o Claude altera, com [`$.ui.log`](https://code.claude.com/docs/pt/plugins/mods/api#show-something-without-starting-a-turn), que adiciona uma linha esmaecida à transcrição que o Claude não lê:120Para agir depois que uma ferramenta foi executada, use `await next(e)`, faça seu trabalho e retorne o que `next` lhe deu. Este hook registra em log cada arquivo `.mdx` que o Claude altera, com [`$.ui.log`](https://code.claude.com/docs/pt/plugins/mods/api#show-something-without-starting-a-turn), que adiciona uma linha esmaecida à transcrição que o Claude não lê:

119 121 

120```javascript theme={null}122```javascript theme={null}


177* **O usuário digita uma resposta**: `$.ui.ask` resolve para o texto digitado. O hook o compara com `Run it`, então qualquer outro texto recusa o comando.179* **O usuário digita uma resposta**: `$.ui.ask` resolve para o texto digitado. O hook o compara com `Run it`, então qualquer outro texto recusa o comando.

178* **Ninguém responde**: `$.ui.ask` é rejeitado quando o usuário dispensa a pergunta ou escolhe **Chat about this**, e em uma execução `claude -p`, então o bloco `catch` mantém a resposta como `Refuse`180* **Ninguém responde**: `$.ui.ask` é rejeitado quando o usuário dispensa a pergunta ou escolhe **Chat about this**, e em uma execução `claude -p`, então o bloco `catch` mantém a resposta como `Refuse`

179 181 

180Mantenha a espera dentro de uma chamada da API de mods, como `$.ui.ask`, porque esse tempo não conta para o [limite de tempo](https://code.claude.com/docs/pt/plugins/mods/reference.md#limits) do hook. O tempo gasto aguardando uma promise sua conta. O Claude Code ignora um hook que excede o tempo limite, então o comando retido seria executado.182Mantenha a espera dentro de uma chamada da API de mods, como `$.ui.ask`, porque esse tempo não conta para o [limite de tempo](https://code.claude.com/docs/pt/plugins/mods/reference.md#limits) do hook. O tempo gasto aguardando uma promise sua conta.

183 

184O Claude Code ignora um hook que excede o tempo limite, então o comando retido seria executado. Para recusá-lo nesse caso, encadeie [um handler `.catch`](#handle-a-hook-that-fails) ao registro que `on` retorna. Esse handler é separado do bloco `catch` dentro do hook.

181 185 

182#### Aprovar ou recusar uma chamada de ferramenta antes de o usuário ser consultado186#### Aprovar ou recusar uma chamada de ferramenta antes de o usuário ser consultado

183 187 


207 211 

208* **Em `main`**: o hook retorna `deny`, mesmo quando uma regra permite `git push`212* **Em `main`**: o hook retorna `deny`, mesmo quando uma regra permite `git push`

209* **Em outro branch, e para outros comandos**: a chamada recebe a decisão que receberia sem o mod213* **Em outro branch, e para outros comandos**: a chamada recebe a decisão que receberia sem o mod

214* **O hook lança um erro ou excede o tempo limite**: a chamada também recebe a decisão que receberia sem o mod. Para recusar a chamada nesse caso, [adicione um handler `.catch`](#handle-a-hook-that-fails) que retorne `{ decision: 'deny', reason: 'the reason' }`.

210 215 

211O hook compara o texto do comando, então trate-o como um lembrete para o Claude. Para bloquear pushes para `main` para todos, proteja o branch no seu host Git.216O hook compara o texto do comando, então trate-o como um lembrete para o Claude. Para bloquear pushes para `main` para todos, proteja o branch no seu host Git.

212 217 


269 274 

270Quando você envia um prompt como `open a PR for this change`, sua mensagem aparece igual na transcrição, e o Claude também lê uma linha como `Current branch: feature/auth` depois dela. Um prompt que não menciona um pull request passa sem alterações, e `git` não é executado.275Quando você envia um prompt como `open a PR for this change`, sua mensagem aparece igual na transcrição, e o Claude também lê uma linha como `Current branch: feature/auth` depois dela. Um prompt que não menciona um pull request passa sem alterações, e `git` não é executado.

271 276 

272Para impedir um prompt, retorne `{ drop: 'the reason' }` sem chamar `next`. O texto volta para a entrada de prompt do usuário, e ele vê `Prompt dropped by a hook:` seguido do seu motivo, então dirija o motivo a ele. Se o seu hook retornar um `drop` depois que sua chamada `next(e)` deixou o prompt passar, o turno ainda é executado, e o hook [falha](#handle-a-hook-that-fails) com uma mensagem que inclui `a drop after its next() was answered`.277Para impedir um prompt, retorne `{ drop: 'the reason' }` sem chamar `next`. O texto volta para a entrada de prompt do usuário, e ele vê `Prompt dropped by a hook:` seguido do seu motivo, então dirija o motivo a ele. O prompt ainda é enviado nestes casos:

278 

279* **Seu hook retorna um `drop` depois que sua chamada `next(e)` deixou o prompt passar**: o turno ainda é executado, e o hook [falha](#handle-a-hook-that-fails) com uma mensagem que inclui `a drop after its next() was answered`

280* **Seu hook lança um erro ou excede o tempo limite**: o Claude Code o ignora e envia o prompt. [Adicione um handler `.catch`](#handle-a-hook-that-fails) para que uma falha não envie um prompt que o hook teria impedido.

273 281 

274[Outros eventos](https://code.claude.com/docs/pt/plugins/mods/reference.md#prompts-and-what-claude-reads) cobrem o restante do que o Claude lê: `prompt.section` para cada seção do system prompt, `prompt.context` para o contexto enviado com a primeira mensagem e `skill.prompt` para o texto de uma skill. Texto desses hooks que muda entre requisições [invalida o cache de prompt](https://code.claude.com/docs/pt/prompt-caching.md). Em um hook `skill.prompt`, você também pode ler [de qual plugin ou arquivo a skill veio](https://code.claude.com/docs/pt/plugins/mods/reference.md#skill-prompt-fields).282[Outros eventos](https://code.claude.com/docs/pt/plugins/mods/reference.md#prompts-and-what-claude-reads) cobrem o restante do que o Claude lê: `prompt.section` para cada seção do system prompt, `prompt.context` para o contexto enviado com a primeira mensagem e `skill.prompt` para o texto de uma skill. Texto desses hooks que muda entre requisições [invalida o cache de prompt](https://code.claude.com/docs/pt/prompt-caching.md). Em um hook `skill.prompt`, você também pode ler [de qual plugin ou arquivo a skill veio](https://code.claude.com/docs/pt/plugins/mods/reference.md#skill-prompt-fields).

275 283 


305 313 

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

307 315 

316### Alterar ou recusar uma leitura de configurações

317 

318Um hook `settings.read` é executado na leitura de um mod e na leitura do próprio Claude Code:

319 

320* **A leitura de um mod**: um mod chama [`$.settings.read`](https://code.claude.com/docs/pt/plugins/mods/api#read-one-source-or-one-key).

321* **A leitura do próprio Claude Code**: o Claude Code monta as configurações mescladas da sessão. Essa leitura se repete quando as configurações ou os plugins carregados mudam.

322 

323Antes de depender de qualquer uma das leituras, verifique a guarda e a sua versão:

324 

325* **A guarda integrada**: com configurações gerenciadas, ou com um [`/login`](https://code.claude.com/docs/pt/authentication#authentication-precedence) Team ou Enterprise como credencial da sessão, a [guarda integrada](https://code.claude.com/docs/pt/plugins/mods/admin.md#know-what-happens-by-default) pode ignorar este hook em um mod que você instala ou carrega com `--plugin-dir`. Para verificar, procure no [log de depuração](https://code.claude.com/docs/pt/plugins/mods/troubleshoot.md#read-the-debug-log) por `settings.read bypassed by cc-plugin-sec-default`. Se uma linha com esse texto citar o seu mod, peça ao administrador da sua organização para [instalar o mod como um dos mods da organização](https://code.claude.com/docs/pt/plugins/mods/admin.md#install-your-organizations-mods).

326* **A versão**: o disparo do evento na leitura do próprio Claude Code, e o campo `e.layers`, requerem o Claude Code v2.1.304 ou posterior.

327 

328#### O que um hook `settings.read` recebe

329 

330| Campo | Tipo | O que contém |

331| :- | :- | :- |

332| `e.layers` | array | Um objeto `{ source, settings }` para cada fonte em uso que contém configurações, da menor [precedência](https://code.claude.com/docs/pt/settings.md#settings-precedence) para a maior: `plugin`, `user`, `project`, `local`, `flag`, `policy`. Vazio em `claude plugin test`. |

333| `e.source` | string | A única fonte que um mod solicitou, como em `$.settings.read({ source: 'policy' })`. `e.layers` então contém apenas essa camada. Ausente na leitura do próprio Claude Code e em qualquer outra leitura das configurações mescladas. |

334 

335Em `e.layers`, `plugin` contém as configurações que os plugins habilitados fornecem, e é apenas um nome de camada, não um `source` que você possa passar para `$.settings.read`. `flag` contém as configurações passadas com `--settings`, e `policy` contém as configurações gerenciadas.

336 

337#### Distinguir a leitura do próprio Claude Code da leitura de um mod

338 

339Na [leitura do próprio Claude Code](#settings-read-hook), [`next.origin`](https://code.claude.com/docs/pt/plugins/mods/reference#the-hook-function) é `{ plugin: 'engine', tier: 'core' }`, e na leitura de um mod `next.origin.plugin` é o nome do mod que fez a chamada.

340 

341#### O que um hook `settings.read` pode retornar

342 

343Seu hook pode retornar o resultado de [`next(e)`](https://code.claude.com/docs/pt/plugins/mods/reference#the-hook-function) sem alterações, um `{ value }` próprio ou `{ deny: reason }`. Na [leitura do próprio Claude Code](#settings-read-hook) e na leitura de um mod, um `{ value }` substitui o que a leitura fornece e `{ deny: reason }` recusa a leitura:

344 

345| Retorno | Na leitura do próprio Claude Code | Na leitura de um mod |

346| :- | :- | :- |

347| `{ value }` | Para cada chave que você altera, o que você retorna substitui o valor inteiro dessa chave nas configurações mescladas da sessão, se [couber no esquema da chave](https://code.claude.com/docs/pt/plugins/mods/troubleshoot.md#settings-read-key-refused) | A chamada desse mod resolve para o seu `value`, ou para a `key` que ele solicitou extraída do seu `value`, então retorne um objeto inteiro e não um array |

348| `{ deny: reason }` | A sessão mantém as configurações como estavam mescladas antes de qualquer hook responder, e o [log de depuração registra o seu `reason`](https://code.claude.com/docs/pt/plugins/mods/troubleshoot#settings-read-refused) | A chamada desse mod é rejeitada com `<calling mod>: $.settings.read: <reason>` |

349 

350Na leitura do próprio Claude Code, monte o seu `{ value }` a partir do [`value` de `next(e)`](#settings-read-next), já que uma chave que você omitir fica indefinida. Onde o Claude Code lê uma chave como `env` de cada fonte separadamente, alterá-la no seu `value` [não tem efeito](https://code.claude.com/docs/pt/plugins/mods/troubleshoot.md#settings-read-key-no-effect).

351 

352#### O que `next(e)` fornece a um hook `settings.read`

353 

354`next(e)` resolve para `{ value }` ou para `{ deny }`:

355 

356* **`{ value }`**: `value` são as configurações mescladas, ou as configurações de uma fonte quando [`e.source`](#settings-read-receives) está definido. Se um hook que [é executado depois do seu](#the-order-mods-run-in) retornou um `{ value }` próprio, você recebe o `value` desse hook.

357* **`{ deny }`**: um hook executado depois do seu recusou a leitura. Retorne esse `{ deny }` sem alterações.

358 

359#### Alterar uma configuração a partir de um hook `settings.read`

360 

361Primeiro verifique [quais mods recebem este evento, e a partir de qual versão](#settings-read-hook).

362 

363Para alterar uma chave, espalhe o `value` de [`next(e)`](https://code.claude.com/docs/pt/plugins/mods/reference#the-hook-function) e defina essa chave, como este hook faz com [`spinnerTipsEnabled`](https://code.claude.com/docs/pt/settings-reference#spinnertipsenabled). O hook não verifica [`next.origin`](#settings-read-origin), então ele altera a chave tanto na [leitura do próprio Claude Code](#settings-read-hook) quanto na leitura mesclada de um mod:

364 

365```javascript theme={null}

366on('settings.read', async ($, e, next) => {

367 const read = await next(e)

368 // Pass through a read of one source, so that only the merged settings change.

369 // Pass through a { deny } from a later hook too: it has no value.

370 if (e.source || !read.value) return read

371 // Keep every other key and change this one

372 return { value: { ...read.value, spinnerTipsEnabled: false } }

373})

374```

375 

376Na leitura do próprio Claude Code, se o seu hook retornar um valor fora do esquema da chave, como uma string, apenas essa chave mantém o valor mesclado antes de qualquer hook responder. O log de depuração então informa [`the answer for <key> is no value the key can hold`](https://code.claude.com/docs/pt/plugins/mods/troubleshoot#settings-read-key-refused). Se o seu valor couber e a chave ainda assim não mudar, consulte [por que uma chave retornada não tem efeito](https://code.claude.com/docs/pt/plugins/mods/troubleshoot.md#settings-read-key-no-effect).

377 

308### Tratar os eventos de hooks de configuração378### Tratar os eventos de hooks de configuração

309 379 

310Hooks de configuração são os hooks de comando, HTTP, prompt e agente que você configura em arquivos de configuração. Cada [evento de hook de configuração](https://code.claude.com/docs/pt/hooks.md#hook-events), como `Stop`, `SessionEnd` ou `PostToolUse`, também é um evento nomeado `classic.` seguido do nome do evento de hook de configuração, como `classic.Stop`. `e` é o JSON que um hook de configuração recebe no stdin, incluindo `transcript_path`.380Hooks de configuração são os hooks de comando, HTTP, prompt e agente que você configura em arquivos de configuração. Cada [evento de hook de configuração](https://code.claude.com/docs/pt/hooks.md#hook-events), como `Stop`, `SessionEnd` ou `PostToolUse`, também é um evento nomeado `classic.` seguido do nome do evento de hook de configuração, como `classic.Stop`. `e` é o JSON que um hook de configuração recebe no stdin, incluindo `transcript_path`.

Details

508* **`Input`**: leva `onSubmit(value)` e `onInput(value)`508* **`Input`**: leva `onSubmit(value)` e `onInput(value)`

509* **`Select`**: leva `onSelect(value)` com suas escolhas em `options`, uma lista de pelo menos uma escolha com valores únicos, como `[{ value: 'sm', label: 'Small' }, { value: 'lg', label: 'Large' }]`509* **`Select`**: leva `onSelect(value)` com suas escolhas em `options`, uma lista de pelo menos uma escolha com valores únicos, como `[{ value: 'sm', label: 'Small' }, { value: 'lg', label: 'Large' }]`

510 510 

511Um teste pressiona ou digita em um controle por sua `key`, então dê a cada um uma. Cada uso de um controle também dispara [`ui.press`, `ui.input` ou `ui.select`](https://code.claude.com/docs/pt/plugins/mods/reference#interface) com a `key` em `e.element`, e outro mod pode tratar esses eventos. Seu hook é executado antes de seu callback, então vê o que o usuário digita em seu `Input` e pode alterá-lo ou responder no lugar de seu callback. A API de mods não tem método que pressione o botão de outro mod.511### Quais controles precisam de uma `key`

512 

513Dê a cada `Input` e `Select` uma prop `key`, como `key: 'size'`. Um `Button` pode ficar sem `key` quando tem uma prop `label` ou um único filho de string. Sua key é então o valor de `label` ou essa string.

514 

515Testes e outros mods identificam um controle por sua key:

516 

517* **Testes**: um [teste](https://code.claude.com/docs/pt/plugins/mods/test.md#test-a-drawing) pressiona ou digita em um controle por sua key.

518* **Outros mods**: o Claude Code dispara [`ui.press`, `ui.input` ou `ui.select`](https://code.claude.com/docs/pt/plugins/mods/reference#interface) com a key do controle em `e.element` antes de executar o callback do controle. O hook de outro mod para esse evento vê o que o usuário digitou em seu `Input` e pode alterar esse texto ou impedir que seu callback seja executado. A API de mods não dá a esse mod nenhum método para pressionar seus botões.

519 

520Se uma mensagem disser `needs a key` ou `is drawn twice`, [encontre a causa por essa mensagem](https://code.claude.com/docs/pt/plugins/mods/troubleshoot.md#needs-a-key).

512 521 

513### Foco do teclado e atalhos de teclado522### Foco do teclado e atalhos de teclado

514 523 

Details

21| `.claude-plugin/plugin.json` | Sim | O [manifesto](https://code.claude.com/docs/pt/plugins/manifest-reference.md) do plugin. Mods não adicionam campos obrigatórios. |21| `.claude-plugin/plugin.json` | Sim | O [manifesto](https://code.claude.com/docs/pt/plugins/manifest-reference.md) do plugin. Mods não adicionam campos obrigatórios. |

22| `hooks/hooks.json` | Sim | `modules`: um array com um caminho, relativo a este arquivo, para o módulo de hooks, como em `"modules": ["./register.js"]`. Também pode conter [hooks de configuração](https://code.claude.com/docs/pt/hooks.md) em `hooks`. |22| `hooks/hooks.json` | Sim | `modules`: um array com um caminho, relativo a este arquivo, para o módulo de hooks, como em `"modules": ["./register.js"]`. Também pode conter [hooks de configuração](https://code.claude.com/docs/pt/hooks.md) em `hooks`. |

23| O módulo de hooks, como [`hooks/register.js`](https://code.claude.com/docs/pt/plugins/mods/create#write-a-mod-yourself) | Sim | O ponto de entrada do mod. Exporta `register(on, options)`. Nomeado `.js`, `.mjs`, `.cjs`, `.jsx`, `.ts`, `.mts`, `.cts` ou `.tsx`. Um módulo ES. |23| O módulo de hooks, como [`hooks/register.js`](https://code.claude.com/docs/pt/plugins/mods/create#write-a-mod-yourself) | Sim | O ponto de entrada do mod. Exporta `register(on, options)`. Nomeado `.js`, `.mjs`, `.cjs`, `.jsx`, `.ts`, `.mts`, `.cts` ou `.tsx`. Um módulo ES. |

24| [`types/index.d.ts`](https://code.claude.com/docs/pt/plugins/mods/interface#declare-the-values), indicado por `types` no manifesto | Quando o mod usa `$.state` ou adiciona um namespace à API de mods | Declara os valores de `PluginState` e qualquer namespace que o mod adiciona |24| [`types/index.d.ts`](https://code.claude.com/docs/pt/plugins/mods/interface#declare-the-values), a menos que `types` no manifesto indique outro caminho | Quando o mod usa `$.state` ou adiciona um namespace à API de mods | Declara os valores de `PluginState` e qualquer namespace que o mod adiciona. Para omitir `types` do manifesto, você precisa da v2.1.299 ou posterior. |

25| Arquivos cujos nomes terminam em `.test.ts` ou `.test.tsx` | Não | Testes que o [`claude plugin test`](https://code.claude.com/docs/pt/plugins/mods/test#write-a-test) executa |25| Arquivos cujos nomes terminam em `.test.ts` ou `.test.tsx` | Não | Testes que o [`claude plugin test`](https://code.claude.com/docs/pt/plugins/mods/test#write-a-test) executa |

26 26 

27`register` recebe `on` e `options`. `options` contém os valores dos campos [`userConfig`](https://code.claude.com/docs/pt/plugins/components#user-configuration) que o manifesto declara, com os valores padrão preenchidos.27`register` recebe `on` e `options`. `options` contém os valores dos campos [`userConfig`](https://code.claude.com/docs/pt/plugins/components#user-configuration) que o manifesto declara, com os valores padrão preenchidos.


110 110 

111### Comandos e configuração111### Comandos e configuração

112 112 

113Eventos de comando e de configuração são disparados quando um comando é executado ou listado, e quando uma linha de `/config` é exibida ou alterada:113Eventos de comando e de configuração são disparados quando um comando é executado ou listado, quando uma linha de `/config` é exibida ou alterada, e em uma leitura de configurações:

114 114 

115| Evento | Dispara quando | Um hook pode retornar |115| Evento | Dispara quando | Um hook pode retornar |

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


118| `command.describe` | Uma vez para cada comando, para a lista de comandos | `{ description, argumentHint, isHidden }` |118| `command.describe` | Uma vez para cada comando, para a lista de comandos | `{ description, argumentHint, isHidden }` |

119| `config.set` | Uma linha de `/config` está prestes a mudar | `next({ ...e, value })` ou `{ deny: reason }` |119| `config.set` | Uma linha de `/config` está prestes a mudar | `next({ ...e, value })` ou `{ deny: reason }` |

120| `config.describe` | Uma vez para cada linha de `/config` | `{ label, description, isHidden }` |120| `config.describe` | Uma vez para cada linha de `/config` | `{ label, description, isHidden }` |

121| [`settings.read`](https://code.claude.com/docs/pt/plugins/mods/events#settings-read-hook) | Um mod chama [`$.settings.read`](https://code.claude.com/docs/pt/plugins/mods/api#reach-files-processes-and-the-network), ou o Claude Code monta as configurações mescladas da sessão | `next(e)`, `{ value }` ou `{ deny: reason }` |

122 

123#### `e.layers` e `e.source` em `settings.read`

124 

125* **`e.layers`**: um objeto `{ source, settings }` para cada origem em uso que contém configurações, da menor [precedência](https://code.claude.com/docs/pt/settings.md#settings-precedence) para a maior. Consulte [O que um hook `settings.read` recebe](https://code.claude.com/docs/pt/plugins/mods/events#settings-read-receives).

126* **`e.source`**: a única origem que um mod solicitou, como em `$.settings.read({ source: 'policy' })`. Ausente na leitura do próprio Claude Code e em qualquer outra leitura das configurações mescladas

127 

128Em `settings.read`, o disparo do evento na leitura do próprio Claude Code e o campo `e.layers` exigem o Claude Code v2.1.304 ou posterior. Para saber quando o hook é executado e o que ele pode retornar, com um exemplo, consulte [Alterar ou recusar uma leitura de configurações](https://code.claude.com/docs/pt/plugins/mods/events.md#settings-read-hook).

121 129 

122### Turnos130### Turnos

123 131 

Details

168 168 

169Antes 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.169Antes 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.

170 170 

171### `This mod's change didn't load` ou `the earlier version is no longer running`

172 

173Uma alteração em um [mod que Claude escreveu nesta sessão](https://code.claude.com/docs/pt/plugins/mods/create.md#ask-claude-for-a-mod) não pôde ser carregada. A linha da transcrição começa com o nome do mod e termina com o motivo:

174 

175* `This mod's change didn't load, so the earlier version is still running: <reason>.`

176* `This mod didn't load, and the earlier version is no longer running: <reason>.`

177 

178Claude não vê essa linha, então cole-a na sua próxima mensagem quando pedir uma correção ao Claude.

179 

171### `$.agent.register refused: the hooks module that made the call is no longer loaded`180### `$.agent.register refused: the hooks module that made the call is no longer loaded`

172 181 

173A 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.182A 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.


225 234 

226Leia o motivo nessa linha. As causas comuns são uma prop que o elemento não aceita e um elemento que o aplicativo não tem.235Leia o motivo nessa linha. As causas comuns são uma prop que o elemento não aceita e um elemento que o aplicativo não tem.

227 236 

237### `needs a key`, `is drawn twice` ou `key each once`

238 

239Um elemento na árvore que seu hook `ui.render` retorna não tem uma [`key`](https://code.claude.com/docs/pt/plugins/mods/interface#which-controls-need-a-key) válida, ou dois elementos compartilham a mesma. Encontre a mensagem que você recebeu:

240 

241* **`<Input> needs a key` ou `<Select> needs a key`**: o elemento não tem a prop `key`, ou sua `key` está vazia ou não é uma string, como em `key: 3`. Dê a ele uma string não vazia como `key`.

242* **`<Button> needs a key`**: dê ao botão uma string não vazia como `key`

243* **`is drawn twice; each takes its own key`**: dois elementos do tipo que a mensagem nomeia têm a mesma `key`, como em `Input "size" is drawn twice; each takes its own key`. Dê a cada elemento sua própria `key`.

244* **`key each once` vindo de `press` em um [teste](https://code.claude.com/docs/pt/plugins/mods/test.md#test-a-drawing)**: o desenho tem mais de um botão com a key que você passou. Botões com o mesmo rótulo e sem a prop `key` compartilham esse rótulo como key. Dê a cada botão sua própria `key`.

245 

228### Uma linha `ui.render` diz `threw while drawn`246### Uma linha `ui.render` diz `threw while drawn`

229 247 

230A linha nomeia o [ponto de renderização](https://code.claude.com/docs/pt/plugins/mods/reference.md#render-sites), depois diz `threw while drawn:` e o erro, como em `first-mod: ui.render (ToolUse) threw while drawn: <error>; the engine drew its own`. Claude Code encontrou esse erro ao desenhar a árvore que seu hook [`ui.render`](https://code.claude.com/docs/pt/plugins/mods/reference#interface) retornou, ou ao desenhar o ponto a partir das [`props` que seu hook passou para `next`](https://code.claude.com/docs/pt/plugins/mods/interface#change-what-claude-code-already-draws). O final `the engine drew its own` significa que o ponto mostra o conteúdo usual de Claude Code.248A linha nomeia o [ponto de renderização](https://code.claude.com/docs/pt/plugins/mods/reference.md#render-sites), depois diz `threw while drawn:` e o erro, como em `first-mod: ui.render (ToolUse) threw while drawn: <error>; the engine drew its own`. Claude Code encontrou esse erro ao desenhar a árvore que seu hook [`ui.render`](https://code.claude.com/docs/pt/plugins/mods/reference#interface) retornou, ou ao desenhar o ponto a partir das [`props` que seu hook passou para `next`](https://code.claude.com/docs/pt/plugins/mods/interface#change-what-claude-code-already-draws). O final `the engine drew its own` significa que o ponto mostra o conteúdo usual de Claude Code.


303 321 

304[Carregue o valor salvo novamente](https://code.claude.com/docs/pt/plugins/mods/interface.md#load-a-saved-value-again-after-clear) em um hook `classic.SessionStart`.322[Carregue o valor salvo novamente](https://code.claude.com/docs/pt/plugins/mods/interface.md#load-a-saved-value-again-after-clear) em um hook `classic.SessionStart`.

305 323 

324### Uma chave que seu hook `settings.read` retorna não entra em vigor

325 

326As entradas `env` retornadas não se tornam variáveis de ambiente. As regras `allow`, `ask` e `deny` retornadas não são verificadas nas chamadas de ferramenta. Defina-as em um [arquivo de configurações](https://code.claude.com/docs/pt/settings.md) ou chame [`$.env.set`](https://code.claude.com/docs/pt/plugins/mods/api#reach-files-processes-and-the-network) para variáveis de ambiente.

327 

328Para outra chave, verifique [quais mods recebem `settings.read` e a partir de qual versão](https://code.claude.com/docs/pt/plugins/mods/events#settings-read-hook), depois pesquise `settings.read` no [log de depuração](#read-the-debug-log) e procure uma destas linhas:

329 

330| Linha do log | Significado e etapa |

331| :- | :- |

332| `settings.read hook skipped`, após o nome do seu mod | Seu hook falhou. [Corrija o erro que a linha informa](#hook-skipped). |

333| `settings.read bypassed by cc-plugin-sec-default`, em uma linha que nomeia seu mod antes dela | A [guarda integrada](https://code.claude.com/docs/pt/plugins/mods/admin.md#know-what-happens-by-default) ignorou seu hook. Peça ao administrador da sua organização para [instalar o mod como um dos mods da organização](https://code.claude.com/docs/pt/plugins/mods/admin.md#install-your-organizations-mods). |

334| `settings.read: the answer for <key> is no value the key can hold` | O valor retornado não se ajusta ao esquema da chave. [Retorne um que ele permita](#settings-read-key-refused). |

335| `settings.read: the merge never settles for <key>` | As chaves que a linha nomeia mantêm os valores das fontes de configurações. Defina-as em um arquivo de configurações. |

336| `answered settings.read without next()`, após o nome de um mod | Relevante apenas se esse mod [executar antes do seu](https://code.claude.com/docs/pt/plugins/mods/events.md#the-order-mods-run-in). Nesse caso, seu hook não executou naquela leitura. [Desative esse mod](https://code.claude.com/docs/pt/plugins/mods/overview.md#turn-mods-on-or-off) ou, se sua organização o implantou, peça ao administrador dela que o faça. |

337| `settings.read: refused to the engine` | A leitura foi recusada, então o `{ value }` de nenhum hook foi aplicado. [Descubra o que a recusou](#settings-read-refused). |

338 

339Se nenhuma linha explicar a chave, verifique nos mods que executam antes do seu se há um hook `settings.read` que [altera a chave](https://code.claude.com/docs/pt/plugins/mods/events.md#settings-read-example). Desative esse mod ou peça ao administrador da sua organização que o faça. Se nenhum hook a alterar, defina a chave em um arquivo de configurações.

340 

341### `the answer for <key> is no value the key can hold`

342 

343Esta linha do [log de depuração](#read-the-debug-log) significa que Claude Code recusou o valor que seu hook [`settings.read`](https://code.claude.com/docs/pt/plugins/mods/events#settings-read-hook) retornou para a chave nomeada, e somente para essa chave:

344 

345```text theme={null}

346settings.read: the answer for <key> is no value the key can hold; the settings' own value stands

347```

348 

349O valor que você retornou para a chave nomeada não se ajustou ao esquema dessa chave, por exemplo, por tipo ou por intervalo. Retorne um valor que a entrada da chave na [referência de configurações](https://code.claude.com/docs/pt/settings-reference.md) permita. Enquanto seu valor não se ajustar, a chave mantém o valor mesclado das fontes de configurações antes de qualquer hook responder. A linha o chama de valor próprio das configurações.

350 

351### `settings.read: refused to the engine`

352 

353Esta linha do [log de depuração](#read-the-debug-log) significa que [a leitura do próprio Claude Code](https://code.claude.com/docs/pt/plugins/mods/events.md#settings-read-hook) foi recusada, então o `{ value }` de nenhum hook foi aplicado, incluindo o seu. Quando um hook `settings.read` recusa essa leitura com [`{ deny: reason }`](https://code.claude.com/docs/pt/plugins/mods/events#settings-read-returns), a linha traz o motivo desse hook:

354 

355```text theme={null}

356settings.read: refused to the engine (engine: $.settings.read: <reason>); the settings' own values stand

357```

358 

359Pesquise o texto `<reason>` no código do seu próprio hook:

360 

361* **Seu código o contém**: seu hook recusou a leitura. Faça-o retornar `{ value }` quando [`next.origin`](https://code.claude.com/docs/pt/plugins/mods/events#settings-read-origin) indicar a leitura do próprio Claude Code.

362* **Seu código não o contém**: [desative](https://code.claude.com/docs/pt/plugins/mods/overview.md#turn-mods-on-or-off) seus outros mods um de cada vez. Após cada um, execute novamente o comando desta sessão a partir do seu shell com um `--debug-file` em um novo caminho e pesquise `refused to the engine` nesse arquivo. Se a linha estiver lá, desative o próximo mod. Se não estiver, o último mod que você desativou recusou a leitura, então mantenha-o desativado.

363 

364Sem nenhum outro mod restante, use um [arquivo de configurações](https://code.claude.com/docs/pt/settings.md) para as chaves que seu hook retorna. Os valores dele se mantêm enquanto a leitura é recusada.

365 

306## Leia o log de depuração366## Leia o log de depuração

307 367 

308O log de depuração tem uma linha para cada módulo que Claude Code carrega ou recusa, cada hook que falha e cada resultado que recusa, então é onde procurar quando a transcrição não mostra nada. Para escrever um, em seu shell inicie Claude Code com `--debug`, ou com `--debug-file <path>` para escolher onde ele vai:368O log de depuração tem uma linha para cada módulo que Claude Code carrega ou recusa, cada hook que falha e cada resultado que recusa, então é onde procurar quando a transcrição não mostra nada. Para escrever um, em seu shell inicie Claude Code com `--debug`, ou com `--debug-file <path>` para escolher onde ele vai:

Details

251 251 

252Primeiro verifique o repositório em si: um `owner/repo` digitado errado, um repositório que não existe ou um repositório privado que você não consegue ver também termina nesta mensagem. Abra a URL do repositório no seu navegador, ou execute `git ls-remote <url>` no seu terminal, para confirmar que existe e você tem acesso.252Primeiro verifique o repositório em si: um `owner/repo` digitado errado, um repositório que não existe ou um repositório privado que você não consegue ver também termina nesta mensagem. Abra a URL do repositório no seu navegador, ou execute `git ls-remote <url>` no seu terminal, para confirmar que existe e você tem acesso.

253 253 

254Se o repositório está correto, a causa é credenciais. Claude Code executa git com prompts interativos desabilitados, então não consegue pedir uma senha, uma frase de passagem de chave ou uma credencial da maneira que seu terminal faria. Se git precisa fazer um prompt, você vê `fatal: Cannot prompt because user interactivity has been disabled` ou `terminal prompts disabled` no erro original. Apenas credenciais que já funcionam de forma não-interativa têm sucesso:254Se o repositório está correto, a causa é credenciais. Claude Code desativa os prompts e os programas askpass do git, incluindo um definido em `GIT_ASKPASS`, e executa SSH em modo batch. Quando git precisa fazer um prompt, o erro do clone inclui `fatal: Cannot prompt because user interactivity has been disabled`, `terminal prompts disabled` ou `fatal: unable to get password from user`. Apenas credenciais que git consegue obter sem um prompt ou programa askpass têm sucesso:

255 255 

256* **SSH**: `ssh -T git@<host>` deve ter sucesso sem pedir uma frase de passagem, e o host já deve estar em `known_hosts`256* **SSH**: `ssh -T git@<host>` deve ter sucesso sem pedir uma frase de passagem, e o host já deve estar em `known_hosts`

257* **HTTPS**: seu auxiliar de credencial deve manter um token para o host. Para GitHub, execute `gh auth login` e `gh auth setup-git`. Para outro host, armazene um token de acesso pessoal no seu auxiliar de credencial git. Teste com `git ls-remote <url>`257* **HTTPS**: seu auxiliar de credencial deve manter um token para o host. Para GitHub, execute `gh auth login` e `gh auth setup-git`. Para outro host, armazene um token de acesso pessoal no seu auxiliar de credencial git. Para testar, remova a definição de `GIT_ASKPASS` no seu terminal e execute `git -c core.askPass= ls-remote <url>`.

258 258 

259Uma vez que `git ls-remote` tenha sucesso no seu terminal sem um prompt, execute a adição ou atualização novamente. Uma adição bem-sucedida imprime `Successfully added marketplace: <name>`. Uma atualização bem-sucedida imprime `Successfully updated marketplace: <name>` a partir do seu shell, ou `✔ Updated 1 marketplace` em uma sessão.259Uma vez que a verificação para o seu protocolo tenha sucesso sem um prompt, execute a adição ou atualização novamente. Uma adição bem-sucedida imprime `Successfully added marketplace: <name>`. Uma atualização bem-sucedida imprime `Successfully updated marketplace: <name>` a partir do seu shell, ou `✔ Updated 1 marketplace` em uma sessão.

260 260 

261Para fazer Claude Code pular SSH para fontes GitHub `owner/repo`, defina `CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1`. Sem isso, Claude Code clona essas fontes sobre SSH quando uma chave SSH para `github.com` parece estar configurada, e volta para HTTPS quando o clone SSH falha.261Para fazer Claude Code pular SSH para fontes GitHub `owner/repo`, defina `CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1`. Sem isso, Claude Code clona essas fontes sobre SSH quando uma chave SSH para `github.com` parece estar configurada, e volta para HTTPS quando o clone SSH falha.

262 262 


318 318 

319Se o repositório é um monorepo, limite o checkout aos diretórios que você nomeia com `claude plugin marketplace add <source> --sparse <paths>`.319Se o repositório é um monorepo, limite o checkout aos diretórios que você nomeia com `claude plugin marketplace add <source> --sparse <paths>`.

320 320 

321Se o repositório tem submódulos git grandes, atualize o Claude Code. Na v2.1.295 e posteriores, Claude Code busca apenas os [submódulos que contêm arquivos de plugin](https://code.claude.com/docs/pt/plugins/marketplace-reference.md#git-submodules-in-the-marketplace-repository). Versões anteriores buscam todos os submódulos, o que pode consumir os 120 segundos por si só.

322 

321### Marketplace updates keep failing offline323### Marketplace updates keep failing offline

322 324 

323Você trabalha em um ambiente onde o host git do marketplace é inacessível, e cada sessão repete uma atualização falhada em segundo plano. Seu checkout existente do marketplace permanece no lugar e a inicialização não é atrasada.325Você trabalha em um ambiente onde o host git do marketplace é inacessível, e cada sessão repete uma atualização falhada em segundo plano. Seu checkout existente do marketplace permanece no lugar e a inicialização não é atrasada.


609| `<Plugin or Dependency> "<name>" has conflicting version requirements` | Nenhuma versão satisfaz cada intervalo que a fixa. A mensagem lista os intervalos. | Desinstale ou atualize um dos plugins conflitantes, ou peça ao autor upstream para ampliar sua restrição. |611| `<Plugin or Dependency> "<name>" has conflicting version requirements` | Nenhuma versão satisfaz cada intervalo que a fixa. A mensagem lista os intervalos. | Desinstale ou atualize um dos plugins conflitantes, ou peça ao autor upstream para ampliar sua restrição. |

610| `... has version requirements too complex to intersect` ou `has an invalid version requirement` | Um intervalo não é semver válido, ou os intervalos combinados não conseguem ser intersectados. | Corrija o intervalo inválido ou simplifique cadeias `\|\|` longas. |612| `... has version requirements too complex to intersect` ou `has an invalid version requirement` | Um intervalo não é semver válido, ou os intervalos combinados não conseguem ser intersectados. | Corrija o intervalo inválido ou simplifique cadeias `\|\|` longas. |

611| `... has no git tag satisfying <range>` | O repositório da dependência não tem uma tag `<name>--v*` no intervalo. | Verifique que o upstream marca lançamentos com essa convenção, ou relaxe o intervalo. |613| `... has no git tag satisfying <range>` | O repositório da dependência não tem uma tag `<name>--v*` no intervalo. | Verifique que o upstream marca lançamentos com essa convenção, ou relaxe o intervalo. |

612| `Dependency "<dep>" (required by <plugin>) is in <marketplace>, which is not in the allowlist` | A dependência está em um marketplace diferente, e a resolução entre marketplaces está desligada por padrão. | Instale a dependência você mesmo no mesmo escopo, no seu shell com `claude plugin install <dep>@<marketplace>` mais o `--scope` em que você está instalando o plugin, depois tente novamente. |614| `Dependency "<dep>" (required by <plugin>) is in marketplace "<marketplace>", which is not in the allowlist` | A dependência está em um marketplace diferente, e a resolução entre marketplaces está desligada por padrão. | Instale a dependência você mesmo no mesmo escopo, no seu shell com `claude plugin install <dep>@<marketplace>` mais o `--scope` em que você está instalando o plugin, depois tente novamente. |

613 615 

614Para ver estes programaticamente, execute `claude plugin list --json` no seu shell. Plugins com problemas carregam um campo `errors` com as mensagens e um campo `errorDetails` com um `type` para cada: as três primeiras linhas são `dependency-unsatisfied` e a quarta é `dependency-version-unsatisfied`.616Para ver estes programaticamente, execute `claude plugin list --json` no seu shell. Plugins com problemas carregam um campo `errors` com as mensagens e um campo `errorDetails` com um `type` para cada: as três primeiras linhas são `dependency-unsatisfied` e a quarta é `dependency-version-unsatisfied`.

615 617 


979 981 

980### `${CLAUDE_PLUGIN_ROOT}` shows forward slashes on Windows982### `${CLAUDE_PLUGIN_ROOT}` shows forward slashes on Windows

981 983 

982No Windows, um hook de plugin recebe `${CLAUDE_PLUGIN_ROOT}` como `C:/Users/you/...` em vez de `C:\Users\you\...`, e um script que esperava barras invertidas quebra.984No Windows, um hook de plugin executado através do Git Bash recebe `${CLAUDE_PLUGIN_ROOT}` como `C:/Users/you/...` em vez de `C:\Users\you\...`, e um script que esperava barras invertidas quebra.

983 985 

984Claude Code executa hooks de forma de shell através do Git Bash no Windows e substitui a raiz do plugin na forma Win32 com barra para frente de propósito. Builtins Bash, ferramentas MSYS e binários Windows nativos todos aceitam essa forma.986Com o Git Bash instalado, um [hook de forma de shell](https://code.claude.com/docs/pt/hooks.md#exec-form-and-shell-form) é executado através do Git Bash por padrão. Para um hook executado através do Git Bash, Claude Code passa o caminho com barras para frente para que o Bash não interprete barras invertidas como escapes. Builtins Bash, ferramentas MSYS e binários Windows nativos todos aceitam essa forma.

985 987 

986Se seu script precisa de barras invertidas, mude o hook para uma das formas que mantêm caminhos nativos, descritas em [exec form and shell form](https://code.claude.com/docs/pt/hooks.md#exec-form-and-shell-form):988Se seu script precisa de barras invertidas, mude o hook para uma das formas que mantêm caminhos nativos, descritas em [exec form and shell form](https://code.claude.com/docs/pt/hooks.md#exec-form-and-shell-form):

987 989 


1090 1092 

1091Alternativamente, hospede o marketplace em um repositório git e diga aos usuários para adicioná-lo com a URL do repositório. Para uma fonte git, Claude Code clona o repositório inteiro, então caminhos relativos resolvem. Tipos de fonte estão na [marketplace reference](https://code.claude.com/docs/pt/plugins/marketplace-reference.md).1093Alternativamente, hospede o marketplace em um repositório git e diga aos usuários para adicioná-lo com a URL do repositório. Para uma fonte git, Claude Code clona o repositório inteiro, então caminhos relativos resolvem. Tipos de fonte estão na [marketplace reference](https://code.claude.com/docs/pt/plugins/marketplace-reference.md).

1092 1094 

1095### A root plugin's files from a git submodule are missing after install

1096 

1097Seu plugin está na raiz do marketplace e executa ou lê um arquivo de um submódulo git do repositório. Após a instalação, o diretório do submódulo está vazio. Antes da v2.1.295, Claude Code buscava todos os submódulos, então o diretório era preenchido.

1098 

1099Quando Claude Code clona seu marketplace, ele busca apenas os [submódulos que contêm arquivos de plugin](https://code.claude.com/docs/pt/plugins/marketplace-reference.md#git-submodules-in-the-marketplace-repository). Para um plugin na raiz, ele decide lendo os caminhos na configuração do plugin e o texto dos arquivos do plugin. Ele não consegue ver um caminho que um script constrói enquanto é executado.

1100 

1101Escreva um caminho para o submódulo por extenso onde Claude Code possa lê-lo, como `${CLAUDE_PLUGIN_ROOT}/vendor/tool/run.sh` em um comando de hook. Claude Code então busca todos os submódulos do repositório para esse plugin.

1102 

1093### Marketplace validation errors1103### Marketplace validation errors

1094 1104 

1095Você executou `claude plugin validate .` a partir de seu diretório de marketplace e relatou erros ou avisos no arquivo do marketplace em si.1105Você executou `claude plugin validate .` a partir de seu diretório de marketplace e relatou erros ou avisos no arquivo do marketplace em si.


1121 1131 

1122### `Marketplace source '<source>' is blocked by enterprise policy`1132### `Marketplace source '<source>' is blocked by enterprise policy`

1123 1133 

1124Você executou `/plugin marketplace add`, `update` ou uma instalação, e Claude Code recusou com esta linha. Para uma fonte GitHub ou git, o host segue a fonte entre parênteses, como em `'github:owner/repo' (github.com)`.1134Você executou `/plugin marketplace add`, `update` ou uma instalação, e Claude Code recusou com esta linha.

1125 1135 

1126Seu administrador definiu `blockedMarketplaces` ou `strictKnownMarketplaces` em configurações gerenciadas, e esta fonte não é permitida. Peça ao seu administrador para permitir a fonte, ou adicione uma das fontes permitidas que a mensagem lista.1136Seu administrador definiu `blockedMarketplaces` ou `strictKnownMarketplaces` em configurações gerenciadas, e esta fonte não é permitida. Peça ao seu administrador para permitir a fonte, ou adicione uma das fontes permitidas que a mensagem lista.

1127 1137 

Details

100 100 

101### Turning on fast mode101### Turning on fast mode

102 102 

103Habilitar [fast mode](https://code.claude.com/docs/pt/fast-mode.md) adiciona um cabeçalho de solicitação que faz parte da chave de cache, então a primeira solicitação que Claude Code envia com fast mode ativado lê todo o histórico de conversa sem acertos de cache. Claude Code define esse cabeçalho uma vez quando um turno começa e o mantém durante todo o turno, então quando você ativa fast mode enquanto Claude está trabalhando, a falha de cache do cabeçalho acontece na primeira solicitação do seu próximo turno. Esses tokens de entrada não armazenados em cache são cobrados com [fast mode rates](https://code.claude.com/docs/pt/fast-mode.md#understand-the-cost-tradeoff), é por isso que ativar no início de uma sessão custa menos do que ativar profundamente em uma longa. Se seu modelo atual não suportar fast mode, habilitar fast mode também [muda seu modelo](#switching-models), e essa mudança inicia um cache novo por conta própria a partir da próxima solicitação no turno em execução.103O [modo rápido](https://code.claude.com/docs/pt/fast-mode.md) e a velocidade padrão mantêm caches separados, então depois que você ativa ou desativa o modo rápido, a próxima requisição não pode usar o que a outra velocidade armazenou em cache. Na primeira vez que você ativa o modo rápido em uma conversa, a próxima requisição lê toda a conversa até então sem cache, com as [tarifas do modo rápido](https://code.claude.com/docs/pt/fast-mode.md#understand-the-cost-tradeoff). Para manter esse custo baixo, ative-o no início de uma sessão.

104 104 

105O custo se aplica uma vez por conversa. Após o primeiro turno de fast mode, Claude Code continua enviando o cabeçalho e varia apenas a configuração de velocidade da solicitação, que não faz parte da chave de cache. Desativar fast mode, o [fallback automático para velocidade padrão](https://code.claude.com/docs/pt/fast-mode.md#handle-rate-limits) após um rate limit, e ativá-lo novamente mais tarde mantêm o cache. Se você [ficar sem créditos de uso](https://code.claude.com/docs/pt/fast-mode.md#handle-rate-limits) no meio da sessão, Claude Code tenta novamente cada solicitação de fast mode rejeitada em velocidade padrão da mesma forma, então esse fallback também mantém o cache. `/clear` e `/compact` redefinem isso, já que reconstroem o cache nesses pontos de qualquer forma.105* Se você ativá-lo enquanto Claude está trabalhando, esse turno termina na velocidade padrão, e você paga por qualquer leitura sem cache na primeira requisição do seu próximo turno.

106* Se seu modelo atual não suportar o modo rápido, habilitar o modo rápido também [muda você para o Opus](https://code.claude.com/docs/pt/fast-mode.md#toggle-fast-mode). Essa [mudança de modelo](#switching-models) inicia um cache novo por conta própria a partir da próxima requisição no turno em execução.

107 

108Cada alternância posterior lê sem cache tudo o que a velocidade para a qual você muda não tem em cache. Mudanças de velocidade que Claude Code faz por conta própria, como o [fallback para a velocidade padrão](https://code.claude.com/docs/pt/fast-mode.md#handle-rate-limits) após um rate limit e o retorno ao modo rápido depois, também contam como alternâncias.

106 109 

107### Connecting or removing an MCP server110### Connecting or removing an MCP server

108 111 


184>187>

185> Compaction funciona a seu favor quando o contexto que você descarta é conteúdo que você não precisa mais. Para escolher quando sua sobrecarga acontece, execute `/compact` em uma pausa natural em seu trabalho, como entre tarefas, em vez de esperar que a auto-compactação seja acionada no meio da tarefa. Se você seguiu um caminho que deseja abandonar inteiramente, [`/rewind`](#rewinding-the-conversation) para um turno anterior em vez disso. Rewind trunca de volta para um prefixo que já está armazenado em cache, em vez de construir um novo como compaction faz.188> Compaction funciona a seu favor quando o contexto que você descarta é conteúdo que você não precisa mais. Para escolher quando sua sobrecarga acontece, execute `/compact` em uma pausa natural em seu trabalho, como entre tarefas, em vez de esperar que a auto-compactação seja acionada no meio da tarefa. Se você seguiu um caminho que deseja abandonar inteiramente, [`/rewind`](#rewinding-the-conversation) para um turno anterior em vez disso. Rewind trunca de volta para um prefixo que já está armazenado em cache, em vez de construir um novo como compaction faz.

186 189 

187Se você deixar uma conversa longa ociosa em uma sessão de terminal enquanto ela estiver no [TTL de uma hora](#which-ttl-each-request-gets), Claude Code pode compactá-la pouco antes de o cache expirar. Para desativar a compactação por inatividade, defina [`idleCompaction`](https://code.claude.com/docs/pt/settings-reference#idlecompaction) como `false`, o que requer Claude Code v2.1.290 ou posterior.190Se você deixar uma conversa longa ociosa enquanto ela estiver no [TTL de uma hora](#which-ttl-each-request-gets), Claude Code pode compactá-la. Para desativar a compactação por inatividade, defina [`idleCompaction`](https://code.claude.com/docs/pt/settings-reference#idlecompaction) como `false`, o que requer Claude Code v2.1.290 ou posterior.

188 191 

189### Accumulating many images192### Accumulating many images

190 193 


309 312 

310Em Claude Code, o cache é efetivamente limitado a uma máquina e diretório. O prompt do sistema incorpora seus caminhos de memória automática, e a conversa abre com um anúncio do diretório de trabalho, plataforma, shell e versão do SO. Duas sessões em diretórios diferentes, portanto, constroem prefixos diferentes e perdem o cache uma da outra.313Em Claude Code, o cache é efetivamente limitado a uma máquina e diretório. O prompt do sistema incorpora seus caminhos de memória automática, e a conversa abre com um anúncio do diretório de trabalho, plataforma, shell e versão do SO. Duas sessões em diretórios diferentes, portanto, constroem prefixos diferentes e perdem o cache uma da outra.

311 314 

312Sessões que você executa em paralelo no mesmo diretório constroem prefixos correspondentes e leem o cache uma da outra. Sessões sequenciais compartilham o prefixo apenas quando o snapshot de status git na inicialização corresponde, já que cada conversa também carrega a branch e commits recentes desse snapshot.315* Sessões que você executa em paralelo no mesmo diretório constroem prefixos correspondentes e podem ler o cache uma da outra.

316* Sessões sequenciais compartilham o prefixo apenas quando o snapshot do status do git obtido na inicialização corresponde, já que cada conversa também carrega o branch e os commits recentes desse snapshot.

317 

318O cache de API subjacente é mais amplo. Os caches são isolados entre organizações e, em alguns provedores, [entre workspaces dentro de uma organização](https://platform.claude.com/docs/pt/build-with-claude/prompt-caching#cache-storage-and-sharing). Dentro desses limites, duas requisições compartilham um cache apenas quando seu modelo, [velocidade](#turning-on-fast-mode) e prefixo correspondem.

313 319 

314O cache de API subjacente é mais amplo. Os caches são isolados entre organizações e, em alguns provedores, [entre workspaces dentro de uma organização](https://platform.claude.com/docs/pt/build-with-claude/prompt-caching#cache-storage-and-sharing). Dentro desses limites, quaisquer duas solicitações com o mesmo modelo e prefixo leem o mesmo cache. Para chamadores do Agent SDK executando frotas de processos automatizados, veja [melhorar prompt caching entre usuários e máquinas](https://code.claude.com/docs/pt/agent-sdk/modifying-system-prompts.md#improve-prompt-caching-across-users-and-machines) para mover a localização da memória automática para fora do prompt do sistema e compartilhar a entrada de cache do prompt do sistema entre usuários e máquinas.320Para chamadores do Agent SDK executando frotas de processos automatizados, veja [melhorar o cache de prompt entre usuários e máquinas](https://code.claude.com/docs/pt/agent-sdk/modifying-system-prompts.md#improve-prompt-caching-across-users-and-machines) para mover a localização da memória automática para fora do system prompt.

315 321 

316## Verificar desempenho do cache322## Verificar desempenho do cache

317 323 

Details

179* **Diff de suas alterações**: quando o diretório da sessão está em um repositório git, o painel de diff de um dispositivo conectado mostra suas alterações. Em uma ramificação que tem commits à frente da ramificação padrão do repositório, o painel mostra as alterações desde que a ramificação se dividiu dela, incluindo suas edições não confirmadas. Na ramificação padrão em si, ou em uma ramificação que não está à frente dela, o painel mostra apenas suas alterações não confirmadas.179* **Diff de suas alterações**: quando o diretório da sessão está em um repositório git, o painel de diff de um dispositivo conectado mostra suas alterações. Em uma ramificação que tem commits à frente da ramificação padrão do repositório, o painel mostra as alterações desde que a ramificação se dividiu dela, incluindo suas edições não confirmadas. Na ramificação padrão em si, ou em uma ramificação que não está à frente dela, o painel mostra apenas suas alterações não confirmadas.

180* **Modelo**: quando você escolhe um [modelo](https://code.claude.com/docs/pt/model-config.md) de um dispositivo conectado, Claude Code executa a sessão nesse modelo. Requer Claude Code v2.1.238 ou posterior. Um modelo que você escolhe do controle de modelo do dispositivo se aplica apenas à sessão atual. Quando você envia `/model <name>` do dispositivo para uma sessão interativa, Claude Code também define seu padrão para novas sessões.180* **Modelo**: quando você escolhe um [modelo](https://code.claude.com/docs/pt/model-config.md) de um dispositivo conectado, Claude Code executa a sessão nesse modelo. Requer Claude Code v2.1.238 ou posterior. Um modelo que você escolhe do controle de modelo do dispositivo se aplica apenas à sessão atual. Quando você envia `/model <name>` do dispositivo para uma sessão interativa, Claude Code também define seu padrão para novas sessões.

181* **Nível de esforço**: quando você define o [nível de esforço](https://code.claude.com/docs/pt/model-config.md#adjust-effort-level) de um dispositivo conectado, com `/effort` ou o controle de esforço do dispositivo, Claude Code o aplica à sessão na sua máquina. Se você fixou um nível com `CLAUDE_CODE_EFFORT_LEVEL`, a sessão mantém esse nível, e Claude Code recusa uma escolha diferente do controle de esforço. Escolher um nível do controle de esforço requer Claude Code v2.1.234 ou posterior na sua máquina.181* **Nível de esforço**: quando você define o [nível de esforço](https://code.claude.com/docs/pt/model-config.md#adjust-effort-level) de um dispositivo conectado, com `/effort` ou o controle de esforço do dispositivo, Claude Code o aplica à sessão na sua máquina. Se você fixou um nível com `CLAUDE_CODE_EFFORT_LEVEL`, a sessão mantém esse nível, e Claude Code recusa uma escolha diferente do controle de esforço. Escolher um nível do controle de esforço requer Claude Code v2.1.234 ou posterior na sua máquina.

182* **Reconectando após uma falha de conexão**: execute `/remote-control` para reconectar. Se a compactação reescreveu a conversa ou você alternou conversas com `/resume` enquanto isso, Claude Code arquiva a sessão do servidor que estava usando em vez de deixá-la na lista de sessões. Você ainda pode encontrá-la [filtrando por sessões arquivadas](https://code.claude.com/docs/pt/claude-code-on-the-web.md#archive-sessions). Alternar conversas enquanto um dispositivo ainda está conectado não arquiva a sessão.182* **Reconectando após uma falha de conexão**: execute `/remote-control` para reconectar. Se a compactação reescreveu a conversa ou você alternou conversas com `/resume` enquanto isso, Claude Code arquiva a sessão do servidor que estava usando em vez de deixá-la na lista de sessões. Você ainda pode encontrar essa sessão entre suas [sessões arquivadas](https://code.claude.com/docs/pt/claude-code-on-the-web.md#find-an-archived-session) em claude.ai/code. Alternar conversas enquanto um dispositivo ainda está conectado não arquiva a sessão.

183 183 

184### Ativar Remote Control para todas as sessões184### Ativar Remote Control para todas as sessões

185 185 


401 401 

402## Solução de problemas402## Solução de problemas

403 403 

404### "Remote Control disconnected" ou "Can't reach"

405 

406Em [claude.ai/code](https://claude.ai/code) ou no aplicativo Desktop, **Remote Control disconnected** ou uma mensagem **Can't reach** significa que seu navegador ou aplicativo perdeu o contato com o Claude Code no seu computador. Nenhuma das mensagens informa se o Claude ou um subagente que você estava acompanhando ainda está trabalhando no seu computador. Nesse computador, verifique o estado em que o Claude Code está e siga a etapa correspondente para se reconectar:

407 

408* **Uma sessão interativa mostra `Remote Control disconnected`**: siga [as etapas de reconexão para o motivo que essa linha indica](#session-ended-elsewhere)

409* **O Claude Code está em execução e não mostra nenhuma falha**: uma sessão interativa se reconecta sozinha assim que a máquina estiver ativa e online, então você não precisa fazer nada. Se você usou `claude remote-control`, consulte **Interrupção prolongada da rede** em [Limitações](#limitations)

410* **O Claude Code não está em execução**: [inicie-o novamente e recupere a sessão](#resume-sessions-after-stopping-the-server)

411 

404### "Remote Control requires a claude.ai subscription"412### "Remote Control requires a claude.ai subscription"

405 413 

406Você não está conectado com uma conta claude.ai, ou outra credencial está tendo precedência sobre o seu login. A mensagem assume uma destas formas:414Você não está conectado com uma conta claude.ai, ou outra credencial está tendo precedência sobre o seu login. A mensagem assume uma destas formas:


463* **Com `/remote-control`, `claude --remote-control` ou [conexão automática](#enable-remote-control-for-all-sessions)**: a sessão continua em execução sem o Remote Control, e o Claude Code a arquiva em claude.ai471* **Com `/remote-control`, `claude --remote-control` ou [conexão automática](#enable-remote-control-for-all-sessions)**: a sessão continua em execução sem o Remote Control, e o Claude Code a arquiva em claude.ai

464* **Com `claude remote-control`**: o servidor para e arquiva as sessões que estava servindo, e então encerra472* **Com `claude remote-control`**: o servidor para e arquiva as sessões que estava servindo, e então encerra

465 473 

466Você ainda pode encontrar uma sessão arquivada [filtrando por sessões arquivadas](https://code.claude.com/docs/pt/claude-code-on-the-web.md#archive-sessions).474Para encontrar uma dessas sessões novamente, abra suas [sessões arquivadas](https://code.claude.com/docs/pt/claude-code-on-the-web.md#find-an-archived-session) em claude.ai/code.

467 475 

468O Remote Control não se reconecta sozinho. Para ativá-lo novamente depois que sua organização voltar a permiti-lo, execute `/remote-control` na sessão ou `claude remote-control` no seu shell. Qualquer um dos comandos falha com [`Remote Control is disabled by your organization's policy`](#remote-control-is-disabled-by-your-organizations-policy) até que o Claude Code nesta máquina tenha buscado a política alterada. Uma sessão aberta a busca aproximadamente uma vez por hora. Para descobrir o que está bloqueando o Remote Control, compare o texto completo que o comando imprime com essa entrada.476O Remote Control não se reconecta sozinho. Para ativá-lo novamente depois que sua organização voltar a permiti-lo, execute `/remote-control` na sessão ou `claude remote-control` no seu shell. Qualquer um dos comandos falha com [`Remote Control is disabled by your organization's policy`](#remote-control-is-disabled-by-your-organizations-policy) até que o Claude Code nesta máquina tenha buscado a política alterada. Uma sessão aberta a busca aproximadamente uma vez por hora. Para descobrir o que está bloqueando o Remote Control, compare o texto completo que o comando imprime com essa entrada.

469 477 

routines.md +24 −4

Details

293 293 

294#### Eventos suportados294#### Eventos suportados

295 295 

296Os acionadores do GitHub podem se inscrever em qualquer uma das seguintes categorias de eventos. Dentro de cada categoria, você pode escolher uma ação específica, como `pull_request.opened`, ou reagir a todas as ações da categoria.296Escolha um evento de qualquer uma das seguintes categorias. Dentro de cada categoria, você pode escolher uma ação específica, como `pull_request.opened`, ou reagir a todas as ações da categoria.

297 297 

298| Evento | Aciona quando |298| Evento | Aciona quando |

299| :- | :- |299| :- | :- |

300| Pull request | Um PR é aberto, fechado, atribuído, rotulado, sincronizado ou atualizado de outra forma |300| Pull request | Um PR é aberto, fechado, atribuído, rotulado, sincronizado ou atualizado de outra forma |

301| Release | Um release é criado, publicado, editado ou excluído |301| Release | Um release é criado, publicado, editado ou excluído |

302| Issue | Uma issue é aberta, editada, fechada, reaberta, rotulada, atribuída ou atualizada de outra forma |

302 303 

303#### Filtrar pull requests304#### Filtrar pull requests

304 305 


333 334 

334Clique em qualquer execução para abri-la como uma sessão completa. A partir dela, você pode ver o que Claude fez, revisar alterações, criar um pull request ou continuar a conversa. Cada sessão de execução funciona como qualquer outra sessão: use o menu suspenso ao lado do título da sessão para renomeá-la, arquivá-la ou excluí-la.335Clique em qualquer execução para abri-la como uma sessão completa. A partir dela, você pode ver o que Claude fez, revisar alterações, criar um pull request ou continuar a conversa. Cada sessão de execução funciona como qualquer outra sessão: use o menu suspenso ao lado do título da sessão para renomeá-la, arquivá-la ou excluí-la.

335 336 

336> [!NOTE]337Em **History**, na página de detalhes da tarefa, a linha de cada execução concluída termina com **Error** se a execução falhou, **Cancelled** se foi cancelada, e nenhuma dessas palavras se foi bem-sucedida. O filtro **Status** nomeia esses mesmos três resultados como **Failed**, **Cancelled** e **Succeeded**. Esses resultados indicam como a sessão terminou, e não se Claude concluiu o trabalho descrito no seu prompt, portanto abra a execução e leia sua transcrição para ver o que aconteceu.

337>338 

338> Um status verde na lista de execuções significa que a sessão foi iniciada e encerrada sem erro de infraestrutura. Isso não significa que o trabalho descrito no seu prompt foi bem-sucedido. Abra a execução para ler a transcrição e confirmar o que Claude realmente fez. Requisições de rede bloqueadas, ferramentas de conector ausentes e falhas no próprio trabalho aparecem ali, e não no indicador de status.339* **Succeeded**: a sessão terminou sem que o Claude Code relatasse uma falha. Requisições de rede bloqueadas, ferramentas de conector ausentes e trabalho que Claude não conseguiu concluir aparecem na transcrição, e não na linha

340* **Failed**: a sessão não terminou normalmente. Por exemplo, ela parou inesperadamente, terminou com um erro ou foi arquivada antes de a execução começar

341* **Cancelled**: a execução não falhou, e sua sessão foi arquivada. Se você arquivar a sessão de uma execução bem-sucedida, a execução muda para **Cancelled**. Nada na tarefa precisa ser alterado

342 

343Se um aviso aparecer em **History**, consulte [Avisos "The last run"](#the-last-run-didnt-start).

339 344 

340### Editar e controlar tarefas agendadas345### Editar e controlar tarefas agendadas

341 346 


499 504 

500Um Owner da sua organização Team ou Enterprise provavelmente desativou o botão de alternância **Scheduled tasks (Was Routines)** em [**Organization settings > Capabilities > Remote sessions**](https://claude.ai/admin-settings/capabilities). No Claude Code v2.1.227 ou posterior, o mesmo botão também oculta `/schedule` na CLI. Esta é uma configuração da organização no lado do servidor, portanto não pode ser substituída pela sua configuração local. Peça a um Owner que reative as tarefas agendadas para sua organização.505Um Owner da sua organização Team ou Enterprise provavelmente desativou o botão de alternância **Scheduled tasks (Was Routines)** em [**Organization settings > Capabilities > Remote sessions**](https://claude.ai/admin-settings/capabilities). No Claude Code v2.1.227 ou posterior, o mesmo botão também oculta `/schedule` na CLI. Esta é uma configuração da organização no lado do servidor, portanto não pode ser substituída pela sua configuração local. Peça a um Owner que reative as tarefas agendadas para sua organização.

501 506 

507### Avisos "The last run"

508 

509Quando um aviso em **History** começar com "The last run", encontre-o na primeira coluna e faça o que a linha correspondente indica. O aviso desaparece assim que uma execução posterior for iniciada.

510 

511| Aviso | O que fazer |

512| :- | :- |

513| "The last run didn't start because your organization had reached its limit on cloud sessions running at once." | A tarefa não precisa de nenhuma alteração. Clique em **Run now** mais tarde ou aguarde a próxima execução |

514| "The last run didn't start because its cloud environment couldn't be found or used." | Na página de detalhes da tarefa, abra o menu ao lado do nome dela, selecione **Edit** e localize o [seletor de ambiente na nuvem](#environments-and-network-access). Se ele mostrar **Unavailable environment**, esse ambiente foi arquivado ou não está mais disponível para sua conta; então escolha outro ali e salve suas alterações. Caso contrário, tente novamente com **Run now** na página de detalhes ou escolha outro ambiente no seletor e salve suas alterações |

515| "The last run was blocked because it couldn't access something it needs, or your organization's policy doesn't allow it." | Verifique se o seu [acesso ao GitHub](#repositories-and-branch-permissions) abrange os repositórios da tarefa. Se abranger, pergunte a um [Owner](https://code.claude.com/docs/pt/server-managed-settings.md#access-control) da sua organização Claude se alguma política bloqueia a tarefa |

516| "The last run didn't start because of a problem that's usually temporary." | Clique em **Run now** para tentar novamente ou aguarde a próxima execução |

517| "The last run didn't start because its repository or branch wasn't available." | Verifique no GitHub se cada repositório da tarefa tem o [branch a partir do qual a execução começa](#repositories-and-branch-permissions). Verifique também se o seu [acesso ao GitHub](#repositories-and-branch-permissions) abrange cada repositório e reconecte o GitHub se a sua conexão tiver expirado |

518| "The last run didn't start because some of its settings weren't accepted." | Na página de detalhes da tarefa, abra o menu ao lado do nome dela e selecione **Edit**. A caixa de diálogo não indica qual configuração não foi aceita, então verifique cada uma ali, incluindo o nome, o prompt, o modelo, os repositórios, o ambiente, os conectores e os gatilhos da tarefa |

519| "The last run stopped because a usage limit was reached." | Para saber quando as execuções da tarefa podem começar novamente após um limite de uso, consulte [Uso e limites](#usage-and-limits) |

520| "The last run failed." | Clique em **Run now** para tentar novamente ou aguarde a próxima execução. A execução com falha não tem nenhuma sessão para abrir |

521 

502## Recursos relacionados522## Recursos relacionados

503 523 

504* [`/loop` e agendamento na sessão](https://code.claude.com/docs/pt/scheduled-tasks): agende tarefas locais dentro de uma sessão aberta da CLI524* [`/loop` e agendamento na sessão](https://code.claude.com/docs/pt/scheduled-tasks): agende tarefas locais dentro de uma sessão aberta da CLI

Details

181 181 

182* [Sandboxing](https://code.claude.com/docs/pt/sandboxing.md): configure a ferramenta Bash sandboxed integrada182* [Sandboxing](https://code.claude.com/docs/pt/sandboxing.md): configure a ferramenta Bash sandboxed integrada

183* [Dev container](https://code.claude.com/docs/pt/devcontainer.md): o container de desenvolvimento Docker pré-configurado183* [Dev container](https://code.claude.com/docs/pt/devcontainer.md): o container de desenvolvimento Docker pré-configurado

184* [Security](https://code.claude.com/docs/pt/security.md): o modelo de segurança completo do Claude Code184* [Segurança](https://code.claude.com/docs/pt/security.md): o modelo de segurança completo do Claude Code

185* [Secure deployment](https://code.claude.com/docs/pt/agent-sdk/secure-deployment.md): orientação de isolamento para aplicações do Agent SDK185* [Implantação segura](https://code.claude.com/docs/pt/agent-sdk/secure-deployment.md): orientação de isolamento para aplicações do Agent SDK

186* [Settings](https://code.claude.com/docs/pt/settings-reference.md#sandbox-settings): todas as chaves de configuração de sandbox, incluindo entrega de configurações gerenciadas186* [Configurações](https://code.claude.com/docs/pt/settings-reference.md#sandbox-settings): todas as chaves de configuração de sandbox, incluindo entrega de configurações gerenciadas

sandboxing.md +26 −2

Details

223* **Uma regra de solicitação para o parâmetro**: adicione uma [regra de solicitação](https://code.claude.com/docs/pt/permissions.md#match-by-input-parameter) para `Bash(dangerouslyDisableSandbox:true)` para receber um prompt nas novas tentativas do Bash. Você recebe o prompt também no modo auto e no modo `bypassPermissions`, e a regra tem precedência sobre uma regra de permissão correspondente223* **Uma regra de solicitação para o parâmetro**: adicione uma [regra de solicitação](https://code.claude.com/docs/pt/permissions.md#match-by-input-parameter) para `Bash(dangerouslyDisableSandbox:true)` para receber um prompt nas novas tentativas do Bash. Você recebe o prompt também no modo auto e no modo `bypassPermissions`, e a regra tem precedência sobre uma regra de permissão correspondente

224* **[`permissions.blockReadsOutsideWorkingDirectories`](https://code.claude.com/docs/pt/settings-reference#permissions-blockreadsoutsideworkingdirectories)**: [Ações que nenhum modo aprova automaticamente](https://code.claude.com/docs/pt/permission-modes.md#actions-no-mode-auto-approves) abrange as novas tentativas que solicitam confirmação enquanto ela está ativada224* **[`permissions.blockReadsOutsideWorkingDirectories`](https://code.claude.com/docs/pt/settings-reference#permissions-blockreadsoutsideworkingdirectories)**: [Ações que nenhum modo aprova automaticamente](https://code.claude.com/docs/pt/permission-modes.md#actions-no-mode-auto-approves) abrange as novas tentativas que solicitam confirmação enquanto ela está ativada

225 225 

226Enquanto os comandos forem recusados com uma [mensagem `Sandbox is required`](#commands-refused-with-sandbox-is-required), o Claude Code ignora o parâmetro `dangerouslyDisableSandbox` e também recusa a nova tentativa.

227 

226#### Desativar a nova tentativa com o modo de sandbox estrito228#### Desativar a nova tentativa com o modo de sandbox estrito

227 229 

228Você pode desativar a nova tentativa fora do sandbox definindo `"allowUnsandboxedCommands": false` nas suas [configurações do sandbox](https://code.claude.com/docs/pt/settings-reference.md#sandbox-settings). Com a nova tentativa desativada, o Claude Code ignora o parâmetro `dangerouslyDisableSandbox`. Enquanto o sandbox estiver em execução, os comandos que o Claude executa passam então a ser executados em sandbox, a menos que correspondam a uma entrada de `excludedCommands`. Para impedir que o Claude Code execute comandos fora do sandbox quando o sandbox não puder ser iniciado, defina também [`failIfUnavailable`](https://code.claude.com/docs/pt/settings-reference#sandbox-failifunavailable). A aba **Overrides** de `/sandbox` mostra essa configuração como **Strict sandbox mode**.230Você pode desativar a nova tentativa fora do sandbox definindo `"allowUnsandboxedCommands": false` nas suas [configurações do sandbox](https://code.claude.com/docs/pt/settings-reference.md#sandbox-settings). Com a nova tentativa desativada, o Claude Code ignora o parâmetro `dangerouslyDisableSandbox`. Enquanto o sandbox estiver em execução, os comandos que o Claude executa passam então a ser executados em sandbox, a menos que correspondam a uma entrada de `excludedCommands`. Para impedir que o Claude Code execute comandos fora do sandbox quando o sandbox não puder ser iniciado, defina também [`failIfUnavailable`](https://code.claude.com/docs/pt/settings-reference#sandbox-failifunavailable). A aba **Overrides** de `/sandbox` mostra essa configuração como **Strict sandbox mode**.


899 901 

900### Arquivos somente leitura de 0 bytes aparecem em caminhos de configurações `.claude`, e "Sim, e não pergunte novamente" não salva902### Arquivos somente leitura de 0 bytes aparecem em caminhos de configurações `.claude`, e "Sim, e não pergunte novamente" não salva

901 903 

902No Linux e WSL2, o sandbox mantém uma negação de gravação em um arquivo que ainda não existe criando um espaço reservado somente leitura de 0 bytes lá enquanto um comando em sandbox é executado. O sandbox remove o espaço reservado depois. Se uma sessão for encerrada antes dessa limpeza ser executada, por exemplo por SIGKILL, os espaços reservados permanecem. Sessões posteriores vinculam os espaços reservados como somente leitura novamente a cada início, então uma gravação de configurações como salvar uma escolha de permissão falha em um caminho onde um espaço reservado permanece.904No Linux e WSL2, o sandbox mantém uma negação de gravação em um arquivo que ainda não existe criando um espaço reservado somente leitura de 0 bytes lá enquanto um comando em sandbox é executado. O sandbox remove o espaço reservado depois.

905 

906Um espaço reservado permanece em casos como estes:

907 

908* A sessão é encerrada antes dessa limpeza ser executada, por exemplo por SIGKILL

909* A sessão termina enquanto um comando em sandbox ainda está em execução, como um comando em segundo plano

903 910 

904Execute `claude doctor` no seu terminal para listar os arquivos de espaço reservado restantes. O aviso [`Sandbox mask files left behind at write-deny paths`](https://code.claude.com/docs/pt/errors#stale-sandbox-mask-files-left-by-a-killed-session) nomeia alguns deles e conta o resto. Delete cada arquivo com `rm` enquanto nenhuma outra sessão Claude Code está sendo executada nesse projeto. Antes da v2.1.257, Claude Code deixava os mesmos espaços reservados para trás sem sinalizá-los.911Sessões posteriores vinculam os espaços reservados como somente leitura novamente a cada início, então uma gravação de configurações como salvar uma escolha de permissão falha em um caminho onde um espaço reservado permanece.

912 

913Execute `claude doctor` no seu terminal para listar os arquivos de espaço reservado restantes. O aviso [`Sandbox mask files left behind at write-deny paths`](https://code.claude.com/docs/pt/errors#stale-sandbox-mask-files-left-by-a-killed-session) nomeia alguns deles e conta o resto. Delete cada arquivo com `rm` enquanto nenhuma outra sessão Claude Code está sendo executada nesse projeto. Antes da v2.1.257, Claude Code deixava os mesmos espaços reservados para trás quando uma sessão era encerrada, sem sinalizá-los.

905 914 

906### `git` via SSH falha com o sandbox ativado915### `git` via SSH falha com o sandbox ativado

907 916 


1000 1009 

1001Antes da v2.1.284, o proxy se conectava a qualquer endereço para o qual um nome de host permitido resolvesse.1010Antes da v2.1.284, o proxy se conectava a qualquer endereço para o qual um nome de host permitido resolvesse.

1002 1011 

1012### Comandos são recusados com `Sandbox is required`

1013 

1014Se você exigir o sandbox com [`sandbox.failIfUnavailable`](https://code.claude.com/docs/pt/settings-reference#sandbox-failifunavailable) e ele falhar de uma destas formas depois que o Claude Code iniciar, cada comando em sandbox que o Claude executar será recusado com a mensagem mostrada. A sessão continua em execução, e o comando recusado não é executado sem sandbox:

1015 

1016* **`Sandbox is required but failed to initialize: <reason>`**: o Claude Code iniciou, mas o sandbox então falhou ao inicializar. Siga a etapa que a mensagem indica: `Restart to retry.` ou `Fix the sandbox settings to retry`.

1017* **`Sandbox is required (sandbox.failIfUnavailable) and stopped being available in this session: <reason>`**: no Linux ou WSL2, o sandbox iniciou e o Claude Code então detectou que uma dependência estava ausente. Corrija o que o motivo indica, como [instalar uma dependência ausente](#set-up-linux-and-wsl2), e então reinicie o Claude Code.

1018 

1019Comandos excluídos e comandos que você mesmo digita continuam sendo executados, e o Claude não pode tentar novamente sem sandbox um comando recusado:

1020 

1021* **Comandos excluídos**: comandos que correspondem a uma entrada de [`excludedCommands`](#run-commands-outside-the-sandbox-with-excludedcommands) continuam sendo executados fora do sandbox. Quando um deles grava em um caminho de [`filesystem.allowWrite`](https://code.claude.com/docs/pt/settings-reference#sandbox-filesystem-allowwrite) fora do seu diretório de trabalho, essa gravação passa pelo fluxo de permissão regular. Sob um [sandbox exigido pelo administrador](#repository-settings-under-an-admin-required-sandbox), o Claude Code ignora entradas das configurações do repositório

1022* **Comandos que você digita no [prompt do modo shell `!`](https://code.claude.com/docs/pt/interactive-mode#shell-mode-with-prefix)**: continuam sendo executados fora do sandbox. Em uma [sessão em segundo plano](https://code.claude.com/docs/pt/agent-view.md), eles também são recusados

1023* **Novas tentativas sem sandbox**: o Claude Code ignora o parâmetro `dangerouslyDisableSandbox` de uma [nova tentativa sem sandbox](#the-unsandboxed-retry-escape-hatch)

1024 

1025Em uma sessão Linux com `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` definida, todo comando é executado no sandbox, então comandos excluídos e comandos que você digita também são recusados.

1026 

1003### `/sandbox` falha com `Sandbox settings are overridden by a higher-priority configuration`1027### `/sandbox` falha com `Sandbox settings are overridden by a higher-priority configuration`

1004 1028 

1005`/sandbox` imprime `Error: Sandbox settings are overridden by a higher-priority configuration and cannot be changed locally.` em vez de abrir seu painel quando um [nível de configurações](https://code.claude.com/docs/pt/settings.md#settings-precedence) superior define `sandbox.enabled`, `sandbox.autoAllowBashIfSandboxed` ou `sandbox.allowUnsandboxedCommands`. O painel salva suas escolhas em `.claude/settings.local.json`, e um valor salvo ali não pode sobrescrever esses níveis.1029`/sandbox` imprime `Error: Sandbox settings are overridden by a higher-priority configuration and cannot be changed locally.` em vez de abrir seu painel quando um [nível de configurações](https://code.claude.com/docs/pt/settings.md#settings-precedence) superior define `sandbox.enabled`, `sandbox.autoAllowBashIfSandboxed` ou `sandbox.allowUnsandboxedCommands`. O painel salva suas escolhas em `.claude/settings.local.json`, e um valor salvo ali não pode sobrescrever esses níveis.

Details

783 783 

784Para a ordem em que essas fontes se aplicam, consulte [settings precedence](https://code.claude.com/docs/pt/settings.md#settings-precedence).784Para a ordem em que essas fontes se aplicam, consulte [settings precedence](https://code.claude.com/docs/pt/settings.md#settings-precedence).

785 785 

786Quando o plano de controle da Anthropic fornece uma sessão com [Claude Code hooks](https://code.claude.com/docs/pt/hooks.md), o runner os instala ao lado, não sobre, sua própria configuração. Requer Claude Code v2.1.229 ou posterior.786Quando o plano de controle da Anthropic fornece a uma sessão [hooks do Claude Code](https://code.claude.com/docs/pt/hooks.md), o runner os instala ao lado, e não por cima, da sua própria configuração. Requer Claude Code v2.1.229 ou posterior; runners mais antigos ignoram os hooks fornecidos. Os hooks fornecidos executam `python3`, então instale `python3` na sua [imagem do runner](https://code.claude.com/docs/pt/self-hosted-environments-deploy.md#build-the-runner-image).

787 787 

788* **Onde eles pousam**: o runner escreve cada script de hook fornecido para um subdiretório reservado `hooks/.ccr-launcher/` do diretório de configuração da sessão e registra os scripts em um arquivo de configurações separado que passa para a sessão com `--settings`, deixando o `settings.json` semeado e seus próprios scripts em `hooks/<name>` intocados. O runner recria o subdiretório reservado para cada sessão e não semeia conteúdo do host em `~/.claude/hooks/.ccr-launcher/` em sessões.788* **Onde eles pousam**: o runner escreve cada script de hook fornecido para um subdiretório reservado `hooks/.ccr-launcher/` do diretório de configuração da sessão e registra os scripts em um arquivo de configurações separado que passa para a sessão com `--settings`, deixando o `settings.json` semeado e seus próprios scripts em `hooks/<name>` intocados. O runner recria o subdiretório reservado para cada sessão e não semeia conteúdo do host em `~/.claude/hooks/.ccr-launcher/` em sessões.

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

Details

348 348 

349As receitas abaixo usam `--capacity 4`, para que um contêiner sirva até quatro sessões simultâneas do mesmo owner bloqueado. Isso não fornece o isolamento de contêiner por sessão na [seção de endurecimento](#harden-your-deployment): antes de conectar um ambiente a sistemas de produção, execute as receitas em `--capacity 1` com um contêiner por sessão, ou use [runners sob demanda](https://code.claude.com/docs/pt/self-hosted-environments-configuration.md#on-demand-runners), que também mantêm o segredo do ambiente fora dos hosts que executam sessões. Se você adicionar o [proxy git da Anthropic](#use-the-anthropic-git-proxy) a uma dessas receitas, também altere `--capacity` para `1`.349As receitas abaixo usam `--capacity 4`, para que um contêiner sirva até quatro sessões simultâneas do mesmo owner bloqueado. Isso não fornece o isolamento de contêiner por sessão na [seção de endurecimento](#harden-your-deployment): antes de conectar um ambiente a sistemas de produção, execute as receitas em `--capacity 1` com um contêiner por sessão, ou use [runners sob demanda](https://code.claude.com/docs/pt/self-hosted-environments-configuration.md#on-demand-runners), que também mantêm o segredo do ambiente fora dos hosts que executam sessões. Se você adicionar o [proxy git da Anthropic](#use-the-anthropic-git-proxy) a uma dessas receitas, também altere `--capacity` para `1`.

350 350 

351Este Dockerfile é um ponto de partida mínimo:351Este Dockerfile é um ponto de partida mínimo. Ele instala `python3` porque os [hooks que o plano de controle da Anthropic fornece](https://code.claude.com/docs/pt/self-hosted-environments-configuration.md#how-each-session’s-config-is-assembled) às sessões do Claude Tag, incluindo aquele que faz o Claude publicar sua resposta no Slack, executam `python3`. Mantenha `python3` no `PATH` em qualquer imagem que atenda sessões do Claude Tag:

352 352 

353```dockerfile theme={null}353```dockerfile theme={null}

354FROM debian:bookworm-slim354FROM debian:bookworm-slim

355ARG CLAUDE_CODE_VERSION355ARG CLAUDE_CODE_VERSION

356RUN apt-get update && apt-get install -y --no-install-recommends git curl ca-certificates openssh-client jq \356RUN apt-get update && apt-get install -y --no-install-recommends git curl ca-certificates openssh-client jq python3 \

357 && rm -rf /var/lib/apt/lists/*357 && rm -rf /var/lib/apt/lists/*

358RUN curl -fsSL "https://downloads.claude.ai/claude-code-releases/${CLAUDE_CODE_VERSION:?set with --build-arg CLAUDE_CODE_VERSION}/linux-x64/claude" \358RUN curl -fsSL "https://downloads.claude.ai/claude-code-releases/${CLAUDE_CODE_VERSION:?set with --build-arg CLAUDE_CODE_VERSION}/linux-x64/claude" \

359 -o /usr/local/bin/claude && chmod +x /usr/local/bin/claude359 -o /usr/local/bin/claude && chmod +x /usr/local/bin/claude


363ENTRYPOINT ["claude"]363ENTRYPOINT ["claude"]

364```364```

365 365 

366Troque `linux-x64` por `linux-arm64` se seus nós forem ARM, ou por `linux-x64-musl` ou `linux-arm64-musl` em uma imagem baseada em musl, como Alpine; consulte [Configuração Alpine Linux](https://code.claude.com/docs/pt/setup.md#alpine-linux-and-musl-based-distributions) para os pacotes extras que imagens musl precisam. A URL é o local de lançamento padrão do Claude Code, para que você possa verificar o binário baixado contra o manifesto assinado do lançamento conforme descrito em [Integridade binária e assinatura de código](https://code.claude.com/docs/pt/setup.md#binary-integrity-and-code-signing). O runner requer Claude Code versão 2.1.224 ou posterior. Construa a imagem, depois envie-a para seu registro e a referencie nas receitas abaixo:366Troque `linux-x64` por `linux-arm64` se seus nós forem ARM, ou por `linux-x64-musl` ou `linux-arm64-musl` em uma imagem baseada em musl, como Alpine; consulte [Configuração Alpine Linux](https://code.claude.com/docs/pt/setup.md#alpine-linux-and-musl-based-distributions) para os pacotes extras que imagens musl precisam. A URL é o local de lançamento padrão do Claude Code, para que você possa verificar o binário baixado contra o manifesto assinado do lançamento conforme descrito em [Integridade binária e assinatura de código](https://code.claude.com/docs/pt/setup.md#binary-integrity-and-code-signing). O runner requer Claude Code versão 2.1.224 ou posterior, ou 2.1.229 ou posterior para atender sessões do Claude Tag. Construa a imagem, depois envie-a para seu registro e a referencie nas receitas abaixo:

367 367 

368```bash theme={null}368```bash theme={null}

369docker build \369docker build \


768 * **Com um hook `checkout`**: repositórios obtidos por meio de um [hook de ciclo de vida `checkout`](https://code.claude.com/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`](https://code.claude.com/docs/pt/self-hosted-environments-configuration#post-session).768 * **Com um hook `checkout`**: repositórios obtidos por meio de um [hook de ciclo de vida `checkout`](https://code.claude.com/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`](https://code.claude.com/docs/pt/self-hosted-environments-configuration#post-session).

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

770 * **Alterações sem commit ainda são perdidas**: para solicitar que Claude faça commit e push quando terminar de responder, consulte [Solicitar que as sessões enviem seu trabalho](https://code.claude.com/docs/pt/self-hosted-environments-configuration.md#prompt-sessions-to-push-their-work)770 * **Alterações sem commit ainda são perdidas**: para solicitar que Claude faça commit e push quando terminar de responder, consulte [Solicitar que as sessões enviem seu trabalho](https://code.claude.com/docs/pt/self-hosted-environments-configuration.md#prompt-sessions-to-push-their-work)

771* **Um comando interrompido por um runner perdido pode ser executado novamente**: quando a sessão é retomada em outro runner, Claude vê a chamada de ferramenta interrompida com um resultado informando que seu desfecho é desconhecido.

771* **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.772* **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.

772* **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.773* **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.

773* **Quando alguém arquiva ou exclui uma sessão, ou libera seu runner a partir do menu da sessão**: não conte com o push de [`--push-outcome-on-release`](https://code.claude.com/docs/pt/self-hosted-environments-reference#runner-cli-flags). Para salvar commits nesses casos, faça push de `HEAD` para um branch de resgate a partir de um [hook `post-session`](https://code.claude.com/docs/pt/self-hosted-environments-configuration#post-session). Se você partir do exemplo ali, faça-o fazer push mesmo quando não houver nada sem commit, porque ele faz push apenas após um commit de snapshot.774* **Quando alguém arquiva ou exclui uma sessão, ou libera seu runner a partir do menu da sessão**: não conte com o push de [`--push-outcome-on-release`](https://code.claude.com/docs/pt/self-hosted-environments-reference#runner-cli-flags). Para salvar commits nesses casos, faça push de `HEAD` para um branch de resgate a partir de um [hook `post-session`](https://code.claude.com/docs/pt/self-hosted-environments-configuration#post-session). Se você partir do exemplo ali, faça-o fazer push mesmo quando não houver nada sem commit, porque ele faz push apenas após um commit de snapshot.


824 Depois que o runner for atualizado ou a causa for corrigida, tente novamente a sessão ou inicie uma nova. Se nenhuma dessas verificações encontrar a causa, [relate um problema](#report-an-issue).825 Depois que o runner for atualizado ou a causa for corrigida, tente novamente a sessão ou inicie uma nova. Se nenhuma dessas verificações encontrar a causa, [relate um problema](#report-an-issue).

825 826 

826 Para a fonte para a qual a sessão envia resultados, um branch excluído faz a sessão falhar. Para uma fonte git que a sessão apenas lê, o runner pula essa fonte e continua nas restantes. O runner faz a sessão falhar quando pular a deixaria sem nenhum repositório. Antes da v2.1.228, tal sessão começava em um diretório vazio.827 Para a fonte para a qual a sessão envia resultados, um branch excluído faz a sessão falhar. Para uma fonte git que a sessão apenas lê, o runner pula essa fonte e continua nas restantes. O runner faz a sessão falhar quando pular a deixaria sem nenhum repositório. Antes da v2.1.228, tal sessão começava em um diretório vazio.

828* **O Claude Tag às vezes não publica sua resposta no Slack**: o lembrete de resposta é um [hook que o plano de controle fornece](https://code.claude.com/docs/pt/self-hosted-environments-configuration.md#how-each-session’s-config-is-assembled). Confirme que o runner é o Claude Code v2.1.229 ou posterior com `claude --version`, já que runners mais antigos ignoram os hooks fornecidos; confirme que `python3 --version` é bem-sucedido dentro da imagem do runner, já que os hooks executam `python3`; e confirme que nenhum arquivo de configurações desativa os hooks, seja `disableAllHooks` em `managed-settings.json`, no `~/.claude/settings.json` do usuário do runner ou no `.claude/settings.json` ou `.claude/settings.local.json` do repositório, ou `allowManagedHooksOnly` ou um [`strictPluginOnlyCustomization`](https://code.claude.com/docs/pt/settings-reference#strictpluginonlycustomization) que abranja hooks nas configurações gerenciadas.

827* **Uma sessão inicia sem um de seus repositórios**: em um runner sem um [hook `checkout`](https://code.claude.com/docs/pt/self-hosted-environments-configuration#checkout), o host git pode recusar a verificação de acesso do runner para um repositório que a sessão apenas lê. O runner então pula esse repositório, registra uma linha `[runner:warn] could not access context source` nomeando a recusa e inicia a sessão nos restantes.829* **Uma sessão inicia sem um de seus repositórios**: em um runner sem um [hook `checkout`](https://code.claude.com/docs/pt/self-hosted-environments-configuration#checkout), o host git pode recusar a verificação de acesso do runner para um repositório que a sessão apenas lê. O runner então pula esse repositório, registra uma linha `[runner:warn] could not access context source` nomeando a recusa e inicia a sessão nos restantes.

828 830 

829 O runner pula apenas uma recusa clara: o host responde que o repositório não foi encontrado, git não encontra credenciais para o host, ou a autenticação falha. Uma falha de rede, um timeout ou um HTTP `403` ainda falha no início da sessão, assim como uma recusa para um repositório para o qual a sessão envia resultados. O runner ainda falha em uma sessão que pular deixaria sem nenhum repositório. Com [`--use-anthropic-git-proxy`](#use-the-anthropic-git-proxy), o runner pula apenas um repositório que o proxy git em si nega.831 O runner pula apenas uma recusa clara: o host responde que o repositório não foi encontrado, git não encontra credenciais para o host, ou a autenticação falha. Uma falha de rede, um timeout ou um HTTP `403` ainda falha no início da sessão, assim como uma recusa para um repositório para o qual a sessão envia resultados. O runner ainda falha em uma sessão que pular deixaria sem nenhum repositório. Com [`--use-anthropic-git-proxy`](#use-the-anthropic-git-proxy), o runner pula apenas um repositório que o proxy git em si nega.

Details

35 35 

36Instale no host antes de começar:36Instale no host antes de começar:

37 37 

38* **Claude Code v2.1.224 ou posterior**, com qualquer um dos [métodos de instalação padrão](https://code.claude.com/docs/pt/setup.md). O runner faz parte do binário `claude` padrão, e versões anteriores não reconhecem o subcomando `self-hosted-runner`. Para fixar a versão exata que sua frota executa, consulte [Instalar uma versão específica](https://code.claude.com/docs/pt/setup.md#install-a-specific-version). Para imagens de container, consulte o Dockerfile em [Implantar em produção](https://code.claude.com/docs/pt/self-hosted-environments-deploy.md#build-the-runner-image).38* **Claude Code v2.1.224 ou posterior**, com qualquer um dos [métodos de instalação padrão](https://code.claude.com/docs/pt/setup.md). O runner faz parte do binário `claude` padrão, e versões anteriores não reconhecem o subcomando `self-hosted-runner`. Um runner que atende sessões do Claude Tag precisa da v2.1.229 ou posterior e de `python3` no seu `PATH`, já que os [hooks que o plano de controle fornece](https://code.claude.com/docs/pt/self-hosted-environments-configuration.md#how-each-session’s-config-is-assembled) para essas sessões executam `python3`. Para fixar a versão exata que sua frota executa, consulte [Instalar uma versão específica](https://code.claude.com/docs/pt/setup.md#install-a-specific-version). Para imagens de container, consulte o Dockerfile em [Implantar em produção](https://code.claude.com/docs/pt/self-hosted-environments-deploy.md#build-the-runner-image).

39* **Git 2.24 ou mais recente**. Algumas opções git na página de implantação precisam de versões mais recentes; [Configurar git](https://code.claude.com/docs/pt/self-hosted-environments-deploy.md#configure-git) declara cada limite.39* **Git 2.24 ou mais recente**. Algumas opções git na página de implantação precisam de versões mais recentes; [Configurar git](https://code.claude.com/docs/pt/self-hosted-environments-deploy.md#configure-git) declara cada limite.

40 40 

41Confirme que o host está pronto:41Confirme que o host está pronto:

Details

52| `--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](https://code.claude.com/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. |52| `--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](https://code.claude.com/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. |

53| `--server-auto-mode-lists <mode>` | `SELF_HOSTED_RUNNER_SERVER_AUTO_MODE_LISTS` | `no-allow` | Quais das listas de regras do classificador do [modo auto](https://code.claude.com/docs/pt/permission-modes.md#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. |53| `--server-auto-mode-lists <mode>` | `SELF_HOSTED_RUNNER_SERVER_AUTO_MODE_LISTS` | `no-allow` | Quais das listas de regras do classificador do [modo auto](https://code.claude.com/docs/pt/permission-modes.md#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. |

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

55| `--startup-timeout-min <n>` | `SELF_HOSTED_RUNNER_STARTUP_TIMEOUT_MS` | `15` | Libere um slot de sessão se o filho não tiver sinalizado no [canal de atividade](https://code.claude.com/docs/pt/self-hosted-environments-configuration.md#keep-stdin-and-file-descriptor-3-attached) que inicializou dentro de N minutos. Os N minutos começam na geração, após a clonagem, e recomeçam a cada mensagem `user` ou `assistant` que o filho emite antes de ter inicializado ou relatado seu estado. Antes da v2.1.299, este timeout deixava de se aplicar na primeira mensagem desse tipo da sessão. Para liberação após o sinal de inicialização, consulte `--release-idle-session-min`. `0` desabilita. |55| `--startup-timeout-min <n>` | `SELF_HOSTED_RUNNER_STARTUP_TIMEOUT_MS` | `15` | Quanto tempo aguardar por um processo filho que não inicializou antes de liberar o slot da sessão. Consulte [Timeout de inicialização da sessão](#session-startup-timeout) para saber onde a contagem começa e quais sessões ela deixa em execução. `0` desabilita o timeout. |

56| `--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](https://code.claude.com/docs/pt/self-hosted-environments-deploy.md#harden-your-deployment) as verifica independentemente deste sinalizador. |56| `--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](https://code.claude.com/docs/pt/self-hosted-environments-deploy.md#harden-your-deployment) as verifica independentemente deste sinalizador. |

57| `--use-anthropic-git-proxy` | `CLAUDE_RUNNER_USE_GIT_PROXY=1` | desligado | Clone repositórios no github.com via [proxy git da Anthropic](https://code.claude.com/docs/pt/self-hosted-environments-deploy.md#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. |57| `--use-anthropic-git-proxy` | `CLAUDE_RUNNER_USE_GIT_PROXY=1` | desligado | Clone repositórios no github.com via [proxy git da Anthropic](https://code.claude.com/docs/pt/self-hosted-environments-deploy.md#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. |

58 58 


61* **Sinalizador**: a inicialização falha com um erro.61* **Sinalizador**: a inicialização falha com um erro.

62* **Variável de ambiente**: o executor fixa o valor ao teto do temporizador em vez de rejeitá-lo.62* **Variável de ambiente**: o executor fixa o valor ao teto do temporizador em vez de rejeitá-lo.

63 63 

64### Timeout de inicialização da sessão

65 

66Se uma sessão perdeu seu slot durante um turno como `/code-review`, atualize o executor e o binário filho para a v2.1.309 ou posterior. Da v2.1.299 até a v2.1.308, o executor liberava uma sessão, mesmo no meio de um turno, assim que o timeout de inicialização passava sem uma mensagem `user` ou `assistant`.

67 

68Com `--startup-timeout-min <n>`, o executor libera o slot de uma sessão quando seu filho não inicializou dentro de `<n>` minutos após a clonagem. Durante um turno que começa antes de o filho inicializar, a sessão mantém seu slot até que `<n>` minutos se passem sem nenhuma linha no [canal de atividade](https://code.claude.com/docs/pt/self-hosted-environments-configuration.md#keep-stdin-and-file-descriptor-3-attached) do filho. Assim que o filho inicializa, o executor zera essa contagem e `--release-idle-session-min` governa a liberação. Para limitar uma sessão cujo filho está vivo, mas travado, defina `--kill-session-after-min`.

69 

64### Listas de regras do modo auto70### Listas de regras do modo auto

65 71 

66`--server-auto-mode-lists` permite que você decida quais regras do classificador do [modo auto](https://code.claude.com/docs/pt/permission-modes.md#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`--server-auto-mode-lists` permite que você decida quais regras do classificador do [modo auto](https://code.claude.com/docs/pt/permission-modes.md#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`:


375 381 

376#### Associar as métricas de uma sessão às do executor382#### Associar as métricas de uma sessão às do executor

377 383 

378Para colocar as métricas próprias de uma sessão ao lado de `claude_code_self_hosted_runner_session_idle_seconds`, faça a junção pelo `session_id` do executor:384Para ver quanto as sessões ociosas custaram, faça a junção de `claude_code_self_hosted_runner_session_idle_seconds` do executor com a métrica de custo do Claude Code por `ccr_session_id`. A métrica do executor não carrega esse rótulo, então atribua-o com `label_replace`, como nesta consulta:

385 

386```text theme={null}

387sum by (ccr_session_id) (claude_code_cost_usage_total)

388and on (ccr_session_id)

389label_replace(

390 claude_code_self_hosted_runner_session_idle_seconds > 600,

391 "ccr_session_id", "cse_$1", "session_id", "session_(.*)"

392)

393```

394 

395A consulta retorna um resultado por sessão ociosa há mais de dez minutos: o custo em dólares americanos que seu processo do Claude Code contabilizou até agora. Para fazer a junção com outra métrica do Claude Code, substitua `claude_code_cost_usage_total` na consulta. A consulta funciona com qualquer `--capacity`.

379 396 

380* **Em `--capacity` acima de um**: faça a junção diretamente. No `/metrics` do executor, as séries da sessão carregam o mesmo `session_id` que essa métrica, no formato `session_...`.397* **`session_id`**: na porta 9464, esse rótulo nas métricas do Claude Code contém o próprio [`session.id`](https://code.claude.com/docs/pt/monitoring-usage#standard-attributes) do Claude Code, que não corresponde a nenhuma série do executor. Uma junção por ele não retorna nada, então faça a junção por `ccr_session_id`.

381* **Em `--capacity 1`**: faça a junção por um `ccr_session_id` convertido. Por padrão, cada métrica do Claude Code na porta 9464 carrega esse rótulo, que contém o ID da sessão no formato `cse_...`. Em um novo rótulo, substitua seu prefixo `cse_` por `session_` para obter o `session_id` do executor. O próprio `session_id` da métrica contém o [`session.id`](https://code.claude.com/docs/pt/monitoring-usage#standard-attributes) do próprio Claude Code, que não corresponde a nenhuma série do executor.398* **As métricas do Claude Code não têm `ccr_session_id`**: verifique se [`OTEL_METRICS_INCLUDE_SESSION_ID`](https://code.claude.com/docs/pt/monitoring-usage#metrics-cardinality-control) não está definido como `false`

382 399 

383### Semântica do contador de ciclo de vida da sessão400### Semântica do contador de ciclo de vida da sessão

384 401 

Details

117| [`gcpAuthRefresh`](#gcpauthrefresh) | Atualize as [credenciais do Google Cloud](https://code.claude.com/docs/pt/google-vertex-ai.md#advanced-credential-configuration) com seu próprio comando | Autenticação e provedores | Any file |117| [`gcpAuthRefresh`](#gcpauthrefresh) | Atualize as [credenciais do Google Cloud](https://code.claude.com/docs/pt/google-vertex-ai.md#advanced-credential-configuration) com seu próprio comando | Autenticação e provedores | Any file |

118| [`hooks`](#hooks) | Execute seus próprios comandos como [hooks](https://code.claude.com/docs/pt/hooks.md) em pontos do ciclo de vida de Claude Code | Hooks e automação | Any file |118| [`hooks`](#hooks) | Execute seus próprios comandos como [hooks](https://code.claude.com/docs/pt/hooks.md) em pontos do ciclo de vida de Claude Code | Hooks e automação | Any file |

119| [`httpHookAllowedEnvVars`](#httphookallowedenvvars) | Limite quais variáveis de ambiente os [hooks HTTP](https://code.claude.com/docs/pt/hooks.md) podem colocar em cabeçalhos | Hooks e automação | Any file |119| [`httpHookAllowedEnvVars`](#httphookallowedenvvars) | Limite quais variáveis de ambiente os [hooks HTTP](https://code.claude.com/docs/pt/hooks.md) podem colocar em cabeçalhos | Hooks e automação | Any file |

120| [`idleCompaction`](#idlecompaction) | Impeça Claude Code de compactar uma conversa longa enquanto sua sessão de terminal está ociosa | Memória e contexto | Any file |120| [`idleCompaction`](#idlecompaction) | Impeça Claude Code de compactar uma conversa longa da qual você se afastou | Memória e contexto | Any file |

121| [`includeCoAuthoredBy`](#includecoauthoredby) | Descontinuado; use `attribution` para ocultar ou alterar a atribuição de commit e PR | Git e atribuição | Any file |121| [`includeCoAuthoredBy`](#includecoauthoredby) | Descontinuado; use `attribution` para ocultar ou alterar a atribuição de commit e PR | Git e atribuição | Any file |

122| [`includeGitInstructions`](#includegitinstructions) | Remova as instruções de commit e PR integradas do contexto de Claude | Git e atribuição | Any file |122| [`includeGitInstructions`](#includegitinstructions) | Remova as instruções de commit e PR integradas do contexto de Claude | Git e atribuição | Any file |

123| [`inputNeededNotifEnabled`](#inputneedednotifenabled) | Receba uma [notificação push](https://code.claude.com/docs/pt/remote-control.md#mobile-push-notifications) quando Claude estiver esperando por você | Remoto, desktop e notificações | Any file |123| [`inputNeededNotifEnabled`](#inputneedednotifenabled) | Receba uma [notificação push](https://code.claude.com/docs/pt/remote-control.md#mobile-push-notifications) quando Claude estiver esperando por você | Remoto, desktop e notificações | Any file |


1229Em uma plataforma que o sandbox não suporta, Claude Code não inicia com essa chave ativada. Consulte [Enforce sandboxing with managed settings](https://code.claude.com/docs/pt/sandboxing.md#enforce-sandboxing-with-managed-settings).1229Em uma plataforma que o sandbox não suporta, Claude Code não inicia com essa chave ativada. Consulte [Enforce sandboxing with managed settings](https://code.claude.com/docs/pt/sandboxing.md#enforce-sandboxing-with-managed-settings).

1230 1230 

1231* **Scope**: [`Any file`](#scopes), com [limites em configurações de projeto e locais](https://code.claude.com/docs/pt/sandboxing.md#repository-settings-under-an-admin-required-sandbox)1231* **Scope**: [`Any file`](#scopes), com [limites em configurações de projeto e locais](https://code.claude.com/docs/pt/sandboxing.md#repository-settings-under-an-admin-required-sandbox)

1232* **Type**: Boolean1232* **Tipo**: booleano

1233 * `true`: Claude Code sai com um erro na inicialização quando `sandbox.enabled` é `true` mas o sandbox não consegue iniciar1233 * `true`: o Claude Code encerra com um erro na inicialização quando `sandbox.enabled` é `true`, mas o sandbox não consegue iniciar. Se o sandbox passar nessa verificação e depois falhar ao inicializar, a sessão continua em execução e o Claude Code [recusa cada comando no sandbox](https://code.claude.com/docs/pt/sandboxing.md#commands-refused-with-sandbox-is-required)

1234 * `false`: Claude Code executa comandos sem sandbox quando o sandbox não consegue iniciar1234 * `false`: o Claude Code executa os comandos fora do sandbox quando o sandbox não consegue iniciar

1235* **Default**: `false`1235* **Default**: `false`

1236 1236 

1237Isso faz com que cada máquina gerenciada faça sandbox dos comandos ou recuse iniciar:1237Isto ativa o sandbox nas máquinas gerenciadas e define `failIfUnavailable` como `true`:

1238 1238 

1239```json managed-settings.json theme={null}1239```json managed-settings.json theme={null}

1240{1240{


2415 2415 

2416### `idleCompaction`2416### `idleCompaction`

2417 2417 

2418A compactação em ociosidade [compacta](https://code.claude.com/docs/pt/context-window.md#what-survives-compaction) uma conversa longa da qual você se afastou, pouco antes de o cache de prompt dela expirar. Sua próxima mensagem então envia um resumo em vez da conversa inteira. Quando você volta, a conversa mostra uma linha que começa com `Compacted while idle, before the prompt cache expired`.2418A compactação em ociosidade [compacta](https://code.claude.com/docs/pt/context-window.md#what-survives-compaction) uma conversa longa da qual você se afastou. Sua próxima mensagem então envia um resumo em vez da conversa inteira. Depois de compactada, a conversa mostra um aviso:

2419 

2420* **Terminal**: uma linha que começa com `Compacted while idle, before the prompt cache expired`

2421* **[Painel de chat do VS Code](#idle-compaction-in-vs-code-and-the-desktop-app)**: um aviso que inclui `a summary written while you were away`

2422* **[Aplicativo desktop](#idle-compaction-in-vs-code-and-the-desktop-app)**: o mesmo aviso, dentro de uma linha cujo rótulo inclui `Claude Code notice`. Se você não vir essa linha ou o texto dela, mude para o [modo de visualização Verbose](https://code.claude.com/docs/pt/desktop.md#switch-view-modes).

2419 2423 

2420A compactação em ociosidade fica ativada por padrão para conversas que atendem a todas estas condições:2424A compactação em ociosidade fica ativada por padrão para conversas que atendem a todas estas condições:

2421 2425 

2422* **Sessão**: você está em uma sessão interativa no terminal2426* **Sessão**: você está em uma sessão interativa no terminal, ou no painel de chat da extensão do VS Code ou na aba Code do aplicativo desktop em uma [conta selecionada pela Anthropic](#idle-compaction-in-vs-code-and-the-desktop-app)

2423* **Compactação automática**: [`autoCompactEnabled`](#autocompactenabled) está ativada2427* **Compactação automática**: [`autoCompactEnabled`](#autocompactenabled) está ativada

2424* **Cache de prompt**: a conversa está no [TTL de cache de prompt de uma hora](https://code.claude.com/docs/pt/prompt-caching.md#which-ttl-each-request-gets)2428* **Cache de prompt**: a conversa está no [TTL de cache de prompt de uma hora](https://code.claude.com/docs/pt/prompt-caching.md#which-ttl-each-request-gets)

2425* **Feature flags**: o Claude Code consegue [buscar feature flags da Anthropic](https://code.claude.com/docs/pt/env-vars.md#features-that-need-feature-flag-fetching)2429* **Feature flags**: o Claude Code consegue [buscar feature flags da Anthropic](https://code.claude.com/docs/pt/env-vars.md#features-that-need-feature-flag-fetching)


2441}2445}

2442```2446```

2443 2447 

2444Para desativar ou ativar a compactação em ociosidade de dentro de uma sessão, execute `/config` e altere a linha **Idle compaction**. Sua escolha é salva nas suas configurações de usuário e se aplica imediatamente. A linha requer o Claude Code v2.1.302 ou posterior. Se você executa uma dessas versões e o `/config` não mostra a linha, verifique estas causas:2448Para desativar ou ativar a compactação em ociosidade de dentro de uma sessão no terminal, execute `/config` e altere a linha **Idle compaction**. Sua escolha é salva nas suas configurações de usuário e se aplica imediatamente. A linha requer o Claude Code v2.1.302 ou posterior. Se você executa uma dessas versões e o `/config` não mostra a linha, verifique estas causas:

2445 2449 

2446* **Outra fonte de configurações define a chave**: um valor nas configurações gerenciadas, na flag `--settings` ou em um arquivo de configurações de projeto ou local sobrescreve suas configurações de usuário. Altere a chave nessa fonte2450* **Outra fonte de configurações define a chave**: um valor nas configurações gerenciadas, na flag `--settings` ou em um arquivo de configurações de projeto ou local sobrescreve suas configurações de usuário. Altere a chave nessa fonte

2447* **Feature flags indisponíveis**: onde o Claude Code não consegue [buscar feature flags da Anthropic](https://code.claude.com/docs/pt/env-vars.md#features-that-need-feature-flag-fetching), a compactação em ociosidade não é executada, então não há nada para desativar2451* **Feature flags indisponíveis**: onde o Claude Code não consegue [buscar feature flags da Anthropic](https://code.claude.com/docs/pt/env-vars.md#features-that-need-feature-flag-fetching), a compactação em ociosidade não é executada, então não há nada para desativar


2462}2466}

2463```2467```

2464 2468 

2469#### Compactação em ociosidade no VS Code e no aplicativo desktop

2470 

2471Um aviso como este significa que o Claude Code [substituiu sua conversa anterior por um resumo](https://code.claude.com/docs/pt/context-window.md#what-survives-compaction) a partir do qual o Claude agora trabalha:

2472 

2473```text theme={null}

2474Compacted using a summary written while you were away · turn off with "idleCompaction": false in settings.json

2475```

2476 

2477Você não precisa fazer nada. Para desativar a compactação em ociosidade, defina `idleCompaction` como `false` em `~/.claude/settings.json` ou em outro [arquivo de configurações](https://code.claude.com/docs/pt/settings.md#settings-files-and-who-they-affect).

2478 

2479No painel de chat da extensão do VS Code e na aba Code do aplicativo desktop, a compactação em ociosidade é executada para contas selecionadas pela Anthropic. O Claude Code escreve o resumo enquanto você está ausente e só compacta com ele se sua próxima mensagem chegar uma hora ou mais depois da última requisição.

2480 

2465### `plansDirectory`2481### `plansDirectory`

2466 2482 

2467Escolhe onde o Claude Code armazena os arquivos de plano que ele grava no [modo de planejamento](https://code.claude.com/docs/pt/permission-modes.md#analyze-before-you-edit-with-plan-mode). O Claude Code resolve o caminho em relação à raiz do projeto.2483Escolhe onde o Claude Code armazena os arquivos de plano que ele grava no [modo de planejamento](https://code.claude.com/docs/pt/permission-modes.md#analyze-before-you-edit-with-plan-mode). O Claude Code resolve o caminho em relação à raiz do projeto.


3522 3538 

3523* **Hooks gerenciados e SDK são executados**: hooks de configurações gerenciadas e hooks que o [Agent SDK](https://code.claude.com/docs/pt/agent-sdk/overview.md) registra em processo3539* **Hooks gerenciados e SDK são executados**: hooks de configurações gerenciadas e hooks que o [Agent SDK](https://code.claude.com/docs/pt/agent-sdk/overview.md) registra em processo

3524* **Hooks de plugins forçadamente ativados são executados**: hooks de plugins que suas configurações gerenciadas forçam a ativar através de [`enabledPlugins`](#enabledplugins). Claude Code corresponde ao ID completo `plugin@marketplace`, portanto um plugin com o mesmo nome de um marketplace diferente permanece bloqueado. Isso permite que você distribua hooks verificados através de um marketplace da organização enquanto bloqueia tudo o mais. Um [mod](https://code.claude.com/docs/pt/plugins/mods/overview.md) em tal plugin é carregado apenas quando [conta como da sua organização](https://code.claude.com/docs/pt/plugins/mods/admin.md#install-your-organizations-mods)3540* **Hooks de plugins forçadamente ativados são executados**: hooks de plugins que suas configurações gerenciadas forçam a ativar através de [`enabledPlugins`](#enabledplugins). Claude Code corresponde ao ID completo `plugin@marketplace`, portanto um plugin com o mesmo nome de um marketplace diferente permanece bloqueado. Isso permite que você distribua hooks verificados através de um marketplace da organização enquanto bloqueia tudo o mais. Um [mod](https://code.claude.com/docs/pt/plugins/mods/overview.md) em tal plugin é carregado apenas quando [conta como da sua organização](https://code.claude.com/docs/pt/plugins/mods/admin.md#install-your-organizations-mods)

3541* **Monitores de outros plugins são bloqueados**: os [monitores](https://code.claude.com/docs/pt/plugins/components.md#monitors) de um plugin não são iniciados a menos que o plugin seja forçadamente ativado. Requer Claude Code v2.1.310 ou posterior

3525* **Tudo o mais é bloqueado**: hooks de usuário, projeto e local, hooks e mods de outros plugins instalados e hooks declarados no frontmatter do agente. [Mods integrados ao Claude Code](https://code.claude.com/docs/pt/plugins/mods/overview.md#mods-built-into-claude-code) continuam sendo executados. Para bloquear apenas os mods dos usuários, defina [`allowManagedModsOnly`](https://code.claude.com/docs/pt/plugins/mods/admin#set-options-on-the-built-in-guard) em vez disso.3542* **Tudo o mais é bloqueado**: hooks de usuário, projeto e local, hooks e mods de outros plugins instalados e hooks declarados no frontmatter do agente. [Mods integrados ao Claude Code](https://code.claude.com/docs/pt/plugins/mods/overview.md#mods-built-into-claude-code) continuam sendo executados. Para bloquear apenas os mods dos usuários, defina [`allowManagedModsOnly`](https://code.claude.com/docs/pt/plugins/mods/admin#set-options-on-the-built-in-guard) em vez disso.

3526* **Plugins com origem em comando são desativados**: Claude Code também desativa plugins com uma [`command` source](https://code.claude.com/docs/pt/plugins/marketplace-reference#command-plugin-source), incluindo plugins forçadamente ativados em `enabledPlugins` gerenciado, a menos que você defina [`disableCommandPluginSources`](#disablecommandpluginsources) explicitamente como `false`3543* **Plugins com origem em comando são desativados**: Claude Code também desativa plugins com uma [`command` source](https://code.claude.com/docs/pt/plugins/marketplace-reference#command-plugin-source), incluindo plugins forçadamente ativados em `enabledPlugins` gerenciado, a menos que você defina [`disableCommandPluginSources`](#disablecommandpluginsources) explicitamente como `false`

3527* **Comandos `headersHelper` do marketplace são bloqueados**: Claude Code também bloqueia comandos [`headersHelper`](https://code.claude.com/docs/pt/plugins/host-marketplace#authenticate-archive-downloads) do marketplace a menos que [`disableCommandPluginSources`](#disablecommandpluginsources) seja explicitamente definido como `false`, exceto para um marketplace que as próprias configurações gerenciadas declaram. Requer Claude Code v2.1.238 ou posterior3544* **Comandos `headersHelper` do marketplace são bloqueados**: Claude Code também bloqueia comandos [`headersHelper`](https://code.claude.com/docs/pt/plugins/host-marketplace#authenticate-archive-downloads) do marketplace a menos que [`disableCommandPluginSources`](#disablecommandpluginsources) seja explicitamente definido como `false`, exceto para um marketplace que as próprias configurações gerenciadas declaram. Requer Claude Code v2.1.238 ou posterior

statusline.md +1 −1

Details

380* `used_percentage` e `resets_at`: vêm com cada resposta, então estão presentes sempre que `spend_limit` estiver. `used_percentage` varia de 0 a 100, ou acima de 100 uma vez que você excede o limite, e `resets_at` são os segundos de época Unix quando o período do limite é redefinido.380* `used_percentage` e `resets_at`: vêm com cada resposta, então estão presentes sempre que `spend_limit` estiver. `used_percentage` varia de 0 a 100, ou acima de 100 uma vez que você excede o limite, e `resets_at` são os segundos de época Unix quando o período do limite é redefinido.

381* `used_usd`, `limit_usd` e `period`: seu gasto estimado até o momento e seu limite em dólares americanos, e o período que o limite cobre, um de `daily`, `weekly` ou `monthly`. O gateway [calcula `used_usd` a partir das contagens de tokens](https://code.claude.com/docs/pt/claude-apps-gateway-spend-limits#how-requests-are-priced), então é uma estimativa e não um valor faturado. O Claude Code os lê do gateway em uma requisição separada, aproximadamente a cada cinco minutos enquanto você envia requisições. Os valores em dólares podem estar cerca de cinco minutos mais desatualizados que `used_percentage`, então os dois podem divergir brevemente. Requer v2.1.284 ou posterior tanto no Claude Code quanto no gateway.381* `used_usd`, `limit_usd` e `period`: seu gasto estimado até o momento e seu limite em dólares americanos, e o período que o limite cobre, um de `daily`, `weekly` ou `monthly`. O gateway [calcula `used_usd` a partir das contagens de tokens](https://code.claude.com/docs/pt/claude-apps-gateway-spend-limits#how-requests-are-priced), então é uma estimativa e não um valor faturado. O Claude Code os lê do gateway em uma requisição separada, aproximadamente a cada cinco minutos enquanto você envia requisições. Os valores em dólares podem estar cerca de cinco minutos mais desatualizados que `used_percentage`, então os dois podem divergir brevemente. Requer v2.1.284 ou posterior tanto no Claude Code quanto no gateway.

382 382 

383Trate `used_usd`, `limit_usd` e `period` como opcionais mesmo quando `spend_limit` estiver presente. Seu script recebe a porcentagem antes deles, e eles permanecem ausentes se você definir `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`, que desativa essa requisição. Leia cada um com um fallback em seu script, como `jq -r '.rate_limits.spend_limit.used_usd // empty'`.383Trate `used_usd`, `limit_usd` e `period` como opcionais mesmo quando `spend_limit` estiver presente, porque seu script recebe a porcentagem antes deles. Leia cada um com um fallback em seu script, como `jq -r '.rate_limits.spend_limit.used_usd // empty'`. Antes do Claude Code v2.1.295, eles permaneciam ausentes se você definisse `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`, que desativava essa requisição.

384 384 

385### Campos de cache de prompt385### Campos de cache de prompt

386 386 

Details

121* **Sessão em segundo plano**: uma [sessão em segundo plano](https://code.claude.com/docs/pt/agent-view.md) 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.121* **Sessão em segundo plano**: uma [sessão em segundo plano](https://code.claude.com/docs/pt/agent-view.md) 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.

122* **[`CLAUDE_CODE_DISABLE_TERMINAL_TITLE`](https://code.claude.com/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.122* **[`CLAUDE_CODE_DISABLE_TERMINAL_TITLE`](https://code.claude.com/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.

123 123 

124O título da aba não começa com um glifo de status em um terminal que informa suporte ao protocolo. O próprio terminal mostra o estado da sessão, então o Claude Code omite o glifo que coloca na frente do título em outros terminais.

125 

124## Configurar tmux126## Configurar tmux

125 127 

126Quando Claude Code é executado dentro do tmux, por padrão Shift+Enter envia em vez de inserir uma nova linha, e notificações de desktop e a [barra de progresso](https://code.claude.com/docs/pt/settings-reference.md#terminalprogressbarenabled) nunca chegam ao terminal externo. Adicione estas linhas a `~/.tmux.conf`, depois execute `tmux source-file ~/.tmux.conf` para aplicá-las ao servidor em execução:128Quando Claude Code é executado dentro do tmux, por padrão Shift+Enter envia em vez de inserir uma nova linha, e notificações de desktop e a [barra de progresso](https://code.claude.com/docs/pt/settings-reference.md#terminalprogressbarenabled) nunca chegam ao terminal externo. Adicione estas linhas a `~/.tmux.conf`, depois execute `tmux source-file ~/.tmux.conf` para aplicá-las ao servidor em execução:

Details

258 258 

259Um 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.259Um 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.

260 260 

261Claude 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.261Claude 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. Se o comando não exibiu nenhum texto do arquivo, como quando uma busca não encontra nenhuma correspondência, a verificação read-before-edit ainda se aplica.

262 262 

263Quando Claude visualiza um arquivo dessa forma, Claude Code também carrega qualquer [`CLAUDE.md` de subdiretório](https://code.claude.com/docs/pt/memory#how-claude-md-files-load) e [regras com escopo de caminho](https://code.claude.com/docs/pt/memory.md#path-specific-rules) que se aplicam a esse arquivo. Consulte [Regras de permissão Read e Edit](https://code.claude.com/docs/pt/permissions.md#read-and-edit) para saber quais comandos Bash suas regras de negação `Read` e `Edit` cobrem.263Quando Claude visualiza um arquivo dessa forma, Claude Code também carrega qualquer [`CLAUDE.md` de subdiretório](https://code.claude.com/docs/pt/memory#how-claude-md-files-load) e [regras com escopo de caminho](https://code.claude.com/docs/pt/memory.md#path-specific-rules) que se aplicam a esse arquivo. Consulte [Regras de permissão Read e Edit](https://code.claude.com/docs/pt/permissions.md#read-and-edit) para saber quais comandos Bash suas regras de negação `Read` e `Edit` cobrem.

264 264 


383 383 

384A [fonte WebSocket](#websocket-source) tem seu próprio prompt de aprovação, que o classificador também decide no modo auto.384A [fonte WebSocket](#websocket-source) tem seu próprio prompt de aprovação, que o classificador também decide no modo auto.

385 385 

386A ferramenta não está disponível no Amazon Bedrock, na Agent Platform do Google Cloud ou no Microsoft Foundry. Também não está disponível quando `DISABLE_TELEMETRY` ou `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` está definido. No Windows, a ferramenta está disponível apenas quando o [Git Bash](https://code.claude.com/docs/pt/setup.md#set-up-on-windows) está instalado.386O Monitor precisa de uma versão mínima ou do Git Bash nestes casos:

387 

388* **Versão mínima**: no Amazon Bedrock, Claude Platform on AWS, Agent Platform do Google Cloud ou Microsoft Foundry, ou com `DISABLE_TELEMETRY` ou `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` definido, o Monitor requer Claude Code v2.1.310 ou posterior. O requisito se aplica quando a [busca de feature flags](https://code.claude.com/docs/pt/env-vars.md#features-that-need-feature-flag-fetching) está desativada

389* **Windows**: a ferramenta está disponível apenas quando o [Git Bash](https://code.claude.com/docs/pt/setup.md#set-up-on-windows) está instalado

387 390 

388Plugins podem declarar monitors que iniciam automaticamente quando o plugin está ativo, em vez de pedir a Claude para iniciá-los. Veja [plugin monitors](https://code.claude.com/docs/pt/plugins/components.md#monitors).391Plugins podem declarar monitors que iniciam automaticamente quando o plugin está ativo, em vez de pedir a Claude para iniciá-los. Veja [plugin monitors](https://code.claude.com/docs/pt/plugins/components.md#monitors).

389 392 

Details

177 177 

178**1. Abra a visualização de diff**178**1. Abra a visualização de diff**

179 179 

180Um indicador de diff mostra linhas adicionadas e removidas em toda a sessão, por exemplo `+42 -18`. Selecione-o para abrir a visualização de diff, com uma lista de arquivos à esquerda e alterações à direita.180Depois que Claude enviar suas alterações para um branch, o cartão **Changes** no painel ao lado do chat mostra as linhas adicionadas e removidas em toda a sessão, por exemplo `+42 -18`. Clique nesses números para abrir a visualização de diff.

181 181 

182O diff compara as alterações da sessão contra seu branch base por padrão. Para comparar contra um branch diferente, selecione **Comparar contra** e escolha um.182* Você também pode clicar em **Changes** na barra de título da sessão ou no menu **⋮** da barra.

183* Para mostrar o painel quando ele estiver oculto, clique no ícone **Show session rail** na barra de título da sessão ou no menu **⋮** da barra.

184 

185O diff compara as alterações da sessão contra seu branch base por padrão. Para comparar contra um branch diferente, selecione **Compare against** e escolha um.

183 186 

184**2. Deixe comentários inline**187**2. Deixe comentários inline**

185 188 


187 190 

188**3. Crie um pull request**191**3. Crie um pull request**

189 192 

190Quando o diff parecer correto, selecione **Criar PR** no topo da visualização de diff. Você pode abri-lo como um PR completo, um rascunho ou ir para a página de composição do GitHub com um título e descrição gerados.193Quando o diff parecer correto, [mostre o painel novamente](https://code.claude.com/docs/pt/claude-code-on-the-web.md#review-changes) se o cartão **Changes** estiver fora de vista e, em seguida, crie um pull request ou um rascunho a partir do cartão:

194 

195* Clique em **Create PR**. O Claude Code cria o pull request com um título e uma descrição gerados.

196* Para abrir um rascunho, clique com o botão direito em **Create PR**, selecione **Create draft PR** para alterar o que o botão faz e, em seguida, clique no botão

191 197 

192**4. Continue iterando após o PR**198**4. Continue iterando após o PR**

193 199