SpyBara
Go Premium

Documentation 2026-09-30 23:00 UTC to 2026-10-01 21:59 UTC

65 files changed +4,277 −518. View all changes and history on the product overview
2026
Thu 1 21:59

admin-setup.md +1 −0

Details

106| [Disable claude.ai sync](/docs/pt/settings-reference#syncclaudeaiskills) | Impedir que Claude Code carregue os [skills](/docs/pt/skills#how-synced-skills-behave) e [plugins](/docs/pt/plugins/loading#synced-plugins) que seus desenvolvedores habilitam em claude.ai. Se você desativar Skills para sua organização em claude.ai, Claude Code interrompe a sincronização de ambos, e na v2.1.273 ou posterior também remove os que já sincronizou. Para interromper um sem desativar Skills, defina sua chave como `false` nas configurações gerenciadas | `syncClaudeAiSkills`, `syncClaudeAiPlugins` |106| [Disable claude.ai sync](/docs/pt/settings-reference#syncclaudeaiskills) | Impedir que Claude Code carregue os [skills](/docs/pt/skills#how-synced-skills-behave) e [plugins](/docs/pt/plugins/loading#synced-plugins) que seus desenvolvedores habilitam em claude.ai. Se você desativar Skills para sua organização em claude.ai, Claude Code interrompe a sincronização de ambos, e na v2.1.273 ou posterior também remove os que já sincronizou. Para interromper um sem desativar Skills, defina sua chave como `false` nas configurações gerenciadas | `syncClaudeAiSkills`, `syncClaudeAiPlugins` |

107| [Hook restrictions](/docs/pt/settings-reference#allowmanagedhooksonly) | Restringir quais hooks são executados e restringir URLs de hook HTTP; consulte [o que é executado em `allowManagedHooksOnly`](/docs/pt/settings-reference#what-runs-under-allowmanagedhooksonly) para a lista completa de efeitos | `allowManagedHooksOnly`, `allowedHttpHookUrls` |107| [Hook restrictions](/docs/pt/settings-reference#allowmanagedhooksonly) | Restringir quais hooks são executados e restringir URLs de hook HTTP; consulte [o que é executado em `allowManagedHooksOnly`](/docs/pt/settings-reference#what-runs-under-allowmanagedhooksonly) para a lista completa de efeitos | `allowManagedHooksOnly`, `allowedHttpHookUrls` |

108| [Login enforcement](/docs/pt/settings-reference#forceloginmethod) | Restringir login a um método específico ou organização Anthropic. A restrição de método se aplica na extensão VS Code, Agent SDK, `claude setup-token` e `/install-github-app`, e a tela de login interativa do terminal, acessada por `/login` ou onboarding de primeira execução, pré-seleciona o método sem aplicá-lo; Claude Code verifica a organização para logins de conta claude.ai no terminal, extensão VS Code e Agent SDK, e não verifica para logins do Claude Console ou para entrada de [gateway](/docs/pt/claude-apps-gateway). Antes da v2.1.212, apenas logins de terminal aplicavam qualquer chave. Quando definido, sessões autenticadas por `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, ou `apiKeyHelper` são bloqueadas na inicialização; sessões de provedor de nuvem não são afetadas a menos que uma dessas credenciais, ou uma chave de API salva por um login anterior do Claude Console, também esteja presente | `forceLoginMethod`, `forceLoginOrgUUID` |108| [Login enforcement](/docs/pt/settings-reference#forceloginmethod) | Restringir login a um método específico ou organização Anthropic. A restrição de método se aplica na extensão VS Code, Agent SDK, `claude setup-token` e `/install-github-app`, e a tela de login interativa do terminal, acessada por `/login` ou onboarding de primeira execução, pré-seleciona o método sem aplicá-lo; Claude Code verifica a organização para logins de conta claude.ai no terminal, extensão VS Code e Agent SDK, e não verifica para logins do Claude Console ou para entrada de [gateway](/docs/pt/claude-apps-gateway). Antes da v2.1.212, apenas logins de terminal aplicavam qualquer chave. Quando definido, sessões autenticadas por `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, ou `apiKeyHelper` são bloqueadas na inicialização; sessões de provedor de nuvem não são afetadas a menos que uma dessas credenciais, ou uma chave de API salva por um login anterior do Claude Console, também esteja presente | `forceLoginMethod`, `forceLoginOrgUUID` |

109| [Provider restrictions](/docs/pt/settings-reference#allowedproviders) | Limitar quais provedores de API uma máquina pode usar. Uma sessão em um provedor que não está listado é recusada na inicialização, no login e quando próximo contata a API. Requer Claude Code v2.1.285 ou posterior | `allowedProviders` |

109| [Disable agent view](/docs/pt/agent-view#how-background-sessions-are-hosted) | Desativar `claude agents`, `--bg`, `/background` e o supervisor sob demanda | `disableAgentView` |110| [Disable agent view](/docs/pt/agent-view#how-background-sessions-are-hosted) | Desativar `claude agents`, `--bg`, `/background` e o supervisor sob demanda | `disableAgentView` |

110| [Configure the corporate launcher](/docs/pt/corporate-launcher) | Prefixar o [supervisor de agente de fundo](/docs/pt/agent-view#how-background-sessions-are-hosted), seus workers e os [outros processos de fundo cobertos](/docs/pt/corporate-launcher#what-the-launcher-covers) com um launcher corporativo obrigatório em vez de desativar a visualização de agente | `processWrapper` |111| [Configure the corporate launcher](/docs/pt/corporate-launcher) | Prefixar o [supervisor de agente de fundo](/docs/pt/agent-view#how-background-sessions-are-hosted), seus workers e os [outros processos de fundo cobertos](/docs/pt/corporate-launcher#what-the-launcher-covers) com um launcher corporativo obrigatório em vez de desativar a visualização de agente | `processWrapper` |

111| [Model restrictions](/docs/pt/model-config#restrict-model-selection) | `availableModels` filtra quais modelos aparecem no seletor. Adicionar `enforceAvailableModels` também restringe o modelo padrão selecionado automaticamente. Consulte [surface coverage](/docs/pt/model-config#surface-coverage) para saber como essa configuração alcança a CLI, web e IDE | `availableModels`, `enforceAvailableModels` |112| [Model restrictions](/docs/pt/model-config#restrict-model-selection) | `availableModels` filtra quais modelos aparecem no seletor. Adicionar `enforceAvailableModels` também restringe o modelo padrão selecionado automaticamente. Consulte [surface coverage](/docs/pt/model-config#surface-coverage) para saber como essa configuração alcança a CLI, web e IDE | `availableModels`, `enforceAvailableModels` |

Details

418 ```418 ```

419</CodeGroup>419</CodeGroup>

420 420 

421Para confirmar o bloqueio, registre o callback sob `PreToolUse` com um matcher `Write|Edit` e peça ao agente para criar um arquivo em `/etc`: o resultado da ferramenta Write no fluxo de mensagens contém `Writing to /etc is not allowed`, e nenhum arquivo é criado.

422 

421<h3 id="auto-approve-specific-tools">423<h3 id="auto-approve-specific-tools">

422 Aprovar automaticamente ferramentas específicas424 Aprovar automaticamente ferramentas específicas

423</h3>425</h3>


468 470 

469Quando um evento é disparado, todos os hooks correspondentes são executados em paralelo. Para decisões de permissão, o resultado mais restritivo vence: um único `deny` bloqueia a chamada de ferramenta independentemente do que os outros hooks retornam. Como a ordem de conclusão é não-determinística, escreva cada hook para agir independentemente em vez de depender de outro hook ter sido executado primeiro.471Quando um evento é disparado, todos os hooks correspondentes são executados em paralelo. Para decisões de permissão, o resultado mais restritivo vence: um único `deny` bloqueia a chamada de ferramenta independentemente do que os outros hooks retornam. Como a ordem de conclusão é não-determinística, escreva cada hook para agir independentemente em vez de depender de outro hook ter sido executado primeiro.

470 472 

471O exemplo abaixo registra três verificações independentes para cada chamada de ferramenta:473O exemplo abaixo registra três verificações independentes para cada chamada de ferramenta. Os nomes de hook nele, como `audit_logger` em Python ou `auditLogger` em TypeScript, representam callbacks que você define:

472 474 

473<CodeGroup>475<CodeGroup>

474 ```python Python theme={null}476 ```python Python theme={null}


500 Filtrar com matchers de múltiplas ferramentas502 Filtrar com matchers de múltiplas ferramentas

501</h3>503</h3>

502 504 

503Use matchers de múltiplas ferramentas para compartilhar um callback entre ferramentas relacionadas. Este exemplo registra três matchers com escopos diferentes:505Use matchers de múltiplas ferramentas para compartilhar um callback entre ferramentas relacionadas. Este exemplo registra três matchers com escopos diferentes, e cada hook que ele nomeia representa um callback que você define:

504 506 

505* Uma lista exata separada por pipe (`Write|Edit|NotebookEdit`) dispara `file_security_hook` apenas para ferramentas de modificação de arquivo.507* Uma lista exata separada por pipe (`Write|Edit|NotebookEdit`) dispara `file_security_hook` apenas para ferramentas de modificação de arquivo.

506* Uma regex (`^mcp__`) dispara `mcp_audit_hook` para qualquer ferramenta MCP cujo nome começa com `mcp__`.508* Uma regex (`^mcp__`) dispara `mcp_audit_hook` para qualquer ferramenta MCP cujo nome começa com `mcp__`.


585 ```587 ```

586</CodeGroup>588</CodeGroup>

587 589 

590Para confirmar que o hook é disparado, registre o callback e peça ao agente para delegar uma pequena tarefa a um subagente, como listar os arquivos no diretório atual: quando o subagente termina, o callback imprime as linhas `[SUBAGENT] Completed:` com o ID do subagente e o caminho da transcrição.

591 

588<h3 id="make-http-requests-from-hooks">592<h3 id="make-http-requests-from-hooks">

589 Fazer requisições HTTP a partir de hooks593 Fazer requisições HTTP a partir de hooks

590</h3>594</h3>

Details

121 121 

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

123 123 

124Se você não definir um, Claude Code escolhe o modo de permissão inicial pelas regras em [Qual modo uma sessão inicia](/docs/pt/permission-modes#which-mode-a-session-starts-in):

125 

126* Um `permissions.defaultMode` dos [arquivos de configuração](/docs/pt/settings#where-settings-live) da sessão quando um se aplica

127* Caso contrário, o padrão integrado, que pode ser [modo auto](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode)

128 

129Uma sessão que inicia em modo auto descarta regras de permissão amplas, como uma entrada `Bash` simples, conforme [Como o modo auto avalia ações](/docs/pt/permission-modes#how-auto-mode-evaluates-actions) descreve. Se sua aplicação depender do modo `default` ou de tal regra, passe `default` explicitamente.

130 

131Antes do TypeScript Agent SDK v0.3.286, omitir `permissionMode` era o mesmo que passar `default`.

132 

124<h3 id="available-modes">133<h3 id="available-modes">

125 Modos disponíveis134 Modos disponíveis

126</h3>135</h3>

agent-sdk/python.md +243 −69

Details

517 async def set_model(self, model: str | None = None) -> None517 async def set_model(self, model: str | None = None) -> None

518 async def rewind_files(self, user_message_id: str) -> None518 async def rewind_files(self, user_message_id: str) -> None

519 async def get_mcp_status(self) -> McpStatusResponse519 async def get_mcp_status(self) -> McpStatusResponse

520 async def get_context_usage(self) -> ContextUsageResponse

520 async def reconnect_mcp_server(self, server_name: str) -> None521 async def reconnect_mcp_server(self, server_name: str) -> None

521 async def toggle_mcp_server(self, server_name: str, enabled: bool) -> None522 async def toggle_mcp_server(self, server_name: str, enabled: bool) -> None

522 async def stop_task(self, task_id: str) -> None523 async def stop_task(self, task_id: str) -> None


540| `set_model(model)` | Altera o modelo para a sessão atual. Passe `None` para redefinir para o [modelo padrão do Claude Code](/docs/pt/model-config) |541| `set_model(model)` | Altera o modelo para a sessão atual. Passe `None` para redefinir para o [modelo padrão do Claude Code](/docs/pt/model-config) |

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

542| `get_mcp_status()` | Obtém o status de todos os servidores MCP configurados. Retorna [`McpStatusResponse`](#mcpstatusresponse) |543| `get_mcp_status()` | Obtém o status de todos os servidores MCP configurados. Retorna [`McpStatusResponse`](#mcpstatusresponse) |

544| `get_context_usage()` | Obtém um detalhamento do uso da janela de contexto por categoria, skill e ferramenta. Os mesmos dados que `/context` mostra em uma sessão interativa. Retorna [`ContextUsageResponse`](#contextusageresponse). Para calcular o detalhamento, Claude Code faz várias solicitações de API de contagem de tokens que não aparecem no fluxo de mensagens; veja [como essas solicitações são tratadas](#contextusageresponse) |

543| `reconnect_mcp_server(server_name)` | Tenta reconectar a um servidor MCP que falhou ou foi desconectado |545| `reconnect_mcp_server(server_name)` | Tenta reconectar a um servidor MCP que falhou ou foi desconectado |

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

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

546| `get_server_info()` | Obtém as informações de inicialização do servidor, incluindo comandos disponíveis e estilos de saída |548| `get_server_info()` | Obtém as informações de inicialização do servidor, incluindo comandos disponíveis e estilos de saída |

547| `disconnect()` | Desconecta de Claude |549| `disconnect()` | Desconecta de Claude |


616 Exemplo - Entrada em streaming com ClaudeSDKClient618 Exemplo - Entrada em streaming com ClaudeSDKClient

617</h4>619</h4>

618 620 

621`query()` também aceita um iterável assíncrono de dicts de mensagem de usuário, para que você possa montar o prompt no momento do envio ou incluir blocos de conteúdo como imagens. Claude Code começa a responder à primeira mensagem gerada assim que ela chega, sem esperar que o iterável termine, e `receive_response()` para na `ResultMessage` que encerra essa resposta. Coloque tudo o que Claude deve ler antes de responder em uma mensagem, como este gerador faz, e emparelhe cada chamada `query()` com seu próprio loop `receive_response()`.

622 

619```python theme={null}623```python theme={null}

620import asyncio624import asyncio

621from claude_agent_sdk import ClaudeSDKClient625from claude_agent_sdk import ClaudeSDKClient

622 626 

623 627 

624async def message_stream():628async def message_stream():

625 """Generate messages dynamically."""629 """Assemble the prompt at send time and yield it as one user message."""

626 yield {630 readings = {"Temperature": "25°C", "Humidity": "60%"}

627 "type": "user",631 data = ", ".join(f"{name}: {value}" for name, value in readings.items())

628 "message": {"role": "user", "content": "Analyze the following data:"},

629 }

630 await asyncio.sleep(0.5)

631 yield {

632 "type": "user",

633 "message": {"role": "user", "content": "Temperature: 25°C, Humidity: 60%"},

634 }

635 await asyncio.sleep(0.5)

636 yield {632 yield {

637 "type": "user",633 "type": "user",

638 "message": {"role": "user", "content": "What patterns do you see?"},634 "message": {

635 "role": "user",

636 "content": f"Analyze the following sensor data and describe any patterns you see: {data}",

637 },

639 }638 }

640 639 

641 640 


1607| `scope` | `str` (opcional) | Escopo de configuração |1606| `scope` | `str` (opcional) | Escopo de configuração |

1608| `tools` | `list` (opcional) | Ferramentas fornecidas por este servidor, cada uma com campos `name`, `description`, e `annotations` |1607| `tools` | `list` (opcional) | Ferramentas fornecidas por este servidor, cada uma com campos `name`, `description`, e `annotations` |

1609 1608 

1609<h3 id="contextusageresponse">

1610 `ContextUsageResponse`

1611</h3>

1612 

1613Resposta de [`ClaudeSDKClient.get_context_usage()`](#methods). Este é o mesmo payload que Claude Code renderiza para o comando `/context` em uma sessão interativa, então ao lado das contagens de token ele carrega campos de exibição como `color` e `gridRows` que Claude Code usa para desenhar a grade de uso `/context`.

1614 

1615Claude Code constrói este payload enviando várias requisições para a API de [contagem de tokens](https://platform.claude.com/docs/en/build-with-claude/token-counting). Estas requisições não aparecem no fluxo de mensagens, então rastreamento de custo que lê o fluxo não as verá. Na API Anthropic, contagem de tokens não é cobrada.

1616 

1617```python theme={null}

1618class ContextUsageResponse(TypedDict):

1619 categories: list[ContextUsageCategory]

1620 totalTokens: int

1621 maxTokens: int

1622 rawMaxTokens: int

1623 percentage: float

1624 model: str

1625 isAutoCompactEnabled: bool

1626 memoryFiles: list[dict[str, Any]]

1627 mcpTools: list[dict[str, Any]]

1628 agents: list[dict[str, Any]]

1629 gridRows: list[list[dict[str, Any]]]

1630 autoCompactThreshold: NotRequired[int]

1631 deferredBuiltinTools: NotRequired[list[dict[str, Any]]]

1632 systemTools: NotRequired[list[dict[str, Any]]]

1633 systemPromptSections: NotRequired[list[dict[str, Any]]]

1634 slashCommands: NotRequired[dict[str, Any]]

1635 skills: NotRequired[dict[str, Any]] # uso de skill com quebra de frontmatter

1636 messageBreakdown: NotRequired[dict[str, Any]] # tokens de mensagem por tipo

1637 apiUsage: NotRequired[dict[str, Any] | None]

1638```

1639 

1640Cada entrada `ContextUsageCategory` carrega `name`, `tokens`, `color`, e uma flag `isDeferred` opcional. `totalTokens` é o uso de contexto atual da sessão, e `maxTokens` é a janela contra a qual o uso é medido. Essa janela é a janela de contexto do modelo, ou a janela de auto-compactação mais baixa quando uma se aplica, e `rawMaxTokens` carrega o mesmo valor que `maxTokens`. `apiUsage` contém o uso da resposta de API mais recente, não um total em execução para a sessão. Claude Code deixa as chaves opcionais `deferredBuiltinTools`, `systemTools`, e `systemPromptSections` não definidas, então espere que elas estejam ausentes mesmo que o tipo as declare.

1641 

1610<h3 id="sdkpluginconfig">1642<h3 id="sdkpluginconfig">

1611 `SdkPluginConfig`1643 `SdkPluginConfig`

1612</h3>1644</h3>


2712 2744 

2713Documentação de schemas de entrada/saída para todas as ferramentas Claude Code integradas. Embora o SDK Python não exporte esses como tipos, eles representam a estrutura de entradas e saídas de ferramenta em mensagens.2745Documentação de schemas de entrada/saída para todas as ferramentas Claude Code integradas. Embora o SDK Python não exporte esses como tipos, eles representam a estrutura de entradas e saídas de ferramenta em mensagens.

2714 2746 

2747Cada saída mostrada é o valor que você lê de [`UserMessage.tool_use_result`](#usermessage) para essa ferramenta. Os nomes de chaves aparecem exatamente como Claude Code os emite. Uma chave anotada com `| None` com um comentário "presente quando" ou "opcional" é omitida quando não se aplica.

2748 

2715<h3 id="agent">2749<h3 id="agent">

2716 Agent2750 Agent

2717</h3>2751</h3>


2885 2919 

2886**Nome da ferramenta:** `Bash`2920**Nome da ferramenta:** `Bash`

2887 2921 

2888Para o que define o limite do primeiro plano, veja [Limites de tempo limite e saída](/docs/pt/tools-reference#timeout-and-output-limits). Para o limite de tempo em segundo plano, veja [Comandos em segundo plano](/docs/pt/tools-reference#background-commands).2922Para o que define o limite do primeiro plano, veja [Limites de tempo limite e saída](/docs/pt/tools-reference#timeout-and-output-limits). Para o limite de tempo em segundo plano, veja [Limite de tempo para comandos em segundo plano](/docs/pt/tools-reference#time-limit-for-background-commands).

2889 2923 

2890**Entrada:**2924**Entrada:**

2891 2925 


2962 2996 

2963```python theme={null}2997```python theme={null}

2964{2998{

2965 "message": str, # Mensagem de confirmação2999 "filePath": str, # O arquivo que foi editado

2966 "replacements": int, # Número de substituições realizadas3000 "oldString": str, # O texto que foi substituído

2967 "file_path": str, # Caminho do arquivo que foi editado3001 "newString": str, # O texto que o substituiu

3002 "originalFile": str | None, # Conteúdo do arquivo antes da edição

3003 "structuredPatch": [ # Hunks de diff para a alteração

3004 {

3005 "oldStart": int,

3006 "oldLines": int,

3007 "newStart": int,

3008 "newLines": int,

3009 "lines": list[str],

3010 }

3011 ],

3012 "userModified": bool, # Se o usuário alterou a edição proposta antes de aceitá-la

3013 "replaceAll": bool, # Se todas as ocorrências foram substituídas

3014 "gitDiff": { # Resumo de diff git opcional para o arquivo

3015 "filename": str,

3016 "status": "modified" | "added",

3017 "additions": int,

3018 "deletions": int,

3019 "changes": int,

3020 "patch": str,

3021 "repository": str | None, # Proprietário/repositório do GitHub quando disponível

3022 } | None,

2968}3023}

2969```3024```

2970 3025 


2984}3039}

2985```3040```

2986 3041 

2987**Saída (Arquivos de texto):**3042A saída assume uma das seguintes formas dependendo do que Claude leu. Verifique a chave `type` para diferenciá-las.

3043 

3044**Saída (type: `"text"`):**

3045 

3046```python theme={null}

3047{

3048 "type": "text",

3049 "file": {

3050 "filePath": str, # O arquivo que foi lido

3051 "content": str, # O conteúdo retornado

3052 "numLines": int, # Número de linhas no conteúdo retornado

3053 "startLine": int, # Número da linha em que o conteúdo começa

3054 "totalLines": int, # Número total de linhas no arquivo

3055 "truncatedByTokenCap": bool | None, # Presente e True quando uma leitura de arquivo inteiro excedeu o limite de tokens e o conteúdo é a primeira página

3056 },

3057}

3058```

3059 

3060**Saída (type: `"image"`):**

3061 

3062```python theme={null}

3063{

3064 "type": "image",

3065 "file": {

3066 "base64": str, # Dados de imagem codificados em Base64

3067 "type": "image/jpeg" | "image/png" | "image/gif" | "image/webp", # Tipo MIME da imagem

3068 "originalSize": int, # Tamanho do arquivo original em bytes

3069 "dimensions": { # Informações de dimensionamento opcionais para mapeamento de coordenadas

3070 "originalWidth": int | None, # Opcional; largura original em pixels

3071 "originalHeight": int | None, # Opcional; altura original em pixels

3072 "displayWidth": int | None, # Opcional; largura após redimensionamento

3073 "displayHeight": int | None, # Opcional; altura após redimensionamento

3074 } | None,

3075 },

3076}

3077```

3078 

3079**Saída (type: `"notebook"`):**

3080 

3081```python theme={null}

3082{

3083 "type": "notebook",

3084 "file": {

3085 "filePath": str, # O notebook que foi lido

3086 "cells": list, # Células do notebook

3087 },

3088}

3089```

3090 

3091**Saída (type: `"pdf"`):**

3092 

3093```python theme={null}

3094{

3095 "type": "pdf",

3096 "file": {

3097 "filePath": str, # O PDF que foi lido

3098 "base64": str, # Dados de PDF codificados em Base64

3099 "originalSize": int, # Tamanho do arquivo em bytes

3100 },

3101}

3102```

3103 

3104**Saída (type: `"parts"`):**

2988 3105 

2989```python theme={null}3106```python theme={null}

2990{3107{

2991 "content": str, # Conteúdo do arquivo com números de linha3108 "type": "parts",

2992 "total_lines": int, # Número total de linhas no arquivo3109 "file": {

2993 "lines_returned": int, # Linhas realmente retornadas3110 "filePath": str, # O PDF que foi lido

3111 "originalSize": int, # Tamanho do arquivo em bytes

3112 "count": int, # Número de páginas extraídas como imagens

3113 "outputDir": str, # Diretório contendo as imagens de página extraídas

3114 },

3115 "firstPage": int | None, # Número de página do documento opcional da primeira página extraída

2994}3116}

2995```3117```

2996 3118 

2997**Saída (Imagens):**3119**Saída (type: `"file_unchanged"`):**

2998 3120 

2999```python theme={null}3121```python theme={null}

3000{3122{

3001 "image": str, # Dados de imagem codificados em Base643123 "type": "file_unchanged", # O arquivo está inalterado desde que Claude o leu pela última vez nesta sessão, então o conteúdo não é repetido

3002 "mime_type": str, # Tipo MIME da imagem3124 "file": {

3003 "file_size": int, # Tamanho do arquivo em bytes3125 "filePath": str,

3126 },

3127 "source": "seeded" | None, # Presente quando a cópia anterior veio de um arquivo CLAUDE.md ou memory carregado na inicialização em vez de uma chamada Read

3004}3128}

3005```3129```

3006 3130 


3023 3147 

3024```python theme={null}3148```python theme={null}

3025{3149{

3026 "message": str, # Mensagem de sucesso3150 "type": "create" | "update", # Se a escrita criou um novo arquivo ou sobrescreveu um existente

3027 "bytes_written": int, # Número de bytes escritos3151 "filePath": str, # O arquivo que foi escrito

3028 "file_path": str, # Caminho do arquivo que foi escrito3152 "content": str, # O conteúdo que foi escrito

3153 "structuredPatch": [ # Hunks de diff; vazio para um novo arquivo, quando nada mudou, ou quando Claude Code pulou o diff

3154 {

3155 "oldStart": int,

3156 "oldLines": int,

3157 "newStart": int,

3158 "newLines": int,

3159 "lines": list[str],

3160 }

3161 ],

3162 "originalFile": str | None, # Conteúdo anterior; None para um novo arquivo ou quando o conteúdo anterior era muito grande para incluir

3163 "gitDiff": { # Resumo de diff git opcional para o arquivo

3164 "filename": str,

3165 "status": "modified" | "added",

3166 "additions": int,

3167 "deletions": int,

3168 "changes": int,

3169 "patch": str,

3170 "repository": str | None, # Proprietário/repositório do GitHub quando disponível

3171 } | None,

3172 "userModified": bool | None, # Opcional; se o usuário editou o conteúdo proposto antes de aceitá-lo

3029}3173}

3030```3174```

3031 3175 


3048 3192 

3049```python theme={null}3193```python theme={null}

3050{3194{

3051 "matches": list[str], # Array de caminhos de arquivo correspondentes3195 "durationMs": int, # Tempo levado para executar a pesquisa, em milissegundos

3052 "count": int, # Número de correspondências encontradas3196 "numFiles": int, # Número de caminhos retornados, após qualquer truncamento

3053 "search_path": str, # Diretório de pesquisa usado3197 "filenames": list[str], # Caminhos de arquivo correspondentes

3198 "truncated": bool, # Se os resultados foram truncados no limite de 100 arquivos

3199 "totalMatches": int | None, # Número total opcional de arquivos correspondentes antes do truncamento; um limite inferior quando countIsComplete é False

3200 "countIsComplete": bool | None, # Opcional; se totalMatches é exato

3054}3201}

3055```3202```

3056 3203 

3204`totalMatches` e `countIsComplete` requerem Claude Code v2.1.191 ou posterior.

3205 

3057<h3 id="grep">3206<h3 id="grep">

3058 Grep3207 Grep

3059</h3>3208</h3>


3074 "-B": int | None, # Linhas a mostrar antes de cada correspondência3223 "-B": int | None, # Linhas a mostrar antes de cada correspondência

3075 "-A": int | None, # Linhas a mostrar após cada correspondência3224 "-A": int | None, # Linhas a mostrar após cada correspondência

3076 "-C": int | None, # Linhas a mostrar antes e depois3225 "-C": int | None, # Linhas a mostrar antes e depois

3226 "context": int | None, # Linhas a mostrar antes e depois; -C é um alias

3227 "-o": bool | None, # Imprimir apenas as partes correspondidas de cada linha

3077 "head_limit": int | None, # Limitar saída às primeiras N linhas/entradas3228 "head_limit": int | None, # Limitar saída às primeiras N linhas/entradas

3229 "offset": int | None, # Pular primeiras N linhas/entradas antes de aplicar head_limit

3078 "multiline": bool | None, # Ativar modo multilinha3230 "multiline": bool | None, # Ativar modo multilinha

3079}3231}

3080```3232```

3081 3233 

3082**Saída (modo content):**3234**Saída:**

3083 3235 

3084```python theme={null}3236```python theme={null}

3085{3237{

3086 "matches": [3238 "mode": "content" | "files_with_matches" | "count" | None, # O modo de saída que foi usado

3087 {3239 "numFiles": int, # Número de arquivos no resultado; sempre 0 em modo content

3088 "file": str,3240 "filenames": list[str], # Arquivos correspondentes em modo files_with_matches; vazio nos outros modos

3089 "line_number": int | None,3241 "content": str | None, # Linhas correspondentes em modo content, ou contagens por arquivo em modo count

3090 "line": str,3242 "numLines": int | None, # Número de linhas no conteúdo, presente em modo content

3091 "before_context": list[str] | None,3243 "numMatches": int | None, # Contagem total de correspondências, presente em modo count

3092 "after_context": list[str] | None,3244 "totalFiles": int | None, # Total opcional antes de head_limit e offset, em modo files_with_matches

3093 }3245 "totalLines": int | None, # Total opcional antes de head_limit e offset, em modo content

3094 ],3246 "appliedLimit": int | None, # Presente quando head_limit truncou o resultado

3095 "total_matches": int,3247 "appliedOffset": int | None, # Presente quando um offset foi aplicado

3096}3248}

3097```3249```

3098 3250 

3099**Saída (modo files\_with\_matches):**3251Grep retorna essa forma de dict em cada modo de saída. Quais chaves opcionais estão presentes depende de `output_mode`.

3100 3252 

3101```python theme={null}3253`totalFiles` requer Claude Code v2.1.208 ou posterior. `totalLines` requer Claude Code v2.1.210 ou posterior.

3102{

3103 "files": list[str], # Arquivos contendo correspondências

3104 "count": int, # Número de arquivos com correspondências

3105}

3106```

3107 3254 

3108<h3 id="notebookedit">3255<h3 id="notebookedit">

3109 NotebookEdit3256 NotebookEdit


3127 3274 

3128```python theme={null}3275```python theme={null}

3129{3276{

3130 "message": str, # Mensagem de sucesso3277 "new_source": str, # A fonte escrita na célula

3131 "edit_type": "replaced" | "inserted" | "deleted", # Tipo de edição realizada3278 "old_source": str | None, # Fonte de célula anterior, presente para replace e delete

3132 "cell_id": str | None, # ID da célula que foi afetada3279 "cell_id": str | None, # ID da célula editada, quando disponível

3133 "total_cells": int, # Total de células no notebook após edição3280 "cell_type": "code" | "markdown", # O tipo de célula

3281 "language": str, # A linguagem de programação do notebook

3282 "edit_mode": str, # O modo de edição que foi usado

3283 "error": str | None, # Mensagem de erro quando a operação falhou

3284 "notebook_path": str, # O arquivo do notebook

3285 "original_file": str, # Conteúdo do notebook antes da edição

3286 "updated_file": str, # Conteúdo do notebook após a edição

3134}3287}

3135```3288```

3136 3289 


3228 3381 

3229```python theme={null}3382```python theme={null}

3230{3383{

3231 "message": str, # Mensagem de sucesso3384 "oldTodos": [ # A lista de tarefas antes da atualização

3232 "stats": {"total": int, "pending": int, "in_progress": int, "completed": int},3385 {

3386 "content": str,

3387 "status": "pending" | "in_progress" | "completed",

3388 "activeForm": str,

3389 }

3390 ],

3391 "newTodos": [ # A lista de tarefas após a atualização

3392 {

3393 "content": str,

3394 "status": "pending" | "in_progress" | "completed",

3395 "activeForm": str,

3396 }

3397 ],

3233}3398}

3234```3399```

3235 3400 


3401 3566 

3402```python theme={null}3567```python theme={null}

3403{3568{

3404 "message": str, # Mensagem de confirmação3569 "plan": str | None, # O plano que foi apresentado ao usuário

3405 "approved": bool | None, # Se o usuário aprovou o plano3570 "isAgent": bool, # True quando um subagente chamou a ferramenta

3571 "filePath": str | None, # Presente quando o plano foi salvo em um arquivo

3572 "hasTaskTool": bool | None, # Opcional; se a ferramenta Agent está disponível no contexto atual

3573 "planWasEdited": bool | None, # Presente e True quando o usuário editou o plano antes de aprovar

3574 "awaitingLeaderApproval": bool | None, # Presente e True quando um colega de equipe enviou o plano para o líder da equipe para aprovação

3575 "requestId": str | None, # ID opcional dessa solicitação de aprovação

3406}3576}

3407```3577```

3408 3578 


3420}3590}

3421```3591```

3422 3592 

3593O resultado é uma lista em vez de um dict, então `tool_use_result` contém uma `list` para essa ferramenta.

3594 

3423**Saída:**3595**Saída:**

3424 3596 

3425```python theme={null}3597```python theme={null}

3426{3598[ # Uma entrada por recurso

3427 "resources": [

3428 {3599 {

3429 "uri": str,3600 "uri": str, # URI do recurso

3430 "name": str,3601 "name": str, # Nome do recurso

3431 "description": str | None,3602 "mimeType": str | None, # Tipo MIME opcional

3432 "mimeType": str | None,3603 "description": str | None, # Descrição opcional

3433 "server": str,3604 "server": str, # Servidor que fornece este recurso

3434 }3605 }

3435 ],3606]

3436 "total": int,

3437}

3438```3607```

3439 3608 

3440<h3 id="readmcpresource">3609<h3 id="readmcpresource">


3457```python theme={null}3626```python theme={null}

3458{3627{

3459 "contents": [3628 "contents": [

3460 {"uri": str, "mimeType": str | None, "text": str | None, "blob": str | None}3629 {

3630 "uri": str, # URI do recurso

3631 "mimeType": str | None, # Tipo MIME opcional

3632 "text": str | None, # Conteúdo de texto, ou uma nota sobre o conteúdo binário

3633 "blobSavedTo": str | None, # Presente quando Claude Code salvou conteúdo binário em disco; caminho do arquivo salvo

3634 }

3461 ],3635 ],

3462 "server": str,3636 "error": str | None, # Presente quando o servidor não conseguiu ler o recurso

3463}3637}

3464```3638```

3465 3639 

Details

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

576| `outputStyle` | `string` | `undefined` | Não é um campo `Options`. Defina `outputStyle` no objeto [`settings`](/docs/pt/settings) inline ou em um arquivo de configurações. Veja [Ativar um estilo de saída](/docs/pt/agent-sdk/modifying-system-prompts#activate-an-output-style) |576| `outputStyle` | `string` | `undefined` | Não é um campo `Options`. Defina `outputStyle` no objeto [`settings`](/docs/pt/settings) inline ou em um arquivo de configurações. Veja [Ativar um estilo de saída](/docs/pt/agent-sdk/modifying-system-prompts#activate-an-output-style) |

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

578| `permissionMode` | [`PermissionMode`](#permissionmode) | `'default'` | Modo de permissão para a sessão |578| `permissionMode` | [`PermissionMode`](#permissionmode) | `undefined` | Modo de permissão para a sessão. Se você omitir, a sessão pode começar em modo automático. Veja [Modos de permissão](/docs/pt/agent-sdk/permissions#permission-modes) para como Claude Code escolhe o modo de permissão inicial |

579| `permissionPromptToolName` | `string` | `undefined` | Nome da ferramenta MCP para prompts de permissão |579| `permissionPromptToolName` | `string` | `undefined` | Nome da ferramenta MCP para prompts de permissão |

580| `permissionPrompts` | `'host' \| 'none'` | `'host'` | Quem responde aos prompts de permissão: `'host'` os encaminha para seu callback [`canUseTool`](#canusetool) ou a ferramenta `permissionPromptToolName`, e `'none'` [nega as chamadas que teriam solicitado](/docs/pt/agent-sdk/permissions#how-permissions-are-evaluated). Requer Claude Code v2.1.259 ou posterior |580| `permissionPrompts` | `'host' \| 'none'` | `'host'` | Quem responde aos prompts de permissão: `'host'` os encaminha para seu callback [`canUseTool`](#canusetool) ou a ferramenta `permissionPromptToolName`, e `'none'` [nega as chamadas que teriam solicitado](/docs/pt/agent-sdk/permissions#how-permissions-are-evaluated). Requer Claude Code v2.1.259 ou posterior |

581| `persistSession` | `boolean` | `true` | Quando `false`, desativa persistência de sessão em disco. Sessões não podem ser retomadas depois |581| `persistSession` | `boolean` | `true` | Quando `false`, desativa persistência de sessão em disco. Sessões não podem ser retomadas depois |


709| `supportedModels()` | Retorna modelos disponíveis com informações de exibição |709| `supportedModels()` | Retorna modelos disponíveis com informações de exibição |

710| `supportedAgents()` | Retorna subagentes disponíveis como [`AgentInfo`](#agentinfo)`[]` |710| `supportedAgents()` | Retorna subagentes disponíveis como [`AgentInfo`](#agentinfo)`[]` |

711| `mcpServerStatus()` | Retorna status de servidores MCP conectados como [`McpServerStatus`](#mcpserverstatus)`[]` |711| `mcpServerStatus()` | Retorna status de servidores MCP conectados como [`McpServerStatus`](#mcpserverstatus)`[]` |

712| `getContextUsage(opts?)` | Retorna um [`SDKControlGetContextUsageResponse`](#sdkcontrolgetcontextusageresponse) dividindo o uso da janela de contexto da sessão por categoria, skill e ferramenta. Com o `detail` padrão, é o mesmo dado que `/context` mostra em uma sessão interativa. A [opção `detail`](#sdkcontrolgetcontextusageresponse) requer Agent SDK v0.3.257 ou posterior |712| `getContextUsage(opts?)` | Retorna um [`SDKControlGetContextUsageResponse`](#sdkcontrolgetcontextusageresponse) dividindo o uso da janela de contexto da sessão por categoria, skill e ferramenta. Com o `detail` padrão, é o mesmo dado que `/context` mostra em uma sessão interativa, computado com solicitações de API de contagem de token que não aparecem no fluxo de mensagens; veja [como essas solicitações são tratadas](#sdkcontrolgetcontextusageresponse). A [opção `detail`](#sdkcontrolgetcontextusageresponse) requer Agent SDK v0.3.257 ou posterior |

713| `readFile(path, options?)` | Lê um arquivo do sistema de arquivos da sessão. Claude Code resolve o caminho contra `cwd`; [O que `readFile()` pode ler](#what-readfile-can-read) lista os arquivos que ele serve. Passe `{ maxBytes }` para alterar o limite de leitura (padrão 1 MB, teto 10 MB) e `{ encoding: 'base64' }` para arquivos binários como imagens. Resolve com um [`SDKControlReadFileResponse`](#sdkcontrolreadfileresponse), ou `null` em negação de permissão, arquivo ausente, ou erro de transporte. Requer TypeScript SDK v0.2.121 ou posterior |713| `readFile(path, options?)` | Lê um arquivo do sistema de arquivos da sessão. Claude Code resolve o caminho contra `cwd`; [O que `readFile()` pode ler](#what-readfile-can-read) lista os arquivos que ele serve. Passe `{ maxBytes }` para alterar o limite de leitura (padrão 1 MB, teto 10 MB) e `{ encoding: 'base64' }` para arquivos binários como imagens. Resolve com um [`SDKControlReadFileResponse`](#sdkcontrolreadfileresponse), ou `null` em negação de permissão, arquivo ausente, ou erro de transporte. Requer TypeScript SDK v0.2.121 ou posterior |

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

715| `reloadSkills()` | Recarrega 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. Resolve com um [`SDKControlReloadSkillsResponse`](#sdkcontrolreloadskillsresponse) listando as skills disponíveis após o recarregamento. Requer Agent SDK v0.3.163 ou posterior |715| `reloadSkills()` | Recarrega 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. Resolve com um [`SDKControlReloadSkillsResponse`](#sdkcontrolreloadskillsresponse) listando as skills disponíveis após o recarregamento. Requer Agent SDK v0.3.163 ou posterior |

716| `reloadOutputStyles()` | Re-lê [estilos de saída](/docs/pt/output-styles) 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. Resolve com um [`SDKControlReloadOutputStylesResponse`](#sdkcontrolreloadoutputstylesresponse) listando os nomes de estilo disponíveis após o recarregamento. Requer Agent SDK v0.3.261 ou posterior |716| `reloadOutputStyles()` | Re-lê [estilos de saída](/docs/pt/output-styles) 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. Resolve com um [`SDKControlReloadOutputStylesResponse`](#sdkcontrolreloadoutputstylesresponse) listando os nomes de estilo disponíveis após o recarregamento. Requer Agent SDK v0.3.261 ou posterior |

717| `accountInfo()` | Retorna informações de conta |717| `accountInfo()` | Retorna informações de conta |

718| `reconnectMcpServer(serverName)` | Reconectar um servidor MCP por nome. Se o nome também corresponder a uma entrada em um arquivo de configurações como `.mcp.json` ou `~/.claude.json`, Claude Code reconecta o servidor que você configurou através 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 |718| `reconnectMcpServer(serverName)` | Reconectar um servidor MCP por nome. Se o nome também corresponder a uma entrada em um arquivo de configurações como `.mcp.json` ou `~/.claude.json`, Claude Code reconecta o servidor que você configurou através 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 |

719| `toggleMcpServer(serverName, enabled)` | Ativar ou desativar um servidor MCP por nome, com a mesma resolução de nome que `reconnectMcpServer()`. Desativar desconecta o servidor |719| `toggleMcpServer(serverName, enabled)` | Ativar ou desativar um servidor MCP por nome, com a mesma resolução de nome que `reconnectMcpServer()`. Desativar um servidor stdio, SSE ou HTTP o desconecta e remove suas ferramentas; para um servidor que você adicionou no meio da sessão com `setMcpServers()`, a remoção de ferramentas requer Claude Code v2.1.285 ou posterior |

720| `setMcpServers(servers)` | Substituir dinamicamente o conjunto de servidores MCP para esta sessão. Resolve com um [`McpSetServersResult`](#mcpsetserversresult) nomeando quais servidores foram adicionados e removidos, e quaisquer erros |720| `setMcpServers(servers)` | Substituir dinamicamente o conjunto de servidores MCP para esta sessão. Resolve com um [`McpSetServersResult`](#mcpsetserversresult) nomeando quais servidores foram adicionados e removidos, e quaisquer erros |

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

722| `streamInput(stream)` | Transmitir mensagens de entrada para a consulta para conversas multi-turno |722| `streamInput(stream)` | Transmitir mensagens de entrada para a consulta para conversas multi-turno |


909 909 

910Tipo de retorno de [`getContextUsage()`](#query-object). Com o `detail` padrão, este é o mesmo payload que Claude Code renderiza para o comando `/context` em uma sessão interativa, então junto com as contagens de token carrega campos de exibição como `color` e `gridRows` que Claude Code usa para desenhar a grade de uso `/context`.910Tipo de retorno de [`getContextUsage()`](#query-object). Com o `detail` padrão, este é o mesmo payload que Claude Code renderiza para o comando `/context` em uma sessão interativa, então junto com as contagens de token carrega campos de exibição como `color` e `gridRows` que Claude Code usa para desenhar a grade de uso `/context`.

911 911 

912O argumento `detail` opcional do método escolhe como Claude Code conta cada categoria. Com o padrão, `'full'`, Claude Code conta cada categoria com solicitações de API de contagem de token. Passe `{ detail: 'summary' }` para obter uma resposta do uso da última resposta e estimativas locais em vez disso. Nenhuma solicitação de contagem de token sai, e os números por categoria são aproximados. O argumento `detail` requer Agent SDK v0.3.257 ou posterior.912O argumento `detail` opcional do método escolhe como Claude Code conta cada categoria. O argumento `detail` requer Agent SDK v0.3.257 ou posterior.

913 

914* **`'full'`**: o padrão. Claude Code conta cada categoria com [solicitações de API de contagem de token](https://platform.claude.com/docs/pt/build-with-claude/token-counting). Estas solicitações não aparecem no fluxo de mensagens, então rastreamento de custo que lê o fluxo não as verá. Na API Anthropic, contagem de token não é cobrada.

915* **`'summary'`**: passe `{ detail: 'summary' }` para obter uma resposta do uso da última resposta e estimativas locais em vez disso. Nenhuma solicitação de contagem de token sai, e os números por categoria são aproximados.

913 916 

914Quando você envia `/context` como um prompt em vez de chamar o método, Claude Code anexa uma carga [`SDKContextUsage`](#sdkcontextusage) ao campo `context_usage` da mensagem do assistente que entrega o resultado. Esse campo requer Agent SDK v0.3.232 ou posterior.917Quando você envia `/context` como um prompt em vez de chamar o método, Claude Code anexa uma carga [`SDKContextUsage`](#sdkcontextusage) ao campo `context_usage` da mensagem do assistente que entrega o resultado. Esse campo requer Agent SDK v0.3.232 ou posterior.

915 918 


1015* `memoryFiles` lista cada arquivo de memória carregado com seu custo.1018* `memoryFiles` lista cada arquivo de memória carregado com seu custo.

1016* `skills.skillFrontmatter` atribui os tokens da listagem de skills a cada skill incluída. As contagens por skill medem cada entrada de listagem de skill conforme Claude Code realmente a envia, que pode ser mais curta que o frontmatter completo da skill. Compare `skills.totalSkills` com `skills.includedSkills` para ver se cada skill descoberta fez parte da listagem.1019* `skills.skillFrontmatter` atribui os tokens da listagem de skills a cada skill incluída. As contagens por skill medem cada entrada de listagem de skill conforme Claude Code realmente a envia, que pode ser mais curta que o frontmatter completo da skill. Compare `skills.totalSkills` com `skills.includedSkills` para ver se cada skill descoberta fez parte da listagem.

1017 1020 

1018`totalTokens` é o uso de contexto atual da sessão, e `maxTokens` é a janela contra a qual o uso é medido. Essa janela é a janela de contexto do modelo, ou a janela de auto-compactação mais baixa quando uma se aplica. `rawMaxTokens` carrega o mesmo valor que `maxTokens`, e `percentage` é `totalTokens` como uma porcentagem arredondada dessa janela.1021`totalTokens` é o uso de contexto atual da sessão, e `maxTokens` é a janela contra a qual o uso é medido. Essa janela é a janela de contexto do modelo, ou a janela de auto-compactação mais baixa quando uma se aplica. `rawMaxTokens` carrega o mesmo valor que `maxTokens`, e `percentage` é `totalTokens` como uma porcentagem arredondada dessa janela. `apiUsage` contém o uso da resposta de API mais recente, não um total em execução para a sessão.

1019 1022 

1020Claude Code deixa os diagnósticos opcionais `deferredBuiltinTools`, `systemTools`, e `systemPromptSections` não definidos, então espere que estejam ausentes mesmo que o tipo os declare.1023Claude Code deixa os diagnósticos opcionais `deferredBuiltinTools`, `systemTools`, e `systemPromptSections` não definidos, então espere que estejam ausentes mesmo que o tipo os declare.

1021 1024 


1821```typescript theme={null}1824```typescript theme={null}

1822type SDKStartupFailureReason =1825type SDKStartupFailureReason =

1823 | "org_pin_api_key_conflict"1826 | "org_pin_api_key_conflict"

1827 | "provider_not_allowed"

1824 | "org_verify_failed"1828 | "org_verify_failed"

1825 | "org_pin_mismatch"1829 | "org_pin_mismatch"

1826 | "managed_settings_invalid"1830 | "managed_settings_invalid"


1843| Valor | O que parou a sessão |1847| Valor | O que parou a sessão |

1844| :- | :- |1848| :- | :- |

1845| `org_pin_api_key_conflict` | Configurações gerenciadas [requerem um login de gateway de primeira parte ou Cloud](/docs/pt/authentication#restrict-login-to-your-organization), e uma chave de API Anthropic, token de autenticação ou `apiKeyHelper` está configurado em vez disso |1849| `org_pin_api_key_conflict` | Configurações gerenciadas [requerem um login de gateway de primeira parte ou Cloud](/docs/pt/authentication#restrict-login-to-your-organization), e uma chave de API Anthropic, token de autenticação ou `apiKeyHelper` está configurado em vez disso |

1850| `provider_not_allowed` | Configurações gerenciadas [listam os provedores de API que esta máquina pode usar](/docs/pt/settings-reference#allowedproviders), e a sessão está configurada para um provedor que não está listado, ou para um endpoint que as configurações não fixam. Requer Claude Code v2.1.285 ou posterior |

1846| `org_verify_failed` | A organização do login não conseguiu ser verificada contra o pin, por exemplo, por causa de uma falha de rede ou um token revogado |1851| `org_verify_failed` | A organização do login não conseguiu ser verificada contra o pin, por exemplo, por causa de uma falha de rede ou um token revogado |

1847| `org_pin_mismatch` | O login pertence a uma organização que o pin não permite |1852| `org_pin_mismatch` | O login pertence a uma organização que o pin não permite |

1848| `managed_settings_invalid` | Configurações de política gerenciada não conseguiram ser lidas, o pin não nomeia nenhuma organização, ou [restrições de modelo gerenciadas](/docs/pt/errors#managed-settings-block-the-default-model) não deixam nenhum modelo permitido para a opção Padrão |1853| `managed_settings_invalid` | Configurações de política gerenciada não conseguiram ser lidas, o pin não nomeia nenhuma organização, ou [restrições de modelo gerenciadas](/docs/pt/errors#managed-settings-block-the-default-model) não deixam nenhum modelo permitido para a opção Padrão |


2082 `SDKContextUsage`2087 `SDKContextUsage`

2083</h3>2088</h3>

2084 2089 

2085Forma estruturada do relatório `/context`, carregada como `context_usage` na [`SDKAssistantMessage`](#sdkassistantmessage) que entrega um resultado `/context`. Agent SDK v0.3.232 e posterior exportam o tipo. Diferentemente de [`SDKControlGetContextUsageResponse`](#sdkcontrolgetcontextusageresponse), carrega apenas os dados necessários para renderizar o detalhamento de uso, sem campos de exibição como `color` e `gridRows`.2090Forma estruturada do relatório `/context`, carregada como `context_usage` na [`SDKAssistantMessage`](#sdkassistantmessage) que entrega um resultado `/context`. Agent SDK v0.3.232 e posterior exportam o tipo. Diferentemente de [`SDKControlGetContextUsageResponse`](#sdkcontrolgetcontextusageresponse), carrega apenas os dados necessários para renderizar o detalhamento de uso, sem campos de exibição como `color` e `gridRows`. Claude Code computa o relatório com solicitações de API de contagem de tokens que não aparecem no fluxo de mensagens; consulte [como essas solicitações são manipuladas](#sdkcontrolgetcontextusageresponse).

2086 2091 

2087```typescript theme={null}2092```typescript theme={null}

2088type SDKContextUsage = {2093type SDKContextUsage = {


3185};3190};

3186```3191```

3187 3192 

3188Executa comandos Bash com timeout opcional e execução em background. O diretório de trabalho persiste entre comandos, incluindo comandos executados em turnos posteriores de uma sessão multi-turno; o estado do shell, como variáveis de ambiente exportadas, não persiste. Para os limites sobre quais mudanças de diretório são mantidas, veja [O que persiste entre comandos](/docs/pt/tools-reference#what-persists-between-commands). Para o que define o limite de foreground, veja [Timeout e limites de saída](/docs/pt/tools-reference#timeout-and-output-limits). Para o limite de tempo em background, veja [Comandos em background](/docs/pt/tools-reference#background-commands).3193Executa comandos Bash com timeout opcional e execução em background. O diretório de trabalho persiste entre comandos, incluindo comandos executados em turnos posteriores de uma sessão multi-turno; o estado do shell, como variáveis de ambiente exportadas, não persiste. Para os limites sobre quais mudanças de diretório são mantidas, veja [O que persiste entre comandos](/docs/pt/tools-reference#what-persists-between-commands). Para o que define o limite de foreground, veja [Timeout e limites de saída](/docs/pt/tools-reference#timeout-and-output-limits). Para o limite de tempo em background, veja [Limite de tempo para comandos em background](/docs/pt/tools-reference#time-limit-for-background-commands).

3189 3194 

3190<h3 id="monitor">3195<h3 id="monitor">

3191 Monitor3196 Monitor


4089 4094 

4090`timedOutAfterMs` é o tempo limite em milissegundos, definido quando o comando atingiu seu tempo limite e passou para o segundo plano em vez de começar lá explicitamente. `backgroundCwdHint` é definido quando o comando em segundo plano continha um builtin de mudança de diretório como `cd`, `pushd`, `popd` ou `chdir`, e observa que o diretório de trabalho da sessão não mudou. Ambos os campos requerem Claude Code v2.1.210 ou posterior.4095`timedOutAfterMs` é o tempo limite em milissegundos, definido quando o comando atingiu seu tempo limite e passou para o segundo plano em vez de começar lá explicitamente. `backgroundCwdHint` é definido quando o comando em segundo plano continha um builtin de mudança de diretório como `cd`, `pushd`, `popd` ou `chdir`, e observa que o diretório de trabalho da sessão não mudou. Ambos os campos requerem Claude Code v2.1.210 ou posterior.

4091 4096 

4092Quando um subagente em execução em primeiro plano possui um comando em segundo plano, o comando [termina quando a execução desse subagente termina](/docs/pt/tools-reference#background-commands). Claude Code define `backgroundEndsWithFinalResponse` como `true` em tais comandos e omite o campo quando o comando sobrevive ao turno, como comandos iniciados pela conversa principal ou por subagentes em segundo plano fazem. O campo requer Claude Code v2.1.227 ou posterior.4097Quando um subagente em execução em primeiro plano possui um comando em segundo plano, o comando [termina quando a execução desse subagente termina](/docs/pt/tools-reference#when-a-background-command-stops). Claude Code define `backgroundEndsWithFinalResponse` como `true` em tais comandos e omite o campo quando o comando sobrevive ao turno, como comandos iniciados pela conversa principal ou por subagentes em segundo plano fazem. O campo requer Claude Code v2.1.227 ou posterior.

4093 4098 

4094Claude Code define `gitOperation.commit.branch` para o branch nomeado na linha de resumo do commit do git e o omite para um commit feito em um HEAD desanexado. O campo requer Agent SDK v0.3.227 ou posterior. Claude Code relata um comando `gh pr reopen` como a ação PR `reopened`, que requer Agent SDK v0.3.234 ou posterior.4099Claude Code define `gitOperation.commit.branch` para o branch nomeado na linha de resumo do commit do git e o omite para um commit feito em um HEAD desanexado. O campo requer Agent SDK v0.3.227 ou posterior. Claude Code relata um comando `gh pr reopen` como a ação PR `reopened`, que requer Agent SDK v0.3.234 ou posterior.

4095 4100 

agent-view.md +2 −20

Details

8 8 

9Agent view, aberto com `claude agents`, é uma tela para todas as suas sessões em background: o que está em execução, o que precisa de sua entrada e o que está concluído. Despache novas sessões, observe seu estado rapidamente em vez de rolar pelos transcritos e intervenha apenas quando uma precisar de você. Cada sessão em background é uma conversa completa do Claude Code que continua em execução sem um terminal anexado, então você pode abri-la, responder e sair sempre que quiser.9Agent view, aberto com `claude agents`, é uma tela para todas as suas sessões em background: o que está em execução, o que precisa de sua entrada e o que está concluído. Despache novas sessões, observe seu estado rapidamente em vez de rolar pelos transcritos e intervenha apenas quando uma precisar de você. Cada sessão em background é uma conversa completa do Claude Code que continua em execução sem um terminal anexado, então você pode abri-la, responder e sair sempre que quiser.

10 10 

11<img src="https://mintcdn.com/claude-code/1B48Qz2Z9hac4SLG/images/agent-view-light.png?fit=max&auto=format&n=1B48Qz2Z9hac4SLG&q=85&s=7a186c96ed47d6700d084d77e786be65" className="dark:hidden" alt="Agent view em um terminal: o cabeçalho mostra Claude Code v2.1.140, o modelo, o diretório de trabalho e uma contagem de resumo. As sessões são agrupadas em Precisa de entrada, Trabalhando e Concluído, com uma entrada de despacho na parte inferior e um rodapé de dicas de atalhos de teclado." width="1772" height="780" data-path="images/agent-view-light.png" />11<img src="https://mintcdn.com/claude-code/HDAmBwgbrZVk0pOt/images/agent-view-light.png?fit=max&auto=format&n=HDAmBwgbrZVk0pOt&q=85&s=d6905012bee31f3e6b3920b09c05dd02" className="dark:hidden" alt="Agent view em um terminal. Uma linha no topo conta as sessões aguardando entrada, trabalhando e concluídas. Quatro sessões são agrupadas em Precisa de entrada, Trabalhando e Concluído. Cada linha mostra o nome da sessão, seu status ou pergunta mais recente e um horário. Na parte inferior há uma entrada para descrever uma nova tarefa e uma linha de dicas de atalhos de teclado." width="1872" height="680" data-path="images/agent-view-light.png" />

12 12 

13<img src="https://mintcdn.com/claude-code/1B48Qz2Z9hac4SLG/images/agent-view-dark.png?fit=max&auto=format&n=1B48Qz2Z9hac4SLG&q=85&s=a5bed7434bae368faea3a8f023b52aa2" className="hidden dark:block" alt="Agent view em um terminal: o cabeçalho mostra Claude Code v2.1.140, o modelo, o diretório de trabalho e uma contagem de resumo. As sessões são agrupadas em Precisa de entrada, Trabalhando e Concluído, com uma entrada de despacho na parte inferior e um rodapé de dicas de atalhos de teclado." width="1772" height="780" data-path="images/agent-view-dark.png" />13<img src="https://mintcdn.com/claude-code/HDAmBwgbrZVk0pOt/images/agent-view-dark.png?fit=max&auto=format&n=HDAmBwgbrZVk0pOt&q=85&s=fc3c195bfc57e313ced1f1beb36cee93" className="hidden dark:block" alt="Agent view em um terminal. Uma linha no topo conta as sessões aguardando entrada, trabalhando e concluídas. Quatro sessões são agrupadas em Precisa de entrada, Trabalhando e Concluído. Cada linha mostra o nome da sessão, seu status ou pergunta mais recente e um horário. Na parte inferior há uma entrada para descrever uma nova tarefa e uma linha de dicas de atalhos de teclado." width="1872" height="680" data-path="images/agent-view-dark.png" />

14 14 

15Use agent view quando você tiver várias tarefas independentes que Claude pode trabalhar sem você observar cada passo. Despache uma correção de bug, uma revisão de pull request e uma investigação de teste instável como três linhas, continue trabalhando em outra janela e verifique quando uma linha mostrar que precisa de você ou tem um resultado.15Use agent view quando você tiver várias tarefas independentes que Claude pode trabalhar sem você observar cada passo. Despache uma correção de bug, uma revisão de pull request e uma investigação de teste instável como três linhas, continue trabalhando em outra janela e verifique quando uma linha mostrar que precisa de você ou tem um resultado.

16 16 


966 966 

967Claude Code nunca reinicia uma linha executando um [shell command](#run-a-shell-command), de `Enter` ou de `claude attach`, porque isso executaria o comando novamente; a mensagem da linha e `claude attach` ambas dizem que o comando não é executado novamente.967Claude Code nunca reinicia uma linha executando um [shell command](#run-a-shell-command), de `Enter` ou de `claude attach`, porque isso executaria o comando novamente; a mensagem da linha e `claude attach` ambas dizem que o comando não é executado novamente.

968 968 

969<h4 id="terminal-host-died">

970 Terminal host died

971</h4>

972 

973No Linux e WSL, o supervisor verifica cada processo host a cada poucos segundos, independentemente de você abrir a sessão ou não, e marca a sessão como falhada quando o processo saiu mas sua conexão com o supervisor nunca fechou.

974 

975* Em agent view, a linha mostra `terminal host process died — press Enter to restart`. Pressione `Enter` nela e Claude Code reinicia a sessão em um novo processo host.

976* Do shell, `claude attach <id>` reinicia uma sessão já marcada como falhada. Caso contrário, relata a causa e sai, dizendo-lhe para executar `claude attach <id>` novamente.

977 

978<h4 id="session-isn’t-responding">

979 Session isn't responding

980</h4>

981 

982Quando o supervisor aceita uma abertura mas nenhuma saída chega por cerca de dez segundos, Claude Code encerra a tentativa e oferece uma reinicialização. Uma sessão que meramente travou, por exemplo durante o sleep da máquina, não chega a essa oferta: o supervisor [a reinicia ao abrir](#read-session-state) por conta própria.

983 

984* Em agent view, o rodapé mostra `Press enter again to restart this session — it isn't responding (its conversation is saved and resumes).` Pressione `Enter` na mesma linha novamente e Claude Code interrompe o processo que não responde e reinicia a sessão; ele não interrompe nada sem esse segundo pressionamento.

985* Do shell, `claude attach <id>` relata a causa e sai, dizendo-lhe para executar `claude stop <id>`, depois `claude attach <id>`.

986 

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

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

989</h3>971</h3>

Details

384 384 

385Aliases de modelo como `opus` não atuam como fixações, e nem um ID de modelo que Claude Code não reconhece, como um ARN de perfil de inferência de aplicação.385Aliases de modelo como `opus` não atuam como fixações, e nem um ID de modelo que Claude Code não reconhece, como um ARN de perfil de inferência de aplicação.

386 386 

387Quando essas verificações encontram um modelo que sua conta não pode invocar, Claude Code lembra a recusa nesta máquina por até um dia, e durante esse tempo inicia ignorando o modelo lembrado sem perguntar ao Amazon Bedrock novamente. Claude Code verifica uma recusa lembrada de um modelo padrão atual novamente na inicialização uma vez que dez minutos tenham passado desde a última verificação, portanto um padrão que seu administrador reativa volta. Para desativar a memória, defina [`CLAUDE_CODE_SKIP_MODEL_ACCESS_MEMORY=1`](/docs/pt/env-vars).

388 

389<h3 id="when-a-model-is-disabled-mid-session">

390 Quando um modelo é desabilitado durante a sessão

391</h3>

392 

393Se sua conta perder acesso ao modelo em que sua sessão está sendo executada, por exemplo porque um administrador o desabilita em sua conta Amazon Bedrock, Claude Code muda a sessão para outro modelo em vez de falhar em cada solicitação, e mostra `Switched to <fallback> because <model> is not available`. Ele tenta os mesmos modelos que o fallback de inicialização: versões anteriores do mesmo nível primeiro e, para uma sessão Opus sem nenhuma versão Opus disponível, o modelo Sonnet padrão.

394 

395A mudança se aplica apenas a um nível que você não fixou, a mesma condição que o fallback de inicialização. Uma sessão em uma versão específica que você escolheu, ou em um [ARN de perfil de inferência de aplicação](#map-each-model-version-to-an-inference-profile), mantém seu modelo e, sem uma cadeia de fallback de modelo, a solicitação falha em vez disso. Em [modo automático](/docs/pt/permission-modes#enable-auto-mode-on-bedrock-agent-platform-or-foundry), Claude Code muda apenas para um modelo que o modo automático suporta no Amazon Bedrock. Se nenhum desses modelos também estiver disponível, a solicitação falha com [falha de autenticação AWS](/docs/pt/errors#aws-authentication-failed) e uma dica para ativar o modelo.

396 

397Uma [cadeia de fallback de modelo](/docs/pt/model-config#fallback-model-chains) que você configura substitui a mudança de nível: nessas recusas Claude Code muda para seu fallback configurado em vez disso. Para fazer com que solicitações recusadas falhem em vez de mudar, defina [`CLAUDE_CODE_DISABLE_MODEL_ACCESS_FALLBACK=1`](/docs/pt/env-vars). Uma cadeia de fallback que você configurou ainda muda nessas recusas; remova a cadeia também se quiser que cada solicitação recusada falhe.

398 

387<h2 id="cross-region-inference-profile-prefixes">399<h2 id="cross-region-inference-profile-prefixes">

388 Prefixos de perfil de inferência entre regiões400 Prefixos de perfil de inferência entre regiões

389</h2>401</h2>

artifacts.md +1 −1

Details

398| [Variável de ambiente](/docs/pt/env-vars) | Defina `CLAUDE_CODE_DISABLE_ARTIFACT=1` |398| [Variável de ambiente](/docs/pt/env-vars) | Defina `CLAUDE_CODE_DISABLE_ARTIFACT=1` |

399| [Regra de permissão](/docs/pt/permissions) | Adicione `Artifact` a `permissions.deny` |399| [Regra de permissão](/docs/pt/permissions) | Adicione `Artifact` a `permissions.deny` |

400 400 

401Depois que você desativar artefatos em um arquivo [`--settings`](/docs/pt/cli-reference#cli-flags) ou com `CLAUDE_CODE_DISABLE_ARTIFACT`, ou seu administrador os desativar em [configurações gerenciadas](/docs/pt/server-managed-settings), nenhum arquivo de configurações os ativa novamente. Antes da v2.1.242, um arquivo mais alto na [pilha de precedência](/docs/pt/settings#settings-precedence) poderia ativar artefatos novamente mesmo quando um arquivo de precedência mais baixa definisse `"enableArtifact": false`.401Depois que você desativar artefatos em um arquivo [`--settings`](/docs/pt/cli-reference#cli-flags) ou com `CLAUDE_CODE_DISABLE_ARTIFACT`, ou seu administrador os desativar em [configurações gerenciadas](/docs/pt/server-managed-settings), nenhum arquivo de configurações os ativa novamente.

402 402 

403Você também pode definir `"enableArtifact": false` no `.claude/settings.json` ou `.claude/settings.local.json` de um projeto para desativar artefatos para sessões nesse projeto. Um `"enableArtifact": true` em qualquer um dos arquivos não os ativa novamente. Honrar a chave em configurações de projeto e local requer Claude Code v2.1.242 ou posterior.403Você também pode definir `"enableArtifact": false` no `.claude/settings.json` ou `.claude/settings.local.json` de um projeto para desativar artefatos para sessões nesse projeto. Um `"enableArtifact": true` em qualquer um dos arquivos não os ativa novamente. Honrar a chave em configurações de projeto e local requer Claude Code v2.1.242 ou posterior.

404 404 

Details

194* **Sessões do provedor de nuvem como Amazon Bedrock**: bloqueadas apenas enquanto uma credencial `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN` ou `apiKeyHelper`, ou uma chave de API salva por um login anterior do Claude Console, ainda estiver presente na máquina. Remova-a e a sessão inicia. Essas sessões autenticam contra seu provedor de nuvem, cujas políticas de acesso as governam194* **Sessões do provedor de nuvem como Amazon Bedrock**: bloqueadas apenas enquanto uma credencial `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN` ou `apiKeyHelper`, ou uma chave de API salva por um login anterior do Claude Console, ainda estiver presente na máquina. Remova-a e a sessão inicia. Essas sessões autenticam contra seu provedor de nuvem, cujas políticas de acesso as governam

195* **[Perfil Anthropic ou credenciais de federação](#anthropic-profiles-and-federation-credentials)**: não bloqueadas a menos que uma credencial `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN` ou `apiKeyHelper`, ou uma chave de API salva por um login anterior do Claude Console, também esteja presente na máquina. As chaves não verificam a qual organização o perfil pertence195* **[Perfil Anthropic ou credenciais de federação](#anthropic-profiles-and-federation-credentials)**: não bloqueadas a menos que uma credencial `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN` ou `apiKeyHelper`, ou uma chave de API salva por um login anterior do Claude Console, também esteja presente na máquina. As chaves não verificam a qual organização o perfil pertence

196 196 

197<h3 id="restrict-which-api-providers-a-machine-may-use">

198 Restrinja quais provedores de API uma máquina pode usar

199</h3>

200 

201[`allowedProviders`](/docs/pt/settings-reference#allowedproviders) em [configurações gerenciadas](/docs/pt/managed-settings) lista quais serviços uma máquina gerenciada pode alcançar Claude através, como a API Anthropic, Amazon Bedrock ou um gateway LLM. Complementa `forceLoginMethod` e `forceLoginOrgUUID`, que governam qual conta uma sessão usa quando fala com Anthropic. Requer Claude Code v2.1.285 ou posterior.

202 

203```json managed-settings.json theme={null}

204{

205 "forceLoginMethod": "claudeai",

206 "forceLoginOrgUUID": ["xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"],

207 "allowedProviders": ["anthropic", "bedrock"]

208}

209```

210 

211Com este arquivo, um desenvolvedor conectado à sua organização claude.ai ou configurado para Amazon Bedrock inicia normalmente. Uma sessão configurada para qualquer outro provedor é recusada na inicialização, e uma sessão em execução que muda para um é recusada em sua próxima solicitação. [Managed settings don't allow this API provider](/docs/pt/errors#managed-settings-dont-allow-this-api-provider) mostra cada mensagem.

212 

213* **Permita um gateway LLM ou proxy**: liste `"customEndpoint"` e defina a URL do gateway no bloco `env` gerenciado da mesma fonte. A [referência de configurações](/docs/pt/settings-reference#allowedproviders) lista cada valor e diz quais variáveis de endpoint precisam de um pino `env` gerenciado.

214* **Implante em máquinas gerenciadas**: coloque a lista na fonte gerenciada que carrega o resto de sua política. A nota [Scope](/docs/pt/settings-reference#allowedproviders) da entrada diz como uma lista gerenciada pelo servidor se combina com ela.

215* **Apenas configurações gerenciadas pelo servidor**: uma lista que você define apenas em [configurações gerenciadas pelo servidor](/docs/pt/server-managed-settings) alcança apenas sessões que buscam as configurações de sua organização, então trate-a como uma conveniência para máquinas que você não consegue alcançar com gerenciamento de dispositivos, não como aplicação. [Platform availability](/docs/pt/server-managed-settings#platform-availability) lista quais sessões as buscam.

216 

197<h2 id="credential-management">217<h2 id="credential-management">

198 Gerenciamento de credenciais218 Gerenciamento de credenciais

199</h2>219</h2>

Details

285 Editar regras de `/permissions`285 Editar regras de `/permissions`

286</h2>286</h2>

287 287 

288Para visualizar e editar regras do classificador sem abrir um arquivo de configurações, execute [`/permissions`](/docs/pt/permissions#manage-permissions) e selecione a aba **Auto mode**. A aba requer Claude Code v2.1.246 ou posterior, e aparece apenas quando [o modo automático está disponível](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode) para sua sessão.288Para visualizar e editar regras do classificador e entradas `environment` sem abrir um arquivo de configurações, execute [`/permissions`](/docs/pt/permissions#manage-permissions) e selecione a aba **Auto mode**. A aba requer Claude Code v2.1.246 ou posterior, e aparece apenas quando [o modo automático está disponível](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode) para sua sessão.

289 289 

290A aba lista as entradas `allow`, `soft_deny`, `hard_deny` e `environment` de cada um dos [escopos que o classificador lê](#where-the-classifier-reads-configuration), e mostra se as regras integradas estão em vigor para cada seção. Claude Code mostra entradas de [configurações gerenciadas](/docs/pt/server-managed-settings) ou a flag `--settings` como somente leitura, e salva todas as alterações que você faz na aba em `~/.claude/settings.json`. A partir da aba você pode:290Claude Code mostra entradas de [configurações gerenciadas](/docs/pt/server-managed-settings) ou a flag `--settings` como somente leitura, e salva todas as alterações que você faz na aba em `~/.claude/settings.json`.

291 

292* Adicionar, editar ou excluir regras nas seções `allow`, `soft_deny` e `hard_deny`. Quando você adiciona a primeira regra a uma seção, Claude Code também insere `"$defaults"` para que as [regras integradas](#override-the-block-and-allow-rules) permaneçam em vigor.

293* Desativar ou reativar as regras integradas para `allow`, `soft_deny` ou `hard_deny`. Claude Code registra a escolha adicionando ou removendo `"$defaults"` em sua lista para essa seção, portanto uma seção precisa de pelo menos uma regra sua antes que você possa desativar suas regras integradas.

294* Editar as entradas `environment` como um documento em seu editor. Se você ainda não configurou nenhuma entrada `environment`, Claude Code primeiro pergunta se deseja substituir o ambiente integrado, depois abre o editor no texto integrado completo. Quando você salva, Claude Code substitui sua matriz `autoMode.environment` pelo documento. Inclua a linha `"$defaults"` para [manter as entradas integradas](#define-trusted-infrastructure).

295 291 

296<h2 id="route-all-shell-commands-through-the-classifier">292<h2 id="route-all-shell-commands-through-the-classifier">

297 Rotear todos os comandos shell através do classificador293 Rotear todos os comandos shell através do classificador

Details

1561| `paste-cache/` | Conteúdo de grandes colagens |1561| `paste-cache/` | Conteúdo de grandes colagens |

1562| `image-cache/<session>/` | Imagens anexadas salvas por Claude Code v2.1.274 e anteriores. Versões posteriores salvam imagens coladas e anexadas fora de `~/.claude`, em um diretório `images/` para cada sessão sob o diretório temporário que [`CLAUDE_CODE_TMPDIR`](/docs/pt/env-vars) controla. A varredura remove diretórios restantes de outras sessões aqui, independentemente da idade. |1562| `image-cache/<session>/` | Imagens anexadas salvas por Claude Code v2.1.274 e anteriores. Versões posteriores salvam imagens coladas e anexadas fora de `~/.claude`, em um diretório `images/` para cada sessão sob o diretório temporário que [`CLAUDE_CODE_TMPDIR`](/docs/pt/env-vars) controla. A varredura remove diretórios restantes de outras sessões aqui, independentemente da idade. |

1563| `uploads/<session>/` | Arquivos que você anexa da web ou do aplicativo móvel, e fotos que você anexa do aplicativo móvel, ao enviar mensagens para uma sessão de [Remote Control](/docs/pt/remote-control). Um anexo a uma [sessão em nuvem](/docs/pt/claude-code-on-the-web) é salvo no próprio ambiente em nuvem dessa sessão, não na sua máquina. |1563| `uploads/<session>/` | Arquivos que você anexa da web ou do aplicativo móvel, e fotos que você anexa do aplicativo móvel, ao enviar mensagens para uma sessão de [Remote Control](/docs/pt/remote-control). Um anexo a uma [sessão em nuvem](/docs/pt/claude-code-on-the-web) é salvo no próprio ambiente em nuvem dessa sessão, não na sua máquina. |

1564| `dev-mods/<session>/` | [Mods que Claude escreveu](/docs/pt/plugins/mods/create#ask-claude-for-a-mod) durante a sessão |

1564| `session-env/` | Metadados de ambiente por sessão |1565| `session-env/` | Metadados de ambiente por sessão |

1565| `tasks/` | Listas de tarefas escritas pelas ferramentas de tarefa, um diretório por lista |1566| `tasks/` | Listas de tarefas escritas pelas ferramentas de tarefa, um diretório por lista |

1566| `shell-snapshots/` | Aliases, funções e opções de shell capturadas na inicialização e aplicadas pela [ferramenta Bash](/docs/pt/tools-reference#bash-tool-behavior) a cada comando. Removidas na saída limpa. A varredura limpa qualquer uma deixada após um crash. |1567| `shell-snapshots/` | Aliases, funções e opções de shell capturadas na inicialização e aplicadas pela [ferramenta Bash](/docs/pt/tools-reference#bash-tool-behavior) a cada comando. Removidas na saída limpa. A varredura limpa qualquer uma deixada após um crash. |

Details

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

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

86| `--debug-file <path>` | Escrever logs de depuração em um caminho de arquivo específico. Ativa implicitamente o modo de depuração. Tem precedência sobre `CLAUDE_CODE_DEBUG_LOGS_DIR` | `claude --debug-file /tmp/claude-debug.log` |86| `--debug-file <path>` | Escrever logs de depuração em um caminho de arquivo específico. Ativa implicitamente o modo de depuração. Tem precedência sobre `CLAUDE_CODE_DEBUG_LOGS_DIR` | `claude --debug-file /tmp/claude-debug.log` |

87| `--desktop` | Abrir o [aplicativo Claude Desktop](/docs/pt/desktop) no diretório atual e sair sem iniciar uma sessão no terminal. Adicione `--continue` ou `--resume` com um ID de sessão para [abrir essa sessão no Desktop](/docs/pt/desktop#coming-from-the-cli) em vez disso. `--resume` aqui leva apenas um ID de sessão, não um nome ou caminho de transcrição. Não leva prompt e nenhum outro sinalizador exceto `--verbose` e os sinalizadores `--debug`, já que o aplicativo inicia a sessão em si. Disponível em macOS e Windows x64 quando você está conectado com uma assinatura Claude. Requer Claude Code v2.1.285 ou posterior | `claude --desktop` |

87| `--disable-slash-commands` | Desativar todas as skills e comandos para esta sessão | `claude --disable-slash-commands` |88| `--disable-slash-commands` | Desativar todas as skills e comandos para esta sessão | `claude --disable-slash-commands` |

88| `--disallowedTools`, `--disallowed-tools` | Regras de negação. Um nome de ferramenta simples remove as ferramentas correspondentes do contexto do Claude: `"Edit"` remove Edit, `"*"` remove todas as ferramentas e `"mcp__*"` remove todas as ferramentas MCP. Uma regra com escopo como `Bash(rm *)` deixa a ferramenta disponível e nega apenas chamadas correspondentes [conforme escrito](/docs/pt/permissions#bash-rule-limits). Uma regra nomeando [`EndConversation`](/docs/pt/tools-reference#endconversation-tool-behavior) não pode removê-la enquanto qualquer outra ferramenta permanecer | `"Bash(git log *)" "Bash(git diff *)" "Edit"` |89| `--disallowedTools`, `--disallowed-tools` | Regras de negação. Um nome de ferramenta simples remove as ferramentas correspondentes do contexto do Claude: `"Edit"` remove Edit, `"*"` remove todas as ferramentas e `"mcp__*"` remove todas as ferramentas MCP. Uma regra com escopo como `Bash(rm *)` deixa a ferramenta disponível e nega apenas chamadas correspondentes [conforme escrito](/docs/pt/permissions#bash-rule-limits). Uma regra nomeando [`EndConversation`](/docs/pt/tools-reference#endconversation-tool-behavior) não pode removê-la enquanto qualquer outra ferramenta permanecer | `"Bash(git log *)" "Bash(git diff *)" "Edit"` |

89| `--effort` | Definir o [nível de esforço](/docs/pt/model-config#adjust-effort-level) para a sessão atual. Opções: `low`, `medium`, `high`, `xhigh`, `max` ou `ultracode`. Os níveis disponíveis dependem do modelo. `ultracode` inicia a sessão em esforço `xhigh` com [ultracode](/docs/pt/workflows#let-claude-decide-with-ultracode) ativado e requer Claude Code v2.1.203 ou posterior. Substitui as configurações [`modelSettings`](/docs/pt/settings-reference#modelsettings) e [`effortLevel`](/docs/pt/settings-reference#effortlevel) para esta sessão e não persiste | `claude --effort high` |90| `--effort` | Definir o [nível de esforço](/docs/pt/model-config#adjust-effort-level) para a sessão atual. Opções: `low`, `medium`, `high`, `xhigh`, `max` ou `ultracode`. Os níveis disponíveis dependem do modelo. `ultracode` inicia a sessão em esforço `xhigh` com [ultracode](/docs/pt/workflows#let-claude-decide-with-ultracode) ativado e requer Claude Code v2.1.203 ou posterior. Substitui as configurações [`modelSettings`](/docs/pt/settings-reference#modelsettings) e [`effortLevel`](/docs/pt/settings-reference#effortlevel) para esta sessão e não persiste | `claude --effort high` |


111| `--no-chrome` | Desativar [integração do navegador Chrome](/docs/pt/chrome) para esta sessão | `claude --no-chrome` |112| `--no-chrome` | Desativar [integração do navegador Chrome](/docs/pt/chrome) para esta sessão | `claude --no-chrome` |

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

113| `--output-format` | Especificar formato de saída para modo print (opções: `text`, `json`, `stream-json`) | `claude -p "query" --output-format json` |114| `--output-format` | Especificar formato de saída para modo print (opções: `text`, `json`, `stream-json`) | `claude -p "query" --output-format json` |

114| `--permission-mode` | Começar em um [modo de permissão](/docs/pt/permission-modes) especificado. Aceita `default`, `acceptEdits`, `plan`, `auto`, `dontAsk`, `bypassPermissions` ou `manual` como um alias para `default`. O alias `manual` seleciona o modo de permissão que a UI rotula como Manual e requer Claude Code v2.1.200 ou posterior; `claude --help` o lista no lugar de `default` e ambos os valores funcionam. Substitui `defaultMode` dos arquivos de configuração. Sem este sinalizador ou `--dangerously-skip-permissions`, uma nova sessão inicia no modo de permissão descrito em [qual modo de permissão uma sessão inicia](/docs/pt/permission-modes#which-mode-a-session-starts-in). Para `-p`, isso é `default` quando nada está configurado | `claude --permission-mode plan` |115| `--permission-mode` | Começar em um [modo de permissão](/docs/pt/permission-modes) especificado. Aceita `default`, `acceptEdits`, `plan`, `auto`, `dontAsk`, `bypassPermissions` ou `manual` como um alias para `default`. O alias `manual` seleciona o modo de permissão que a UI rotula como Manual e requer Claude Code v2.1.200 ou posterior; `claude --help` o lista no lugar de `default` e ambos os valores funcionam. Substitui `defaultMode` dos arquivos de configuração. Sem este sinalizador ou `--dangerously-skip-permissions`, uma nova sessão inicia no modo de permissão descrito em [qual modo de permissão uma sessão inicia](/docs/pt/permission-modes#which-mode-a-session-starts-in), que também cobre o que uma execução `-p` inicia | `claude --permission-mode plan` |

115| `--permission-prompt-tool` | Especificar uma ferramenta MCP para lidar com prompts de permissão em modo não interativo. Claude Code aguarda a conexão do servidor MCP dessa ferramenta antes de executar o primeiro turno, até o tempo limite de inicialização [`MCP_TIMEOUT`](/docs/pt/env-vars), 30 segundos por padrão. <br /><br />A ferramenta de prompt não pode aprovar uma ferramenta MCP marcada como [exigindo interação do usuário](/docs/pt/mcp#require-approval-for-a-specific-tool): Claude Code converte um resultado `allow` para uma em uma negação. Esta restrição requer Claude Code v2.1.199 ou posterior | `claude -p --permission-prompt-tool mcp_auth_tool "query"` |116| `--permission-prompt-tool` | Especificar uma ferramenta MCP para lidar com prompts de permissão em modo não interativo. Claude Code aguarda a conexão do servidor MCP dessa ferramenta antes de executar o primeiro turno, até o tempo limite de inicialização [`MCP_TIMEOUT`](/docs/pt/env-vars), 30 segundos por padrão. <br /><br />A ferramenta de prompt não pode aprovar uma ferramenta MCP marcada como [exigindo interação do usuário](/docs/pt/mcp#require-approval-for-a-specific-tool): Claude Code converte um resultado `allow` para uma em uma negação. Esta restrição requer Claude Code v2.1.199 ou posterior | `claude -p --permission-prompt-tool mcp_auth_tool "query"` |

116| `--permission-prompts` | Definir quem responde prompts de permissão em modo print. Com o padrão `host`, Claude Code os envia para o host do Agent SDK ou a ferramenta `--permission-prompt-tool`. Passe `none` quando ninguém puder responder, e Claude Code os nega em vez disso. Veja [Desativar prompts de permissão em execuções sem supervisão](/docs/pt/headless#turn-off-permission-prompts-in-unattended-runs). Requer Claude Code v2.1.259 ou posterior | `claude -p --permission-prompts none "query"` |117| `--permission-prompts` | Definir quem responde prompts de permissão em modo print. Com o padrão `host`, Claude Code os envia para o host do Agent SDK ou a ferramenta `--permission-prompt-tool`. Passe `none` quando ninguém puder responder, e Claude Code os nega em vez disso. Veja [Desativar prompts de permissão em execuções sem supervisão](/docs/pt/headless#turn-off-permission-prompts-in-unattended-runs). Requer Claude Code v2.1.259 ou posterior | `claude -p --permission-prompts none "query"` |

117| `--plugin-dir` | Carregar um plugin de um diretório ou arquivo `.zip`, ou vários de uma [pasta de plugins](/docs/pt/plugins/create#load-a-directory-or-archive-for-one-session), apenas para esta sessão. Cada sinalizador leva um caminho. Repita o sinalizador para mais caminhos: `--plugin-dir A --plugin-dir B.zip`. Passar uma pasta de plugins requer Claude Code v2.1.265 ou posterior | `claude --plugin-dir ./my-plugin` |118| `--plugin-dir` | Carregar um plugin de um diretório ou arquivo `.zip`, ou vários de uma [pasta de plugins](/docs/pt/plugins/create#load-a-directory-or-archive-for-one-session), apenas para esta sessão. Cada sinalizador leva um caminho. Repita o sinalizador para mais caminhos: `--plugin-dir A --plugin-dir B.zip`. Passar uma pasta de plugins requer Claude Code v2.1.265 ou posterior | `claude --plugin-dir ./my-plugin` |

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

119| `--print`, `-p` | Imprimir resposta sem modo interativo (veja [documentação do Agent SDK](/docs/pt/agent-sdk/overview) para detalhes de uso programático) | `claude -p "query"` |120| `--print`, `-p` | Imprimir resposta sem modo interativo (veja [documentação do Agent SDK](/docs/pt/agent-sdk/overview) para detalhes de uso programático). Para `--resume` em uma sessão de fundo que ainda está em execução, veja [Retomar uma sessão](/docs/pt/sessions#resume-a-running-background-session) | `claude -p "query"` |

120| `--prompt-suggestions` | Emitir uma mensagem `prompt_suggestion` com um prompt de usuário previsto após cada turno que gera um; conversas muito curtas podem não produzir nenhum. Requer `--print`, `--output-format stream-json` e `--verbose`. Veja [Sugestões de prompt](/docs/pt/interactive-mode#prompt-suggestions) | `claude -p --prompt-suggestions --output-format stream-json --verbose "query"` |121| `--prompt-suggestions` | Emitir uma mensagem `prompt_suggestion` com um prompt de usuário previsto após cada turno que gera um; conversas muito curtas podem não produzir nenhum. Requer `--print`, `--output-format stream-json` e `--verbose`. Veja [Sugestões de prompt](/docs/pt/interactive-mode#prompt-suggestions) | `claude -p --prompt-suggestions --output-format stream-json --verbose "query"` |

121| `--ref <branch>` | Com `--environment`, basear o checkout da nova sessão em uma ref nomeada em vez de `HEAD` local | `claude -p "Run the smoke test" --environment ccpool_abc123 --ref main` |122| `--ref <branch>` | Com `--environment`, basear o checkout da nova sessão em uma ref nomeada em vez de `HEAD` local | `claude -p "Run the smoke test" --environment ccpool_abc123 --ref main` |

122| `--remote` | Alias descontinuado para `--cloud`, incluindo o formulário de sessão existente | `claude --remote "Fix the login bug"` |123| `--remote` | Alias descontinuado para `--cloud`, incluindo o formulário de sessão existente | `claude --remote "Fix the login bug"` |


124| `--remote-control-session-name-prefix <prefix>` | Prefixo para nomes de sessão [Remote Control](/docs/pt/remote-control) gerados automaticamente quando nenhum nome explícito está definido. Padrão é o nome do host da sua máquina, produzindo nomes como `myhost-graceful-unicorn`. Defina `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` para o mesmo efeito | `claude remote-control --remote-control-session-name-prefix dev-box` |125| `--remote-control-session-name-prefix <prefix>` | Prefixo para nomes de sessão [Remote Control](/docs/pt/remote-control) gerados automaticamente quando nenhum nome explícito está definido. Padrão é o nome do host da sua máquina, produzindo nomes como `myhost-graceful-unicorn`. Defina `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` para o mesmo efeito | `claude remote-control --remote-control-session-name-prefix dev-box` |

125| `--replay-user-messages` | Re-emitir mensagens do usuário de stdin de volta em stdout para confirmação. Requer `--input-format stream-json` e `--output-format stream-json` | `claude -p --input-format stream-json --output-format stream-json --verbose --replay-user-messages` |126| `--replay-user-messages` | Re-emitir mensagens do usuário de stdin de volta em stdout para confirmação. Requer `--input-format stream-json` e `--output-format stream-json` | `claude -p --input-format stream-json --output-format stream-json --verbose --replay-user-messages` |

126| `--restricted` | Iniciar em modo restrito. Use-o quando um harness de avaliação dirige `claude` em uma máquina compartilhada e Claude Code não deve executar comandos ou ler configurações de usuário e projeto dessa máquina. Claude Code remove as ferramentas integradas que executam comandos ou código, e WebFetch, a menos que você as nomeie individualmente em `--tools`, não através do preset `default`. Também confina as ferramentas de arquivo integradas aos [diretórios de trabalho](/docs/pt/permissions#working-directories), carrega apenas [configurações gerenciadas](/docs/pt/managed-settings) e `--settings`, recusa [`bypassPermissions`](/docs/pt/permission-modes#skip-all-checks-with-bypasspermissions-mode) e [recusa criar sessões em nuvem](/docs/pt/errors#cloud-sessions-cannot-be-created-from-a-restricted-session). Requer Claude Code v2.1.248 ou posterior | `claude --restricted -p "query"` |127| `--restricted` | Iniciar em modo restrito. Use-o quando um harness de avaliação dirige `claude` em uma máquina compartilhada e Claude Code não deve executar comandos ou ler configurações de usuário e projeto dessa máquina. Claude Code remove as ferramentas integradas que executam comandos ou código, e WebFetch, a menos que você as nomeie individualmente em `--tools`, não através do preset `default`. Também confina as ferramentas de arquivo integradas aos [diretórios de trabalho](/docs/pt/permissions#working-directories), carrega apenas [configurações gerenciadas](/docs/pt/managed-settings) e `--settings`, recusa [`bypassPermissions`](/docs/pt/permission-modes#skip-all-checks-with-bypasspermissions-mode) e [recusa criar sessões em nuvem](/docs/pt/errors#cloud-sessions-cannot-be-created-from-a-restricted-session). Requer Claude Code v2.1.248 ou posterior | `claude --restricted -p "query"` |

127| `--resume`, `-r` | Retomar uma sessão específica por ID ou nome, ou mostrar um seletor interativo para escolher uma sessão. No lugar de um ID, você pode passar o caminho absoluto para o arquivo de [transcrição](/docs/pt/sessions#where-transcripts-are-stored) `.jsonl` de uma sessão. O seletor e a busca por nome incluem sessões que adicionaram este diretório com `/add-dir`. Quando você passa um ID de sessão, Claude Code pesquisa o diretório do projeto atual e seus git worktrees, depois todos os outros projetos nesta máquina. Antes de v2.1.223, a busca de ID cobria apenas o diretório do projeto atual e seus git worktrees. [Sessões de fundo](/docs/pt/agent-view) aparecem no seletor marcadas com `bg` | `claude --resume auth-refactor` |128| `--resume`, `-r` | Retomar uma sessão específica por ID ou nome, ou mostrar um seletor interativo para escolher uma sessão. No lugar de um ID, você pode passar o caminho absoluto para o arquivo de [transcrição](/docs/pt/sessions#where-transcripts-are-stored) `.jsonl` de uma sessão. O seletor e a busca por nome incluem sessões que adicionaram este diretório com `/add-dir`. Quando você passa um ID de sessão, Claude Code pesquisa o diretório do projeto atual e seus git worktrees, depois todos os outros projetos nesta máquina. Antes de v2.1.223, a busca de ID cobria apenas o diretório do projeto atual e seus git worktrees. [Sessões de fundo](/docs/pt/agent-view) aparecem no seletor marcadas com `bg`. Retomar uma que ainda está em execução [abre essa sessão](/docs/pt/sessions#resume-a-running-background-session) neste terminal através de `claude attach`, e um prompt que você passa na linha de comando vai para ela como seu próximo turno. Antes de v2.1.285, Claude Code recusava e imprimia o comando `claude attach` para executar em vez disso | `claude --resume auth-refactor` |

128| `--safe-mode` | Iniciar com todas as personalizações desativadas para solucionar problemas de uma configuração quebrada: CLAUDE.md, skills, plugins, hooks, servidores MCP, comandos e agentes personalizados, estilos de saída, workflows, temas personalizados, atalhos de teclado personalizados, comandos de linha de status e sugestão de arquivo, servidores LSP e memória automática não carregam. Autenticação, seleção de modelo, ferramentas integradas e permissões funcionam normalmente, o que difere de [`--bare`](/docs/pt/headless#start-faster-with-bare-mode). A política de configurações gerenciadas ainda se aplica, incluindo hooks configurados por política, linha de status e comandos de sugestão de arquivo; plugins gerenciados, skills gerenciadas, CLAUDE.md gerenciado e servidores MCP configurados por política não. Útil para verificar se uma personalização é o que dispara [fallback automático de modelo](/docs/pt/model-config#automatic-model-fallback). Define [`CLAUDE_CODE_SAFE_MODE`](/docs/pt/env-vars) | `claude --safe-mode` |129| `--safe-mode` | Iniciar com todas as personalizações desativadas para solucionar problemas de uma configuração quebrada: CLAUDE.md, skills, plugins, hooks, servidores MCP, comandos e agentes personalizados, estilos de saída, workflows, temas personalizados, atalhos de teclado personalizados, comandos de linha de status e sugestão de arquivo, servidores LSP e memória automática não carregam. Autenticação, seleção de modelo, ferramentas integradas e permissões funcionam normalmente, o que difere de [`--bare`](/docs/pt/headless#start-faster-with-bare-mode). A política de configurações gerenciadas ainda se aplica, incluindo hooks configurados por política, linha de status e comandos de sugestão de arquivo; plugins gerenciados, skills gerenciadas, CLAUDE.md gerenciado e servidores MCP configurados por política não. Útil para verificar se uma personalização é o que dispara [fallback automático de modelo](/docs/pt/model-config#automatic-model-fallback). Define [`CLAUDE_CODE_SAFE_MODE`](/docs/pt/env-vars) | `claude --safe-mode` |

129| `--session-id` | Usar um ID de sessão específico para a conversa (deve ser um UUID válido) | `claude --session-id "550e8400-e29b-41d4-a716-446655440000"` |130| `--session-id` | Usar um ID de sessão específico para a conversa (deve ser um UUID válido) | `claude --session-id "550e8400-e29b-41d4-a716-446655440000"` |

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

Details

439 439 

440* **Comandos que Claude executa**: um ambiente na nuvem não define seu próprio timeout de comando, portanto os padrões da ferramenta Bash se aplicam. Claude aguarda 2 minutos por um comando por padrão e pode pedir até 10 minutos.440* **Comandos que Claude executa**: um ambiente na nuvem não define seu próprio timeout de comando, portanto os padrões da ferramenta Bash se aplicam. Claude aguarda 2 minutos por um comando por padrão e pode pedir até 10 minutos.

441 441 

442 Quando um comando atinge seu [timeout](/docs/pt/tools-reference#timeout-and-output-limits), Claude Code [o move para o background](/docs/pt/tools-reference#background-commands) em vez de pará-lo, a menos que o comando comece com `sleep`. Um comando movido dessa forma pode continuar executando por até 30 minutos a mais antes de Claude Code pará-lo em seu [limite de tempo de background](/docs/pt/tools-reference#background-commands). Definir `BASH_DEFAULT_TIMEOUT_MS` acima de `1800000` milissegundos alonga esse limite bem como o padrão de foreground.442 Quando um comando atinge seu [timeout](/docs/pt/tools-reference#timeout-and-output-limits), Claude Code [o move para o background](/docs/pt/tools-reference#foreground-commands-that-move-to-the-background) em vez de pará-lo, a menos que o comando comece com `sleep`. Um comando movido dessa forma pode continuar executando por até 30 minutos a mais antes de Claude Code pará-lo em seu [limite de tempo de background](/docs/pt/tools-reference#time-limit-for-background-commands). Definir `BASH_DEFAULT_TIMEOUT_MS` acima de `1800000` milissegundos alonga esse limite bem como o padrão de foreground.

443* **Hooks SessionStart**: Claude Code cancela um hook `command` após 600 segundos a menos que você defina [`timeout`](/docs/pt/hooks#common-fields), em segundos, na entrada do hook. Claude Code não aplica o timeout em um hook que você executa com [`async: true`](/docs/pt/hooks#run-hooks-in-the-background).443* **Hooks SessionStart**: Claude Code cancela um hook `command` após 600 segundos a menos que você defina [`timeout`](/docs/pt/hooks#common-fields), em segundos, na entrada do hook. Claude Code não aplica o timeout em um hook que você executa com [`async: true`](/docs/pt/hooks#run-hooks-in-the-background).

444* **Script de configuração**: um script que leva mais tempo do que aproximadamente cinco minutos não é armazenado em cache. [Requisitos de script](#script-requirements) cobre como ficar abaixo disso.444* **Script de configuração**: um script que leva mais tempo do que aproximadamente cinco minutos não é armazenado em cache. [Requisitos de script](#script-requirements) cobre como ficar abaixo disso.

445* **Sessões inativas**: após alguns minutos sem atividade, a VM de uma sessão pausa com seus arquivos salvos, e uma VM pausada pode ser recuperada posteriormente. [Defina variáveis de ambiente](#set-environment-variables) descreve o que uma sessão pega em cada caso, e [Environment expired](/docs/pt/claude-code-on-the-web#environment-expired) cobre como reabrir uma sessão cuja VM foi recuperada.445* **Sessões inativas**: após alguns minutos sem atividade, a VM de uma sessão pausa com seus arquivos salvos, e uma VM pausada pode ser recuperada posteriormente. [Defina variáveis de ambiente](#set-environment-variables) descreve o que uma sessão pega em cada caso, e [Environment expired](/docs/pt/claude-code-on-the-web#environment-expired) cobre como reabrir uma sessão cuja VM foi recuperada.

commands.md +1 −1

Details

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

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

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

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

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

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

138| `/run` | **[Skill](/docs/pt/skills#bundled-skills).** Inicie e dirija o aplicativo do seu projeto para ver uma mudança funcionando, não apenas passando testes. Consulte [Execute e verifique seu aplicativo](/docs/pt/skills#run-and-verify-your-app) |138| `/run` | **[Skill](/docs/pt/skills#bundled-skills).** Inicie e dirija o aplicativo do seu projeto para ver uma mudança funcionando, não apenas passando testes. Consulte [Execute e verifique seu aplicativo](/docs/pt/skills#run-and-verify-your-app) |

Details

1634 1634 

1635Se você precisar de uma janela maior em vez de uma conversa menor, modelos Fable, Sonnet 5 e posteriores, Opus 4.6 e posteriores, e Sonnet 4.6 suportam uma janela de contexto de 1 milhão de tokens. Veja [Extended context](/docs/pt/model-config#extended-context) para disponibilidade por plano e como selecionar uma variante de modelo `[1m]`. A compactação funciona da mesma forma no limite maior.1635Se você precisar de uma janela maior em vez de uma conversa menor, modelos Fable, Sonnet 5 e posteriores, Opus 4.6 e posteriores, e Sonnet 4.6 suportam uma janela de contexto de 1 milhão de tokens. Veja [Extended context](/docs/pt/model-config#extended-context) para disponibilidade por plano e como selecionar uma variante de modelo `[1m]`. A compactação funciona da mesma forma no limite maior.

1636 1636 

1637Sonnet 5.5 e Sonnet 5 são executados com a janela de contexto de 1M e não têm variante `[1m]` para selecionar. Veja [Sonnet 5.5 and Sonnet 5 context window](/docs/pt/model-config#sonnet-5-5-and-sonnet-5-context-window) para seus limites de auto-compactação e a exceção do gateway LLM.1637Sonnet 5.5 e Sonnet 5 são executados com a janela de contexto de 1M e não têm variante `[1m]` para selecionar. Veja [Sonnet 5.5 and Sonnet 5 context window](/docs/pt/model-config#sonnet-5-5-and-sonnet-5-context-window) para seus limites de auto-compactação, e [the context window behind a gateway](/docs/pt/model-config#context-window-behind-a-gateway) para como Claude Code dimensiona a janela quando você define `ANTHROPIC_BASE_URL` para um [LLM gateway](/docs/pt/llm-gateway).

1638 1638 

1639O ponto em que a compactação automática é executada depende do seu modelo e configuração. Veja [Default auto-compact thresholds](/docs/pt/model-config#default-auto-compact-thresholds) para os limites por modelo, e [Correct the window for a gateway or custom model ID](/docs/pt/model-config#correct-the-window-for-a-gateway-or-custom-model-id) se Claude Code assumir a janela errada para seu ID de modelo, como um alias de [LLM gateway](/docs/pt/llm-gateway).1639O ponto em que a compactação automática é executada depende do seu modelo e configuração. Veja [Default auto-compact thresholds](/docs/pt/model-config#default-auto-compact-thresholds) para os limites por modelo, e [Correct the window for a gateway or custom model ID](/docs/pt/model-config#correct-the-window-for-a-gateway-or-custom-model-id) se Claude Code assumir a janela errada para seu ID de modelo, como um alias de [LLM gateway](/docs/pt/llm-gateway).

1640 1640 

costs.md +1 −1

Details

51 51 

52As falhas, reconstruções esperadas e partes aquecidas ou frias da linha significam o seguinte:52As falhas, reconstruções esperadas e partes aquecidas ou frias da linha significam o seguinte:

53 53 

54* **Misses**: solicitações que reprocessaram conteúdo que o cache já continha, com a hora da última falha e quantos tokens essas solicitações escreveram de volta no cache. Claude Code conta uma solicitação como uma falha quando a solicitação reprocessou mais de 5% e pelo menos 2.000 tokens do que poderia ter lido do cache. [Ações que invalidam o cache](/docs/pt/prompt-caching#actions-that-invalidate-the-cache) lista as causas usuais. Quando Claude Code pode identificar uma causa provável para a última falha, a linha a nomeia também, por exemplo `likely cause: tool definitions changed`. O texto de causa provável requer Claude Code v2.1.260 ou posterior.54* **Misses**: solicitações que reprocessaram conteúdo que o cache já continha, com a hora da última falha e quantos tokens essas solicitações escreveram de volta no cache. [Ações que invalidam o cache](/docs/pt/prompt-caching#actions-that-invalidate-the-cache) lista as causas usuais. Quando Claude Code pode identificar uma causa provável para a última falha, a linha a nomeia também, por exemplo `likely cause: tool definitions changed`. O texto de causa provável requer Claude Code v2.1.260 ou posterior.

55* **Expected rebuilds**: quando Claude Code reescreveu a conversa, por [compactação](/docs/pt/prompt-caching#compacting-the-conversation) ou limpando resultados de ferramentas antigas do contexto, ele conta o mesmo tipo de falha como uma reconstrução esperada. Esta parte aparece apenas após pelo menos uma reconstrução esperada ter acontecido.55* **Expected rebuilds**: quando Claude Code reescreveu a conversa, por [compactação](/docs/pt/prompt-caching#compacting-the-conversation) ou limpando resultados de ferramentas antigas do contexto, ele conta o mesmo tipo de falha como uma reconstrução esperada. Esta parte aparece apenas após pelo menos uma reconstrução esperada ter acontecido.

56* **Warm or cold**: se o prefixo em cache ainda está dentro de seu [tempo de vida do cache](/docs/pt/prompt-caching#cache-lifetime), com o TTL em vigor. Quando o cache está frio, a linha mostra há quanto tempo a sessão está ociosa. Quando nenhuma resposta relatou tokens de cache, a linha termina com `no prompt caching reported by the API`.56* **Warm or cold**: se o prefixo em cache ainda está dentro de seu [tempo de vida do cache](/docs/pt/prompt-caching#cache-lifetime), com o TTL em vigor. Quando o cache está frio, a linha mostra há quanto tempo a sessão está ociosa. Quando nenhuma resposta relatou tokens de cache, a linha termina com `no prompt caching reported by the API`.

57 57 

desktop.md +8 −0

Details

967 967 

968Para mover uma sessão CLI para Desktop, execute `/desktop` no terminal. Claude salva sua sessão e a abre no aplicativo desktop, depois sai do CLI. Este comando está disponível em macOS e Windows x64 quando você está conectado com uma assinatura Claude. Não está disponível com autenticação de chave de API ou em Amazon Bedrock, Google Cloud's Agent Platform ou Microsoft Foundry.968Para mover uma sessão CLI para Desktop, execute `/desktop` no terminal. Claude salva sua sessão e a abre no aplicativo desktop, depois sai do CLI. Este comando está disponível em macOS e Windows x64 quando você está conectado com uma assinatura Claude. Não está disponível com autenticação de chave de API ou em Amazon Bedrock, Google Cloud's Agent Platform ou Microsoft Foundry.

969 969 

970Do seu shell, [`claude --desktop`](/docs/pt/cli-reference#cli-flags) abre Desktop diretamente sem iniciar uma sessão de terminal. Requer Claude Code v2.1.285 ou posterior e tem os mesmos requisitos de plataforma e login que `/desktop`. Sem outros argumentos, abre Desktop no diretório atual. Para abrir uma sessão CLI existente em Desktop, adicione `--continue` para a conversa mais recente neste diretório, ou `--resume` com o ID da sessão que `/status` mostra:

971 

972```bash theme={null}

973claude --desktop --resume <session-id>

974```

975 

976Claude Code imprime `Opening session <session-id> in Claude Desktop`, a sessão abre no aplicativo e o comando sai. Um nome de sessão não funciona no lugar do ID. Claude Code não move uma sessão que está aberta em outro terminal ou ainda em execução em segundo plano. Se Claude Desktop não estiver instalado, o comando imprime um link de download e sai.

977 

970Você também pode retomar uma sessão CLI de dentro do Desktop com `/resume`. O comando está disponível em sessões locais, não em SSH, WSL ou sessões na nuvem.978Você também pode retomar uma sessão CLI de dentro do Desktop com `/resume`. O comando está disponível em sessões locais, não em SSH, WSL ou sessões na nuvem.

971 979 

972Para continuar uma sessão de terminal em Desktop:980Para continuar uma sessão de terminal em Desktop:

desktop-linux.md +12 −0

Details

163 163 

164Se `claude-desktop` sair com esta mensagem, você o iniciou como root. Faça login como um usuário regular e inicie-o a partir daí.164Se `claude-desktop` sair com esta mensagem, você o iniciou como root. Faça login como um usuário regular e inicie-o a partir daí.

165 165 

166<h3 id="your-sign-in-won’t-be-saved-on-this-device">

167 Seu sign-in não será salvo neste dispositivo

168</h3>

169 

170Claude Desktop salva seu sign-in no keyring do seu desktop, como GNOME Keyring ou KDE Wallet. Se não conseguir acessar um keyring desbloqueado, seu sign-in não será salvo e você fará login novamente cada vez que iniciar o aplicativo. Escolha o caso que corresponde ao seu sistema:

171 

172* **Nenhum keyring instalado, em um desktop diferente de KDE Plasma**: se você instalou com `--no-install-recommends`, ou em uma imagem mínima que pula pacotes recomendados, o apt não instalou um keyring. Instale GNOME Keyring com `sudo apt install gnome-keyring`.

173* **KDE Plasma com GNOME Keyring também instalado**: KDE Wallet vem com o desktop Plasma. Os dois keyrings entram em conflito, e Claude Desktop pode mostrar este aviso mesmo que KDE Wallet funcione. Remova o extra com `sudo apt remove gnome-keyring`, depois reinicie seu computador.

174* **Keyring instalado mas bloqueado**: desbloqueie-o.

175 

176Após a correção, reinicie o aplicativo e faça login. Depois saia e inicie-o novamente para confirmar que o aplicativo abre com você ainda conectado.

177 

166<h3 id="cowork-isn’t-available">178<h3 id="cowork-isn’t-available">

167 Cowork não está disponível179 Cowork não está disponível

168</h3>180</h3>

env-vars.md +211 −209

Details

56 </Tab>56 </Tab>

57</Tabs>57</Tabs>

58 58 

59A linha de atribuição não imprime nada em caso de sucesso, então confirme se a variável está definida imprimindo-a no mesmo shell antes de executar `claude`:59A linha de atribuição não imprime nada em caso de sucesso. Para confirmar que a variável está definida, imprima-a no mesmo shell:

60 60 

61<Tabs>61<Tabs>

62 <Tab title="macOS, Linux, WSL">62 <Tab title="macOS, Linux, WSL">


127Variáveis numéricas como timeouts, orçamentos de tokens e contagens de tentativas aceitam notação científica e grafias com separadores de dígitos além de dígitos simples, exceto onde a linha de uma variável observa que ela aceita apenas dígitos simples. Por exemplo, Claude Code lê `2e3` como 2000 e `64_000` como 64000. Antes da v2.1.211, essas grafias poderiam silenciosamente definir um valor muito menor, como `1e6` definindo um timeout para 1.127Variáveis numéricas como timeouts, orçamentos de tokens e contagens de tentativas aceitam notação científica e grafias com separadores de dígitos além de dígitos simples, exceto onde a linha de uma variável observa que ela aceita apenas dígitos simples. Por exemplo, Claude Code lê `2e3` como 2000 e `64_000` como 64000. Antes da v2.1.211, essas grafias poderiam silenciosamente definir um valor muito menor, como `1e6` definindo um timeout para 1.

128 128 

129<Note>129<Note>

130 Para variáveis que ativam ou desativam um comportamento, defina `1` ou `true` para ativar e `0` ou `false` para desativar, em qualquer capitalização.130 Para variáveis que ativam ou desativam um comportamento, defina `1`, `true`, `yes` ou `on` para ativar e `0`, `false`, `no` ou `off` para desativar, em qualquer capitalização.

131 131 

132 Algumas variáveis leem apenas se você as definiu, então qualquer valor não vazio, incluindo `0`, ativa o comportamento, e você desativa o comportamento ao desconfigurar a variável ou defini-la como um valor vazio. Essas variáveis funcionam dessa forma:132 Algumas variáveis leem apenas se você as definiu, então qualquer valor não vazio, incluindo `0`, ativa o comportamento, e você desativa o comportamento desconfigurado a variável ou definindo-a como um valor vazio. Essas variáveis funcionam dessa forma:

133 133 

134 * `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`134 * `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`

135 * `DISABLE_TELEMETRY`135 * `DISABLE_TELEMETRY`


138 * `FALLBACK_FOR_ALL_PRIMARY_MODELS`138 * `FALLBACK_FOR_ALL_PRIMARY_MODELS`

139 * `IS_DEMO`139 * `IS_DEMO`

140 140 

141 Uma outra variável tem sua própria regra: `FORCE_HYPERLINK` lê um número, então apenas `0` a desativa. A linha de cada variável também declara sua própria regra.141 Uma outra variável tem sua própria regra: `FORCE_HYPERLINK` lê um número, então apenas `0` a desativa. Cada linha de variável também declara sua própria regra.

142</Note>142</Note>

143 143 

144| Variável | Propósito |144| Variável | Propósito |

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

146| `ANTHROPIC_API_KEY` | Chave de API enviada como cabeçalho `X-Api-Key`. Quando definida, essa chave é usada em vez de sua assinatura Claude Pro, Max, Team ou Enterprise, mesmo que você esteja conectado. Em modo não interativo (`-p`), a chave é sempre usada quando presente. Em modo interativo, você é solicitado a aprovar a chave uma vez antes de ela substituir sua assinatura. Para usar sua assinatura, execute `unset ANTHROPIC_API_KEY` |146| `ANTHROPIC_API_KEY` | Chave de API enviada como cabeçalho `X-Api-Key`. Quando definida, essa chave é usada em vez de sua assinatura Claude Pro, Max, Team ou Enterprise, mesmo que você esteja conectado. Em modo não interativo (`-p`), a chave é sempre usada quando presente. Em modo interativo, você é solicitado a aprovar a chave uma vez antes que ela substitua sua assinatura. Para usar sua assinatura, execute `unset ANTHROPIC_API_KEY` |

147| `ANTHROPIC_AUTH_TOKEN` | Valor personalizado para o cabeçalho `Authorization` (o valor que você definir aqui será prefixado com `Bearer `) |147| `ANTHROPIC_AUTH_TOKEN` | Valor personalizado para o cabeçalho `Authorization` (o valor que você definir aqui será prefixado com `Bearer `) |

148| `ANTHROPIC_AWS_API_KEY` | Chave de API do workspace para [Claude Platform on AWS](/docs/pt/claude-platform-on-aws), gerada no AWS Console. Enviada como `x-api-key` e tem precedência sobre AWS SigV4 |148| `ANTHROPIC_AWS_API_KEY` | Chave de API do workspace para [Claude Platform on AWS](/docs/pt/claude-platform-on-aws), gerada no AWS Console. Enviada como `x-api-key` e tem precedência sobre AWS SigV4 |

149| `ANTHROPIC_AWS_BASE_URL` | Substitua a URL do endpoint [Claude Platform on AWS](/docs/pt/claude-platform-on-aws). Use para regiões personalizadas ou ao rotear através de um [gateway LLM](/docs/pt/llm-gateway). Padrão: `https://aws-external-anthropic.{region}.api.aws`. Claude Code resolve a região com a [mesma precedência que no Amazon Bedrock](/docs/pt/amazon-bedrock#3-configure-claude-code) |149| `ANTHROPIC_AWS_BASE_URL` | Substitua a URL do endpoint [Claude Platform on AWS](/docs/pt/claude-platform-on-aws). Use para regiões personalizadas ou ao rotear através de um [gateway LLM](/docs/pt/llm-gateway). Padrão é `https://aws-external-anthropic.{region}.api.aws`. Claude Code resolve a região com a [mesma precedência que no Amazon Bedrock](/docs/pt/amazon-bedrock#3-configure-claude-code) |

150| `ANTHROPIC_AWS_WORKSPACE_ID` | Obrigatório para [Claude Platform on AWS](/docs/pt/claude-platform-on-aws). Enviado em cada solicitação como o cabeçalho `anthropic-workspace-id` |150| `ANTHROPIC_AWS_WORKSPACE_ID` | Obrigatório para [Claude Platform on AWS](/docs/pt/claude-platform-on-aws). Enviado em cada solicitação como o cabeçalho `anthropic-workspace-id` |

151| `ANTHROPIC_BASE_URL` | Substitua o endpoint da API para rotear solicitações através de um proxy ou gateway. Quando definido para um host que não é de primeira parte, [busca de ferramentas MCP](/docs/pt/mcp#scale-with-mcp-tool-search) é desabilitada por padrão. Defina `ENABLE_TOOL_SEARCH=true` se seu proxy encaminha blocos `tool_reference`. A partir da v2.1.196, [Remote Control](/docs/pt/remote-control#requirements) é desabilitado quando isso aponta para um host diferente de `api.anthropic.com`, correspondendo ao seu comportamento no Amazon Bedrock, Google Cloud's Agent Platform e Microsoft Foundry |151| `ANTHROPIC_BASE_URL` | Substitua o endpoint da API para rotear solicitações através de um proxy ou gateway. Quando definido para um host que não é de primeira parte, [busca de ferramentas MCP](/docs/pt/mcp#scale-with-mcp-tool-search) é desabilitada por padrão. Defina `ENABLE_TOOL_SEARCH=true` se seu proxy encaminha blocos `tool_reference`. A partir da v2.1.196, [Remote Control](/docs/pt/remote-control#requirements) é desabilitado quando isso aponta para um host diferente de `api.anthropic.com`, correspondendo ao seu comportamento no Amazon Bedrock, Google Cloud's Agent Platform e Microsoft Foundry |

152| `ANTHROPIC_BEDROCK_BASE_URL` | Substitua a URL do endpoint Amazon Bedrock. Use para endpoints Amazon Bedrock personalizados ou ao rotear através de um [gateway LLM](/docs/pt/llm-gateway). Veja [Amazon Bedrock](/docs/pt/amazon-bedrock) |152| `ANTHROPIC_BEDROCK_BASE_URL` | Substitua a URL do endpoint do Amazon Bedrock. Use para endpoints personalizados do Amazon Bedrock ou ao rotear através de um [gateway LLM](/docs/pt/llm-gateway). Veja [Amazon Bedrock](/docs/pt/amazon-bedrock) |

153| `ANTHROPIC_BEDROCK_MANTLE_BASE_URL` | Substitua a URL do endpoint Amazon Bedrock Mantle. Veja [endpoint Mantle](/docs/pt/amazon-bedrock#use-the-mantle-endpoint) |153| `ANTHROPIC_BEDROCK_MANTLE_BASE_URL` | Substitua a URL do endpoint do Amazon Bedrock Mantle. Veja [endpoint Mantle](/docs/pt/amazon-bedrock#use-the-mantle-endpoint) |

154| `ANTHROPIC_BEDROCK_REGION_PREFIX` | Prefixo do perfil de inferência entre regiões (`us`, `eu`, `apac`, `jp`, `au` ou `global`) que Claude Code tenta primeiro em vez do derivado da região AWS. Ignorado em regiões AWS GovCloud. Requer Claude Code v2.1.224 ou posterior. Veja [Amazon Bedrock](/docs/pt/amazon-bedrock#cross-region-inference-profile-prefixes) |154| `ANTHROPIC_BEDROCK_REGION_PREFIX` | Prefixo do perfil de inferência entre regiões (`us`, `eu`, `apac`, `jp`, `au` ou `global`) que Claude Code tenta primeiro em vez do derivado da região AWS. Ignorado em regiões AWS GovCloud. Requer Claude Code v2.1.224 ou posterior. Veja [Amazon Bedrock](/docs/pt/amazon-bedrock#cross-region-inference-profile-prefixes) |

155| `ANTHROPIC_BEDROCK_SERVICE_TIER` | [Nível de serviço](https://docs.aws.amazon.com/bedrock/latest/userguide/service-tiers-inference.html) Amazon Bedrock (`default`, `flex` ou `priority`). Enviado como o cabeçalho `X-Amzn-Bedrock-Service-Tier`. Veja [Amazon Bedrock](/docs/pt/amazon-bedrock#service-tiers) |155| `ANTHROPIC_BEDROCK_SERVICE_TIER` | [Nível de serviço](https://docs.aws.amazon.com/bedrock/latest/userguide/service-tiers-inference.html) do Amazon Bedrock (`default`, `flex` ou `priority`). Enviado como o cabeçalho `X-Amzn-Bedrock-Service-Tier`. Veja [Amazon Bedrock](/docs/pt/amazon-bedrock#service-tiers) |

156| `ANTHROPIC_BETAS` | Lista separada por vírgulas de valores de cabeçalho `anthropic-beta` adicionais para incluir em solicitações de API. Claude Code já envia os cabeçalhos beta que precisa; use isso para optar por um [beta da API Anthropic](https://platform.claude.com/docs/en/api/beta-headers) antes de Claude Code adicionar suporte nativo. Diferentemente da flag [`--betas`](/docs/pt/cli-reference#cli-flags), que requer autenticação de chave de API, essa variável funciona com todos os métodos de autenticação, incluindo assinatura Claude.ai |156| `ANTHROPIC_BETAS` | Lista separada por vírgulas de valores adicionais de cabeçalho `anthropic-beta` para incluir em solicitações de API. Claude Code já envia os cabeçalhos beta que precisa; use isso para optar por um [beta da API Anthropic](https://platform.claude.com/docs/en/api/beta-headers) antes que Claude Code adicione suporte nativo. Diferentemente da flag [`--betas`](/docs/pt/cli-reference#cli-flags), que requer autenticação de chave de API, essa variável funciona com todos os métodos de autenticação, incluindo assinatura Claude.ai |

157| `ANTHROPIC_CUSTOM_HEADERS` | Cabeçalhos personalizados para adicionar a solicitações (formato `Name: Value`, separados por quebra de linha para múltiplos cabeçalhos). Se um nome ou valor contiver um caractere que um cabeçalho HTTP não pode carregar, como uma aspas curva ou um espaço de largura zero, a solicitação falha com um erro que identifica o par por posição. Requer Claude Code v2.1.227 ou posterior. [Valor de cabeçalho de solicitação inválido](/docs/pt/errors#invalid-request-header-value) lista o conjunto exato de caracteres e onde a verificação é executada. Um valor que define um cabeçalho de credencial, org ou tenant, roteamento ou comportamento de API, como `Authorization` ou `Host`, conta como uma [configuração que precisa de aprovação](/docs/pt/server-managed-settings#environment-variables-and-the-approval-dialog) quando as configurações gerenciadas pelo servidor a entregam. A partir de configurações de projeto ou local, tal valor segue as [regras para quando valores `env` se aplicam](/docs/pt/settings-reference#when-claude-code-applies-env-values) |157| `ANTHROPIC_CUSTOM_HEADERS` | Cabeçalhos personalizados para adicionar a solicitações (formato `Name: Value`, separados por quebra de linha para múltiplos cabeçalhos). Se um nome ou valor contiver um caractere que um cabeçalho HTTP não pode carregar, como uma aspas curva ou um espaço de largura zero, a solicitação falha com um erro que identifica o par por posição. Requer Claude Code v2.1.227 ou posterior. [Valor de cabeçalho de solicitação inválido](/docs/pt/errors#invalid-request-header-value) lista o conjunto exato de caracteres e onde a verificação é executada. Um valor que define um cabeçalho de credencial, org ou tenant, roteamento ou comportamento de API, como `Authorization` ou `Host`, conta como uma [configuração que precisa de aprovação](/docs/pt/server-managed-settings#environment-variables-and-the-approval-dialog) quando as configurações gerenciadas pelo servidor a entregam. A partir de configurações de projeto ou local, tal valor segue as [regras para quando valores `env` se aplicam](/docs/pt/settings-reference#when-claude-code-applies-env-values) |

158| `ANTHROPIC_CUSTOM_MODEL_OPTION` | ID do modelo para adicionar como entrada personalizada no seletor `/model`. Use isso para tornar um modelo não padrão ou específico de gateway selecionável sem substituir aliases integrados. Veja [Configuração de modelo](/docs/pt/model-config#add-a-custom-model-option) |158| `ANTHROPIC_CUSTOM_MODEL_OPTION` | ID do modelo para adicionar como entrada personalizada no seletor `/model`. Use isso para tornar um modelo não padrão ou específico de gateway selecionável sem substituir aliases integrados. Veja [Configuração de modelo](/docs/pt/model-config#add-a-custom-model-option) |

159| `ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION` | Descrição de exibição para a entrada de modelo personalizado no seletor `/model`. Padrão: `Custom model (<model-id>)` quando não definido |159| `ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION` | Descrição de exibição para a entrada de modelo personalizado no seletor `/model`. Padrão é `Custom model (<model-id>)` quando não definido |

160| `ANTHROPIC_CUSTOM_MODEL_OPTION_NAME` | Nome de exibição para a entrada de modelo personalizado no seletor `/model`. Quando não definido, a entrada mostra o nome do modelo se Claude Code [reconhecer o ID](/docs/pt/model-config#customize-pinned-model-display-and-capabilities), e o ID do modelo caso contrário |160| `ANTHROPIC_CUSTOM_MODEL_OPTION_NAME` | Nome de exibição para a entrada de modelo personalizado no seletor `/model`. Quando não definido, a entrada mostra o nome do modelo se Claude Code [reconhecer o ID](/docs/pt/model-config#customize-pinned-model-display-and-capabilities), e o ID do modelo caso contrário |

161| `ANTHROPIC_CUSTOM_MODEL_OPTION_SUPPORTED_CAPABILITIES` | Lista separada por vírgulas de [capacidades](/docs/pt/model-config#customize-pinned-model-display-and-capabilities) que o modelo personalizado suporta, por exemplo `effort,thinking`. Veja [Configuração de modelo](/docs/pt/model-config#customize-pinned-model-display-and-capabilities) |161| `ANTHROPIC_CUSTOM_MODEL_OPTION_SUPPORTED_CAPABILITIES` | Lista separada por vírgulas de [capacidades](/docs/pt/model-config#customize-pinned-model-display-and-capabilities) que o modelo personalizado suporta, por exemplo `effort,thinking`. Veja [Configuração de modelo](/docs/pt/model-config#customize-pinned-model-display-and-capabilities) |

162| `ANTHROPIC_DEFAULT_FABLE_MODEL` | ID do modelo que o alias `fable` resolve para, e o ID que Claude Code reconhece como um modelo Fable para [fallback automático de modelo](/docs/pt/model-config#automatic-model-fallback) em provedores de terceiros. Veja [Configuração de modelo](/docs/pt/model-config#environment-variables) |162| `ANTHROPIC_DEFAULT_FABLE_MODEL` | ID do modelo para o qual o alias `fable` se resolve, e o ID que Claude Code reconhece como um modelo Fable para [fallback automático de modelo](/docs/pt/model-config#automatic-model-fallback) em provedores de terceiros. Veja [Configuração de modelo](/docs/pt/model-config#environment-variables) |

163| `ANTHROPIC_DEFAULT_FABLE_MODEL_DESCRIPTION` | Descrição de exibição para o modelo Fable fixado no seletor `/model`. Quando não definido, a linha mostra uma descrição padrão que começa com `Custom Fable model`. Veja [Configuração de modelo](/docs/pt/model-config#customize-pinned-model-display-and-capabilities) |163| `ANTHROPIC_DEFAULT_FABLE_MODEL_DESCRIPTION` | Descrição de exibição para o modelo Fable fixado no seletor `/model`. Quando não definido, a linha mostra uma descrição padrão que começa com `Custom Fable model`. Veja [Configuração de modelo](/docs/pt/model-config#customize-pinned-model-display-and-capabilities) |

164| `ANTHROPIC_DEFAULT_FABLE_MODEL_NAME` | Nome de exibição para o modelo Fable fixado no seletor `/model`. Quando não definido, a linha mostra o nome do modelo se Claude Code reconhecer o ID fixado, e o ID fixado caso contrário. Veja [Configuração de modelo](/docs/pt/model-config#customize-pinned-model-display-and-capabilities) |164| `ANTHROPIC_DEFAULT_FABLE_MODEL_NAME` | Nome de exibição para o modelo Fable fixado no seletor `/model`. Quando não definido, a linha mostra o nome do modelo se Claude Code reconhecer o ID fixado, e o ID fixado caso contrário. Veja [Configuração de modelo](/docs/pt/model-config#customize-pinned-model-display-and-capabilities) |

165| `ANTHROPIC_DEFAULT_FABLE_MODEL_SUPPORTED_CAPABILITIES` | Lista separada por vírgulas de [capacidades](/docs/pt/model-config#customize-pinned-model-display-and-capabilities) que o modelo Fable fixado suporta, por exemplo `effort,thinking`. Veja [Configuração de modelo](/docs/pt/model-config#customize-pinned-model-display-and-capabilities) |165| `ANTHROPIC_DEFAULT_FABLE_MODEL_SUPPORTED_CAPABILITIES` | Lista separada por vírgulas de [capacidades](/docs/pt/model-config#customize-pinned-model-display-and-capabilities) que o modelo Fable fixado suporta, por exemplo `effort,thinking`. Veja [Configuração de modelo](/docs/pt/model-config#customize-pinned-model-display-and-capabilities) |

166| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | ID do modelo que o alias `haiku` resolve para, também usado para [funcionalidade em background](/docs/pt/costs#background-token-usage). Veja [Configuração de modelo](/docs/pt/model-config#environment-variables) |166| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | ID do modelo para o qual o alias `haiku` se resolve, também usado para [funcionalidade em segundo plano](/docs/pt/costs#background-token-usage). Veja [Configuração de modelo](/docs/pt/model-config#environment-variables) |

167| `ANTHROPIC_DEFAULT_HAIKU_MODEL_DESCRIPTION` | Descrição de exibição para o modelo Haiku fixado no seletor `/model`. Quando não definido, a linha mostra uma descrição padrão que começa com `Custom Haiku model`. Veja [Configuração de modelo](/docs/pt/model-config#customize-pinned-model-display-and-capabilities) |167| `ANTHROPIC_DEFAULT_HAIKU_MODEL_DESCRIPTION` | Descrição de exibição para o modelo Haiku fixado no seletor `/model`. Quando não definido, a linha mostra uma descrição padrão que começa com `Custom Haiku model`. Veja [Configuração de modelo](/docs/pt/model-config#customize-pinned-model-display-and-capabilities) |

168| `ANTHROPIC_DEFAULT_HAIKU_MODEL_NAME` | Nome de exibição para o modelo Haiku fixado no seletor `/model`. Quando não definido, a linha mostra o nome do modelo se Claude Code reconhecer o ID fixado, e o ID fixado caso contrário. Veja [Configuração de modelo](/docs/pt/model-config#customize-pinned-model-display-and-capabilities) |168| `ANTHROPIC_DEFAULT_HAIKU_MODEL_NAME` | Nome de exibição para o modelo Haiku fixado no seletor `/model`. Quando não definido, a linha mostra o nome do modelo se Claude Code reconhecer o ID fixado, e o ID fixado caso contrário. Veja [Configuração de modelo](/docs/pt/model-config#customize-pinned-model-display-and-capabilities) |

169| `ANTHROPIC_DEFAULT_HAIKU_MODEL_SUPPORTED_CAPABILITIES` | Lista separada por vírgulas de [capacidades](/docs/pt/model-config#customize-pinned-model-display-and-capabilities) que o modelo Haiku fixado suporta, por exemplo `effort,thinking`. Veja [Configuração de modelo](/docs/pt/model-config#customize-pinned-model-display-and-capabilities) |169| `ANTHROPIC_DEFAULT_HAIKU_MODEL_SUPPORTED_CAPABILITIES` | Lista separada por vírgulas de [capacidades](/docs/pt/model-config#customize-pinned-model-display-and-capabilities) que o modelo Haiku fixado suporta, por exemplo `effort,thinking`. Veja [Configuração de modelo](/docs/pt/model-config#customize-pinned-model-display-and-capabilities) |

170| `ANTHROPIC_DEFAULT_MODEL` | Modelo em que novas sessões começam por padrão. Requer Claude Code v2.1.236 ou posterior. Veja [Defina um modelo padrão para novas sessões](/docs/pt/model-config#set-a-default-model-for-new-sessions) |170| `ANTHROPIC_DEFAULT_MODEL` | Modelo em que novas sessões começam por padrão. Requer Claude Code v2.1.236 ou posterior. Veja [Defina um modelo padrão para novas sessões](/docs/pt/model-config#set-a-default-model-for-new-sessions) |

171| `ANTHROPIC_DEFAULT_OPUS_MODEL` | ID do modelo que o alias `opus` resolve para, e que `opusplan` usa enquanto Plan Mode está ativo. Veja [Configuração de modelo](/docs/pt/model-config#environment-variables) |171| `ANTHROPIC_DEFAULT_OPUS_MODEL` | ID do modelo para o qual o alias `opus` se resolve, e que `opusplan` usa enquanto Plan Mode está ativo. Veja [Configuração de modelo](/docs/pt/model-config#environment-variables) |

172| `ANTHROPIC_DEFAULT_OPUS_MODEL_DESCRIPTION` | Descrição de exibição para o modelo Opus fixado no seletor `/model`. Quando não definido, a linha mostra uma descrição padrão que começa com `Custom Opus model`. Veja [Configuração de modelo](/docs/pt/model-config#customize-pinned-model-display-and-capabilities) |172| `ANTHROPIC_DEFAULT_OPUS_MODEL_DESCRIPTION` | Descrição de exibição para o modelo Opus fixado no seletor `/model`. Quando não definido, a linha mostra uma descrição padrão que começa com `Custom Opus model`. Veja [Configuração de modelo](/docs/pt/model-config#customize-pinned-model-display-and-capabilities) |

173| `ANTHROPIC_DEFAULT_OPUS_MODEL_NAME` | Nome de exibição para o modelo Opus fixado no seletor `/model`. Quando não definido, a linha mostra o nome do modelo se Claude Code reconhecer o ID fixado, e o ID fixado caso contrário. Veja [Configuração de modelo](/docs/pt/model-config#customize-pinned-model-display-and-capabilities) |173| `ANTHROPIC_DEFAULT_OPUS_MODEL_NAME` | Nome de exibição para o modelo Opus fixado no seletor `/model`. Quando não definido, a linha mostra o nome do modelo se Claude Code reconhecer o ID fixado, e o ID fixado caso contrário. Veja [Configuração de modelo](/docs/pt/model-config#customize-pinned-model-display-and-capabilities) |

174| `ANTHROPIC_DEFAULT_OPUS_MODEL_SUPPORTED_CAPABILITIES` | Lista separada por vírgulas de [capacidades](/docs/pt/model-config#customize-pinned-model-display-and-capabilities) que o modelo Opus fixado suporta, por exemplo `effort,thinking`. Veja [Configuração de modelo](/docs/pt/model-config#customize-pinned-model-display-and-capabilities) |174| `ANTHROPIC_DEFAULT_OPUS_MODEL_SUPPORTED_CAPABILITIES` | Lista separada por vírgulas de [capacidades](/docs/pt/model-config#customize-pinned-model-display-and-capabilities) que o modelo Opus fixado suporta, por exemplo `effort,thinking`. Veja [Configuração de modelo](/docs/pt/model-config#customize-pinned-model-display-and-capabilities) |

175| `ANTHROPIC_DEFAULT_SONNET_MODEL` | ID do modelo que o alias `sonnet` resolve para, e que `opusplan` usa quando Plan Mode não está ativo. Veja [Configuração de modelo](/docs/pt/model-config#environment-variables) |175| `ANTHROPIC_DEFAULT_SONNET_MODEL` | ID do modelo para o qual o alias `sonnet` se resolve, e que `opusplan` usa quando Plan Mode não está ativo. Veja [Configuração de modelo](/docs/pt/model-config#environment-variables) |

176| `ANTHROPIC_DEFAULT_SONNET_MODEL_DESCRIPTION` | Descrição de exibição para o modelo Sonnet fixado no seletor `/model`. Quando não definido, a linha mostra uma descrição padrão que começa com `Custom Sonnet model`. Veja [Configuração de modelo](/docs/pt/model-config#customize-pinned-model-display-and-capabilities) |176| `ANTHROPIC_DEFAULT_SONNET_MODEL_DESCRIPTION` | Descrição de exibição para o modelo Sonnet fixado no seletor `/model`. Quando não definido, a linha mostra uma descrição padrão que começa com `Custom Sonnet model`. Veja [Configuração de modelo](/docs/pt/model-config#customize-pinned-model-display-and-capabilities) |

177| `ANTHROPIC_DEFAULT_SONNET_MODEL_NAME` | Nome de exibição para o modelo Sonnet fixado no seletor `/model`. Quando não definido, a linha mostra o nome do modelo se Claude Code reconhecer o ID fixado, e o ID fixado caso contrário. Veja [Configuração de modelo](/docs/pt/model-config#customize-pinned-model-display-and-capabilities) |177| `ANTHROPIC_DEFAULT_SONNET_MODEL_NAME` | Nome de exibição para o modelo Sonnet fixado no seletor `/model`. Quando não definido, a linha mostra o nome do modelo se Claude Code reconhecer o ID fixado, e o ID fixado caso contrário. Veja [Configuração de modelo](/docs/pt/model-config#customize-pinned-model-display-and-capabilities) |

178| `ANTHROPIC_DEFAULT_SONNET_MODEL_SUPPORTED_CAPABILITIES` | Lista separada por vírgulas de [capacidades](/docs/pt/model-config#customize-pinned-model-display-and-capabilities) que o modelo Sonnet fixado suporta, por exemplo `effort,thinking`. Veja [Configuração de modelo](/docs/pt/model-config#customize-pinned-model-display-and-capabilities) |178| `ANTHROPIC_DEFAULT_SONNET_MODEL_SUPPORTED_CAPABILITIES` | Lista separada por vírgulas de [capacidades](/docs/pt/model-config#customize-pinned-model-display-and-capabilities) que o modelo Sonnet fixado suporta, por exemplo `effort,thinking`. Veja [Configuração de modelo](/docs/pt/model-config#customize-pinned-model-display-and-capabilities) |

179| `ANTHROPIC_FEDERATION_RULE_ID` | ID da regra de federação para [Workload Identity Federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation). Quando você a define junto com `ANTHROPIC_ORGANIZATION_ID`, Claude Code seleciona credenciais de federação, que têm precedência sobre sua credencial `/login`. Veja [precedência de autenticação](/docs/pt/authentication#authentication-precedence) |179| `ANTHROPIC_FEDERATION_RULE_ID` | ID da regra de federação para [Workload Identity Federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation). Quando você a define junto com `ANTHROPIC_ORGANIZATION_ID`, Claude Code seleciona credenciais de federação, que têm precedência sobre sua credencial `/login`. Veja [precedência de autenticação](/docs/pt/authentication#authentication-precedence) |

180| `ANTHROPIC_FOUNDRY_API_KEY` | Chave de API para autenticação Microsoft Foundry (veja [Microsoft Foundry](/docs/pt/microsoft-foundry)) |180| `ANTHROPIC_FOUNDRY_API_KEY` | Chave de API para autenticação do Microsoft Foundry (veja [Microsoft Foundry](/docs/pt/microsoft-foundry)) |

181| `ANTHROPIC_FOUNDRY_AUTH_TOKEN` | Token Bearer para autenticação Microsoft Foundry, como um token de acesso Microsoft Entra. Claude Code o envia como o cabeçalho `Authorization: Bearer`. Tem precedência sobre `ANTHROPIC_FOUNDRY_API_KEY` e sobre a cadeia de credencial padrão do Azure. Veja [Microsoft Foundry](/docs/pt/microsoft-foundry). Requer Claude Code v2.1.203 ou posterior |181| `ANTHROPIC_FOUNDRY_AUTH_TOKEN` | Token de portador para autenticação do Microsoft Foundry, como um token de acesso do Microsoft Entra. Claude Code o envia como o cabeçalho `Authorization: Bearer`. Tem precedência sobre `ANTHROPIC_FOUNDRY_API_KEY` e sobre a cadeia de credenciais padrão do Azure. Veja [Microsoft Foundry](/docs/pt/microsoft-foundry). Requer Claude Code v2.1.203 ou posterior |

182| `ANTHROPIC_FOUNDRY_BASE_URL` | URL base completa para o recurso Microsoft Foundry (por exemplo, `https://my-resource.services.ai.azure.com/anthropic`). Alternativa a `ANTHROPIC_FOUNDRY_RESOURCE` (veja [Microsoft Foundry](/docs/pt/microsoft-foundry)) |182| `ANTHROPIC_FOUNDRY_BASE_URL` | URL base completa para o recurso do Microsoft Foundry (por exemplo, `https://my-resource.services.ai.azure.com/anthropic`). Alternativa a `ANTHROPIC_FOUNDRY_RESOURCE` (veja [Microsoft Foundry](/docs/pt/microsoft-foundry)) |

183| `ANTHROPIC_FOUNDRY_RESOURCE` | Nome do recurso Microsoft Foundry (por exemplo, `my-resource`). Obrigatório se `ANTHROPIC_FOUNDRY_BASE_URL` não estiver definido (veja [Microsoft Foundry](/docs/pt/microsoft-foundry)) |183| `ANTHROPIC_FOUNDRY_RESOURCE` | Nome do recurso do Microsoft Foundry (por exemplo, `my-resource`). Obrigatório se `ANTHROPIC_FOUNDRY_BASE_URL` não estiver definido (veja [Microsoft Foundry](/docs/pt/microsoft-foundry)) |

184| `ANTHROPIC_MODEL` | Nome da configuração de modelo a usar (veja [Configuração de Modelo](/docs/pt/model-config#environment-variables)) |184| `ANTHROPIC_MODEL` | Nome da configuração de modelo a usar (veja [Configuração de Modelo](/docs/pt/model-config#environment-variables)) |

185| `ANTHROPIC_ORGANIZATION_ID` | ID da organização para [Workload Identity Federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation). Defina junto com `ANTHROPIC_FEDERATION_RULE_ID`. Veja [precedência de autenticação](/docs/pt/authentication#authentication-precedence) |185| `ANTHROPIC_ORGANIZATION_ID` | ID da organização para [Workload Identity Federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation). Defina junto com `ANTHROPIC_FEDERATION_RULE_ID`. Veja [precedência de autenticação](/docs/pt/authentication#authentication-precedence) |

186| `ANTHROPIC_PROFILE` | Nome do perfil Anthropic para autenticar, como um criado por [`ant auth login`](https://platform.claude.com/docs/en/cli-sdks-libraries/cli/authentication) ou por [entrar em uma conta Console sem uma chave de API](/docs/pt/authentication#sign-in-without-an-api-key). Veja [precedência de autenticação](/docs/pt/authentication#authentication-precedence) |186| `ANTHROPIC_PROFILE` | Nome do perfil Anthropic para autenticar, como um criado por [`ant auth login`](https://platform.claude.com/docs/en/cli-sdks-libraries/cli/authentication) ou por [entrar em uma conta Console sem uma chave de API](/docs/pt/authentication#sign-in-without-an-api-key). Veja [precedência de autenticação](/docs/pt/authentication#authentication-precedence) |

187| `ANTHROPIC_SMALL_FAST_MODEL` | \[DEPRECATED] Nome de [modelo classe Haiku para tarefas em background](/docs/pt/costs) |187| `ANTHROPIC_SMALL_FAST_MODEL` | \[DEPRECATED] Nome de [modelo da classe Haiku para tarefas em segundo plano](/docs/pt/costs) |

188| `ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION` | Substitua a região AWS para o modelo classe Haiku ao usar Amazon Bedrock ou Amazon Bedrock Mantle. No Amazon Bedrock, isso só tem efeito quando `ANTHROPIC_DEFAULT_HAIKU_MODEL` ou o deprecated `ANTHROPIC_SMALL_FAST_MODEL` também está definido, já que Amazon Bedrock caso contrário executa tarefas em background no [modelo Sonnet padrão ou no modelo primário](/docs/pt/amazon-bedrock#4-pin-model-versions) na região da sessão |188| `ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION` | Substitua a região AWS para o modelo da classe Haiku ao usar Amazon Bedrock ou Amazon Bedrock Mantle. No Amazon Bedrock, isso só tem efeito quando `ANTHROPIC_DEFAULT_HAIKU_MODEL` ou o `ANTHROPIC_SMALL_FAST_MODEL` descontinuado também está definido, já que o Amazon Bedrock caso contrário executa tarefas em segundo plano no [modelo Sonnet padrão ou no modelo primário](/docs/pt/amazon-bedrock#4-pin-model-versions) na região da sessão |

189| `ANTHROPIC_VERTEX_BASE_URL` | Substitua a URL do endpoint Google Cloud's Agent Platform. Use para endpoints Google Cloud's Agent Platform personalizados ou ao rotear através de um [gateway LLM](/docs/pt/llm-gateway). Veja [Google Cloud's Agent Platform](/docs/pt/google-vertex-ai) |189| `ANTHROPIC_VERTEX_BASE_URL` | Substitua a URL do endpoint do Google Cloud's Agent Platform. Use para endpoints personalizados do Google Cloud's Agent Platform ou ao rotear através de um [gateway LLM](/docs/pt/llm-gateway). Veja [Google Cloud's Agent Platform](/docs/pt/google-vertex-ai) |

190| `ANTHROPIC_VERTEX_PROJECT_ID` | ID do projeto GCP para o qual as solicitações Google Cloud's Agent Platform são endereçadas. Veja [Configurar credenciais GCP](/docs/pt/google-vertex-ai#3-configure-gcp-credentials) |190| `ANTHROPIC_VERTEX_PROJECT_ID` | ID do projeto GCP para o qual as solicitações do Google Cloud's Agent Platform são endereçadas. Veja [Configurar credenciais GCP](/docs/pt/google-vertex-ai#3-configure-gcp-credentials) |

191| `ANTHROPIC_WORKSPACE_ID` | ID do workspace para [federação de identidade de carga de trabalho](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation). Defina isso quando sua regra de federação está no escopo de mais de um workspace para que a troca de token saiba qual workspace direcionar |191| `ANTHROPIC_WORKSPACE_ID` | ID do workspace para [federação de identidade de carga de trabalho](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation). Defina isso quando sua regra de federação está no escopo de mais de um workspace para que a troca de token saiba qual workspace direcionar |

192| `API_FORCE_IDLE_TIMEOUT` | Substitua o timeout de inatividade do corpo de 5 minutos que aborta uma resposta de modelo de streaming quando nenhum byte chega. Defina como `0` para desativar o timeout, por exemplo quando um [gateway](/docs/pt/llm-gateway) lento ou modelo local pausa por mais de 5 minutos entre chunks, ou `1` para mantê-lo ativo para cada provedor. Quando não definido, o timeout está ativo em provedores diferentes da API Anthropic direta, [Claude Platform on AWS](/docs/pt/claude-platform-on-aws) e Amazon Bedrock com `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK=1` definido. Os [watchdogs de stream](/docs/pt/network-config#streaming-idle-watchdogs) funcionam independentemente e abortam uma pausa longa silenciosa mesmo quando você define `0` aqui |192| `API_FORCE_IDLE_TIMEOUT` | Substitua o timeout de inatividade do corpo de 5 minutos que aborta uma resposta de modelo de streaming quando nenhum byte chega. Defina como `0` para desativar o timeout, por exemplo quando um [gateway](/docs/pt/llm-gateway) lento ou modelo local pausa por mais de 5 minutos entre chunks, ou `1` para mantê-lo ativo para cada provedor. Quando não definido, o timeout está ativo em provedores diferentes da API Anthropic direta, [Claude Platform on AWS](/docs/pt/claude-platform-on-aws) e Amazon Bedrock com `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK=1` definido. Os [watchdogs de streaming](/docs/pt/network-config#streaming-idle-watchdogs) funcionam independentemente e abortam uma pausa longa silenciosa mesmo quando você define `0` aqui |

193| `API_TIMEOUT_MS` | Timeout para solicitações de API em milissegundos (padrão: 600000, ou 10 minutos; máximo: 2147483647). Aumente isso quando as solicitações expiram em redes lentas ou ao rotear através de um proxy. Valores acima do máximo causam overflow do timer subjacente e fazem as solicitações falharem imediatamente |193| `API_TIMEOUT_MS` | Timeout para solicitações de API em milissegundos (padrão: 600000, ou 10 minutos; máximo: 2147483647). Aumente isso quando as solicitações expiram em redes lentas ou ao rotear através de um proxy. Valores acima do máximo causam overflow do timer subjacente e fazem as solicitações falharem imediatamente |

194| `AWS_BEARER_TOKEN_BEDROCK` | Chave de API Amazon Bedrock para autenticação (veja [Chaves de API Amazon Bedrock](https://aws.amazon.com/blogs/machine-learning/accelerate-ai-development-with-amazon-bedrock-api-keys/)) |194| `AWS_BEARER_TOKEN_BEDROCK` | Chave de API do Amazon Bedrock para autenticação (veja [Chaves de API do Amazon Bedrock](https://aws.amazon.com/blogs/machine-learning/accelerate-ai-development-with-amazon-bedrock-api-keys/)) |

195| `BASH_DEFAULT_TIMEOUT_MS` | Timeout padrão para comandos bash de longa duração (padrão: 120000, ou 2 minutos) |195| `BASH_DEFAULT_TIMEOUT_MS` | Timeout padrão para um comando de ferramenta Bash ou PowerShell em primeiro plano, em milissegundos (padrão: 120000, ou 2 minutos). Um padrão mais longo que 30 minutos também se torna o [limite de tempo padrão para comandos em segundo plano](/docs/pt/tools-reference#time-limit-for-background-commands). O limite de tempo em segundo plano requer Claude Code v2.1.285 ou posterior |

196| `BASH_MAX_OUTPUT_LENGTH` | Número máximo de caracteres de saída bash que Claude Code lê de volta para o resultado de um comando (padrão: 30000; máximo: 150000). Se você definir a configuração [`bashOutputMaxChars`](/docs/pt/settings-reference#bashoutputmaxchars), Claude Code ignora essa variável. Veja [Limites de saída](/docs/pt/tools-reference#output-limits) |196| `BASH_MAX_OUTPUT_LENGTH` | Número máximo de caracteres de saída bash que Claude Code lê de volta para o resultado de um comando (padrão: 30000; máximo: 150000). Se você definir a configuração [`bashOutputMaxChars`](/docs/pt/settings-reference#bashoutputmaxchars), Claude Code ignora essa variável. Veja [Limites de saída](/docs/pt/tools-reference#output-limits) |

197| `BASH_MAX_TIMEOUT_MS` | Timeout máximo que o modelo pode definir para comandos bash de longa duração (padrão: 600000, ou 10 minutos). O teto efetivo é o maior entre isso e `BASH_DEFAULT_TIMEOUT_MS` |197| `BASH_MAX_TIMEOUT_MS` | Timeout máximo que o modelo pode definir para um comando de ferramenta Bash ou PowerShell em primeiro plano, em milissegundos (padrão: 600000, ou 10 minutos). O teto efetivo é o maior entre isso e `BASH_DEFAULT_TIMEOUT_MS`. Um teto efetivo mais longo que 2 horas também se torna o máximo [limite de tempo para comandos em segundo plano](/docs/pt/tools-reference#time-limit-for-background-commands). O limite de tempo em segundo plano requer Claude Code v2.1.285 ou posterior |

198| `BETA_TRACING_ENDPOINT` | Endpoint OTLP para [rastreamento beta detalhado](/docs/pt/monitoring-usage#traces-beta): com `ENABLE_BETA_TRACING_DETAILED=1`, logs e rastreamentos vão para lá em vez de para os exportadores configurados. Defina em seu shell, configurações de usuário ou configurações gerenciadas. Ignorado em [configurações de projeto e local](/docs/pt/settings-reference#variables-claude-code-ignores-in-env) |198| `BETA_TRACING_ENDPOINT` | Endpoint OTLP para [rastreamento beta detalhado](/docs/pt/monitoring-usage#traces-beta): com `ENABLE_BETA_TRACING_DETAILED=1`, logs e rastreamentos vão para lá em vez de para os exportadores configurados. Defina-o em seu shell, configurações de usuário ou configurações gerenciadas. Ignorado em [configurações de projeto e local](/docs/pt/settings-reference#variables-claude-code-ignores-in-env) |

199| `CCR_FORCE_BUNDLE` | Defina como `1` para forçar [`claude --cloud`](/docs/pt/claude-code-on-the-web#send-local-repositories-without-github) a agrupar e fazer upload do seu repositório local em vez de clonar de seu remoto |199| `CCR_FORCE_BUNDLE` | Defina como `1` para forçar [`claude --cloud`](/docs/pt/claude-code-on-the-web#send-local-repositories-without-github) a agrupar e fazer upload de seu repositório local em vez de clonar de seu remoto |

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

201| `CLAUDE_AFK_COUNTDOWN_MS` | Quantos milissegundos antes de auto-continuar a contagem regressiva na tela aparece em um diálogo [`AskUserQuestion`](/docs/pt/tools-reference) sem resposta. Padrão `20000` (20 segundos), limitado ao timeout de auto-continuação. Não tem efeito a menos que auto-continuação esteja ativada; veja a configuração [`askUserQuestionTimeout`](/docs/pt/settings-reference#askuserquestiontimeout) e `CLAUDE_AFK_TIMEOUT_MS`. Requer Claude Code v2.1.198 ou posterior |201| `CLAUDE_AFK_COUNTDOWN_MS` | Quantos milissegundos antes de auto-continuar a contagem regressiva na tela aparece em um diálogo [`AskUserQuestion`](/docs/pt/tools-reference) sem resposta. Padrão `20000` (20 segundos), limitado ao timeout de auto-continuação. Não tem efeito a menos que auto-continuação esteja ativada; veja a configuração [`askUserQuestionTimeout`](/docs/pt/settings-reference#askuserquestiontimeout) e `CLAUDE_AFK_TIMEOUT_MS`. Requer Claude Code v2.1.198 ou posterior |

202| `CLAUDE_AFK_TIMEOUT_MS` | Quantos milissegundos de tempo ocioso antes de um diálogo [`AskUserQuestion`](/docs/pt/tools-reference) sem resposta auto-continuar sem você. Auto-continuação está desativada por padrão; opte por ela com a configuração [`askUserQuestionTimeout`](/docs/pt/settings-reference#askuserquestiontimeout). Essa variável é uma substituição para demos e testes automatizados: quando definida, tem precedência sobre essa configuração e ativa auto-continuação mesmo quando a configuração não está definida ou é `never`. Definir `0` não desativa o timeout; fecha o diálogo imediatamente. Na v2.1.198 e v2.1.199, auto-continuação estava ativada por padrão com um timeout de `60000` (60 segundos). Requer Claude Code v2.1.198 ou posterior |202| `CLAUDE_AFK_TIMEOUT_MS` | Quantos milissegundos de tempo ocioso antes de um diálogo [`AskUserQuestion`](/docs/pt/tools-reference) sem resposta auto-continuar sem você. Auto-continuação está desativada por padrão; opte por ela com a configuração [`askUserQuestionTimeout`](/docs/pt/settings-reference#askuserquestiontimeout). Essa variável é uma substituição para demos e testes automatizados: quando definida, tem precedência sobre essa configuração e ativa auto-continuação mesmo quando a configuração não está definida ou é `never`. Definir `0` não desativa o timeout; fecha o diálogo imediatamente. Na v2.1.198 e v2.1.199, auto-continuação estava ativada por padrão com um timeout de `60000` (60 segundos). Requer Claude Code v2.1.198 ou posterior |

203| `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS` | Defina como `1` para desabilitar todos os tipos de [subagente](/docs/pt/sub-agents) integrados, como Explore e Plan. Aplica-se apenas em modo não interativo (flag `-p`). Útil para usuários SDK que querem uma tela em branco. Isso também remove `general-purpose`, o subagente que Claude Code executa quando uma chamada de ferramenta Agent omite `subagent_type`. Tal chamada então falha com [`subagent_type is required`](/docs/pt/errors#subagent-type-is-required) |203| `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS` | Defina como `1` para desabilitar todos os tipos de [subagente](/docs/pt/sub-agents) integrados, como Explore e Plan. Aplica-se apenas em modo não interativo (a flag `-p`). Útil para usuários do SDK que querem uma tela em branco. Isso também remove `general-purpose`, o subagente que Claude Code executa quando uma chamada de ferramenta Agent omite `subagent_type`. Tal chamada então falha com [`subagent_type is required`](/docs/pt/errors#subagent-type-is-required) |

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

205| `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS` | Timeout de travamento em milissegundos para subagentes. Padrão `600000` (10 minutos); se você aumentar `CLAUDE_STREAM_IDLE_TIMEOUT_MS` enquanto o watchdog de stream está ativo, o padrão sobe com ele, como [Lidar com respostas de API lentas ou travadas](/docs/pt/agent-sdk/typescript#handle-slow-or-stalled-api-responses) descreve. O timer reinicia em cada evento de progresso de streaming; se nenhum progresso chegar dentro da janela, Claude Code aborta o subagente e relata o travamento ao pai |205| `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS` | Timeout de travamento em milissegundos para subagentes. Padrão `600000` (10 minutos); se você aumentar `CLAUDE_STREAM_IDLE_TIMEOUT_MS` enquanto o watchdog de stream está ativo, o padrão sobe com ele, como [Lidar com respostas de API lentas ou travadas](/docs/pt/agent-sdk/typescript#handle-slow-or-stalled-api-responses) descreve. O timer reinicia em cada evento de progresso de streaming; se nenhum progresso chegar dentro da janela, Claude Code aborta o subagente e relata o travamento ao pai |

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

207| `CLAUDE_AUTO_BACKGROUND_TASKS` | Defina como `1` para forçar a ativação do backgrounding automático de tarefas de agente de longa duração. Quando ativado, subagentes são movidos para o background após executar por aproximadamente dois minutos. Também ativa [backgrounding automático de chamadas de ferramentas MCP longas](/docs/pt/mcp#automatic-backgrounding-of-long-tool-calls) em modo não interativo no Claude Code v2.1.212 ou posterior |207| `CLAUDE_AUTO_BACKGROUND_TASKS` | Defina como `1` para forçar a ativação do backgrounding automático de tarefas de agente de longa duração. Quando ativado, subagentes são movidos para o segundo plano após executar por aproximadamente dois minutos. Também ativa [backgrounding automático de chamadas de ferramenta MCP longas](/docs/pt/mcp#automatic-backgrounding-of-long-tool-calls) em modo não interativo no Claude Code v2.1.212 ou posterior |

208| `CLAUDE_AX_PREPARK_MS` | Em [modo leitor de tela](/docs/pt/accessibility#what-your-screen-reader-hears), quantos milissegundos Claude Code aguarda, com o cursor no início da linha, antes de escrever uma linha nova ou alterada. Padrão `50`. Defina `0` para escrever imediatamente. Claude Code limita a espera a `5000`. Requer Claude Code v2.1.233 ou posterior |208| `CLAUDE_AX_PREPARK_MS` | Em [modo leitor de tela](/docs/pt/accessibility#what-your-screen-reader-hears), quantos milissegundos Claude Code aguarda, com o cursor no início da linha, antes de escrever uma linha nova ou alterada. Padrão `50`. Defina `0` para escrever imediatamente. Claude Code limita a espera a `5000`. Requer Claude Code v2.1.233 ou posterior |

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

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

211| `CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR` | Retorne ao diretório de trabalho original após cada comando Bash ou PowerShell na sessão principal |211| `CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR` | Retorne ao diretório de trabalho original após cada comando Bash ou PowerShell na sessão principal |

212| `CLAUDE_BYTE_STREAM_IDLE_TIMEOUT_MS` | Timeout em milissegundos para o watchdog de inatividade de streaming em nível de byte; quando definido, tem precedência sobre `CLAUDE_STREAM_IDLE_TIMEOUT_MS` para esse watchdog e deixa o watchdog em nível de evento inalterado. Claude Code limita essa variável entre 10 segundos e 30 minutos. Requer Claude Code v2.1.210 ou posterior |212| `CLAUDE_BYTE_STREAM_IDLE_TIMEOUT_MS` | Timeout em milissegundos para o watchdog de inatividade de streaming em nível de byte; quando definido, tem precedência sobre `CLAUDE_STREAM_IDLE_TIMEOUT_MS` para esse watchdog e deixa o watchdog em nível de evento inalterado. Claude Code limita essa variável entre 10 segundos e 30 minutos. Requer Claude Code v2.1.210 ou posterior |

213| `CLAUDE_CLIENT_PRESENCE_FILE` | Caminho para um arquivo que uma ferramenta externa, como um ouvinte de bloqueio de tela, cria quando você desbloqueia sua tela e exclui quando você a bloqueia. Enquanto o arquivo existe, Claude Code pula [notificações push móveis Remote Control](/docs/pt/remote-control#mobile-push-notifications), para que você pare de receber pushes enquanto está usando ativamente o computador. Quando o arquivo está ausente ou ilegível, as notificações são enviadas normalmente. Claude Code verifica o arquivo uma vez por evento de disparo de push em vez de fazer polling. Requer Claude Code v2.1.181 ou posterior |213| `CLAUDE_CLIENT_PRESENCE_FILE` | Caminho para um arquivo que uma ferramenta externa, como um ouvinte de bloqueio de tela, cria quando você desbloqueia sua tela e exclui quando você a bloqueia. Enquanto o arquivo existe, Claude Code pula [notificações push móveis do Remote Control](/docs/pt/remote-control#mobile-push-notifications), para que você pare de receber pushes enquanto está usando ativamente o computador. Quando o arquivo está ausente ou ilegível, as notificações são enviadas normalmente. Claude Code verifica o arquivo uma vez por evento de disparo de push em vez de fazer polling. Requer Claude Code v2.1.181 ou posterior |

214| `CLAUDE_CODE_ACCESSIBILITY` | Defina como `1` para manter o cursor do terminal nativo visível e desabilitar o indicador de cursor de texto invertido. Permite que ampliadores de tela como macOS Zoom rastreiem a posição do cursor |214| `CLAUDE_CODE_ACCESSIBILITY` | Defina como `1` para manter o cursor do terminal nativo visível e desabilitar o indicador de cursor de texto invertido. Permite que ampliadores de tela como macOS Zoom rastreiem a posição do cursor |

215| `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD` | Defina como `1` para carregar arquivos de memória de diretórios especificados com `--add-dir`. Carrega `CLAUDE.md`, `.claude/CLAUDE.md`, `.claude/rules/*.md` e `CLAUDE.local.md`. Por padrão, diretórios adicionais não carregam arquivos de memória |215| `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD` | Defina como `1` para carregar arquivos de memória de diretórios especificados com `--add-dir`. Carrega `CLAUDE.md`, `.claude/CLAUDE.md`, `.claude/rules/*.md` e `CLAUDE.local.md`. Por padrão, diretórios adicionais não carregam arquivos de memória |

216| `CLAUDE_CODE_ALT_SCREEN_FULL_REPAINT` | Defina como `1` para repintar a tela inteira em cada quadro em [renderização fullscreen](/docs/pt/fullscreen) em vez de enviar atualizações incrementais. Use isso se o modo fullscreen mostrar fragmentos de texto obsoletos ou deslocados. Claude Code ativa isso automaticamente para sessões em background e [agent view](/docs/pt/agent-view) no Windows |216| `CLAUDE_CODE_ALT_SCREEN_FULL_REPAINT` | Defina como `1` para repintar a tela inteira em cada quadro em [renderização em tela cheia](/docs/pt/fullscreen) em vez de enviar atualizações incrementais. Use isso se o modo tela cheia mostrar fragmentos de texto obsoletos ou deslocados. Claude Code ativa isso automaticamente para sessões em segundo plano e [visualização de agente](/docs/pt/agent-view) no Windows |

217| `CLAUDE_CODE_ALWAYS_ENABLE_EFFORT` | Defina como `1` para enviar o parâmetro [effort](/docs/pt/model-config#adjust-effort-level) com cada solicitação, mesmo quando Claude Code não reconhece o ID do modelo como capaz de effort. Use isso ao rotear através de um [gateway LLM](/docs/pt/llm-gateway) ou provedor de terceiros que serve modelos sob identificadores personalizados. Modelos que rejeitam o parâmetro effort na API, incluindo modelos Claude 3, Sonnet 4.0 e 4.5, Opus 4.0 e 4.1 e Haiku 4.5, ainda são excluídos para que as solicitações não falhem |217| `CLAUDE_CODE_ALWAYS_ENABLE_EFFORT` | Defina como `1` para enviar o parâmetro [effort](/docs/pt/model-config#adjust-effort-level) com cada solicitação, mesmo quando Claude Code não reconhece o ID do modelo como capaz de effort. Use isso ao rotear através de um [gateway LLM](/docs/pt/llm-gateway) ou provedor de terceiros que serve modelos sob identificadores personalizados. Modelos que rejeitam o parâmetro effort na API, incluindo modelos Claude 3, Sonnet 4.0 e 4.5, Opus 4.0 e 4.1 e Haiku 4.5, ainda são excluídos para que as solicitações não falhem |

218| `CLAUDE_CODE_API_KEY_HELPER_TTL_MS` | Intervalo em milissegundos em que as credenciais devem ser atualizadas (ao usar [`apiKeyHelper`](/docs/pt/settings-reference#apikeyhelper)) |218| `CLAUDE_CODE_API_KEY_HELPER_TTL_MS` | Intervalo em milissegundos em que as credenciais devem ser atualizadas (ao usar [`apiKeyHelper`](/docs/pt/settings-reference#apikeyhelper)) |

219| `CLAUDE_CODE_ARTIFACT_AUTO_OPEN` | Defina como `0` para impedir que Claude Code abra o navegador automaticamente quando um novo [artifact](/docs/pt/artifacts#create-an-artifact) é publicado |219| `CLAUDE_CODE_ARTIFACT_AUTO_OPEN` | Defina como `0` para impedir que Claude Code abra o navegador automaticamente quando um novo [artefato](/docs/pt/artifacts#create-an-artifact) é publicado |

220| `CLAUDE_CODE_ARTIFACT_COMMENTS` | Defina como `0` para parar Claude de ler e responder a [comentários em um artifact](/docs/pt/artifacts#collect-comments-on-an-artifact). Não tem efeito quando `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` [desativou artifacts](/docs/pt/artifacts#availability). Requer Claude Code v2.1.221 ou posterior |220| `CLAUDE_CODE_ARTIFACT_COMMENTS` | Defina como `0` para impedir que Claude leia e responda a [comentários em um artefato](/docs/pt/artifacts#collect-comments-on-an-artifact). Não tem efeito quando `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` [desativou artefatos](/docs/pt/artifacts#availability). Requer Claude Code v2.1.221 ou posterior |

221| `CLAUDE_CODE_ARTIFACT_COMMENTS_AUTOREACT` | Defina como `0` para parar Claude de [responder por conta própria a comentários enviados para ele](/docs/pt/artifacts#let-claude-reply-to-comments-on-its-own). Requer Claude Code v2.1.228 ou posterior |221| `CLAUDE_CODE_ARTIFACT_COMMENTS_AUTOREACT` | Defina como `0` para impedir que Claude [responda por conta própria a comentários enviados a ele](/docs/pt/artifacts#let-claude-reply-to-comments-on-its-own). Requer Claude Code v2.1.228 ou posterior |

222| `CLAUDE_CODE_ATTRIBUTION_HEADER` | Defina como `0` para omitir o [bloco de atribuição](/docs/pt/llm-gateway-protocol#system-prompt-attribution-block), que carrega a versão do cliente e uma impressão digital de prompt, do início do prompt do sistema. O cache em uma conexão direta com a API Anthropic não é afetado de qualquer forma. Em algumas configurações de conexão direta, Claude Code mantém o bloco em solicitações do classificador [modo auto](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode) mesmo quando você define `0`. Em [Bloco de atribuição de prompt do sistema](/docs/pt/llm-gateway-protocol#system-prompt-attribution-block), verifique quais conexões e credenciais isso cobre. Antes da v2.1.181, o bloco incluía um token por solicitação em URLs de base personalizadas e conexões Microsoft Foundry, então nessas versões defina como `0` quando seu gateway LLM faz cache no corpo da solicitação ou encaminha solicitações para um provedor de terceiros, ou quando você se conecta ao Microsoft Foundry diretamente |222| `CLAUDE_CODE_ATTRIBUTION_HEADER` | Defina como `0` para omitir o [bloco de atribuição](/docs/pt/llm-gateway-protocol#system-prompt-attribution-block), que carrega a versão do cliente e uma impressão digital do prompt, do início do prompt do sistema. O cache em uma conexão direta com a API Anthropic não é afetado de qualquer forma. Em algumas configurações de conexão direta, Claude Code mantém o bloco em solicitações do classificador [modo automático](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode) mesmo quando você define `0`. Em [Bloco de atribuição do prompt do sistema](/docs/pt/llm-gateway-protocol#system-prompt-attribution-block), verifique quais conexões e credenciais isso cobre. Antes da v2.1.181, o bloco incluía um token por solicitação em URLs de base personalizados e conexões do Microsoft Foundry, então nessas versões defina como `0` quando seu gateway LLM faz cache no corpo da solicitação ou encaminha solicitações para um provedor de terceiros, ou quando você se conecta ao Microsoft Foundry diretamente |

223| `CLAUDE_CODE_AUTO_BACKGROUND_WORKER_CHECKIN_SECONDS` | Quando `CLAUDE_AUTO_BACKGROUND_TASKS` está ativado, segundos entre lembretes para Claude verificar [subagentes em background](/docs/pt/sub-agents#run-subagents-in-foreground-or-background) que ainda estão em execução. Aceita um inteiro simples de `1` a `86400` apenas; qualquer outro valor ou grafia lê como não definido. Quando não definido, não há lembretes de check-in. Requer Claude Code v2.1.248 ou posterior |223| `CLAUDE_CODE_AUTO_BACKGROUND_WORKER_CHECKIN_SECONDS` | Quando `CLAUDE_AUTO_BACKGROUND_TASKS` está ativado, segundos entre lembretes para Claude verificar [subagentes em segundo plano](/docs/pt/sub-agents#run-subagents-in-foreground-or-background) que ainda estão em execução. Aceita um inteiro simples de `1` a `86400` apenas; qualquer outro valor ou grafia lê como não definido. Quando não definido, não há lembretes de check-in. Requer Claude Code v2.1.248 ou posterior |

224| `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | Defina a [janela de auto-compactação](/docs/pt/model-config#set-the-auto-compact-window) em tokens, de `100000` a `1000000`. Aceita apenas um inteiro simples como `500000`: um valor como `500k` lê como `500` e é limitado ao mínimo de 100K. A janela efetiva também é limitada à janela de contexto do modelo. Tem precedência sobre o comando `/autocompact`, a flag `--autocompact` e a configuração `autoCompactWindow`. A `used_percentage` da status line sempre mede contra a janela de contexto completo do modelo, então uma vez que essa variável está definida, essa porcentagem não indica mais quando a compactação será executada |224| `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | Defina a [janela de auto-compactação](/docs/pt/model-config#set-the-auto-compact-window) em tokens, de `100000` a `1000000`. Aceita apenas um inteiro simples como `500000`: um valor como `500k` lê como `500` e é limitado ao mínimo de 100K. A janela efetiva também é limitada à janela de contexto do modelo. Tem precedência sobre o comando `/autocompact`, a flag `--autocompact` e a configuração `autoCompactWindow`. A `used_percentage` da linha de status sempre mede contra a janela de contexto completa do modelo, então uma vez que essa variável está definida, essa porcentagem não indica mais quando a compactação será executada |

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

226| `CLAUDE_CODE_AUTO_MODE_SERVER` | Controla se Claude Code pede ao servidor para [revisar ações de modo auto](/docs/pt/permission-modes#server-side-classifier-review). Defina como `0` para usar as solicitações do classificador próprio de Claude Code. Em uma conexão direta com a API Anthropic, requer v2.1.281 ou posterior. A seção vinculada lista quais sessões pedem ao servidor quando a variável não está definida, e a partir de qual versão. Requer Claude Code v2.1.271 ou posterior |226| `CLAUDE_CODE_AUTO_MODE_SERVER` | Controla se Claude Code pede ao servidor para [revisar ações de modo automático](/docs/pt/permission-modes#server-side-classifier-review). Defina como `0` para usar as solicitações do classificador próprio de Claude Code. Em uma conexão direta com a API Anthropic, requer v2.1.281 ou posterior. A seção vinculada lista quais sessões pedem ao servidor quando a variável não está definida, e a partir de qual versão. Requer Claude Code v2.1.271 ou posterior |

227| `CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS` | Tempo em milissegundos que Claude Code aguarda a cadeia de provedor de credencial padrão AWS produzir credenciais antes da solicitação falhar com [`AWS default-chain credential resolve timed out`](/docs/pt/errors#aws-default-chain-credential-resolve-timed-out) (padrão: `60000`). Aumente quando uma etapa em sua cadeia legitimamente precisa de mais tempo, como um sign-in baseado em navegador com MFA através de um wrapper como `aws-vault`. Aplica-se em qualquer lugar que Claude Code assine com a cadeia padrão: [Amazon Bedrock](/docs/pt/amazon-bedrock#credential-caching-and-resolution-timeout), [Claude Platform on AWS](/docs/pt/claude-platform-on-aws) e o [endpoint Mantle](/docs/pt/amazon-bedrock#use-the-mantle-endpoint). Requer Claude Code v2.1.207 ou posterior |227| `CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS` | Tempo em milissegundos que Claude Code aguarda a cadeia de provedor de credenciais padrão AWS produzir credenciais antes da solicitação falhar com [`AWS default-chain credential resolve timed out`](/docs/pt/errors#aws-default-chain-credential-resolve-timed-out) (padrão: `60000`). Aumente quando uma etapa em sua cadeia legitimamente precisa de mais tempo, como um sign-in baseado em navegador com MFA através de um wrapper como `aws-vault`. Aplica-se onde quer que Claude Code assine com a cadeia padrão: [Amazon Bedrock](/docs/pt/amazon-bedrock#credential-caching-and-resolution-timeout), [Claude Platform on AWS](/docs/pt/claude-platform-on-aws) e o [endpoint Mantle](/docs/pt/amazon-bedrock#use-the-mantle-endpoint). Requer Claude Code v2.1.207 ou posterior |

228| `CLAUDE_CODE_BASH_EDIT_DIFF` | Defina como `0` para desativar o [diff dos arquivos que mudaram enquanto um comando Bash foi executado](/docs/pt/hooks#bash), ou `1` para registrá-lo em cada modo de permissão. Tem precedência sobre a configuração [`bashEditDiffEnabled`](/docs/pt/settings-reference#basheditdiffenabled). Requer Claude Code v2.1.269 ou posterior |228| `CLAUDE_CODE_BASH_EDIT_DIFF` | Defina como `0` para desativar o [diff dos arquivos que mudaram enquanto um comando Bash foi executado](/docs/pt/hooks#bash), ou `1` para registrá-lo em cada modo de permissão. Tem precedência sobre a configuração [`bashEditDiffEnabled`](/docs/pt/settings-reference#basheditdiffenabled). Requer Claude Code v2.1.269 ou posterior |

229| `CLAUDE_CODE_BG_TASKS_REPORT_RUNNING` | Defina como `0` para fazer uma sessão não interativa relatar um status ocioso ao seu host no final de cada turno, mesmo enquanto o trabalho em background ainda está em execução. Por padrão, a sessão continua relatando um status em execução após o final do turno enquanto trabalho em background, como um agente em background ou uma execução de [workflow](/docs/pt/workflows), ainda está ativo. Isso mantém um host que observa o status, como uma lista de sessão remota, de anunciar que Claude está aguardando sua entrada no meio do trabalho. Comandos shell em background, como um servidor dev, não mantêm o status em execução. O padrão de status em execução e a opção de desativação `0` requerem Claude Code v2.1.269 ou posterior; em versões anteriores, defina `1` para manter o status em execução |229| `CLAUDE_CODE_BG_TASKS_REPORT_RUNNING` | Defina como `0` para fazer uma sessão não interativa relatar um status ocioso ao seu host no final de cada turno, mesmo enquanto o trabalho em segundo plano ainda está em execução. Por padrão, a sessão continua relatando um status em execução após o final do turno enquanto trabalho em segundo plano, como um agente em segundo plano ou uma execução de [workflow](/docs/pt/workflows), ainda está ativo. Isso mantém um host que observa o status, como uma lista de sessão remota, de anunciar que Claude está aguardando sua entrada no meio do trabalho. Comandos de shell em segundo plano, como um servidor dev, não mantêm o status em execução. O padrão de status em execução e a opção de desativação `0` requerem Claude Code v2.1.269 ou posterior; em versões anteriores, defina `1` para manter o status em execução |

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

231| `CLAUDE_CODE_BS_AS_CTRL_BACKSPACE` | Defina como `0` para fazer Claude Code ler o byte `0x08`, também escrito `^H`, como Backspace simples, ou `1` para lê-lo como Ctrl+Backspace. Qualquer valor substitui o padrão da plataforma. Por padrão, Claude Code o lê como Ctrl+Backspace no Windows, exceto quando `TERM_PROGRAM` é `mintty` ou `TERM` é `cygwin`, e como Backspace simples no macOS e Linux. Defina `0` em um terminal Windows onde [Backspace exclui uma palavra inteira](/docs/pt/terminal-config#fix-backspace-deleting-a-whole-word-on-windows) |231| `CLAUDE_CODE_BS_AS_CTRL_BACKSPACE` | Defina como `0` para fazer Claude Code ler o byte `0x08`, também escrito `^H`, como Backspace simples, ou `1` para lê-lo como Ctrl+Backspace. Qualquer valor substitui o padrão da plataforma. Por padrão, Claude Code o lê como Ctrl+Backspace no Windows, exceto quando `TERM_PROGRAM` é `mintty` ou `TERM` é `cygwin`, e como Backspace simples no macOS e Linux. Defina `0` em um terminal Windows onde [Backspace exclui uma palavra inteira](/docs/pt/terminal-config#fix-backspace-deleting-a-whole-word-on-windows) |

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

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

234| `CLAUDE_CODE_CLIENT_CERT` | Caminho para arquivo de certificado de cliente para autenticação mTLS |234| `CLAUDE_CODE_CLIENT_CERT` | Caminho para arquivo de certificado de cliente para autenticação mTLS |

235| `CLAUDE_CODE_CLIENT_KEY` | Caminho para arquivo de chave privada de cliente para autenticação mTLS |235| `CLAUDE_CODE_CLIENT_KEY` | Caminho para arquivo de chave privada de cliente para autenticação mTLS |

236| `CLAUDE_CODE_CLIENT_KEY_PASSPHRASE` | Frase-passe para CLAUDE\_CODE\_CLIENT\_KEY criptografado (opcional) |236| `CLAUDE_CODE_CLIENT_KEY_PASSPHRASE` | Frase-passe para CLAUDE\_CODE\_CLIENT\_KEY criptografado (opcional) |

237| `CLAUDE_CODE_CONNECT_TIMEOUT_MS` | Removido na v2.1.186 e agora é um no-op. Anteriormente definia um timeout separado para a fase de conexão, TLS e cabeçalho de resposta de uma solicitação de API de streaming. Use `API_TIMEOUT_MS` para o timeout por solicitação. Para a fase de cabeçalho de resposta de uma solicitação de streaming, veja `CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS` |237| `CLAUDE_CODE_CONNECT_TIMEOUT_MS` | Removido na v2.1.186 e agora é um no-op. Anteriormente definia um timeout separado para a fase de conexão, TLS e cabeçalho de resposta de uma solicitação de API de streaming. Use `API_TIMEOUT_MS` para o timeout por solicitação. Para a fase de cabeçalho de resposta de uma solicitação de streaming, veja `CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS` |

238| `CLAUDE_CODE_DEBUG_LOGS_DIR` | Substitua o caminho do arquivo de log de depuração. Apesar do nome, este é um caminho de arquivo, não um diretório. Requer que o modo de depuração seja ativado separadamente via `--debug`, `/debug` ou a variável de ambiente `DEBUG`: definir apenas essa variável não ativa o logging. A flag [`--debug-file`](/docs/pt/cli-reference#cli-flags) faz ambos de uma vez. Padrão é `~/.claude/debug/<session-id>.txt` |238| `CLAUDE_CODE_DEBUG_LOGS_DIR` | Substitua o caminho do arquivo de log de depuração. Apesar do nome, este é um caminho de arquivo, não um diretório. Requer que o modo de depuração seja ativado separadamente via `--debug`, `/debug` ou a variável de ambiente `DEBUG`: definir apenas essa variável não ativa o logging. A flag [`--debug-file`](/docs/pt/cli-reference#cli-flags) faz ambos de uma vez. Padrão é `~/.claude/debug/<session-id>.txt` |

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

240| `CLAUDE_CODE_DISABLE_1M_CONTEXT` | Defina como `1` para desabilitar suporte a [janela de contexto 1M](/docs/pt/model-config#extended-context). Quando definido, variantes de modelo 1M não estão disponíveis no seletor de modelo, e Claude Code mantém sessões em modelos com uma janela nativa 1M, como [Sonnet 5.5](/docs/pt/model-config#sonnet-5-5-and-sonnet-5-context-window) e os modelos Fable, para uma janela 200K; veja [Contexto estendido](/docs/pt/model-config#extended-context) para como a retenção é aplicada. Útil para ambientes empresariais com requisitos de conformidade. Para seu papel em corrigir a janela para um ID de modelo não reconhecido `[1m]`, veja [Corrigir a janela para um ID de modelo de gateway ou personalizado](/docs/pt/model-config#correct-the-window-for-a-gateway-or-custom-model-id) |240| `CLAUDE_CODE_DISABLE_1M_CONTEXT` | Defina como `1` para desabilitar suporte a [janela de contexto de 1M](/docs/pt/model-config#extended-context). Quando definido, variantes de modelo 1M não estão disponíveis no seletor de modelo, e Claude Code mantém sessões em modelos com uma janela nativa de 1M, como [Sonnet 5.5](/docs/pt/model-config#sonnet-5-5-and-sonnet-5-context-window) e os modelos Fable, para uma janela de 200K; veja [Contexto estendido](/docs/pt/model-config#extended-context) para como a retenção é aplicada. Útil para ambientes corporativos com requisitos de conformidade. Para seu papel em corrigir a janela para um ID de modelo não reconhecido `[1m]`, veja [Corrigir a janela para um ID de modelo de gateway ou personalizado](/docs/pt/model-config#correct-the-window-for-a-gateway-or-custom-model-id) |

241| `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` | Defina como `1` para desabilitar [raciocínio adaptativo](/docs/pt/model-config#adjust-effort-level) em Opus 4.6 e Sonnet 4.6 e voltar ao orçamento de pensamento fixo controlado por `MAX_THINKING_TOKENS`. Não tem efeito em [modelos Fable](/docs/pt/model-config#extended-thinking), Sonnet 5 ou Opus 4.7 e posterior, que sempre usam raciocínio adaptativo |241| `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` | Defina como `1` para desabilitar [raciocínio adaptativo](/docs/pt/model-config#adjust-effort-level) em Opus 4.6 e Sonnet 4.6 e voltar ao orçamento de pensamento fixo controlado por `MAX_THINKING_TOKENS`. Não tem efeito em [modelos Fable](/docs/pt/model-config#extended-thinking), Sonnet 5 e posterior, ou Opus 4.7 e posterior, que sempre usam raciocínio adaptativo |

242| `CLAUDE_CODE_DISABLE_ADMIN_ENV_UNION` | Defina como `1` para parar Claude Code de mesclar blocos `env` de [configurações gerenciadas](/docs/pt/managed-settings#precedence-within-the-managed-tier) por chave em fontes de admin, para que apenas o bloco `env` da fonte de prioridade mais alta se aplique, como antes da v2.1.223. Defina no ambiente que inicia Claude Code, já que Claude Code ignora uma cópia entregue através de um bloco `env` de configurações. Requer Claude Code v2.1.223 ou posterior |242| `CLAUDE_CODE_DISABLE_ADMIN_ENV_UNION` | Defina como `1` para impedir que Claude Code mescle blocos `env` de [configurações gerenciadas](/docs/pt/managed-settings#precedence-within-the-managed-tier) por chave em fontes de admin, para que apenas o bloco `env` da fonte de prioridade mais alta se aplique, como antes da v2.1.223. Defina-o no ambiente que inicia Claude Code, já que Claude Code ignora uma cópia entregue através de um bloco `env` de configurações. Requer Claude Code v2.1.223 ou posterior |

243| `CLAUDE_CODE_DISABLE_ADVISOR_TOOL` | Defina como `1` para desabilitar a [ferramenta advisor](/docs/pt/advisor). O comando `/advisor` fica indisponível, qualquer `advisorModel` configurado é ignorado, e a flag `--advisor` é aceita mas não tem efeito, para que scripts existentes que a passam continuem funcionando sem erros |243| `CLAUDE_CODE_DISABLE_ADVISOR_TOOL` | Defina como `1` para desabilitar a [ferramenta advisor](/docs/pt/advisor). O comando `/advisor` fica indisponível, qualquer `advisorModel` configurado é ignorado, e a flag `--advisor` é aceita mas não tem efeito, para que scripts existentes que a passam continuem funcionando sem erros |

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

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

246| `CLAUDE_CODE_DISABLE_ARTIFACT` | Defina como `1` para desativar a ferramenta [Artifact](/docs/pt/artifacts), que publica saída de sessão como uma página web privada em claude.ai. Uma vez que você a define, nenhum arquivo de configurações ativa a ferramenta novamente. Para desativar a ferramenta de um arquivo de configurações, defina [`enableArtifact`](/docs/pt/settings-reference#enableartifact) como `false`; a chave deprecated [`disableArtifact`](/docs/pt/settings-reference#disableartifact) também a desativa |246| `CLAUDE_CODE_DISABLE_ARTIFACT` | Defina como `1` para desativar a ferramenta [Artifact](/docs/pt/artifacts), que publica saída de sessão como uma página web privada em claude.ai. Uma vez que você a define, nenhum arquivo de configurações ativa a ferramenta novamente. Para desativar a ferramenta de um arquivo de configurações, defina [`enableArtifact`](/docs/pt/settings-reference#enableartifact) como `false`; a chave descontinuada [`disableArtifact`](/docs/pt/settings-reference#disableartifact) também a desativa |

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

248| `CLAUDE_CODE_DISABLE_AUTO_MEMORY` | Defina como `1` para desabilitar [memória automática](/docs/pt/memory#auto-memory). Defina como `0` para forçar memória automática ativada mesmo quando modo `--bare` ou [`autoMemoryEnabled: false`](/docs/pt/settings-reference#automemoryenabled) desabilitaria. Quando desabilitada, Claude não cria ou carrega arquivos de memória automática |248| `CLAUDE_CODE_DISABLE_AUTO_MEMORY` | Defina como `1` para desabilitar [memória automática](/docs/pt/memory#auto-memory). Defina como `0` para forçar memória automática ativada mesmo quando modo `--bare` ou [`autoMemoryEnabled: false`](/docs/pt/settings-reference#automemoryenabled) a desativaria. Quando desabilitada, Claude não cria ou carrega arquivos de memória automática |

249| `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` | Defina como `1` para desabilitar toda funcionalidade de tarefa em background, incluindo o parâmetro `run_in_background` em ferramentas Bash e subagente, auto-backgrounding e o atalho Ctrl+B |249| `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` | Defina como `1` para desabilitar toda funcionalidade de tarefa em segundo plano, incluindo o parâmetro `run_in_background` em ferramentas Bash e subagente, auto-backgrounding e o atalho Ctrl+B |

250| `CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_DEFAULT` | Defina como `1` para parar Claude Code de tratar uma resposta de streaming [Amazon Bedrock](/docs/pt/amazon-bedrock) com cabeçalho `Content-Type` ausente ou vazio como fluxo de evento binário Amazon Bedrock. Por padrão, Claude Code assume que um gateway descartou o cabeçalho de uma resposta caso contrário não modificada, para que decodifique o corpo e o streaming continue funcionando. Defina isso apenas para um gateway que também re-emite o stream como eventos enviados pelo servidor; Claude Code então lê o corpo sem cabeçalho como eventos enviados pelo servidor. Requer Claude Code v2.1.239 ou posterior |250| `CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_DEFAULT` | Defina como `1` para impedir que Claude Code trate uma resposta de streaming [Amazon Bedrock](/docs/pt/amazon-bedrock) com um cabeçalho `Content-Type` ausente ou vazio como fluxo de evento binário do Amazon Bedrock. Por padrão, Claude Code assume que um gateway descartou o cabeçalho de uma resposta caso contrário não modificada, para que decodifique o corpo e o streaming continue funcionando. Defina isso apenas para um gateway que também re-emite o stream como eventos enviados pelo servidor; Claude Code então lê o corpo sem cabeçalho como eventos enviados pelo servidor. Requer Claude Code v2.1.239 ou posterior |

251| `CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD` | Defina como `1` para pular a verificação de que uma resposta de streaming [Amazon Bedrock](/docs/pt/amazon-bedrock) carrega o tipo de conteúdo `application/vnd.amazon.eventstream`. Sem essa variável, quando uma resposta carrega um tipo de conteúdo diferente, Claude Code falha a solicitação com um erro nomeando esse tipo, o que significa que um [gateway ou proxy está transformando a resposta](/docs/pt/amazon-bedrock#streaming-errors-behind-a-gateway-or-proxy). Configure o gateway para encaminhar o cabeçalho `Content-Type` e o corpo não modificados em vez de definir essa variável. Requer Claude Code v2.1.208 ou posterior |251| `CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD` | Defina como `1` para pular a verificação de que uma resposta de streaming [Amazon Bedrock](/docs/pt/amazon-bedrock) carrega o tipo de conteúdo `application/vnd.amazon.eventstream`. Sem essa variável, quando uma resposta carrega um tipo de conteúdo diferente, Claude Code falha a solicitação com um erro nomeando esse tipo, o que significa que um [gateway ou proxy está transformando a resposta](/docs/pt/amazon-bedrock#streaming-errors-behind-a-gateway-or-proxy). Configure o gateway para encaminhar o cabeçalho `Content-Type` e o corpo sem modificação em vez de definir essa variável. Requer Claude Code v2.1.208 ou posterior |

252| `CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF` | Defina como `1` para parar os comandos shell em background em execução de uma [sessão em background](/docs/pt/agent-view), workflows dinâmicos, e, a partir da v2.1.198, subagentes em background quando o [supervisor](/docs/pt/agent-view#the-supervisor-process) para, reinicia ou atualiza o processo dessa sessão, em vez de entregá-los ao próximo processo da sessão. Afeta apenas esse handoff: backgrounding uma sessão com `←` ou [`/background`](/docs/pt/agent-view#from-inside-a-session) ainda carrega trabalho em voo, e `CLAUDE_DISABLE_ADOPT` desativa ambos. Requer Claude Code v2.1.196 ou posterior |252| `CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF` | Defina como `1` para impedir que comandos de shell em execução de uma [sessão em segundo plano](/docs/pt/agent-view), workflows dinâmicos, e, a partir da v2.1.198, subagentes em segundo plano quando o [supervisor](/docs/pt/agent-view#the-supervisor-process) para, reinicia ou atualiza o processo dessa sessão, em vez de entregá-los ao próximo processo da sessão. Afeta apenas essa entrega: backgrounding uma sessão com `←` ou [`/background`](/docs/pt/agent-view#from-inside-a-session) ainda carrega trabalho em voo, e `CLAUDE_DISABLE_ADOPT` desativa ambos. Requer Claude Code v2.1.196 ou posterior |

253| `CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP` | Defina como `1` para parar Claude Code de encerrar [comandos shell em background](/docs/pt/interactive-mode#background-bash-commands) sob pressão de memória. Por padrão, no macOS e Linux, Claude Code encerra shells em background quando o sistema operacional relata pressão de memória crítica e a sessão está ociosa há 30 minutos sem turno ou subagente em execução. Windows não tem sinal de pressão de memória, então essa variável não tem efeito lá. Requer Claude Code v2.1.193 ou posterior |253| `CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP` | Defina como `1` para impedir que Claude Code termine [comandos de shell em segundo plano](/docs/pt/interactive-mode#background-bash-commands) sob pressão de memória. Por padrão, no macOS e Linux, Claude Code termina shells em segundo plano quando o sistema operacional relata pressão de memória crítica e a sessão está ociosa por 30 minutos sem turno ou subagente em execução. Windows não tem sinal de pressão de memória, então essa variável não tem efeito lá. Requer Claude Code v2.1.193 ou posterior |

254| `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS` | Defina como `1` para desabilitar as [skills](/docs/pt/skills) e workflows inclusos com Claude Code: skills inclusos e workflows são removidos completamente, enquanto comandos integrados como `/init` permanecem digitáveis mas são ocultados do modelo. `/doctor` permanece digitável como os comandos integrados; ocultá-lo com `DISABLE_DOCTOR_COMMAND`. Skills de plugins, `.claude/skills/` e `.claude/commands/` não são afetadas. Equivalente à configuração [`disableBundledSkills`](/docs/pt/settings-reference#disablebundledskills) |254| `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS` | Defina como `1` para desabilitar as [skills](/docs/pt/skills) e workflows inclusos com Claude Code: skills inclusos e workflows são removidos inteiramente, enquanto comandos integrados como `/init` permanecem digitáveis mas são ocultados do modelo. `/doctor` permanece digitável como os comandos integrados; ocultá-lo com `DISABLE_DOCTOR_COMMAND`. Skills de plugins, `.claude/skills/` e `.claude/commands/` não são afetadas. Equivalente à configuração [`disableBundledSkills`](/docs/pt/settings-reference#disablebundledskills) |

255| `CLAUDE_CODE_DISABLE_CFC_PROMPT` | Defina como `1` para manter as ferramentas de navegador [Claude in Chrome](/docs/pt/chrome) disponíveis enquanto omite a seção Chrome do prompt do sistema e a [skill incluída](/docs/pt/skills#bundled-skills) `/claude-in-chrome`. Para hosts que incorporam Claude Code e fornecem sua própria orientação de navegador. Requer Claude Code v2.1.257 ou posterior |255| `CLAUDE_CODE_DISABLE_CFC_PROMPT` | Defina como `1` para manter as ferramentas do navegador [Claude in Chrome](/docs/pt/chrome) disponíveis enquanto omite a seção Chrome do prompt do sistema e a [skill incluída](/docs/pt/skills#bundled-skills) `/claude-in-chrome`. Para hosts que incorporam Claude Code e fornecem sua própria orientação de navegador. Requer Claude Code v2.1.257 ou posterior |

256| `CLAUDE_CODE_DISABLE_CLAUDE_MDS` | Defina como `1` para evitar carregar qualquer arquivo de memória CLAUDE.md em contexto, incluindo arquivos de memória de usuário, projeto e automática |256| `CLAUDE_CODE_DISABLE_CLAUDE_MDS` | Defina como `1` para impedir o carregamento de qualquer arquivo de memória CLAUDE.md em contexto, incluindo arquivos de memória de usuário, projeto e automática |

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

258| `CLAUDE_CODE_DISABLE_DANGEROUS_RM_TIMEOUT` | Defina como `1` para desativar o limite de tempo em prompts de [remoção de caminho crítico](/docs/pt/permission-modes#critical-paths). Em modo `auto`, Claude Code então envia essas remoções para o classificador, e em modo `bypassPermissions`, o prompt aguarda sua resposta. Defina no ambiente que inicia Claude Code, já que Claude Code ignora uma cópia entregue através de um bloco `env` de configurações. Requer Claude Code v2.1.281 ou posterior |258| `CLAUDE_CODE_DISABLE_DANGEROUS_RM_TIMEOUT` | Defina como `1` para desativar o limite de tempo em prompts de [remoção de caminho crítico](/docs/pt/permission-modes#critical-paths). Em modo `auto`, Claude Code então envia essas remoções para o classificador, e em modo `bypassPermissions`, o prompt aguarda sua resposta. Defina-o no ambiente que inicia Claude Code, já que Claude Code ignora uma cópia entregue através de um bloco `env` de configurações. Requer Claude Code v2.1.281 ou posterior |

259| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | Defina como `1` para remover cabeçalhos de solicitação `anthropic-beta` específicos de Anthropic e campos de esquema de ferramenta beta (como `defer_loading` e `eager_input_streaming`) de solicitações de API. Use isso quando um gateway proxy rejeita solicitações com erros como "Unexpected value(s) for the `anthropic-beta` header" ou "Extra inputs are not permitted". Campos padrão (`name`, `description`, `input_schema`, `cache_control`) são preservados. [Busca de ferramentas MCP](/docs/pt/mcp#scale-with-mcp-tool-search) é desabilitada e todas as ferramentas MCP carregam antecipadamente, mesmo quando você define `ENABLE_TOOL_SEARCH`. No Claude Code v2.1.227 ou posterior, [configurações gerenciadas](/docs/pt/managed-settings) podem manter a busca de ferramentas ativada. [Desabilitar capacidades de pré-lançamento](/docs/pt/llm-gateway-protocol#disable-pre-release-capabilities) cobre onde a substituição se aplica |259| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | Defina como `1` para remover cabeçalhos de solicitação `anthropic-beta` específicos de Anthropic e campos de esquema de ferramenta beta (como `defer_loading` e `eager_input_streaming`) de solicitações de API. Use isso quando um gateway proxy rejeita solicitações com erros como "Unexpected value(s) for the `anthropic-beta` header" ou "Extra inputs are not permitted". Campos padrão (`name`, `description`, `input_schema`, `cache_control`) são preservados. [Busca de ferramentas MCP](/docs/pt/mcp#scale-with-mcp-tool-search) é desabilitada e todas as ferramentas MCP carregam antecipadamente, mesmo quando você define `ENABLE_TOOL_SEARCH`. No Claude Code v2.1.227 ou posterior, [configurações gerenciadas](/docs/pt/managed-settings) podem manter a busca de ferramentas ativada. [Desabilitar capacidades de pré-lançamento](/docs/pt/llm-gateway-protocol#disable-pre-release-capabilities) cobre onde a substituição se aplica |

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

261| `CLAUDE_CODE_DISABLE_FAST_MODE` | Defina como `1` para desabilitar [modo rápido](/docs/pt/fast-mode) |261| `CLAUDE_CODE_DISABLE_FAST_MODE` | Defina como `1` para desabilitar [modo rápido](/docs/pt/fast-mode) |

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

263| `CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING` | Defina como `1` para desabilitar [checkpointing](/docs/pt/checkpointing) de arquivo. O comando `/rewind` não será capaz de restaurar alterações de código. Substitui a configuração [`fileCheckpointingEnabled`](/docs/pt/settings-reference#filecheckpointingenabled) |263| `CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING` | Defina como `1` para desabilitar [checkpointing](/docs/pt/checkpointing) de arquivo. O comando `/rewind` não será capaz de restaurar alterações de código. Substitui a configuração [`fileCheckpointingEnabled`](/docs/pt/settings-reference#filecheckpointingenabled) |

264| `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` | Defina como `1` para remover instruções de workflow de commit e PR integradas e o snapshot de status git do contexto de Claude. Útil ao usar suas próprias skills de workflow git. Tem precedência sobre a configuração [`includeGitInstructions`](/docs/pt/settings-reference#includegitinstructions) quando definido |264| `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` | Defina como `1` para remover instruções de workflow de commit e PR integradas e o snapshot de status git do contexto de Claude. Útil ao usar suas próprias skills de workflow git. Tem precedência sobre a configuração [`includeGitInstructions`](/docs/pt/settings-reference#includegitinstructions) quando definido |

265| `CLAUDE_CODE_DISABLE_LEGACY_MODEL_REMAP` | Defina como `1` para evitar remapeamento automático de Opus 4.0 e 4.1 para a versão Opus atual na API Anthropic. Use quando você intencionalmente quer fixar um modelo mais antigo. O remapeamento não é executado no Amazon Bedrock, Google Cloud's Agent Platform ou Microsoft Foundry |265| `CLAUDE_CODE_DISABLE_LEGACY_MODEL_REMAP` | Defina como `1` para impedir remapeamento automático de Opus 4.0 e 4.1 para a versão Opus atual na API Anthropic. Use quando você intencionalmente quer fixar um modelo mais antigo. O remapeamento não é executado no Amazon Bedrock, Google Cloud's Agent Platform ou Microsoft Foundry |

266| `CLAUDE_CODE_DISABLE_MOUSE` | Defina como `1` para desabilitar rastreamento de mouse em [renderização fullscreen](/docs/pt/fullscreen). Rolagem de teclado com `PgUp` e `PgDn` ainda funciona. Use isso para manter o comportamento de cópia ao selecionar nativo do seu terminal |266| `CLAUDE_CODE_DISABLE_MODEL_ACCESS_FALLBACK` | Defina como `1` para impedir que Claude Code em [Amazon Bedrock](/docs/pt/amazon-bedrock#when-a-model-is-disabled-mid-session) e [Google Cloud's Agent Platform](/docs/pt/google-vertex-ai#when-a-model-is-disabled-mid-session) mude para um modelo mais antigo quando sua conta perde acesso ao modelo de uma sessão no meio da sessão; a solicitação recusada falha imediatamente. Uma [cadeia de modelo fallback](/docs/pt/model-config#fallback-model-chains) que você configura ainda muda nessa recusa, e as [verificações de modelo de inicialização](/docs/pt/amazon-bedrock#startup-model-checks) ainda caem de volta no lançamento. Requer Claude Code v2.1.285 ou posterior |

267| `CLAUDE_CODE_DISABLE_MOUSE_CLICKS` | Defina como `1` para desabilitar manipulação de clique, arrasto e hover em [renderização fullscreen](/docs/pt/fullscreen) enquanto mantém rolagem de roda do mouse. Use isso quando você quer que a rolagem de roda funcione dentro de Claude Code mas não quer que cliques posicionem o cursor, expandam saída de ferramenta ou abram links. `CLAUDE_CODE_DISABLE_MOUSE` tem precedência quando ambos estão definidos. Requer Claude Code v2.1.195 ou posterior |267| `CLAUDE_CODE_DISABLE_MOUSE` | Defina como `1` para desabilitar rastreamento de mouse em [renderização em tela cheia](/docs/pt/fullscreen). Rolagem de teclado com `PgUp` e `PgDn` ainda funciona. Use isso para manter o comportamento de cópia nativa do seu terminal |

268| `CLAUDE_CODE_DISABLE_MTLS_RELOAD_ON_STALE_CONNECTION` | Defina como `1` para parar Claude Code de re-ler o [certificado de cliente mTLS e chave](/docs/pt/network-config#mtls-authentication) quando uma solicitação de API falha com um erro em nível de conexão, como uma redefinição de conexão ou erro de handshake TLS. Com o recarregamento desabilitado, Claude Code carrega arquivos rotacionados apenas quando aplica configurações novamente ou na próxima inicialização. Requer Claude Code v2.1.232 ou posterior |268| `CLAUDE_CODE_DISABLE_MOUSE_CLICKS` | Defina como `1` para desabilitar manipulação de clique, arrasto e hover em [renderização em tela cheia](/docs/pt/fullscreen) enquanto mantém rolagem de roda do mouse. Use isso quando você quer que a rolagem de roda funcione dentro de Claude Code mas não quer que cliques posicionem o cursor, expandam saída de ferramenta ou abram links. `CLAUDE_CODE_DISABLE_MOUSE` tem precedência quando ambos estão definidos. Requer Claude Code v2.1.195 ou posterior |

269| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | Defina como qualquer valor não vazio, como `1`, para desabilitar tráfego de rede não essencial: auto-atualizações, telemetria, relatório de erros, comando `/feedback`, [feedback redigido por Claude](/docs/pt/tools-reference#sendfeedback-tool-behavior), notas de lançamento, verificações de [badge de status PR e MR](/docs/pt/interactive-mode#pr-review-status) e verificações de disponibilidade como a verificação de [modo rápido](/docs/pt/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways). Também para as [execuções em background de fontes de `command` de plugin](/docs/pt/plugins/loading#when-a-command-source-re-runs), que são comandos locais em vez de tráfego de rede, porque podem disparar instalações de dependência. **Defini-lo como `0` ou `false` ainda desabilita esse tráfego**, diferentemente da maioria das variáveis on/off; desconfigurar a variável para permitir novamente. Também desabilita busca de sinalizador de recurso, o que torna [Remote Control](/docs/pt/remote-control#requirements) e os outros [recursos que precisam de busca de sinalizador de recurso](#features-that-need-feature-flag-fetching) indisponíveis. Auto-instalação do marketplace de plugin oficial não é coberta; desabilite com `CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL`. Não afeta [descoberta de modelo de gateway](/docs/pt/llm-gateway-connect#add-gateway-models-to-the-model-picker), que tem seu próprio opt-in |269| `CLAUDE_CODE_DISABLE_MTLS_RELOAD_ON_STALE_CONNECTION` | Defina como `1` para impedir que Claude Code releia o [certificado de cliente mTLS e chave](/docs/pt/network-config#mtls-authentication) quando uma solicitação de API falha com um erro em nível de conexão, como uma redefinição de conexão ou erro de handshake TLS. Com o recarregamento desabilitado, Claude Code carrega arquivos rotacionados apenas quando aplica configurações novamente ou na próxima inicialização. Requer Claude Code v2.1.232 ou posterior |

270| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | Defina como qualquer valor não vazio, como `1`, para desabilitar tráfego de rede não essencial: auto-atualizações, telemetria, relatório de erros, comando `/feedback`, [feedback redigido por Claude](/docs/pt/tools-reference#sendfeedback-tool-behavior), notas de lançamento, verificações de [badge de status de PR e MR](/docs/pt/interactive-mode#pr-review-status) e verificações de disponibilidade como a verificação de [modo rápido](/docs/pt/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways). Também para as [execuções em segundo plano de fontes de comando de plugin](/docs/pt/plugins/loading#when-a-command-source-re-runs), que são comandos locais em vez de tráfego de rede, porque podem disparar instalações de dependência. **Defini-lo como `0` ou `false` ainda desabilita esse tráfego**, diferentemente da maioria das variáveis on/off; desconfigurar a variável para permitir novamente. Também desabilita busca de sinalizador de recurso, o que torna [Remote Control](/docs/pt/remote-control#requirements) e os outros [recursos que precisam de busca de sinalizador de recurso](#features-that-need-feature-flag-fetching) indisponíveis. Auto-instalação do marketplace de plugin oficial não é coberta; desabilite com `CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL`. Não afeta [descoberta de modelo de gateway](/docs/pt/llm-gateway-connect#add-gateway-models-to-the-model-picker), que tem seu próprio opt-in |

270| `CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK` | Defina como `1` para desabilitar o fallback não-streaming quando uma solicitação de streaming falha no meio do stream. Erros de streaming se propagam para a camada de retry. Útil quando um proxy ou gateway causa o fallback produzir execução de ferramenta duplicada |271| `CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK` | Defina como `1` para desabilitar o fallback não-streaming quando uma solicitação de streaming falha no meio do stream. Erros de streaming se propagam para a camada de retry. Útil quando um proxy ou gateway causa o fallback produzir execução de ferramenta duplicada |

271| `CLAUDE_CODE_DISABLE_NOTIFICATION_PRESENCE_CHECK` | Defina como `1` para enviar a notificação de desktop da ferramenta `PushNotification` mesmo enquanto você está digitando ou focado no terminal. Por padrão, a ferramenta pula tanto a notificação de desktop quanto o [push móvel](/docs/pt/remote-control#mobile-push-notifications) quando detecta atividade de teclado recente ou foco de terminal. Essa variável desabilita apenas essa verificação local, para que o servidor ainda possa suprimir o push móvel quando detecta que você está ativo. Requer Claude Code v2.1.193 ou posterior |272| `CLAUDE_CODE_DISABLE_NOTIFICATION_PRESENCE_CHECK` | Defina como `1` para enviar a notificação de desktop da ferramenta `PushNotification` mesmo enquanto você está digitando ou focado no terminal. Por padrão, a ferramenta pula tanto a notificação de desktop quanto o [push móvel](/docs/pt/remote-control#mobile-push-notifications) quando detecta atividade de teclado recente ou foco de terminal. Essa variável desabilita apenas essa verificação local, para que o servidor ainda possa suprimir o push móvel quando detecta que você está ativo. Requer Claude Code v2.1.193 ou posterior |

272| `CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL` | Defina como `1` para desabilitar registro automático do marketplace de plugin oficial. Claude Code lê a variável quando está prestes a registrar o marketplace, geralmente durante o primeiro lançamento interativo de uma máquina. Se a variável estiver definida nesse ponto, Claude Code pula o registro permanentemente. Desconfigurar a variável depois não desfaz o pulo. Execute `claude plugin marketplace add anthropics/claude-plugins-official` para registrar o marketplace a qualquer momento |273| `CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL` | Defina como `1` para desabilitar registro automático do marketplace de plugin oficial. Claude Code lê a variável quando está prestes a registrar o marketplace, geralmente durante o primeiro lançamento interativo de uma máquina. Se a variável estiver definida nesse ponto, Claude Code pula o registro permanentemente. Desconfigurar a variável depois não desfaz o pulo. Execute `claude plugin marketplace add anthropics/claude-plugins-official` para registrar o marketplace a qualquer momento |

273| `CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS` | Defina como `1` para parar Claude Code de executar seus [hooks `Notification` para solicitações de permissão sem resposta](/docs/pt/hooks#notification) em sessões onde Claude Code as envia para o callback `canUseTool` do Agent SDK, que é como Claude Desktop e a extensão VS Code hospedam Claude Code. Não tem efeito em sessões de terminal. Requer Claude Code v2.1.233 ou posterior |274| `CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS` | Defina como `1` para impedir que Claude Code execute seus [hooks `Notification` para solicitações de permissão sem resposta](/docs/pt/hooks#notification) em sessões onde Claude Code as envia para o callback `canUseTool` do Agent SDK, que é como Claude Desktop e a extensão VS Code hospedam Claude Code. Não tem efeito em sessões de terminal. Requer Claude Code v2.1.233 ou posterior |

274| `CLAUDE_CODE_DISABLE_POLICY_SKILLS` | Defina como `1` para pular carregamento de skills do diretório de skills gerenciadas em todo o sistema. Útil para sessões de container ou CI que não devem carregar skills provisionadas por operador |275| `CLAUDE_CODE_DISABLE_POLICY_SKILLS` | Defina como `1` para pular o carregamento de skills do diretório de skills gerenciado em todo o sistema. Útil para sessões de container ou CI que não devem carregar skills provisionadas por operador |

275| `CLAUDE_CODE_DISABLE_POWERSHELL_CMD_RM_DENY` | Defina como `1` para desativar a verificação da [ferramenta PowerShell](/docs/pt/tools-reference#powershell-tool) que nega os built-ins `cmd` `rd`, `rmdir`, `del` e `erase` em um [caminho do sistema](/docs/pt/permission-modes#remove-item-in-powershell), como uma raiz de unidade ou seu diretório inicial. Claude Code ignora essa variável em um bloco `env` de arquivo de configurações. Requer Claude Code v2.1.283 ou posterior |276| `CLAUDE_CODE_DISABLE_POWERSHELL_CMD_RM_DENY` | Defina como `1` para desativar a verificação da [ferramenta PowerShell](/docs/pt/tools-reference#powershell-tool) que nega os built-ins `cmd` `rd`, `rmdir`, `del` e `erase` em um [caminho do sistema](/docs/pt/permission-modes#remove-item-in-powershell), como raiz de unidade ou seu diretório inicial. Claude Code ignora essa variável em um bloco `env` de arquivo de configurações. Requer Claude Code v2.1.283 ou posterior |

276| `CLAUDE_CODE_DISABLE_SUBSTITUTION_RM_PROMPT` | Defina como `1` para desativar a verificação de [caminho crítico](/docs/pt/permission-modes#critical-paths) para um `rm` recursivo cujo alvo é inteiramente a saída de uma substituição de comando, como `rm -rf "$(pwd)"`. As outras verificações de caminho crítico continuam em execução. Defina no ambiente que inicia Claude Code, já que Claude Code ignora uma cópia entregue através de um bloco `env` de configurações. Requer Claude Code v2.1.281 ou posterior |277| `CLAUDE_CODE_DISABLE_SUBSTITUTION_RM_PROMPT` | Defina como `1` para desativar a verificação de [caminho crítico](/docs/pt/permission-modes#critical-paths) para um `rm` recursivo cujo alvo é inteiramente a saída de uma substituição de comando, como `rm -rf "$(pwd)"`. As outras verificações de caminho crítico continuam funcionando. Defina-o no ambiente que inicia Claude Code, já que Claude Code ignora uma cópia entregue através de um bloco `env` de configurações. Requer Claude Code v2.1.281 ou posterior |

277| `CLAUDE_CODE_DISABLE_TERMINAL_TITLE` | Defina como `1` para desabilitar atualizações automáticas de título de terminal com base no contexto de conversa. Isso também pula a solicitação de modelo pequeno/rápido em background que [gera um título de sessão](/docs/pt/sessions#name-your-sessions) |278| `CLAUDE_CODE_DISABLE_TERMINAL_TITLE` | Defina como `1` para desabilitar atualizações automáticas de título de terminal com base no contexto de conversa. Isso também pula a solicitação de modelo pequeno/rápido em segundo plano que [gera um título de sessão](/docs/pt/sessions#name-your-sessions) |

278| `CLAUDE_CODE_DISABLE_THINKING` | Defina como `1` para omitir o parâmetro `thinking` de solicitações de API completamente. Esta é uma opção de compatibilidade para proxies e gateways que rejeitam o parâmetro. Em modelos que pensam por padrão, omitir o parâmetro significa que o modelo ainda pode pensar. Para desabilitar explicitamente [pensamento estendido](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) na API Anthropic, use `MAX_THINKING_TOKENS=0`. Nenhuma variável desativa pensamento em Opus 5.5, Sonnet 5.5 ou modelos Fable, que não podem ter pensamento desativado. Em [provedores de terceiros](/docs/pt/third-party-integrations), `MAX_THINKING_TOKENS=0` igualmente omite o parâmetro, para que as duas variáveis se comportem igual lá |279| `CLAUDE_CODE_DISABLE_THINKING` | Defina como `1` para omitir o parâmetro `thinking` de solicitações de API inteiramente. Esta é uma opção de compatibilidade para proxies e gateways que rejeitam o parâmetro. Em modelos que pensam por padrão, omitir o parâmetro significa que o modelo ainda pode pensar. Para desabilitar explicitamente [pensamento estendido](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) na API Anthropic, use `MAX_THINKING_TOKENS=0`. Nenhuma variável desativa pensamento em Opus 5.5, Sonnet 5.5 ou os modelos Fable, que não podem ter pensamento desativado. Em [provedores de terceiros](/docs/pt/third-party-integrations), `MAX_THINKING_TOKENS=0` igualmente omite o parâmetro, para que as duas variáveis se comportem igual lá |

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

280| `CLAUDE_CODE_DISABLE_VIRTUAL_SCROLL` | Defina como `1` para desabilitar rolagem virtual em [renderização fullscreen](/docs/pt/fullscreen) e renderizar cada mensagem na transcrição. Use isso se a rolagem em modo fullscreen mostrar regiões em branco onde mensagens devem aparecer |281| `CLAUDE_CODE_DISABLE_VIRTUAL_SCROLL` | Defina como `1` para desabilitar rolagem virtual em [renderização em tela cheia](/docs/pt/fullscreen) e renderizar cada mensagem na transcrição. Use isso se a rolagem em modo tela cheia mostrar regiões em branco onde as mensagens devem aparecer |

281| `CLAUDE_CODE_DISABLE_WINDOWS_SHELL_LAUNCHER` | Defina como `1` para iniciar comandos da [ferramenta PowerShell](/docs/pt/tools-reference#powershell-tool) no Windows diretamente em vez de através do launcher `cmd.exe`. Por padrão, o launcher permite que um comando PowerShell [em execução em background](/docs/pt/tools-reference#background-commands) [seja transferido para o próximo processo da sessão](/docs/pt/agent-view#the-supervisor-process), como quando você [coloca a sessão em background](/docs/pt/agent-view#from-inside-a-session). Se você definir a variável, um comando PowerShell em background para quando o processo da sessão sai. Comandos Bash não são afetados. Requer Claude Code v2.1.269 ou posterior |282| `CLAUDE_CODE_DISABLE_WINDOWS_SHELL_LAUNCHER` | Defina como `1` para iniciar comandos da [ferramenta PowerShell](/docs/pt/tools-reference#powershell-tool) no Windows diretamente em vez de através do lançador `cmd.exe`. Por padrão, o lançador permite que um comando PowerShell [em execução em segundo plano](/docs/pt/tools-reference#background-commands) [seja transferido para o próximo processo da sessão](/docs/pt/agent-view#the-supervisor-process), como quando você [coloca a sessão em segundo plano](/docs/pt/agent-view#from-inside-a-session). Se você definir a variável, um comando PowerShell em segundo plano para quando o processo da sessão sai. Comandos Bash não são afetados. Requer Claude Code v2.1.269 ou posterior |

282| `CLAUDE_CODE_DISABLE_WORKFLOWS` | Defina como `1` para desabilitar [workflows](/docs/pt/workflows#turn-workflows-off). Equivalente à configuração [`disableWorkflows`](/docs/pt/settings-reference#disableworkflows) |283| `CLAUDE_CODE_DISABLE_WORKFLOWS` | Defina como `1` para desabilitar [workflows](/docs/pt/workflows#turn-workflows-off). Equivalente à configuração [`disableWorkflows`](/docs/pt/settings-reference#disableworkflows) |

283| `CLAUDE_CODE_EFFORT_LEVEL` | Defina o nível de effort para modelos suportados. Valores: `low`, `medium`, `high`, `xhigh`, `max` ou `auto` para usar o padrão do modelo. Os níveis disponíveis dependem do modelo. Tem precedência sobre `--effort`, `/effort` e as configurações `modelSettings` e `effortLevel`. Um limite [`maxEffortLevel`](/docs/pt/settings-reference#maxeffortlevel) ainda se aplica. Veja [Ajustar nível de effort](/docs/pt/model-config#adjust-effort-level) |284| `CLAUDE_CODE_EFFORT_LEVEL` | Defina o nível de esforço para modelos suportados. Valores: `low`, `medium`, `high`, `xhigh`, `max` ou `auto` para usar o padrão do modelo. Os níveis disponíveis dependem do modelo. Tem precedência sobre `--effort`, `/effort` e as configurações `modelSettings` e `effortLevel`. Um limite [`maxEffortLevel`](/docs/pt/settings-reference#maxeffortlevel) ainda se aplica. Veja [Ajustar nível de esforço](/docs/pt/model-config#adjust-effort-level) |

284| `CLAUDE_CODE_ENABLE_AUTO_MODE` | Aceito para compatibilidade com versões mais antigas e não tem efeito. Modo auto está disponível por padrão em cada provedor, incluindo Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry e sessões [gateway de aplicativos Claude](/docs/pt/claude-apps-gateway) conectadas. Na v2.1.158 através v2.1.206, definir isso como `1` era necessário para tornar [modo auto](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode) disponível nesses provedores |285| `CLAUDE_CODE_ENABLE_AUTO_MODE` | Aceito para compatibilidade com versões mais antigas e não tem efeito. Modo automático está disponível por padrão em cada provedor, incluindo Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry e sessões de [gateway de aplicativos Claude](/docs/pt/claude-apps-gateway) conectadas. Na v2.1.158 até v2.1.206, definir isso como `1` era necessário para tornar [modo automático](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode) disponível nesses provedores |

285| `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` | Substitua disponibilidade de [recapitulação de sessão](/docs/pt/interactive-mode#session-recap). Defina como `0` para forçar recapitulações desativadas independentemente do toggle `/config`. Defina como `1` para forçar recapitulações ativadas quando [`awaySummaryEnabled`](/docs/pt/settings-reference#awaysummaryenabled) é `false`. Tem precedência sobre a configuração e toggle `/config` |286| `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` | Substitua a disponibilidade de [recapitulação de sessão](/docs/pt/interactive-mode#session-recap). Defina como `0` para forçar recapitulações desativadas independentemente da alternância `/config`. Defina como `1` para forçar recapitulações ativadas quando [`awaySummaryEnabled`](/docs/pt/settings-reference#awaysummaryenabled) é `false`. Tem precedência sobre a configuração e alternância `/config` |

286| `CLAUDE_CODE_ENABLE_BACKGROUND_PLUGIN_REFRESH` | Defina como `1` para atualizar estado de plugin em limites de turno em [modo não interativo](/docs/pt/headless) após uma instalação em background ser concluída. Desativado por padrão porque a atualização muda o prompt do sistema no meio da sessão, o que invalida [cache de prompt](/docs/pt/prompt-caching) para esse turno |287| `CLAUDE_CODE_ENABLE_BACKGROUND_PLUGIN_REFRESH` | Defina como `1` para atualizar o estado do plugin em limites de turno em [modo não interativo](/docs/pt/headless) após uma instalação em segundo plano ser concluída. Desativado por padrão porque a atualização muda o prompt do sistema no meio da sessão, o que invalida [cache de prompt](/docs/pt/prompt-caching) para esse turno |

287| `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` | Defina como `1` para rotear a pesquisa de qualidade de sessão "How is Claude doing?" para seu próprio [coletor OpenTelemetry](/docs/pt/monitoring-usage) quando tráfego não essencial vinculado a Anthropic é bloqueado. Classificações de pesquisa são emitidas apenas como eventos OTEL para seu coletor configurado. Nenhum dado de pesquisa é enviado para Anthropic neste modo. Aplica-se quando `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`, `DISABLE_TELEMETRY` ou `DO_NOT_TRACK` está definido, e não tem efeito caso contrário. `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` e a política de feedback de produto da organização têm precedência |288| `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` | Defina como `1` para rotear a pesquisa de qualidade de sessão "Como Claude está indo?" para seu próprio [coletor OpenTelemetry](/docs/pt/monitoring-usage) quando o tráfego não essencial vinculado a Anthropic está bloqueado. As classificações de pesquisa são emitidas apenas como eventos OTEL para seu coletor configurado. Nenhum dado de pesquisa é enviado para Anthropic neste modo. Aplica-se quando `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`, `DISABLE_TELEMETRY` ou `DO_NOT_TRACK` está definido, e não tem efeito caso contrário. `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` e a política de feedback de produto da organização têm precedência |

288| `CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING` | Controla se entradas de chamada de ferramenta fazem stream da API conforme Claude as gera. Com isso desativado, uma entrada de ferramenta grande como uma escrita de arquivo longa chega apenas após Claude terminar de gerá-la, o que pode parecer que está travando. Ativado por padrão na API Anthropic. No Amazon Bedrock e Google Cloud's Agent Platform, ativado por modelo onde o container implantado o suporta. Defina como `0` para desativar. Defina como `1` para forçar ativado ao rotear através de um proxy via `ANTHROPIC_BASE_URL`, `ANTHROPIC_VERTEX_BASE_URL` ou `ANTHROPIC_BEDROCK_BASE_URL`. Desativado por padrão em Microsoft Foundry e conexões [gateway](/docs/pt/llm-gateway) |289| `CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING` | Controla se entradas de chamada de ferramenta fluem da API conforme Claude as gera. Com isso desativado, uma entrada de ferramenta grande, como uma escrita de arquivo longa, chega apenas após Claude terminar de gerá-la, o que pode parecer que está travando. Ativado por padrão na API Anthropic. No Amazon Bedrock e Google Cloud's Agent Platform, ativado por modelo onde o contêiner implantado o suporta. Defina como `0` para desativar. Defina como `1` para forçar ativado ao rotear através de um proxy via `ANTHROPIC_BASE_URL`, `ANTHROPIC_VERTEX_BASE_URL` ou `ANTHROPIC_BEDROCK_BASE_URL`. Desativado por padrão no Microsoft Foundry e conexões de [gateway](/docs/pt/llm-gateway) |

289| `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` | Defina como `1` para popular o seletor `/model` do endpoint `/v1/models` do seu gateway quando `ANTHROPIC_BASE_URL` aponta para um gateway compatível com Anthropic como LiteLLM, Kong ou um proxy interno. Desativado por padrão porque gateways apoiados por uma chave de API compartilhada mostrariam cada usuário cada modelo que a chave pode acessar. Modelos descobertos ainda são filtrados por uma lista de permissão [`availableModels`](/docs/pt/settings-reference#availablemodels) que a sessão recebe; entregue a lista através de [MDM ou arquivo de configurações gerenciadas](/docs/pt/managed-settings#delivery-mechanisms), já que [entrega gerenciada pelo servidor não está disponível em configurações de gateway](/docs/pt/server-managed-settings#platform-availability) |290| `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` | Defina como `1` para preencher o seletor `/model` do endpoint `/v1/models` do seu gateway quando `ANTHROPIC_BASE_URL` aponta para um gateway compatível com Anthropic, como LiteLLM, Kong ou um proxy interno. Desativado por padrão porque gateways apoiados por uma chave de API compartilhada mostrariam a cada usuário cada modelo que a chave pode acessar. Modelos descobertos ainda são filtrados por uma lista de permissão [`availableModels`](/docs/pt/settings-reference#availablemodels) que a sessão recebe; entregue a lista através de [MDM ou arquivo de configurações gerenciadas](/docs/pt/managed-settings#delivery-mechanisms), já que [entrega gerenciada pelo servidor não está disponível em configurações de gateway](/docs/pt/server-managed-settings#platform-availability) |

290| `CLAUDE_CODE_ENABLE_OPUS_4_7_FAST_MODE` | Removido na v2.1.142, quando o padrão de [modo rápido](/docs/pt/fast-mode) se moveu de Opus 4.6 para Opus 4.7 |291| `CLAUDE_CODE_ENABLE_OPUS_4_7_FAST_MODE` | Removido na v2.1.142, quando o padrão de [modo rápido](/docs/pt/fast-mode) mudou de Opus 4.6 para Opus 4.7 |

291| `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` | Defina como `false` para desativar sugestões de prompt, as previsões acinzentadas que aparecem em sua entrada de prompt. Tem precedência sobre a configuração [`promptSuggestionEnabled`](/docs/pt/settings-reference#promptsuggestionenabled), que é o que o toggle **Prompt suggestions** em `/config` escreve. Claude Code também [pausa sugestões enquanto sua conta está próxima ou no limite de uso](/docs/pt/interactive-mode#when-claude-code-skips-suggestions). Defina como `true` para mantê-las ativadas até atingir o limite. Requer Claude Code v2.1.238 ou posterior. Veja [Sugestões de prompt](/docs/pt/interactive-mode#prompt-suggestions) |292| `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` | Defina como `false` para desativar sugestões de prompt, as previsões acinzentadas que aparecem em sua entrada de prompt. Tem precedência sobre a configuração [`promptSuggestionEnabled`](/docs/pt/settings-reference#promptsuggestionenabled), que é o que a alternância **Prompt suggestions** em `/config` escreve. Claude Code também [pausa sugestões enquanto sua conta está próxima ou no seu limite de uso](/docs/pt/interactive-mode#when-claude-code-skips-suggestions). Defina como `true` para mantê-las ativadas até atingir o limite. Requer Claude Code v2.1.238 ou posterior. Veja [Sugestões de prompt](/docs/pt/interactive-mode#prompt-suggestions) |

292| `CLAUDE_CODE_ENABLE_TASKS` | Seleciona quais ferramentas de rastreamento de tarefas Claude Code fornece em [sessões que as têm](/docs/pt/tools-reference#task-tool-availability). Por padrão, Claude Code fornece as ferramentas Task `TaskCreate`, `TaskUpdate`, `TaskGet` e `TaskList`. Defina como `0` para obter a ferramenta legacy `TodoWrite`. Veja [Lista de tarefas](/docs/pt/interactive-mode#task-list) |293| `CLAUDE_CODE_ENABLE_TASKS` | Seleciona quais ferramentas de rastreamento de tarefas Claude Code fornece em [sessões que as têm](/docs/pt/tools-reference#task-tool-availability). Por padrão, Claude Code fornece as ferramentas Task `TaskCreate`, `TaskUpdate`, `TaskGet` e `TaskList`. Defina como `0` para obter a ferramenta `TodoWrite` legada. Veja [Lista de tarefas](/docs/pt/interactive-mode#task-list) |

293| `CLAUDE_CODE_ENABLE_TELEMETRY` | Defina como `1` para ativar coleta de dados OpenTelemetry para métricas e logging. Necessário antes de configurar exportadores OTel. Defina em seu shell, configurações de usuário ou configurações gerenciadas. Ignorado em [configurações de projeto e local](/docs/pt/settings-reference#variables-claude-code-ignores-in-env). Veja [Monitoramento](/docs/pt/monitoring-usage) |294| `CLAUDE_CODE_ENABLE_TELEMETRY` | Defina como `1` para ativar coleta de dados OpenTelemetry para métricas e logging. Necessário antes de configurar exportadores OTel. Defina-o em seu shell, configurações de usuário ou configurações gerenciadas. Ignorado em [configurações de projeto e local](/docs/pt/settings-reference#variables-claude-code-ignores-in-env). Veja [Monitoramento](/docs/pt/monitoring-usage) |

294| `CLAUDE_CODE_ENABLE_TODO_TOOLS` | Defina como `1` para obter as ferramentas de rastreamento de tarefas em cada modelo. Sem isso, Claude Code as fornece por padrão apenas nos modelos listados em [Disponibilidade de ferramenta Task](/docs/pt/tools-reference#task-tool-availability). `CLAUDE_CODE_ENABLE_TASKS` ainda seleciona as ferramentas Task ou `TodoWrite`. Requer Claude Code v2.1.233 ou posterior |295| `CLAUDE_CODE_ENABLE_TODO_TOOLS` | Defina como `1` para obter as ferramentas de rastreamento de tarefas em cada modelo. Sem isso, Claude Code as fornece por padrão apenas nos modelos listados em [Disponibilidade da ferramenta Task](/docs/pt/tools-reference#task-tool-availability). `CLAUDE_CODE_ENABLE_TASKS` ainda seleciona as ferramentas Task ou `TodoWrite`. Requer Claude Code v2.1.233 ou posterior |

295| `CLAUDE_CODE_EXIT_AFTER_STOP_DELAY` | Tempo em milissegundos para aguardar após o loop de consulta ficar ocioso antes de sair automaticamente. Útil para workflows automatizados e scripts usando modo SDK |296| `CLAUDE_CODE_EXIT_AFTER_STOP_DELAY` | Tempo em milissegundos para aguardar após o loop de consulta ficar ocioso antes de sair automaticamente. Útil para workflows automatizados e scripts usando modo SDK |

296| `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` | Defina como `1` para ativar [equipes de agentes](/docs/pt/agent-teams). Equipes de agentes são experimentais e desabilitadas por padrão |297| `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` | Defina como `1` para ativar [equipes de agentes](/docs/pt/agent-teams). Equipes de agentes são experimentais e desabilitadas por padrão |

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

298| `CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS` | Substitua o limite de token padrão para leituras de arquivo. Útil quando você precisa ler arquivos maiores completamente |299| `CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS` | Substitua o limite de token padrão para leituras de arquivo. Útil quando você precisa ler arquivos maiores completamente |

299| `CLAUDE_CODE_FORCE_SESSION_PERSISTENCE` | Defina como `1` para forçar persistência de transcrição, histórico de prompt e registro `claude agents` mesmo quando este `claude` foi iniciado de dentro de outra sessão Claude Code. Use quando um valor `CLAUDE_CODE_CHILD_SESSION` herdado, por exemplo de uma sessão `screen` ou um launcher em background iniciado primeiro pela ferramenta Bash de Claude Code, causa uma sessão genuína de nível superior a ser mal classificada como aninhada. A partir da v2.1.178, Claude Code detecta o caso tmux automaticamente e ignora o marcador herdado, para que tmux não precise mais dessa variável. Também honrado na v2.1.169 e anterior; não tem efeito na v2.1.170 e v2.1.171, onde a detecção de sessão aninhada que substitui foi removida |300| `CLAUDE_CODE_FORCE_SESSION_PERSISTENCE` | Defina como `1` para forçar persistência de transcrição, histórico de prompt e registro `claude agents` mesmo quando este `claude` foi iniciado de dentro de outra sessão Claude Code. Use quando um valor `CLAUDE_CODE_CHILD_SESSION` herdado, por exemplo de uma sessão `screen` ou um lançador em segundo plano iniciado primeiro pela ferramenta Bash de Claude Code, causa uma sessão genuína de nível superior ser mal classificada como aninhada. A partir da v2.1.178, Claude Code detecta o caso tmux automaticamente e ignora o marcador herdado, para que tmux não precise mais dessa variável. Também honrado na v2.1.169 e anterior; não tem efeito na v2.1.170 e v2.1.171, onde a detecção de sessão aninhada que substitui foi removida |

300| `CLAUDE_CODE_FORCE_STRIKETHROUGH` | Defina como `1` para forçar renderização de tachado para `~~text~~` nas respostas de Claude quando seu terminal o suporta mas não é auto-detectado, como sobre SSH sem `TERM_PROGRAM` encaminhado. Sem isso, terminais não detectados mostram os marcadores literais `~~` em vez de renderizar o texto como tachado. Requer Claude Code v2.1.186 ou posterior |301| `CLAUDE_CODE_FORCE_STRIKETHROUGH` | Defina como `1` para forçar renderização de tachado para `~~text~~` nas respostas de Claude quando seu terminal o suporta mas não é auto-detectado, como sobre SSH sem `TERM_PROGRAM` encaminhado. Sem isso, terminais não detectados mostram os marcadores literais `~~` em vez de renderizar o texto como tachado. Requer Claude Code v2.1.186 ou posterior |

301| `CLAUDE_CODE_FORCE_SYNC_OUTPUT` | Defina como `1` para forçar ativação do modo privado DEC 2026 [saída sincronizada](https://gist.github.com/christianparpart/d8a62cc1ab659194337d73e399004036) quando seu terminal o suporta mas não é auto-detectado. Útil para emuladores como `eat` do Emacs que implementam BSU/ESU mas não respondem à sonda de capacidade. Não tem efeito sob tmux. Diferentemente de `CLAUDE_CODE_NO_FLICKER`, que muda para [renderização fullscreen](/docs/pt/fullscreen), isso não muda o renderizador |302| `CLAUDE_CODE_FORCE_SYNC_OUTPUT` | Defina como `1` para forçar ativação do modo privado DEC 2026 [saída sincronizada](https://gist.github.com/christianparpart/d8a62cc1ab659194337d73e399004036) quando seu terminal o suporta mas não é auto-detectado. Útil para emuladores como `eat` do Emacs que implementam BSU/ESU mas não respondem à sonda de capacidade. Não tem efeito sob tmux. Diferentemente de `CLAUDE_CODE_NO_FLICKER`, que muda para [renderização em tela cheia](/docs/pt/fullscreen), isso não muda o renderizador |

302| `CLAUDE_CODE_FORK_SUBAGENT` | Controla [modo fork](/docs/pt/sub-agents#turn-fork-mode-on-or-off), que permite Claude gerar [subagentes bifurcados](/docs/pt/sub-agents#fork-the-current-conversation) e está ativado por padrão apenas em sessões interativas. Defina como `1` para ativá-lo em `claude -p` e Agent SDK também, ou `0` para desativá-lo em todo tipo de sessão. Você pode executar `/subtask` independentemente de modo fork estar ativado. O padrão interativo requer Claude Code v2.1.232 ou posterior; em versões anteriores, defina a variável como `1` para ativar modo fork |303| `CLAUDE_CODE_FORK_SUBAGENT` | Controla [modo fork](/docs/pt/sub-agents#turn-fork-mode-on-or-off), que permite que Claude gere [subagentes bifurcados](/docs/pt/sub-agents#fork-the-current-conversation) e está ativado por padrão apenas em sessões interativas. Defina como `1` para ativá-lo em `claude -p` e Agent SDK também, ou `0` para desativá-lo em todo tipo de sessão. Você pode executar `/subtask` independentemente de o modo fork estar ativado. O padrão interativo requer Claude Code v2.1.232 ou posterior; em versões anteriores, defina a variável como `1` para ativar o modo fork |

303| `CLAUDE_CODE_FORWARD_SUBAGENT_TEXT` | Defina como `1` para emitir blocos de texto e pensamento de [subagente](/docs/pt/sub-agents) em saída `claude -p --output-format stream-json`, o mesmo comportamento que a flag [`--forward-subagent-text`](/docs/pt/cli-reference#cli-flags). Use a variável quando um harness invoca `claude` e não pode passar a flag. Diferentemente da flag, que sai com um erro fora do modo não interativo com saída stream-json, a variável é ignorada lá para que invocações aninhadas continuem funcionando quando está definida em todo o processo. Requer Claude Code v2.1.211 ou posterior |304| `CLAUDE_CODE_FORWARD_SUBAGENT_TEXT` | Defina como `1` para emitir blocos de texto e pensamento de [subagente](/docs/pt/sub-agents) em saída `claude -p --output-format stream-json`, o mesmo comportamento que a flag [`--forward-subagent-text`](/docs/pt/cli-reference#cli-flags). Use a variável quando um harness invoca `claude` e não pode passar a flag. Diferentemente da flag, que sai com um erro fora do modo não interativo com saída stream-json, a variável é ignorada lá para que invocações aninhadas continuem funcionando quando está definida em todo o processo. Requer Claude Code v2.1.211 ou posterior |

304| `CLAUDE_CODE_GATEWAY_HINT_HEADERS` | Defina como `1` para enviar os [cabeçalhos de dica de gateway](/docs/pt/llm-gateway-protocol#gateway-hint-headers), como `x-claude-code-request-class` e `x-claude-code-compaction`, em um proxy personalizado ou provedor de terceiros como Amazon Bedrock ou Claude Platform on AWS. Defina como `0` para parar de enviá-los em cada conexão, incluindo uma conexão direta com a API Anthropic, onde Claude Code os envia por padrão. Requer Claude Code v2.1.273 ou posterior |305| `CLAUDE_CODE_GATEWAY_HINT_HEADERS` | Defina como `1` para enviar os [cabeçalhos de dica de gateway](/docs/pt/llm-gateway-protocol#gateway-hint-headers), como `x-claude-code-request-class` e `x-claude-code-compaction`, em um proxy personalizado ou provedor de terceiros como Amazon Bedrock ou Claude Platform on AWS. Defina como `0` para parar de enviá-los em cada conexão, incluindo uma conexão direta com a API Anthropic, onde Claude Code os envia por padrão. Requer Claude Code v2.1.273 ou posterior |

305| `CLAUDE_CODE_GATEWAY_MODEL_DISCOVERY_TIMEOUT_MS` | Timeout em milissegundos para a solicitação de [descoberta de modelo de gateway](/docs/pt/llm-gateway-protocol#model-discovery) que `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` ativa (padrão: `3000`). Aumente quando seu gateway precisa de mais de três segundos para responder `/v1/models` na inicialização. Aceita apenas dígitos simples; `0`, valores negativos e outras grafias mantêm o padrão. Requer Claude Code v2.1.269 ou posterior |306| `CLAUDE_CODE_GATEWAY_MODEL_DISCOVERY_TIMEOUT_MS` | Timeout em milissegundos para a solicitação de [descoberta de modelo de gateway](/docs/pt/llm-gateway-protocol#model-discovery) que `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` ativa (padrão: `3000`). Aumente quando seu gateway precisa de mais de três segundos para responder `/v1/models` na inicialização. Aceita apenas dígitos simples; `0`, valores negativos e outras grafias mantêm o padrão. Requer Claude Code v2.1.269 ou posterior |

306| `CLAUDE_CODE_GIT_BASH_PATH` | Apenas Windows: caminho para o executável Git Bash (`bash.exe`). Use quando Git Bash está instalado mas não em seu PATH. Se o caminho não existir ou o arquivo não for nomeado `bash.exe`, `sh.exe`, `bash` ou `sh`, Claude Code ignora a variável e auto-detecta Git Bash como se não estivesse definida, registrando um aviso visível com `--debug`. Antes da v2.1.219, Claude Code saía na inicialização quando o caminho não existia e usava qualquer arquivo existente como shell sem verificar que era bash ou sh. Veja [Configuração Windows](/docs/pt/setup#set-up-on-windows) |307| `CLAUDE_CODE_GIT_BASH_PATH` | Apenas Windows: caminho para o executável Git Bash (`bash.exe`). Use quando Git Bash está instalado mas não em seu PATH. Se o caminho não existir ou o arquivo não for nomeado `bash.exe`, `sh.exe`, `bash` ou `sh`, Claude Code ignora a variável e auto-detecta Git Bash como se não estivesse definida, registrando um aviso visível com `--debug`. Antes da v2.1.219, Claude Code saía na inicialização quando o caminho não existia e usava qualquer arquivo existente como shell sem verificar que era bash ou sh. Veja [Configuração do Windows](/docs/pt/setup#set-up-on-windows) |

307| `CLAUDE_CODE_GLOB_HIDDEN` | Defina como `false` para excluir dotfiles dos resultados quando Claude invoca a [ferramenta Glob](/docs/pt/tools-reference#glob-tool-behavior). Incluído por padrão. Não afeta autocompletar `@`, `ls`, Grep ou Read |308| `CLAUDE_CODE_GLOB_HIDDEN` | Defina como `false` para excluir dotfiles dos resultados quando Claude invoca a [ferramenta Glob](/docs/pt/tools-reference#glob-tool-behavior). Incluído por padrão. Não afeta autocompletar arquivo `@`, `ls`, Grep ou Read |

308| `CLAUDE_CODE_GLOB_NO_IGNORE` | Defina como `false` para fazer a [ferramenta Glob](/docs/pt/tools-reference#glob-tool-behavior) respeitar padrões `.gitignore`. Por padrão, Glob retorna todos os arquivos correspondentes, incluindo os ignorados por git. Não afeta autocompletar `@`, que tem sua própria configuração [`respectGitignore`](/docs/pt/settings-reference#respectgitignore) |309| `CLAUDE_CODE_GLOB_NO_IGNORE` | Defina como `false` para fazer a [ferramenta Glob](/docs/pt/tools-reference#glob-tool-behavior) respeitar padrões `.gitignore`. Por padrão, Glob retorna todos os arquivos correspondentes, incluindo os ignorados por git. Não afeta autocompletar arquivo `@`, que tem sua própria configuração [`respectGitignore`](/docs/pt/settings-reference#respectgitignore) |

309| `CLAUDE_CODE_GLOB_TIMEOUT_SECONDS` | Timeout em segundos para descoberta de arquivo da ferramenta Glob. Padrão 20 segundos na maioria das plataformas e 60 segundos no WSL |310| `CLAUDE_CODE_GLOB_TIMEOUT_SECONDS` | Timeout em segundos para descoberta de arquivo da ferramenta Glob. Padrão de 20 segundos na maioria das plataformas e 60 segundos no WSL |

310| `CLAUDE_CODE_GOAL_CHECKIN_MINUTES` | Quantos minutos o trabalho em background pode manter uma meta ativa aguardando antes de Claude Code [pedir a Claude para verificá-la](/docs/pt/goal#background-work-defers-evaluation). Padrão `30`. Defina `0` para desativar check-ins. Dê minutos inteiros em dígitos simples, no máximo `10080`, que é uma semana. Claude Code trata qualquer outro valor como não definido e usa o padrão. Requer Claude Code v2.1.234 ou posterior |311| `CLAUDE_CODE_GOAL_CHECKIN_MINUTES` | Quantos minutos o trabalho em segundo plano pode manter uma meta ativa aguardando antes que Claude Code [peça a Claude para verificá-la](/docs/pt/goal#background-work-defers-evaluation). Padrão `30`. Defina `0` para desativar check-ins. Dê minutos inteiros em dígitos simples, no máximo `10080`, que é uma semana. Claude Code trata qualquer outro valor como não definido e usa o padrão. Requer Claude Code v2.1.234 ou posterior |

311| `CLAUDE_CODE_HIDE_CWD` | Defina como `1` para ocultar o diretório de trabalho no logo de inicialização. Útil para compartilhamentos de tela ou gravações onde o caminho expõe seu nome de usuário do SO |312| `CLAUDE_CODE_HIDE_CWD` | Defina como `1` para ocultar o diretório de trabalho no logo de inicialização. Útil para compartilhamentos de tela ou gravações onde o caminho expõe seu nome de usuário do SO |

312| `CLAUDE_CODE_IDE_HOST_OVERRIDE` | Substitua o endereço de host usado para conectar à extensão IDE. Por padrão, Claude Code auto-detecta o endereço correto, incluindo roteamento WSL-para-Windows |313| `CLAUDE_CODE_IDE_HOST_OVERRIDE` | Substitua o endereço de host usado para conectar à extensão IDE. Por padrão, Claude Code auto-detecta o endereço correto, incluindo roteamento WSL-para-Windows |

313| `CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL` | Defina como `1` para pular auto-instalação de extensões IDE. Equivalente a definir [`autoInstallIdeExtension`](/docs/pt/settings-reference#autoinstallideextension) como `false` |314| `CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL` | Defina como `1` para pular auto-instalação de extensões IDE. Equivalente a definir [`autoInstallIdeExtension`](/docs/pt/settings-reference#autoinstallideextension) como `false` |

314| `CLAUDE_CODE_IDE_SKIP_VALID_CHECK` | Defina como `1` para pular validação de entradas de arquivo de bloqueio IDE durante conexão. Use quando auto-conexão falha em encontrar seu IDE apesar dele estar em execução |315| `CLAUDE_CODE_IDE_SKIP_VALID_CHECK` | Defina como `1` para pular validação de entradas de arquivo de bloqueio IDE durante conexão. Use quando auto-conexão falha em encontrar seu IDE apesar dele estar em execução |

315| `CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS` | Quantos [subagentes](/docs/pt/sub-agents#concurrent-subagent-limit) podem estar em execução em uma sessão antes da ferramenta Agent recusar gerar outro (padrão: 20). Aceita um número inteiro positivo em dígitos simples; qualquer outra coisa é ignorada, para que a variável possa ajustar o limite mas não desabilitá-lo. Requer Claude Code v2.1.217 ou posterior |316| `CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS` | Quantos [subagentes](/docs/pt/sub-agents#concurrent-subagent-limit) podem estar em execução em uma sessão antes que a ferramenta Agent recuse gerar outro (padrão: 20). Aceita um número inteiro positivo em dígitos simples; qualquer outra coisa é ignorada, para que o limite possa ser ajustado mas não desabilitado. Requer Claude Code v2.1.217 ou posterior |

316| `CLAUDE_CODE_MAX_CONTEXT_TOKENS` | Substitua o tamanho da janela de contexto que Claude Code assume para o modelo ativo. A partir da v2.1.193, como se aplica depende de como Claude Code resolve o ID do modelo; veja [Corrigir a janela para um ID de modelo de gateway ou personalizado](/docs/pt/model-config#correct-the-window-for-a-gateway-or-custom-model-id). Use isso ao rotear para um modelo através de `ANTHROPIC_BASE_URL` cuja janela de contexto não corresponde ao tamanho integrado para seu nome |317| `CLAUDE_CODE_MAX_CONTEXT_TOKENS` | Substitua o tamanho da janela de contexto que Claude Code assume para o modelo ativo. A partir da v2.1.193, como se aplica depende de como Claude Code resolve o ID do modelo; veja [Corrigir a janela para um ID de modelo de gateway ou personalizado](/docs/pt/model-config#correct-the-window-for-a-gateway-or-custom-model-id). Use isso ao rotear para um modelo através de `ANTHROPIC_BASE_URL` cuja janela de contexto não corresponde ao tamanho integrado para seu nome |

317| `CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH` | Comprimento máximo em caracteres de cada descrição de ferramenta MCP e instruções de cada servidor MCP que Claude Code envia ao modelo (padrão: 2048). Claude Code [trunca texto mais longo](/docs/pt/mcp#for-mcp-server-authors). Aceita um número inteiro positivo em dígitos simples. Qualquer outra coisa é ignorada e o padrão se aplica. Requer Claude Code v2.1.280 ou posterior |318| `CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH` | Comprimento máximo em caracteres de cada descrição de ferramenta MCP e instruções de cada servidor MCP que Claude Code envia ao modelo (padrão: 2048). Claude Code [trunca texto mais longo](/docs/pt/mcp#for-mcp-server-authors). Aceita um número inteiro positivo em dígitos simples. Qualquer outra coisa é ignorada e o padrão se aplica. Requer Claude Code v2.1.280 ou posterior |

318| `CLAUDE_CODE_MAX_OUTPUT_TOKENS` | Defina o número máximo de tokens de saída para a maioria das solicitações. Padrões e limites variam por modelo; veja [max output tokens](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison). Claude Code padrão para 32000 para IDs de modelo que não reconhece, como nomes específicos de gateway, e reduz valores acima do limite de um modelo para o limite. Aumentar esse valor reduz a janela de contexto efetiva disponível antes de [auto-compactação](/docs/pt/costs#reduce-token-usage) ser acionada |319| `CLAUDE_CODE_MAX_OUTPUT_TOKENS` | Defina o número máximo de tokens de saída para a maioria das solicitações. Padrões e limites variam por modelo; veja [max output tokens](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison). Claude Code reduz um valor acima do limite de um modelo para o limite. Para um ID de modelo que Claude Code não pode resolver para um modelo que conhece, o padrão é 32000 e o limite é 128000. Aumentar esse valor reduz a janela de contexto efetiva disponível antes que [auto-compactação](/docs/pt/costs#reduce-token-usage) seja acionada |

319| `CLAUDE_CODE_MAX_RETRIES` | Substitua o número de vezes para tentar novamente solicitações de API falhadas (padrão: 10). Limitado a 15 a partir da v2.1.186; a partir da v2.1.199, `CLAUDE_CODE_RETRY_WATCHDOG` aumenta o padrão e remove o limite. Para sessões não supervisionadas que precisam aguardar através de interrupções mais longas, defina `CLAUDE_CODE_RETRY_WATCHDOG` |320| `CLAUDE_CODE_MAX_RETRIES` | Substitua o número de vezes para tentar novamente solicitações de API falhadas (padrão: 10). Limitado a 15 a partir da v2.1.186; a partir da v2.1.199, `CLAUDE_CODE_RETRY_WATCHDOG` aumenta o padrão e remove o limite. Para sessões não supervisionadas que precisam aguardar através de interrupções mais longas, defina `CLAUDE_CODE_RETRY_WATCHDOG` |

320| `CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION` | Removido na v2.1.224 e agora é um no-op. Anteriormente limitava o número total de [subagentes](/docs/pt/sub-agents) que Claude poderia gerar com a ferramenta Agent em uma sessão (padrão: 200); gerar além do limite falhava com `Subagent spawn limit reached`. O [limite de subagente concorrente](/docs/pt/sub-agents#concurrent-subagent-limit) e o [limite de profundidade](/docs/pt/sub-agents#let-subagents-spawn-their-own-subagents) ainda se aplicam |321| `CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION` | Removido na v2.1.224 e agora é um no-op. Anteriormente limitava o número total de [subagentes](/docs/pt/sub-agents) que Claude poderia gerar com a ferramenta Agent em uma sessão (padrão: 200); gerar além do limite falhava com `Subagent spawn limit reached`. O [limite de subagente concorrente](/docs/pt/sub-agents#concurrent-subagent-limit) e o [limite de profundidade](/docs/pt/sub-agents#let-subagents-spawn-their-own-subagents) ainda se aplicam |

321| `CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH` | Número de [camadas de subagente](/docs/pt/sub-agents#let-subagents-spawn-their-own-subagents) permitidas abaixo da conversa principal (padrão: 3). No padrão, subagentes podem gerar seus próprios subagentes, e um subagente na terceira camada não pode gerar mais; defina `1` para desativar aninhamento. Na v2.1.217 através v2.1.218, o padrão era 1, para que um subagente não pudesse gerar seu próprio a menos que você aumentasse o limite; v2.1.219 aumentou o padrão para 3. Aceita um número inteiro positivo em dígitos simples; qualquer outra coisa é ignorada, para que o limite possa ser ajustado mas não removido. Requer Claude Code v2.1.217 ou posterior |322| `CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH` | Número de [camadas de subagente](/docs/pt/sub-agents#let-subagents-spawn-their-own-subagents) permitidas abaixo da conversa principal (padrão: 3). No padrão, subagentes podem gerar seus próprios subagentes, e um subagente na terceira camada não pode gerar mais; defina `1` para desativar aninhamento. Na v2.1.217 até v2.1.218, o padrão era 1, para que um subagente não pudesse gerar o seu próprio a menos que você aumentasse o limite; v2.1.219 aumentou o padrão para 3. Aceita um número inteiro positivo em dígitos simples; qualquer outra coisa é ignorada, para que o limite possa ser ajustado mas não removido. Requer Claude Code v2.1.217 ou posterior |

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

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

324| `CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION` | Limite no número total de chamadas [WebSearch](/docs/pt/tools-reference#websearch-tool-behavior) que uma sessão pode fazer (padrão: 200). Quando Claude atinge o limite, chamadas WebSearch adicionais retornam um aviso dizendo a ele para continuar com as informações que já reuniu. Aceita um número inteiro positivo sem limite superior. Qualquer outra coisa é ignorada e o padrão se aplica, para que o limite possa ser aumentado mas não desativado. Requer Claude Code v2.1.212 ou posterior |325| `CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION` | Limite no número total de chamadas [WebSearch](/docs/pt/tools-reference#websearch-tool-behavior) que uma sessão pode fazer (padrão: 200). Quando Claude atinge o limite, chamadas WebSearch adicionais retornam um aviso dizendo a ele para continuar com as informações que já reuniu. Aceita um número inteiro positivo sem limite superior. Qualquer outra coisa é ignorada e o padrão se aplica, para que o limite possa ser aumentado mas não desativado. Requer Claude Code v2.1.212 ou posterior |

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

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

327| `CLAUDE_CODE_MCP_STARTUP_WAIT_MS` | Quanto tempo em milissegundos o primeiro turno de uma sessão [não interativa](/docs/pt/headless) aguarda servidores MCP que ainda estão se conectando, no lugar da [espera de primeiro turno](/docs/pt/agent-sdk/mcp#connection-timing) padrão. Quando definido, a espera cobre cada servidor pendente. Defina como `0` para pular a espera. Um servidor [`--permission-prompt-tool`](/docs/pt/cli-reference#cli-flags) mantém sua própria espera `MCP_TIMEOUT` independentemente do valor. Requer Claude Code v2.1.274 ou posterior |328| `CLAUDE_CODE_MCP_STARTUP_WAIT_MS` | Quanto tempo em milissegundos o primeiro turno de uma sessão [não interativa](/docs/pt/headless) aguarda servidores MCP que ainda estão se conectando, no lugar da [espera de primeiro turno](/docs/pt/agent-sdk/mcp#connection-timing) padrão. Quando definido, a espera cobre cada servidor pendente. Defina como `0` para pular a espera. Um servidor [`--permission-prompt-tool`](/docs/pt/cli-reference#cli-flags) mantém sua própria espera `MCP_TIMEOUT` independentemente do valor. Requer Claude Code v2.1.274 ou posterior |

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

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

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

331| `CLAUDE_CODE_NATIVE_CURSOR` | Defina como `1` para mostrar o cursor próprio do terminal na marca de inserção em vez de um bloco desenhado. O cursor respeita as configurações de piscar, forma e foco do terminal |332| `CLAUDE_CODE_NATIVE_CURSOR` | Defina como `1` para mostrar o cursor próprio do terminal na marca de inserção em vez de um bloco desenhado. O cursor respeita as configurações de piscar, forma e foco do terminal |

332| `CLAUDE_CODE_NEW_INIT` | Defina como `1` para fazer `/init` executar um fluxo de configuração interativo. O fluxo pergunta quais arquivos gerar, incluindo CLAUDE.md, skills e hooks, antes de explorar a base de código e escrevê-los. Sem essa variável, `/init` gera um CLAUDE.md automaticamente sem solicitar |333| `CLAUDE_CODE_NEW_INIT` | Defina como `1` para fazer `/init` executar um fluxo de configuração interativo. O fluxo pergunta quais arquivos gerar, incluindo CLAUDE.md, skills e hooks, antes de explorar a base de código e escrevê-los. Sem essa variável, `/init` gera um CLAUDE.md automaticamente sem solicitar |

333| `CLAUDE_CODE_NONBLOCKING_STDOUT` | Defina como `1` para escrever saída de terminal através de um segundo descritor de arquivo não bloqueante, para que um terminal que para de ler, como um painel tmux control-mode pausado ou uma conexão SSH travada, não possa congelar Claude Code no meio da sessão. Aplica-se em macOS, Linux e WSL quando stdout é um terminal. Requer Claude Code v2.1.261 ou posterior |334| `CLAUDE_CODE_NONBLOCKING_STDOUT` | Defina como `1` para escrever saída de terminal através de um segundo descritor de arquivo não bloqueante, para que um terminal que para de ler, como um painel de modo de controle tmux pausado ou uma conexão SSH travada, não possa congelar Claude Code no meio da sessão. Aplica-se no macOS, Linux e WSL quando stdout é um terminal. Requer Claude Code v2.1.261 ou posterior |

334| `CLAUDE_CODE_NO_FLICKER` | Defina como `1` para ativar [renderização fullscreen](/docs/pt/fullscreen), uma visualização de pesquisa que reduz cintilação e mantém memória plana em conversas longas. Substitui a configuração [`tui`](/docs/pt/settings-reference#tui); você também pode alternar com `/tui fullscreen` |335| `CLAUDE_CODE_NO_FLICKER` | Defina como `1` para ativar [renderização em tela cheia](/docs/pt/fullscreen), uma visualização de pesquisa que reduz cintilação e mantém memória plana em conversas longas. Substitui a configuração [`tui`](/docs/pt/settings-reference#tui); você também pode alternar com `/tui fullscreen` |

335| `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` | Token de atualização OAuth para autenticação Claude.ai. Quando definido, `claude auth login` troca esse token diretamente em vez de abrir um navegador. Requer `CLAUDE_CODE_OAUTH_SCOPES`. Útil para provisionar autenticação em ambientes automatizados |336| `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` | Token de atualização OAuth para autenticação Claude.ai. Quando definido, `claude auth login` troca esse token diretamente em vez de abrir um navegador. Requer `CLAUDE_CODE_OAUTH_SCOPES`. Útil para provisionar autenticação em ambientes automatizados |

336| `CLAUDE_CODE_OAUTH_SCOPES` | Escopos OAuth separados por espaço que o token de atualização foi emitido com, como `"user:profile user:inference user:sessions:claude_code"`. Obrigatório quando `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` está definido |337| `CLAUDE_CODE_OAUTH_SCOPES` | Escopos OAuth separados por espaço com os quais o token de atualização foi emitido, como `"user:profile user:inference user:sessions:claude_code"`. Obrigatório quando `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` está definido |

337| `CLAUDE_CODE_OAUTH_TOKEN` | Token de acesso OAuth para autenticação claude.ai. Alternativa a `/login` para SDK e ambientes automatizados. Tem precedência sobre credenciais armazenadas em keychain. Gere um com [`claude setup-token`](/docs/pt/authentication#generate-a-long-lived-token). A menos que você execute [`/login`](/docs/pt/authentication#authentication-precedence), Claude Code usa o token que você define para a sessão inteira. Para substituir um token expirado, gere um novo e reinicie |338| `CLAUDE_CODE_OAUTH_TOKEN` | Token de acesso OAuth para autenticação claude.ai. Alternativa a `/login` para SDK e ambientes automatizados. Tem precedência sobre credenciais armazenadas em keychain. Gere um com [`claude setup-token`](/docs/pt/authentication#generate-a-long-lived-token). A menos que você execute [`/login`](/docs/pt/authentication#authentication-precedence), Claude Code usa o token que você define para a sessão inteira. Para substituir um token expirado, gere um novo e reinicie |

338| `CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE` | Removido na v2.1.160 e agora é um no-op. Anteriormente fixava [modo rápido](/docs/pt/fast-mode) em Claude Opus 4.6 em vez do padrão atual. Opus 4.6 não suporta mais modo rápido |339| `CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE` | Removido na v2.1.160 e agora é um no-op. Anteriormente fixava [modo rápido](/docs/pt/fast-mode) em Claude Opus 4.6 em vez do padrão atual. Opus 4.6 não suporta mais modo rápido |

339| `CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` | Comprimento máximo de atributos OpenTelemetry que carregam conteúdo (respostas de modelo, conteúdo de ferramenta, prompts do sistema, corpos de API brutos), marcador de truncamento incluído, em unidades de código UTF-16 (padrão: 61440, ou seja, 60 KB). Aumente apenas se seu backend de telemetria aceita valores de atributo maiores que 64 KB, ou reduza para cortar volume de telemetria. Requer Claude Code v2.1.214 ou posterior. Veja [Monitoramento](/docs/pt/monitoring-usage) |340| `CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` | Comprimento máximo de atributos OpenTelemetry que carregam conteúdo (respostas de modelo, conteúdo de ferramenta, prompts do sistema, corpos de API brutos), marcador de truncamento incluído, em unidades de código UTF-16 (padrão: 61440, ou seja, 60 KB). Aumente apenas se seu backend de telemetria aceita valores de atributo maiores que 64 KB, ou diminua para cortar volume de telemetria. Requer Claude Code v2.1.214 ou posterior. Veja [Monitoramento](/docs/pt/monitoring-usage) |

340| `CLAUDE_CODE_OTEL_DIAG_STDERR` | Defina como `1` para escrever erros de diagnóstico do exportador OpenTelemetry para stderr. Por padrão, esses erros aparecem apenas com `--debug`, para que um exportador mal configurado como uma colisão de porta Prometheus falhe silenciosamente. Requer Claude Code v2.1.179 ou posterior. Veja [Monitoramento](/docs/pt/monitoring-usage) |341| `CLAUDE_CODE_OTEL_DIAG_STDERR` | Defina como `1` para escrever erros de diagnóstico do exportador OpenTelemetry para stderr. Por padrão, esses erros aparecem apenas com `--debug`, para que um exportador mal configurado, como uma colisão de porta Prometheus, falhe silenciosamente. Requer Claude Code v2.1.179 ou posterior. Veja [Monitoramento](/docs/pt/monitoring-usage) |

341| `CLAUDE_CODE_OTEL_FLUSH_TIMEOUT_MS` | Timeout em milissegundos para liberar spans OpenTelemetry pendentes (padrão: 5000). Veja [Monitoramento](/docs/pt/monitoring-usage) |342| `CLAUDE_CODE_OTEL_FLUSH_TIMEOUT_MS` | Timeout em milissegundos para liberar spans OpenTelemetry pendentes (padrão: 5000). Veja [Monitoramento](/docs/pt/monitoring-usage) |

342| `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` | Intervalo para atualizar cabeçalhos OpenTelemetry dinâmicos em milissegundos (padrão: 1740000 / 29 minutos). Veja [Cabeçalhos dinâmicos](/docs/pt/monitoring-usage#dynamic-headers) |343| `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` | Intervalo para atualizar cabeçalhos OpenTelemetry dinâmicos em milissegundos (padrão: 1740000 / 29 minutos). Veja [Cabeçalhos dinâmicos](/docs/pt/monitoring-usage#dynamic-headers) |

343| `CLAUDE_CODE_OTEL_SHUTDOWN_TIMEOUT_MS` | Timeout em milissegundos para o exportador OpenTelemetry terminar no desligamento (padrão: 2000). Aumente se métricas forem descartadas na saída. Veja [Monitoramento](/docs/pt/monitoring-usage) |344| `CLAUDE_CODE_OTEL_SHUTDOWN_TIMEOUT_MS` | Timeout em milissegundos para o exportador OpenTelemetry terminar no desligamento (padrão: 2000). Aumente se métricas forem descartadas na saída. Veja [Monitoramento](/docs/pt/monitoring-usage) |

344| `CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE` | Defina como `1` para permitir que Claude Code execute o comando de upgrade do seu gerenciador de pacotes em background quando uma nova versão está disponível. Aplica-se a instalações Homebrew e WinGet. Outros gerenciadores de pacotes continuam mostrando o comando de upgrade sem executá-lo. Veja [Auto-atualizações](/docs/pt/setup#auto-updates) |345| `CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE` | Defina como `1` para permitir que Claude Code execute o comando de upgrade do seu gerenciador de pacotes em segundo plano quando uma nova versão estiver disponível. Aplica-se a instalações Homebrew e WinGet. Outros gerenciadores de pacotes continuam mostrando o comando de upgrade sem executá-lo. Veja [Auto-atualizações](/docs/pt/setup#auto-updates) |

345| `CLAUDE_CODE_PERFORCE_MODE` | Defina como `1` para ativar proteção de escrita ciente de Perforce. Quando definido, Edit, Write e NotebookEdit falham com uma dica `p4 edit <file>` se o arquivo de destino não tiver o bit de escrita do proprietário, que Perforce limpa em arquivos sincronizados até `p4 edit` abri-los. Isso evita que Claude Code contorne rastreamento de mudança Perforce |346| `CLAUDE_CODE_PERFORCE_MODE` | Defina como `1` para ativar proteção de escrita ciente de Perforce. Quando definido, Edit, Write e NotebookEdit falham com uma dica `p4 edit <file>` se o arquivo de destino não tiver o bit de escrita do proprietário, que Perforce limpa em arquivos sincronizados até `p4 edit` abri-los. Isso impede que Claude Code contorne rastreamento de mudança Perforce |

346| `CLAUDE_CODE_PLUGIN_CACHE_DIR` | Substitua o diretório raiz de plugins. Apesar do nome, isso define o diretório pai, não o cache em si: marketplaces e o cache de plugin vivem em subdiretórios sob esse caminho. Padrão é `~/.claude/plugins` |347| `CLAUDE_CODE_PLUGIN_CACHE_DIR` | Substitua o diretório raiz de plugins. Apesar do nome, isso define o diretório pai, não o cache em si: marketplaces e o cache de plugin vivem em subdiretórios sob esse caminho. Padrão é `~/.claude/plugins` |

347| `CLAUDE_CODE_PLUGIN_DIRS` | Diretórios de plugin para carregar para a sessão, cada um carregado da forma que uma flag [`--plugin-dir`](/docs/pt/plugins/cli-reference#flags-that-load-a-plugin-for-one-session) carrega. Separe múltiplos caminhos com `:` em Unix ou `;` no Windows. Dê cada caminho como um caminho absoluto ou comece com `~`, porque Claude Code pula caminhos relativos. Requer Claude Code v2.1.280 ou posterior. Veja [Carregar um plugin para uma sessão](/docs/pt/plugins/create#load-a-directory-or-archive-for-one-session) |348| `CLAUDE_CODE_PLUGIN_DIRS` | Diretórios de plugin para carregar para a sessão, cada um carregado da forma que uma flag [`--plugin-dir`](/docs/pt/plugins/cli-reference#flags-that-load-a-plugin-for-one-session) carrega. Separe múltiplos caminhos com `:` no Unix ou `;` no Windows. Dê cada caminho como um caminho absoluto ou comece com `~`, porque Claude Code pula caminhos relativos. Requer Claude Code v2.1.280 ou posterior. Veja [Carregar um plugin para uma sessão](/docs/pt/plugins/create#load-a-directory-or-archive-for-one-session) |

348| `CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS` | Timeout em milissegundos para clonar ou atualizar um marketplace de plugin (padrão: 120000). Aumente esse valor para repositórios grandes ou conexões de rede lentas. Veja [Git clone expirou](/docs/pt/plugins/troubleshooting#git-clone-timed-out-after-120s) |349| `CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS` | Timeout em milissegundos para clonar ou atualizar um marketplace de plugin (padrão: 120000). Aumente esse valor para repositórios grandes ou conexões de rede lentas. Veja [Git clone expirou](/docs/pt/plugins/troubleshooting#git-clone-timed-out-after-120s) |

349| `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE` | Defina como `1` para pular a tentativa de re-clone e continuar usando o checkout de marketplace existente quando uma atualização de marketplace não consegue alcançar ou autenticar no remoto. Útil em ambientes offline ou airgapped onde re-clonar falharia da mesma forma. Veja [Atualizações de Marketplace falham em ambientes offline](/docs/pt/plugins/troubleshooting#marketplace-updates-keep-failing-offline) |350| `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE` | Defina como `1` para pular a tentativa de re-clone e continuar usando o checkout de marketplace existente quando uma atualização de marketplace não consegue alcançar ou autenticar no remoto. Útil em ambientes offline ou airgapped onde re-clonar falharia da mesma forma. Veja [Atualizações de marketplace continuam falhando offline](/docs/pt/plugins/troubleshooting#marketplace-updates-keep-failing-offline) |

350| `CLAUDE_CODE_PLUGIN_PREFER_HTTPS` | Defina como `1` para clonar fontes de atalho GitHub `owner/repo` sobre HTTPS em vez de SSH. Aplica-se a instalação e atualização de plugin, e a `/plugin marketplace add` e `update`. Útil em runners CI, containers ou qualquer ambiente sem uma chave SSH configurada para `github.com` |351| `CLAUDE_CODE_PLUGIN_PREFER_HTTPS` | Defina como `1` para clonar fontes de atalho GitHub `owner/repo` sobre HTTPS em vez de SSH. Aplica-se a instalação e atualização de plugin, e a `/plugin marketplace add` e `update`. Útil em executores CI, containers ou qualquer ambiente sem uma chave SSH configurada para `github.com` |

351| `CLAUDE_CODE_PLUGIN_SEED_DIR` | Caminho para um ou mais diretórios de seed de plugin somente leitura, separados por `:` em Unix ou `;` no Windows. Use isso para agrupar um diretório de plugins pré-populado em uma imagem de container. Claude Code registra marketplaces desses diretórios na inicialização e usa plugins pré-armazenados em cache sem re-clonar. Veja [Pré-popular plugins para containers](/docs/pt/plugins/org#seed-containers-and-ci) |352| `CLAUDE_CODE_PLUGIN_SEED_DIR` | Caminho para um ou mais diretórios de seed de plugin somente leitura, separados por `:` no Unix ou `;` no Windows. Use isso para agrupar um diretório de plugins pré-populado em uma imagem de container. Claude Code registra marketplaces desses diretórios na inicialização e usa plugins pré-armazenados em cache sem re-clonar. Veja [Pré-popular plugins para containers](/docs/pt/plugins/org#seed-containers-and-ci) |

352| `CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY` | Defina como `1` para parar Claude Code de passar `-ExecutionPolicy Bypass` ao gerar PowerShell para chamadas de ferramenta, hooks e comandos de status line, e respeitar a política de execução efetiva da máquina. Por padrão, Claude Code contorna política de execução em escopo de processo para que scripts `.ps1` e importações de módulo funcionem em instalações Windows padrão com Restricted. Bypass em escopo de processo nunca substitui `MachinePolicy` ou `UserPolicy` de Group Policy independentemente dessa configuração |353| `CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY` | Defina como `1` para impedir que Claude Code passe `-ExecutionPolicy Bypass` ao gerar PowerShell para chamadas de ferramenta, hooks e comandos de linha de status, e respeite a política de execução efetiva da máquina. Por padrão, Claude Code contorna política de execução no escopo de processo para que scripts `.ps1` e importações de módulo funcionem em instalações Windows padrão com Restricted. Bypass no escopo de processo nunca substitui Group Policy `MachinePolicy` ou `UserPolicy` independentemente dessa configuração |

353| `CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS` | Teto em milissegundos na espera ociosa por subagentes em background e workflows após o turno final em [modo não interativo](/docs/pt/headless#background-tasks-at-exit) com a flag `-p`. A espera ociosa começa novamente cada vez que Claude toma um turno para lidar com um resultado em background. Padrão: `600000`, ou 10 minutos. Quando a espera ociosa atinge o teto, Claude Code para de aguardar as tarefas em background restantes e sai. Defina como `0` para aguardar indefinidamente. Esse limite é separado do período de graça de cinco segundos que se aplica a shells em background simples. Requer Claude Code v2.1.182 ou posterior |354| `CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS` | Teto em milissegundos na espera ociosa por subagentes em segundo plano e workflows após o turno final em [modo não interativo](/docs/pt/headless#background-tasks-at-exit) com a flag `-p`. A espera ociosa recomeça cada vez que Claude toma um turno para lidar com um resultado em segundo plano. Padrão: `600000`, ou 10 minutos. Quando a espera ociosa atinge o teto, Claude Code para de aguardar as tarefas em segundo plano restantes e sai. Defina como `0` para aguardar indefinidamente. Esse limite é separado do período de graça de cinco segundos que se aplica a shells em segundo plano simples. Requer Claude Code v2.1.182 ou posterior |

354| `CLAUDE_CODE_PROCESS_WRAPPER` | Inicie os processos que Claude Code começa de seu próprio binário, como o serviço em background que hospeda sessões [agent view](/docs/pt/agent-view), através de um launcher corporativo dado como um prefixo argv como `/opt/corp/launcher`. Defina no bloco `env` de configurações de usuário ou [gerenciadas](/docs/pt/managed-settings), não como exportação de shell, para que o serviço em background desanexado o herde; configurações de projeto e local não podem defini-lo. Equivalente à configuração [`processWrapper`](/docs/pt/settings-reference#processwrapper), que requer Claude Code v2.1.210 ou posterior; essa variável tem precedência quando ambas estão definidas. A extensão VS Code configura seu próprio launcher separadamente através de sua configuração `claudeProcessWrapper`. Ignorado no Windows. Veja [Executar Claude Code atrás de um launcher corporativo](/docs/pt/corporate-launcher) para o formato de valor, o que o launcher cobre e o contrato que o launcher deve satisfazer. Requer Claude Code v2.1.208 ou posterior |355| `CLAUDE_CODE_PROCESS_WRAPPER` | Inicie os processos que Claude Code começa de seu próprio binário, como o serviço em segundo plano que hospeda sessões de [visualização de agente](/docs/pt/agent-view), através de um lançador corporativo dado como um prefixo argv como `/opt/corp/launcher`. Defina-o no bloco `env` de configurações de usuário ou [gerenciadas](/docs/pt/managed-settings), não como exportação de shell, para que o serviço em segundo plano desacoplado o herde; configurações de projeto e local não podem defini-lo. Equivalente à configuração [`processWrapper`](/docs/pt/settings-reference#processwrapper), que requer Claude Code v2.1.210 ou posterior; essa variável tem precedência quando ambas estão definidas. A extensão VS Code configura seu próprio lançador separadamente através de sua configuração `claudeProcessWrapper`. Ignorado no Windows. Veja [Executar Claude Code atrás de um lançador corporativo](/docs/pt/corporate-launcher) para o formato de valor, o que o lançador cobre e o contrato que o lançador deve satisfazer. Requer Claude Code v2.1.208 ou posterior |

355| `CLAUDE_CODE_PROJECT_DIR_NAME` | Defina junto com `CLAUDE_CONFIG_DIR` para escolher o nome do diretório `projects/` em que Claude Code armazena transcrições dessa sessão e memória automática, no lugar de um derivado do caminho do diretório de trabalho. Por exemplo, iniciar Claude Code com `CLAUDE_CONFIG_DIR=/srv/tenant-a CLAUDE_CODE_PROJECT_DIR_NAME=work claude` armazena sob `/srv/tenant-a/projects/work/`. Claude Code ignora essa variável quando `CLAUDE_CONFIG_DIR` não está definido, e a lê apenas do ambiente em que você inicia `claude`, nunca de um bloco `env` de arquivo de configurações. Veja [Nomeie o diretório de projeto você mesmo](/docs/pt/sessions#name-the-project-directory-yourself). Requer Claude Code v2.1.234 ou posterior |356| `CLAUDE_CODE_PROJECT_DIR_NAME` | Defina junto com `CLAUDE_CONFIG_DIR` para escolher o nome do diretório `projects/` que Claude Code armazena transcrições e memória automática dessa sessão, no lugar de um derivado do caminho do diretório de trabalho. Por exemplo, iniciar Claude Code com `CLAUDE_CONFIG_DIR=/srv/tenant-a CLAUDE_CODE_PROJECT_DIR_NAME=work claude` armazena sob `/srv/tenant-a/projects/work/`. Claude Code ignora essa variável quando `CLAUDE_CONFIG_DIR` não está definido, e a lê apenas do ambiente que você inicia `claude`, nunca de um bloco `env` de arquivo de configurações. Veja [Nomeie o diretório de projeto você mesmo](/docs/pt/sessions#name-the-project-directory-yourself). Requer Claude Code v2.1.234 ou posterior |

356| `CLAUDE_CODE_PROMPT_CACHE_TTL` | Defina `5m` ou `1h`, os únicos valores que Claude Code aceita, para escolher o [TTL de cache de prompt](/docs/pt/prompt-caching#cache-lifetime) para a conversa principal: seus turnos interativos, `-p` e SDK, mais os helpers que executam inline com eles. Tem precedência sobre a configuração `promptCacheTtl` e sobre `ENABLE_PROMPT_CACHING_1H`, e `FORCE_PROMPT_CACHING_5M` a substitui. A API cobra escritas de cache de 1 hora a uma taxa mais alta. Requer Claude Code v2.1.242 ou posterior |357| `CLAUDE_CODE_PROMPT_CACHE_TTL` | Defina `5m` ou `1h`, os únicos valores que Claude Code aceita, para escolher o [TTL de cache de prompt](/docs/pt/prompt-caching#cache-lifetime) para a conversa principal: seus turnos interativos, `-p` e SDK, mais os helpers que executam inline com eles. Tem precedência sobre a configuração `promptCacheTtl` e sobre `ENABLE_PROMPT_CACHING_1H`, e `FORCE_PROMPT_CACHING_5M` a substitui. Escritas de cache de 1 hora são faturadas a uma taxa mais alta. Requer Claude Code v2.1.242 ou posterior |

357| `CLAUDE_CODE_PROPAGATE_TRACEPARENT` | Defina como `1` para propagar contexto de rastreamento W3C quando `ANTHROPIC_BASE_URL` aponta para um proxy personalizado. A propagação cobre o cabeçalho `traceparent` em solicitações de modelo e MCP HTTP e a variável de ambiente `TRACEPARENT` para subprocessos Bash, PowerShell e hook. Por padrão, a propagação é ativada apenas quando conectado diretamente à API Anthropic. Adicionado na v2.1.152. Veja [Rastreamentos (beta)](/docs/pt/monitoring-usage#traces-beta) |358| `CLAUDE_CODE_PROPAGATE_TRACEPARENT` | Defina como `1` para propagar contexto de rastreamento W3C quando `ANTHROPIC_BASE_URL` aponta para um proxy personalizado. A propagação cobre o cabeçalho `traceparent` em solicitações de modelo e MCP HTTP e a variável de ambiente `TRACEPARENT` para subprocessos Bash, PowerShell e hook. Por padrão, a propagação é ativada apenas quando conectado diretamente à API Anthropic. Adicionado na v2.1.152. Veja [Rastreamentos (beta)](/docs/pt/monitoring-usage#traces-beta) |

358| `CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST` | Defina por plataformas host que incorporam Claude Code e gerenciam roteamento de provedor de modelo em seu nome. Quando definido, Claude Code ignora variáveis de seleção de provedor, endpoint e autenticação como `CLAUDE_CODE_USE_BEDROCK`, `ANTHROPIC_BASE_URL` e `ANTHROPIC_API_KEY` em arquivos de configurações, para que configurações de usuário não possam substituir o roteamento do host. Claude Code também ignora chaves de seleção de modelo como `model`, `fallbackModel` e `modelOverrides` em [configurações gerenciadas](/docs/pt/managed-settings), qualquer que seja a fonte gerenciada que as entregue, para que a configuração de modelo do host tenha precedência sobre um pin de modelo desatualizado. Claude Code também ignora variáveis de seleção de modelo como `ANTHROPIC_MODEL` e a família `ANTHROPIC_DEFAULT_*_MODEL` em um bloco `env` gerenciado; uma lista de permissão [`availableModels`](/docs/pt/model-config#restrict-model-selection) em configurações gerenciadas ainda se aplica a menos que o host forneça a sua. Claude Code também pula o opt-out de telemetria automática que de outra forma se aplica em provedores de terceiros como Amazon Bedrock, Claude Platform on AWS, Google Cloud's Agent Platform e Microsoft Foundry, para que telemetria siga o opt-out padrão `DISABLE_TELEMETRY`. Veja [Comportamentos padrão por provedor de API](/docs/pt/data-usage#default-behaviors-by-api-provider) |359| `CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST` | Defina por plataformas host que incorporam Claude Code e gerenciam roteamento de provedor de modelo em seu nome. Quando definido, Claude Code ignora variáveis de seleção de provedor, endpoint e autenticação, como `CLAUDE_CODE_USE_BEDROCK`, `ANTHROPIC_BASE_URL` e `ANTHROPIC_API_KEY` em arquivos de configurações, para que configurações de usuário não possam substituir o roteamento do host. Claude Code também ignora chaves de seleção de modelo como `model`, `fallbackModel` e `modelOverrides` em [configurações gerenciadas](/docs/pt/managed-settings), qualquer que seja a fonte gerenciada que as entregue, para que a configuração de modelo do host tenha precedência sobre um pin de modelo desatualizado. Claude Code também ignora variáveis de seleção de modelo como `ANTHROPIC_MODEL` e a família `ANTHROPIC_DEFAULT_*_MODEL` em um bloco `env` gerenciado; uma lista de permissão [`availableModels`](/docs/pt/model-config#restrict-model-selection) em configurações gerenciadas ainda se aplica a menos que o host forneça a sua. Claude Code também pula o opt-out de telemetria automática que de outra forma se aplica em provedores de terceiros como Amazon Bedrock, Claude Platform on AWS, Google Cloud's Agent Platform e Microsoft Foundry, para que a telemetria siga o opt-out padrão `DISABLE_TELEMETRY`. Veja [Comportamentos padrão por provedor de API](/docs/pt/data-usage#default-behaviors-by-api-provider) |

359| `CLAUDE_CODE_PROXY_RESOLVES_HOSTS` | Defina como `1` para permitir que o proxy execute resolução de DNS em vez do chamador. Opt-in para ambientes onde o proxy deve lidar com resolução de nome de host |360| `CLAUDE_CODE_PROXY_RESOLVES_HOSTS` | Defina como `1` para permitir que o proxy execute resolução de DNS em vez do chamador. Opt-in para ambientes onde o proxy deve lidar com resolução de nome de host |

360| `CLAUDE_CODE_REMOTE` | Defina automaticamente como `true` quando Claude Code está em execução como uma [sessão em nuvem](/docs/pt/claude-code-on-the-web). Leia isso de um hook ou script de configuração para detectar se você está em uma sessão em nuvem |361| `CLAUDE_CODE_REMOTE` | Defina automaticamente como `true` quando Claude Code está em execução como uma [sessão em nuvem](/docs/pt/claude-code-on-the-web). Leia isso de um hook ou script de configuração para detectar se você está em uma sessão em nuvem |

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

362| `CLAUDE_CODE_RESTRICTED` | Defina como `1` para iniciar a sessão em modo restrito, o mesmo que passar [`--restricted`](/docs/pt/cli-reference#cli-flags). Claude Code ignora essa variável em um bloco `env` de arquivo de configurações. Requer Claude Code v2.1.248 ou posterior |363| `CLAUDE_CODE_RESTRICTED` | Defina como `1` para iniciar a sessão em modo restrito, o mesmo que passar [`--restricted`](/docs/pt/cli-reference#cli-flags). Claude Code ignora essa variável em um bloco `env` de arquivo de configurações. Requer Claude Code v2.1.248 ou posterior |

363| `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` | Defina como `1` para retomar automaticamente se a sessão anterior terminou no meio de um turno. Usado em modo SDK para que o modelo continue sem exigir que o SDK reenvie o prompt. Para desativar isso, desconfigurar a variável ou defini-la como `0`. Antes da v2.1.221, Claude Code ignorava `0` e outros valores falsos, para que definir `0` ainda acionasse a retomada em modo não interativo e desconfigurar a variável era a única forma de desativar |364| `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` | Defina como `1` para retomar automaticamente se a sessão anterior terminou no meio do turno. Usado em modo SDK para que o modelo continue sem exigir que o SDK reenvie o prompt. Para desativar isso, desconfigurar a variável ou defini-la como `0`. Antes da v2.1.221, Claude Code ignorava `0` e outros valores falsos, para que definir `0` ainda acionasse a retomada em modo não interativo e desconfigurar a variável era a única forma de desativar |

364| `CLAUDE_CODE_RESUME_INTERRUPTED_TURN_MAX_AGE_MS` | Idade máxima em milissegundos da última mensagem de transcrição para uma sessão que terminou no meio de um turno para continuar automaticamente na retomada. Quando a última mensagem é mais antiga que esse limite, Claude Code pula a retomada automática `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` e sua mensagem de continuação `CLAUDE_CODE_RESUME_PROMPT`, e a sessão começa ociosa para que você continue explicitamente. Não definido ou `0` significa sem limite, exceto que um turno cuja última solicitação falhou com um erro de API retoma apenas enquanto esse erro tem menos de seis horas. Um valor positivo limita cada turno, incluindo aqueles; um valor negativo ou não numérico aplica um limite de uma hora. Scripts de spawn para agentes de longa duração podem definir isso para que uma reinicialização contra uma transcrição antiga não re-execute um prompt obsoleto. Claude Code define um limite de uma hora a si mesmo quando reinicia uma sessão [agent view](/docs/pt/agent-view) travada que herdou sua conversa de uma sessão interativa. Requer Claude Code v2.1.211 ou posterior |365| `CLAUDE_CODE_RESUME_INTERRUPTED_TURN_MAX_AGE_MS` | Idade máxima em milissegundos da última mensagem de transcrição para uma sessão que terminou no meio do turno para continuar automaticamente na retomada. Quando a última mensagem é mais antiga que esse limite, Claude Code pula a retomada automática `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` e sua mensagem de continuação `CLAUDE_CODE_RESUME_PROMPT`, e a sessão começa ociosa para que você continue explicitamente. Não definido ou `0` significa sem limite, exceto que um turno cuja última solicitação falhou com um erro de API retoma apenas enquanto esse erro tem menos de seis horas. Um valor positivo limita cada turno, incluindo aqueles; um valor negativo ou não numérico aplica um limite de uma hora. Scripts de geração para agentes de longa duração podem definir isso para que uma retomada contra uma transcrição antiga não re-execute um prompt obsoleto. Claude Code define um limite de uma hora a si mesmo quando reinicia uma sessão [visualização de agente](/docs/pt/agent-view) travada que herdou sua conversa de uma sessão interativa. Requer Claude Code v2.1.211 ou posterior |

365| `CLAUDE_CODE_RESUME_PROMPT` | Substitua a mensagem de continuação que Claude Code envia a Claude quando `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` continua um turno interrompido em vez de reenviar seu prompt, ou quando você retoma uma [chamada de ferramenta adiada](/docs/pt/hooks#defer-a-tool-call-for-later) com `-p`. Padrão é `Continue from where you left off.`. Uma string vazia usa o padrão |366| `CLAUDE_CODE_RESUME_PROMPT` | Substitua a mensagem de continuação que Claude Code envia a Claude quando `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` continua um turno interrompido em vez de reenviar seu prompt, ou quando você retoma uma [chamada de ferramenta adiada](/docs/pt/hooks#defer-a-tool-call-for-later) com `-p`. Padrão é `Continue from where you left off.`. Uma string vazia usa o padrão |

366| `CLAUDE_CODE_RETRY_WATCHDOG` | Defina como `1` para sessões não supervisionadas como harnesses de eval, trabalhos CI ou workers remotos. Tenta novamente erros de capacidade `429` e `529` indefinidamente em vez de falhar após tentativas `CLAUDE_CODE_MAX_RETRIES`. Claude Code falha imediatamente quando uma solicitação de velocidade padrão recebe um `429` que relata um limite de gastos ou créditos de uso esgotados, mesmo um de um [limite de gastos de gateway](/docs/pt/errors#spend-limit-reached) que reinicia em um cronograma. Antes da v2.1.239, o watchdog tentava novamente esses indefinidamente. Para solicitações de modo rápido, veja [Lidar com limites de taxa](/docs/pt/fast-mode#handle-rate-limits). O watchdog recua até 5 minutos entre tentativas, ou até o limite ser reiniciado quando a resposta carrega um tempo de reinicialização de limite de taxa, para que uma sessão que atinge um limite de uso aguarde a janela restante. Na v2.1.199 ou posterior, também aumenta a contagem de tentativa padrão para outros erros transitórios, como erros de servidor, timeouts e conexões descartadas, para 300, aproximadamente três horas de recuo, e remove o limite de 15 em `CLAUDE_CODE_MAX_RETRIES` se você definir essa variável explicitamente. Requer Claude Code v2.1.186 ou posterior |367| `CLAUDE_CODE_RETRY_WATCHDOG` | Defina como `1` para sessões não supervisionadas, como harnesses de avaliação, trabalhos CI ou workers remotos. Tenta novamente erros de capacidade `429` e `529` indefinidamente em vez de falhar após `CLAUDE_CODE_MAX_RETRIES` tentativas. Claude Code falha imediatamente quando uma solicitação de velocidade padrão recebe um `429` que relata um limite de gastos ou créditos de uso esgotados, mesmo um de um [limite de gastos de gateway](/docs/pt/errors#spend-limit-reached) que reinicia em um cronograma. Antes da v2.1.239, o watchdog tentava novamente esses indefinidamente. Para solicitações de modo rápido, veja [Lidar com limites de taxa](/docs/pt/fast-mode#handle-rate-limits). O watchdog recua até 5 minutos entre tentativas, ou até o limite ser redefinido quando a resposta carrega um tempo de redefinição de limite de taxa, para que uma sessão que atinge um limite de uso aguarde a janela restante. Na v2.1.199 ou posterior, também aumenta a contagem de tentativas padrão para outros erros transitórios, como erros de servidor, timeouts e conexões descartadas, para 300, aproximadamente três horas de recuo, e remove o limite de 15 em `CLAUDE_CODE_MAX_RETRIES` se você definir essa variável explicitamente. Requer Claude Code v2.1.186 ou posterior |

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

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

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

370| `CLAUDE_CODE_SEND_FEEDBACK` | Defina como `0` para desativar [feedback redigido por Claude](/docs/pt/tools-reference#sendfeedback-tool-behavior) para uma sessão. Defina como `1` para ativá-lo onde sua conta já tem acesso; a variável não pode conceder acesso a si mesma, e os outros switches que desativam feedback, como `DISABLE_FEEDBACK_COMMAND` e o valor `off` da configuração [`feedbackDrafts`](/docs/pt/settings-reference#feedbackdrafts), ainda se aplicam |371| `CLAUDE_CODE_SEND_FEEDBACK` | Defina como `0` para desativar [feedback redigido por Claude](/docs/pt/tools-reference#sendfeedback-tool-behavior) para uma sessão. Defina como `1` para ativá-lo onde sua conta já tem acesso; a variável não pode conceder acesso a si mesma, e os outros switches que desativam feedback, como `DISABLE_FEEDBACK_COMMAND` e o valor `off` da configuração [`feedbackDrafts`](/docs/pt/settings-reference#feedbackdrafts), ainda se aplicam |

371| `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` | Substitua o orçamento de tempo em milissegundos para hooks [SessionEnd](/docs/pt/hooks#sessionend). O valor também é o timeout para cada hook que não define seu próprio `timeout`. Aplica-se à saída de sessão, `/clear` e alternância de sessões via `/resume` interativo. Por padrão, o orçamento é 1,5 segundos, automaticamente aumentado para o `timeout` por hook mais alto configurado em arquivos de configurações, até 60 segundos. Timeouts em hooks fornecidos por plugin não aumentam o orçamento |372| `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` | Substitua o orçamento de tempo em milissegundos para hooks [SessionEnd](/docs/pt/hooks#sessionend). O valor também é o timeout para cada hook que não define seu próprio `timeout`. Aplica-se à saída de sessão, `/clear` e alternância de sessões via `/resume` interativo. Por padrão, o orçamento é 1,5 segundos, automaticamente aumentado para o `timeout` por hook mais alto configurado em arquivos de configurações, até 60 segundos. Timeouts em hooks fornecidos por plugin não aumentam o orçamento |

372| `CLAUDE_CODE_SESSION_ID` | Defina automaticamente para o ID da sessão atual em subprocessos de ferramenta Bash e PowerShell, subprocessos [comando hook](/docs/pt/hooks) e subprocessos [servidor MCP](/docs/pt/mcp) stdio. Para Bash, PowerShell e hooks, isso corresponde ao campo `session_id` na entrada JSON do hook e é atualizado em `/clear`. Um subprocesso de servidor MCP retém o ID com o qual foi gerado. Em `--resume <session-id>` recebe o ID retomado, correspondendo hooks e Bash. Em `--continue` ou `--resume` sem um ID explícito pode receber o ID de inicialização inicial. Use para correlacionar scripts e ferramentas externas com a sessão Claude Code que os iniciou |373| `CLAUDE_CODE_SESSION_ID` | Defina automaticamente para o ID da sessão atual em subprocessos de ferramenta Bash e PowerShell, subprocessos de [comando hook](/docs/pt/hooks) e subprocessos do servidor [MCP](/docs/pt/mcp) stdio. Para Bash, PowerShell e hooks, isso corresponde ao campo `session_id` na entrada JSON do hook e é atualizado em `/clear`. Um subprocesso do servidor MCP retém o ID com o qual foi gerado. Em `--resume <session-id>` recebe o ID retomado, correspondendo a hooks e Bash. Em `--continue` ou `--resume` sem um ID explícito pode receber o ID de inicialização inicial. Use para correlacionar scripts e ferramentas externas com a sessão Claude Code que os iniciou |

373| `CLAUDE_CODE_SHELL` | Defina o shell que Claude Code usa para executar comandos de ferramenta Bash. Aceita um caminho para um binário `bash` ou `zsh`, por exemplo `/opt/homebrew/bin/bash`. Outros shells como `fish` não são suportados. Se o valor não for um caminho `bash` ou `zsh` funcionando, Claude Code o ignora e volta para auto-detecção. Auto-detecção usa seu `$SHELL` quando aponta para `bash` ou `zsh`, caso contrário escolhe o primeiro `zsh` funcionando depois `bash` encontrado em seu `PATH` e locais de instalação padrão |374| `CLAUDE_CODE_SHELL` | Defina o shell que Claude Code usa para executar comandos de ferramenta Bash. Aceita um caminho para um binário `bash` ou `zsh`, por exemplo `/opt/homebrew/bin/bash`. Outros shells como `fish` não são suportados. Se o valor não for um caminho `bash` ou `zsh` funcionando, Claude Code o ignora e volta para auto-detecção. Auto-detecção usa seu `$SHELL` quando aponta para `bash` ou `zsh`, caso contrário escolhe o primeiro `zsh` funcionando e depois `bash` encontrado em seu `PATH` e locais de instalação padrão |

374| `CLAUDE_CODE_SHELL_PREFIX` | Prefixo de comando que envolve comandos de shell que Claude Code gera: chamadas de ferramenta Bash, comandos [hook](/docs/pt/hooks), comandos [status line](/docs/pt/statusline) e comandos de inicialização [servidor MCP](/docs/pt/mcp) stdio. Hooks de forma exec e PowerShell executam sem o prefixo. Útil para logging ou auditoria. Definir um caminho de executável simples como `/path/to/logger.sh` executa cada comando como `/path/to/logger.sh '<command>'`. O wrapper recebe a linha de comando como um único argumento shell-quoted em `$1`, para que o wrapper deva re-avaliar `$1` com um shell, por exemplo `exec bash -c "$1"`. Tratar `$1` como um caminho de executável simples quebra servidores MCP stdio que passam argumentos como `npx -y <package>`. Para chamadas de ferramenta Bash, `$1` contém a invocação de shell completa que Claude Code monta, incluindo configuração de ambiente, não apenas o comando que Claude executou |375| `CLAUDE_CODE_SHELL_PREFIX` | Prefixo de comando que envolve comandos de shell que Claude Code gera: chamadas de ferramenta Bash, comandos [hook](/docs/pt/hooks), comandos [linha de status](/docs/pt/statusline) e comandos de inicialização do servidor [MCP](/docs/pt/mcp) stdio. Hooks de PowerShell e hooks de forma exec executam sem o prefixo. Útil para logging ou auditoria. Definir um caminho de executável simples como `/path/to/logger.sh` executa cada comando como `/path/to/logger.sh '<command>'`. O wrapper recebe a linha de comando como um único argumento com shell-quoted em `$1`, para que o wrapper deva re-avaliar `$1` com um shell, por exemplo `exec bash -c "$1"`. Tratar `$1` como um caminho de executável simples quebra servidores MCP stdio que passam argumentos como `npx -y <package>`. Para chamadas de ferramenta Bash, `$1` contém a invocação de shell completa que Claude Code monta, incluindo configuração de ambiente, não apenas o comando que Claude executou |

375| `CLAUDE_CODE_SIMPLE` | Defina como `1` para executar com um prompt do sistema mínimo e apenas ferramentas Bash, leitura de arquivo e edição de arquivo. Ferramentas MCP de `--mcp-config` ainda estão disponíveis. Desabilita auto-descoberta de hooks, skills, comandos personalizados, subagentes, plugins instalados, servidores MCP, memória automática e CLAUDE.md. Skills em um diretório que você passa com `--add-dir` ainda carregam. Tokens OAuth e credenciais de keychain não são lidos, para que autenticação Anthropic deva vir de `ANTHROPIC_API_KEY` ou um `apiKeyHelper` em `--settings`. Equivalente a passar [`--bare`](/docs/pt/headless#start-faster-with-bare-mode) |376| `CLAUDE_CODE_SIMPLE` | Defina como `1` para executar com um prompt do sistema mínimo e apenas ferramentas Bash, leitura de arquivo e edição de arquivo. Ferramentas MCP de `--mcp-config` ainda estão disponíveis. Desabilita auto-descoberta de hooks, skills, comandos personalizados, subagentes, plugins instalados, servidores MCP, memória automática e CLAUDE.md. Skills em um diretório que você passa com `--add-dir` ainda carregam. Tokens OAuth e credenciais de keychain não são lidos, para que autenticação Anthropic deva vir de `ANTHROPIC_API_KEY` ou um `apiKeyHelper` em `--settings`. Equivalente a passar [`--bare`](/docs/pt/headless#start-faster-with-bare-mode) |

376| `CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT` | Defina como `1` para usar um prompt do sistema mais curto e descrições de ferramenta abreviadas em qualquer modelo. Defina como `0`, `false`, `no` ou `off` para desativar mesmo em modelos onde o experimento ou configuração do servidor ativaria. O conjunto completo de ferramentas, descoberta de hooks, servidores MCP e CLAUDE.md permanecem ativados |377| `CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT` | Defina como `1` para usar um prompt do sistema mais curto e descrições de ferramenta abreviadas em qualquer modelo. Defina como `0`, `false`, `no` ou `off` para desativar mesmo em modelos onde o experimento ou configuração do servidor a ativaria. O conjunto completo de ferramentas, descoberta de hooks, servidores MCP e CLAUDE.md permanecem ativados |

377| `CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH` | Pule autenticação do lado do cliente para [Claude Platform on AWS](/docs/pt/claude-platform-on-aws), para gateways que assinam solicitações a si mesmos |378| `CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH` | Pule autenticação do lado do cliente para [Claude Platform on AWS](/docs/pt/claude-platform-on-aws), para gateways que assinam solicitações a si mesmos |

378| `CLAUDE_CODE_SKIP_AWS_CRED_CACHE` | Defina como `1` para desativar o cache em processo de credenciais resolvidas da cadeia de provedor de credencial padrão AWS, para que Claude Code resolva a cadeia em cada solicitação de API. Com o cache desativado, um perfil apoiado por SSO solicita credenciais do IAM Identity Center em cada solicitação. Veja [cache de credencial e timeout de resolução](/docs/pt/amazon-bedrock#credential-caching-and-resolution-timeout). Requer Claude Code v2.1.207 ou posterior |379| `CLAUDE_CODE_SKIP_AWS_CRED_CACHE` | Defina como `1` para desativar o cache em processo de credenciais resolvidas da cadeia de provedor de credenciais padrão AWS, para que Claude Code resolva a cadeia em cada solicitação de API. Com o cache desativado, um perfil apoiado por SSO solicita credenciais do IAM Identity Center em cada solicitação. Veja [cache de credenciais e timeout de resolução](/docs/pt/amazon-bedrock#credential-caching-and-resolution-timeout). Requer Claude Code v2.1.207 ou posterior |

379| `CLAUDE_CODE_SKIP_BEDROCK_AUTH` | Pule autenticação AWS para Amazon Bedrock (por exemplo, ao usar um gateway LLM) |380| `CLAUDE_CODE_SKIP_BEDROCK_AUTH` | Pule autenticação AWS para Amazon Bedrock (por exemplo, ao usar um gateway LLM) |

380| `CLAUDE_CODE_SKIP_FAST_MODE_NETWORK_ERRORS` | Defina como `1` para tratar uma verificação de disponibilidade de [modo rápido](/docs/pt/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways) falhada como disponível, para redes que bloqueiam a solicitação direta da verificação para `api.anthropic.com`. Claude Code ainda honra uma resposta "desabilitado pela sua organização" |381| `CLAUDE_CODE_SKIP_FAST_MODE_NETWORK_ERRORS` | Defina como `1` para tratar uma verificação de disponibilidade de [modo rápido](/docs/pt/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways) falhada como disponível, para redes que bloqueiam a solicitação direta da verificação para `api.anthropic.com`. Claude Code ainda honra uma resposta "desabilitado pela sua organização" |

381| `CLAUDE_CODE_SKIP_FAST_MODE_ORG_CHECK` | Defina como `1` para pular a verificação de disponibilidade de [modo rápido](/docs/pt/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways) do lado do cliente, para proxies que interceptam a solicitação da verificação em vez de recusá-la. A API ainda rejeita solicitações de modo rápido quando sua organização tem modo rápido desabilitado |382| `CLAUDE_CODE_SKIP_FAST_MODE_ORG_CHECK` | Defina como `1` para pular a verificação de disponibilidade de [modo rápido](/docs/pt/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways) do lado do cliente, para proxies que interceptam a solicitação da verificação em vez de recusá-la. A API ainda rejeita solicitações de modo rápido quando sua organização tem modo rápido desabilitado |

382| `CLAUDE_CODE_SKIP_FOUNDRY_AUTH` | Pule autenticação Azure para Microsoft Foundry, para um proxy ou gateway que injeta seu próprio cabeçalho `Authorization`. Claude Code envia solicitações sem uma credencial Azure e preserva o cabeçalho `Authorization` que você fornece, por exemplo através de `ANTHROPIC_CUSTOM_HEADERS`. Ignorado quando `ANTHROPIC_FOUNDRY_API_KEY` ou `ANTHROPIC_FOUNDRY_AUTH_TOKEN` está definido. Antes da v2.1.203, essa variável deixava o cliente Microsoft Foundry incapaz de enviar solicitações a menos que uma chave de API também estivesse definida |383| `CLAUDE_CODE_SKIP_FOUNDRY_AUTH` | Pule autenticação Azure para Microsoft Foundry, para um proxy ou gateway que injeta seu próprio cabeçalho `Authorization`. Claude Code envia solicitações sem uma credencial Azure e preserva o cabeçalho `Authorization` que você fornece, por exemplo através de `ANTHROPIC_CUSTOM_HEADERS`. Ignorado quando `ANTHROPIC_FOUNDRY_API_KEY` ou `ANTHROPIC_FOUNDRY_AUTH_TOKEN` está definido. Antes da v2.1.203, essa variável deixava o cliente Microsoft Foundry incapaz de enviar solicitações a menos que uma chave de API também estivesse definida |

383| `CLAUDE_CODE_SKIP_MANTLE_AUTH` | Pule autenticação AWS para Amazon Bedrock Mantle (por exemplo, ao usar um gateway LLM) |384| `CLAUDE_CODE_SKIP_MANTLE_AUTH` | Pule autenticação AWS para Amazon Bedrock Mantle (por exemplo, ao usar um gateway LLM) |

385| `CLAUDE_CODE_SKIP_MODEL_ACCESS_MEMORY` | As [verificações de modelo de inicialização](/docs/pt/amazon-bedrock#startup-model-checks) em [Amazon Bedrock](/docs/pt/amazon-bedrock) e [Google Cloud's Agent Platform](/docs/pt/google-vertex-ai) lembram nesta máquina quais modelos encontraram que sua conta não pode invocar, por até um dia. Defina como `1` para desativar essa memória. Requer Claude Code v2.1.285 ou posterior |

384| `CLAUDE_CODE_SKIP_PROMPT_HISTORY` | Defina como `1` para pular escrita de histórico de prompt e transcrições de sessão em disco. Sessões iniciadas com essa variável definida não aparecem em `--resume`, `--continue` ou histórico de seta para cima. Útil para sessões de script efêmeras |386| `CLAUDE_CODE_SKIP_PROMPT_HISTORY` | Defina como `1` para pular escrita de histórico de prompt e transcrições de sessão em disco. Sessões iniciadas com essa variável definida não aparecem em `--resume`, `--continue` ou histórico de seta para cima. Útil para sessões de script efêmeras |

385| `CLAUDE_CODE_SKIP_VERTEX_AUTH` | Pule autenticação Google para Google Cloud's Agent Platform (por exemplo, ao usar um gateway LLM) |387| `CLAUDE_CODE_SKIP_VERTEX_AUTH` | Pule autenticação Google para Google Cloud's Agent Platform (por exemplo, ao usar um gateway LLM) |

386| `CLAUDE_CODE_STARTUP_FAILURE_RESULTS` | Defina como `1` para fazer uma sessão iniciada com `--output-format stream-json` escrever uma [mensagem de resultado nomeando por que Claude Code recusou iniciar](/docs/pt/agent-sdk/typescript#startup_failure_reason) para falhas de inicialização que de outra forma terminam apenas com stderr. Requer Claude Code v2.1.274 ou posterior |388| `CLAUDE_CODE_STARTUP_FAILURE_RESULTS` | Defina como `1` para fazer uma sessão iniciada com `--output-format stream-json` escrever uma [mensagem de resultado nomeando por que Claude Code recusou iniciar](/docs/pt/agent-sdk/typescript#startup_failure_reason) para falhas de inicialização que de outra forma terminam apenas com stderr. Requer Claude Code v2.1.274 ou posterior |

387| `CLAUDE_CODE_STOP_HOOK_BLOCK_CAP` | Número máximo de vezes consecutivas que um hook [Stop](/docs/pt/hooks#stop) ou [SubagentStop](/docs/pt/hooks#subagentstop) pode bloquear o turno de terminar antes de Claude Code substituí-lo e terminar o turno mesmo assim (padrão: 8). Defina como `0` para desabilitar o limite. Aumente isso se seu hook legitimamente precisa de mais iterações para resolver |389| `CLAUDE_CODE_STOP_HOOK_BLOCK_CAP` | Número máximo de vezes consecutivas que um hook [Stop](/docs/pt/hooks#stop) ou [SubagentStop](/docs/pt/hooks#subagentstop) pode bloquear o turno de terminar antes que Claude Code o substitua e termine o turno mesmo assim (padrão: 8). Defina como `0` para desabilitar o limite. Aumente isso se seu hook legitimamente precisa de mais iterações para resolver |

388| `CLAUDE_CODE_SUBAGENT_MODEL` | O modelo padrão para [subagentes](/docs/pt/sub-agents#choose-a-model), [equipe de agentes](/docs/pt/agent-teams#specify-teammates-and-models) companheiros e agentes [workflow](/docs/pt/workflows) que não são atribuídos a um modelo de outra forma. Aceita um alias como `haiku` ou um nome de modelo completo. Duas fontes têm precedência sobre ele: um modelo que Claude passa quando gera o agente, e um campo `model` na definição do agente, incluindo `inherit`. Para mudar isso, defina [`CLAUDE_CODE_SUBAGENT_MODEL_FORCE`](/docs/pt/sub-agents#run-every-subagent-on-one-model). Veja [Escolha um modelo](/docs/pt/sub-agents#choose-a-model) para a ordem completa. Defini-lo como `inherit` é o mesmo que deixá-lo não definido. Antes da v2.1.251, essa variável substituía tanto o modelo por invocação quanto o campo `model` da definição |390| `CLAUDE_CODE_SUBAGENT_MODEL` | O modelo padrão para [subagentes](/docs/pt/sub-agents#choose-a-model), [equipe de agentes](/docs/pt/agent-teams#specify-teammates-and-models) companheiros e agentes de [workflow](/docs/pt/workflows) que não são atribuídos a um modelo de outra forma. Aceita um alias como `haiku` ou um nome de modelo completo. Duas fontes têm precedência sobre ele: um modelo que Claude passa quando gera o agente, e um campo `model` na definição do agente, incluindo `inherit`. Para mudar isso, defina [`CLAUDE_CODE_SUBAGENT_MODEL_FORCE`](/docs/pt/sub-agents#run-every-subagent-on-one-model). Veja [Escolha um modelo](/docs/pt/sub-agents#choose-a-model) para a ordem completa. Defini-lo como `inherit` é o mesmo que deixá-lo não definido. Antes da v2.1.251, essa variável substituía tanto o modelo por invocação quanto o campo `model` da definição |

389| `CLAUDE_CODE_SUBAGENT_MODEL_FORCE` | Defina como `1` para forçar um modelo em subagentes, companheiros e agentes de workflow. [Executar cada subagente em um modelo](/docs/pt/sub-agents#run-every-subagent-on-one-model) diz qual modelo é. Requer Claude Code v2.1.257 ou posterior |391| `CLAUDE_CODE_SUBAGENT_MODEL_FORCE` | Defina como `1` para forçar um modelo em subagentes, companheiros e agentes de workflow. [Executar cada subagente em um modelo](/docs/pt/sub-agents#run-every-subagent-on-one-model) diz qual modelo é. Requer Claude Code v2.1.257 ou posterior |

390| `CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL` | Defina `5m` ou `1h`, os únicos valores que Claude Code aceita, para escolher o [TTL de cache de prompt](/docs/pt/prompt-caching#cache-lifetime) para solicitações fora da conversa principal, como [subagentes](/docs/pt/sub-agents), workflows e trabalho em background. Tem precedência sobre a configuração `subagentPromptCacheTtl` e sobre `ENABLE_PROMPT_CACHING_1H`, e `FORCE_PROMPT_CACHING_5M` a substitui. A API cobra escritas de cache de 1 hora a uma taxa mais alta. Requer Claude Code v2.1.242 ou posterior |392| `CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL` | Defina `5m` ou `1h`, os únicos valores que Claude Code aceita, para escolher o [TTL de cache de prompt](/docs/pt/prompt-caching#cache-lifetime) para solicitações fora da conversa principal, como [subagentes](/docs/pt/sub-agents), workflows e trabalho em segundo plano. Tem precedência sobre a configuração `subagentPromptCacheTtl` e sobre `ENABLE_PROMPT_CACHING_1H`, e `FORCE_PROMPT_CACHING_5M` a substitui. Escritas de cache de 1 hora são faturadas a uma taxa mais alta. Requer Claude Code v2.1.242 ou posterior |

391| `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` | Defina como `1` para remover credenciais de ambientes de subprocesso (ferramenta Bash, hooks, servidores MCP stdio): credenciais Anthropic e provedor de nuvem, qualquer outra variável que Claude Code reconhece como credencial e credenciais incorporadas em URLs de registro de pacotes. O processo Claude pai mantém essas credenciais para chamadas de API, mas processos filhos não podem lê-las, reduzindo exposição a ataques de injeção de prompt que tentam exfiltrar segredos via expansão de shell. Na v2.1.251 ou posterior, o scrub também remove variáveis de ponteiro de armazenamento de configuração de Claude Code (como `CLAUDE_CONFIG_DIR`), para que um processo filho não possa localizar um diretório de configuração realocado. Deixe o scrub não definido se um subprocesso precisa dessas variáveis. No Linux, isso também executa subprocessos Bash em um namespace PID isolado para que não possam ler ambientes de processo host via `/proc`; como efeito colateral, `ps`, `pgrep` e `kill` não podem ver ou sinalizar processos host. `claude-code-action` define isso automaticamente quando `allowed_non_write_users` está configurado |393| `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` | Defina como `1` para remover credenciais de ambientes de subprocesso (ferramenta Bash, hooks, servidores MCP stdio): credenciais Anthropic e provedor de nuvem, qualquer outra variável que Claude Code reconhece como credencial e credenciais incorporadas em URLs de registro de pacotes. O processo Claude pai mantém essas credenciais para chamadas de API, mas processos filhos não podem lê-las, reduzindo exposição a ataques de injeção de prompt que tentam exfiltrar segredos via expansão de shell. Na v2.1.251 ou posterior, o scrub também remove variáveis de ponteiro de armazenamento de configuração próprio de Claude Code (como `CLAUDE_CONFIG_DIR`), para que um processo filho não possa localizar um diretório de configuração realocado. Deixe o scrub não definido se um subprocesso precisa dessas variáveis. No Linux, isso também executa subprocessos Bash em um namespace PID isolado para que não possam ler ambientes de processo host via `/proc`; como efeito colateral, `ps`, `pgrep` e `kill` não podem ver ou sinalizar processos host. `claude-code-action` define isso automaticamente quando `allowed_non_write_users` está configurado |

392| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL` | Defina como `1` em modo não interativo (flag `-p`) para aguardar a conclusão da instalação de plugin antes da primeira consulta. Sem isso, plugins instalam em background e podem não estar disponíveis no primeiro turno. Combine com `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS` para limitar a espera |394| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL` | Defina como `1` em modo não interativo (a flag `-p`) para aguardar a conclusão da instalação de plugin antes da primeira consulta. Sem isso, plugins instalam em segundo plano e podem não estar disponíveis no primeiro turno. Combine com `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS` para limitar a espera |

393| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS` | Timeout em milissegundos para instalação de plugin síncrona. Quando excedido, Claude Code prossegue sem plugins e registra um erro. Sem padrão: sem essa variável, instalação síncrona aguarda até conclusão |395| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS` | Timeout em milissegundos para instalação de plugin síncrono. Quando excedido, Claude Code prossegue sem plugins e registra um erro. Sem padrão: sem essa variável, instalação síncrona aguarda até conclusão |

394| `CLAUDE_CODE_SYNC_SKILLS` | Defina como `1` em modo não interativo com a flag `-p` para fazer Claude Code baixar as skills ativadas para sua conta claude.ai nessa execução e aguardar a lista delas, até `CLAUDE_CODE_SYNC_SKILLS_WAIT_TIMEOUT_MS`, antes de executar a primeira consulta. Os downloads em si terminam em background, e Claude aguarda o download de uma skill quando a invoca. Requer autenticação claude.ai. Sessões de terminal onde você entra com sua conta claude.ai [baixam essas skills](/docs/pt/skills#where-synced-skills-load) em `~/.claude/skills/synced/` e ressincronizam aproximadamente a cada 10 minutos sem essa variável, para que a defina apenas quando uma execução `-p` precisa de suas skills atuais em sua primeira consulta. Antes da v2.1.273, sessões de terminal as baixavam apenas em uma execução `-p` com essa variável definida. O nome da pasta `synced` é [reservado para esse download](/docs/pt/skills#where-synced-skills-load). Antes da v2.1.227, as skills baixavam em `~/.claude/skills/` diretamente. Claude Code aplica [regras extras às skills baixadas](/docs/pt/skills#how-synced-skills-behave), como não executar seus comandos `!` em sua máquina |396| `CLAUDE_CODE_SYNC_SKILLS` | Defina como `1` em modo não interativo com a flag `-p` para fazer Claude Code baixar as skills ativadas para sua conta claude.ai nessa execução e aguardar a lista delas, até `CLAUDE_CODE_SYNC_SKILLS_WAIT_TIMEOUT_MS`, antes de executar a primeira consulta. Os downloads em si terminam em segundo plano, e Claude aguarda o download de uma skill quando a invoca. Requer autenticação claude.ai. Sessões de terminal onde você entra com sua conta claude.ai [baixam essas skills](/docs/pt/skills#where-synced-skills-load) em `~/.claude/skills/synced/` e ressincronizam aproximadamente a cada 10 minutos sem essa variável, para que a defina apenas quando uma execução `-p` precisa de suas skills atuais em sua primeira consulta. Antes da v2.1.273, sessões de terminal as baixavam apenas em uma execução `-p` com essa variável definida. O nome da pasta `synced` é [reservado para esse download](/docs/pt/skills#where-skills-live). Antes da v2.1.227, as skills baixavam em `~/.claude/skills/` diretamente. Claude Code aplica [regras extras às skills baixadas](/docs/pt/skills#how-synced-skills-behave), como não executar seus comandos `!` em sua máquina |

395| `CLAUDE_CODE_SYNC_SKILLS_INSTALL_TIMEOUT_MS` | Timeout em milissegundos para a ressincronização de skills que executa no meio da sessão quando um app construído no [Agent SDK](/docs/pt/agent-sdk/typescript#query-object) recarrega skills (padrão: 30000). Quando excedido, o recarregamento continua com quaisquer skills que chegaram, e os downloads restantes terminam em background |397| `CLAUDE_CODE_SYNC_SKILLS_INSTALL_TIMEOUT_MS` | Timeout em milissegundos para a ressincronização de skills que executa no meio da sessão quando um app construído no [Agent SDK](/docs/pt/agent-sdk/typescript#query-object) recarrega skills (padrão: 30000). Quando excedido, o recarregamento continua com quaisquer skills que chegaram, e os downloads restantes terminam em segundo plano |

396| `CLAUDE_CODE_SYNC_SKILLS_WAIT_TIMEOUT_MS` | Timeout em milissegundos para a primeira consulta aguardar a lista de skills inicial quando `CLAUDE_CODE_SYNC_SKILLS` está definido (padrão: 5000). Quando excedido, a primeira consulta executa com quaisquer skills que chegaram. Os downloads terminam em background de qualquer forma, e Claude aguarda o download de uma skill quando a invoca |398| `CLAUDE_CODE_SYNC_SKILLS_WAIT_TIMEOUT_MS` | Timeout em milissegundos para a primeira consulta aguardar a lista de skills inicial quando `CLAUDE_CODE_SYNC_SKILLS` está definido (padrão: 5000). Quando excedido, a primeira consulta executa com quaisquer skills que chegaram. Os downloads terminam em segundo plano de qualquer forma, e Claude aguarda o download de uma skill quando a invoca |

397| `CLAUDE_CODE_SYNTAX_HIGHLIGHT` | Defina como `false` para desabilitar destaque de sintaxe em saída de diff. Útil quando cores interferem com sua configuração de terminal. Para também desabilitar destaque em blocos de código e visualizações de arquivo, use a configuração [`syntaxHighlightingDisabled`](/docs/pt/settings-reference#syntaxhighlightingdisabled) |399| `CLAUDE_CODE_SYNTAX_HIGHLIGHT` | Defina como `false` para desabilitar destaque de sintaxe em saída de diff. Útil quando cores interferem com sua configuração de terminal. Para também desabilitar destaque em blocos de código e visualizações de arquivo, use a configuração [`syntaxHighlightingDisabled`](/docs/pt/settings-reference#syntaxhighlightingdisabled) |

398| `CLAUDE_CODE_TASK_LIST_ID` | Compartilhe uma lista de tarefas entre sessões. Defina o mesmo ID em múltiplas instâncias Claude Code para coordenar em uma lista de tarefas compartilhada, em [sessões que têm as ferramentas Task](/docs/pt/tools-reference#task-tool-availability). Veja [Lista de tarefas](/docs/pt/interactive-mode#task-list) |400| `CLAUDE_CODE_TASK_LIST_ID` | Compartilhe uma lista de tarefas entre sessões. Defina o mesmo ID em múltiplas instâncias de Claude Code para coordenar em uma lista de tarefas compartilhada, em [sessões que têm as ferramentas Task](/docs/pt/tools-reference#task-tool-availability). Veja [Lista de tarefas](/docs/pt/interactive-mode#task-list) |

399| `CLAUDE_CODE_TEAM_TEARDOWN_PARK_TIMEOUT_MS` | Substitua, em milissegundos, quanto tempo uma sessão não interativa aguarda na saída para sua [equipe de agentes](/docs/pt/agent-teams) terminar de desmontar. Aceita 1000 a 60000; um valor fora do intervalo é ignorado e o padrão de 10000 se aplica. Requer Claude Code v2.1.206 ou posterior |401| `CLAUDE_CODE_TEAM_TEARDOWN_PARK_TIMEOUT_MS` | Substitua, em milissegundos, quanto tempo uma sessão não interativa aguarda na saída para sua [equipe de agentes](/docs/pt/agent-teams) terminar de desmontar. Aceita 1000 a 60000; um valor fora do intervalo é ignorado e o padrão de 10000 se aplica. Requer Claude Code v2.1.206 ou posterior |

400| `CLAUDE_CODE_TMPDIR` | Substitua o diretório temporário usado para arquivos temporários internos. Claude Code acrescenta `/claude-{uid}/` em Unix ou `/claude/` no Windows a esse caminho. Padrão: `/tmp` em macOS, `os.tmpdir()` em Linux e Windows. Em macOS e Linux, subprocessos Bash [sandboxed](/docs/pt/sandboxing) recebem um fallback `$TMPDIR` curto sob o padrão do sistema quando sua substituição é um caminho longo, já que algumas ferramentas falham quando caminhos temporários ficam muito longos. Comandos Bash não sandboxed herdam seu `$TMPDIR` de shell quando está definido. Os próprios arquivos temporários de Claude Code sempre usam sua substituição. Defina em seu shell, configurações de usuário ou configurações gerenciadas. Ignorado em [configurações de projeto e local](/docs/pt/settings-reference#variables-claude-code-ignores-in-env) |402| `CLAUDE_CODE_TMPDIR` | Substitua o diretório temporário usado para arquivos temporários internos. Claude Code acrescenta `/claude-{uid}/` a esse caminho no Unix, ou `/claude/` no Windows. Padrão: `/tmp` no macOS, `os.tmpdir()` no Linux e Windows. No macOS e Linux, subprocessos Bash [sandboxed](/docs/pt/sandboxing) recebem um fallback `$TMPDIR` curto sob o padrão do sistema quando sua substituição é um caminho longo, já que algumas ferramentas falham quando caminhos temporários ficam muito longos. Comandos Bash não sandboxed herdam seu `$TMPDIR` de shell quando está definido. No Windows nativo, quando seu shell não define `$TMPDIR`, um comando Bash que referencia `$TMPDIR` recebe sua substituição, ou `%TEMP%` quando você não definiu uma. Os arquivos temporários próprios de Claude Code sempre usam sua substituição. Defina-o em seu shell, configurações de usuário ou configurações gerenciadas. Ignorado em [configurações de projeto e local](/docs/pt/settings-reference#variables-claude-code-ignores-in-env) |

401| `CLAUDE_CODE_TMUX_TRUECOLOR` | Defina como qualquer valor não vazio, como `1`, para permitir saída truecolor de 24 bits dentro de tmux. **Defini-lo como `0` ou `false` ainda permite truecolor**, diferentemente da maioria das variáveis on/off; desconfigurar a variável para restaurar o clamp de 256 cores. Por padrão, Claude Code limita a 256 cores quando `$TMUX` está definido porque tmux não passa sequências de escape truecolor a menos que configurado. Defina isso após adicionar `set -ga terminal-overrides ',*:Tc'` ao seu `~/.tmux.conf`. Veja [Configuração de terminal](/docs/pt/terminal-config) para outras configurações tmux |403| `CLAUDE_CODE_TMUX_TRUECOLOR` | Defina como qualquer valor não vazio, como `1`, para permitir saída truecolor de 24 bits dentro de tmux. **Defini-lo como `0` ou `false` ainda permite truecolor**, diferentemente da maioria das variáveis on/off; desconfigurar a variável para restaurar o limite de 256 cores. Por padrão, Claude Code limita a 256 cores quando `$TMUX` está definido porque tmux não passa sequências de escape truecolor a menos que configurado. Defina isso após adicionar `set -ga terminal-overrides ',*:Tc'` ao seu `~/.tmux.conf`. Veja [Configuração de terminal](/docs/pt/terminal-config) para outras configurações tmux |

402| `CLAUDE_CODE_TOOL_MEMORY_CGROUP_EXCLUDE` | Em Linux e WSL, defina como uma lista separada por vírgulas dos tipos de processos que Claude Code [exclui do limite de memória de ferramenta](/docs/pt/tools-reference#memory-limit-on-linux-and-wsl), como `mcp` ou `lsp`. Defina `none` para limitar cada tipo, ou `all-new` para limitar apenas comandos de ferramentas Bash, PowerShell e Monitor. Claude Code mantém comandos de ferramentas Bash, PowerShell e Monitor sob o limite qualquer que você liste. Requer Claude Code v2.1.246 ou posterior |404| `CLAUDE_CODE_TOOL_MEMORY_CGROUP_EXCLUDE` | No Linux e WSL, defina como uma lista separada por vírgulas dos tipos de processos que Claude Code [exclui do limite de memória da ferramenta](/docs/pt/tools-reference#memory-limit-on-linux-and-wsl), como `mcp` ou `lsp`. Defina `none` para limitar cada tipo, ou `all-new` para limitar apenas comandos de ferramentas Bash, PowerShell e Monitor. Claude Code mantém comandos de ferramentas Bash, PowerShell e Monitor sob o limite qualquer que seja o que você liste. Requer Claude Code v2.1.246 ou posterior |

403| `CLAUDE_CODE_TOOL_MEMORY_LIMIT` | Em Linux e WSL, defina como um tamanho como `4G` para [limitar a memória que comandos de ferramentas Bash e PowerShell podem usar](/docs/pt/tools-reference#memory-limit-on-linux-and-wsl), e comandos de ferramenta Monitor na v2.1.246 ou posterior. Escreva o tamanho em dígitos simples, sozinho para um número de bytes ou com um sufixo `K`, `M`, `G` ou `T`. Defina `0` ou `off` para desativar o limite. Uma vez que o primeiro processo que Claude Code inicia tenha ativado ou desativado o limite, um valor alterado tem efeito na próxima vez que você inicia `claude`. Requer Claude Code v2.1.233 ou posterior |405| `CLAUDE_CODE_TOOL_MEMORY_LIMIT` | No Linux e WSL, defina como um tamanho como `4G` para [limitar a memória que comandos de ferramenta Bash e PowerShell podem usar](/docs/pt/tools-reference#memory-limit-on-linux-and-wsl), e comandos de ferramenta Monitor na v2.1.246 ou posterior. Escreva o tamanho em dígitos simples, sozinho para um número de bytes ou com um sufixo `K`, `M`, `G` ou `T`. Defina `0` ou `off` para desativar o limite. Uma vez que o primeiro processo que Claude Code inicia tenha ativado ou desativado o limite, um valor alterado tem efeito na próxima vez que você inicia `claude`. Requer Claude Code v2.1.233 ou posterior |

404| `CLAUDE_CODE_USER_DIALOG_TIMEOUT_MS` | Prazo em milissegundos antes de Claude Code cancelar um diálogo que encaminha para um cliente remoto como um [Remote Control](/docs/pt/remote-control) ou host SDK, ou o diálogo de aprovação para uma [mensagem entre sessões retida](/docs/pt/cross-session-messaging#control-inbound-messages); prompts de permissão e perguntas `AskUserQuestion` usam seus próprios fluxos e não são governados por ele. No Claude Code v2.1.236 ou posterior, também limita o prompt de consentimento de créditos de uso [Fable](/docs/pt/model-config#fable-and-usage-credits) no meio da sessão em uma sessão que pode estar em execução sem supervisão. [Controlar mensagens de entrada](/docs/pt/cross-session-messaging#control-inbound-messages) e [sessões não interativas](/docs/pt/cross-session-messaging#non-interactive-sessions) cobrem as regras de expiração de mensagem retida completas, incluindo os casos onde o prazo não se aplica. Substitui a configuração [`dialogExpiry`](/docs/pt/settings-reference#dialogexpiry). `0` ou um valor negativo desabilita o prazo |406| `CLAUDE_CODE_USER_DIALOG_TIMEOUT_MS` | Prazo em milissegundos antes que Claude Code cancele um diálogo que encaminha para um cliente remoto, como um [Remote Control](/docs/pt/remote-control) ou host SDK, ou o diálogo de aprovação para uma [mensagem entre sessões retida](/docs/pt/cross-session-messaging#control-inbound-messages); prompts de permissão e perguntas `AskUserQuestion` usam seus próprios fluxos e não são governados por ele. No Claude Code v2.1.236 ou posterior, também limita o prompt de consentimento de créditos de uso [Fable](/docs/pt/model-config#fable-and-usage-credits) no meio da sessão em uma sessão que pode estar em execução sem supervisão. [Controlar mensagens de entrada](/docs/pt/cross-session-messaging#control-inbound-messages) e [sessões não interativas](/docs/pt/cross-session-messaging#non-interactive-sessions) cobrem as regras de expiração de mensagem retida completas, incluindo os casos onde o prazo não se aplica. Substitui a configuração [`dialogExpiry`](/docs/pt/settings-reference#dialogexpiry). `0` ou um valor negativo desabilita o prazo |

405| `CLAUDE_CODE_USE_ANTHROPIC_AWS` | Use [Claude Platform on AWS](/docs/pt/claude-platform-on-aws) |407| `CLAUDE_CODE_USE_ANTHROPIC_AWS` | Use [Claude Platform on AWS](/docs/pt/claude-platform-on-aws) |

406| `CLAUDE_CODE_USE_BEDROCK` | Use [Amazon Bedrock](/docs/pt/amazon-bedrock) |408| `CLAUDE_CODE_USE_BEDROCK` | Use [Amazon Bedrock](/docs/pt/amazon-bedrock) |

407| `CLAUDE_CODE_USE_FOUNDRY` | Use [Microsoft Foundry](/docs/pt/microsoft-foundry) |409| `CLAUDE_CODE_USE_FOUNDRY` | Use [Microsoft Foundry](/docs/pt/microsoft-foundry) |

408| `CLAUDE_CODE_USE_MANTLE` | Use o endpoint [Mantle](/docs/pt/amazon-bedrock#use-the-mantle-endpoint) Amazon Bedrock |410| `CLAUDE_CODE_USE_MANTLE` | Use o endpoint [Mantle](/docs/pt/amazon-bedrock#use-the-mantle-endpoint) do Amazon Bedrock |

409| `CLAUDE_CODE_USE_NATIVE_FILE_SEARCH` | Defina como `1` para descobrir comandos personalizados, subagentes e estilos de saída usando APIs de arquivo Node.js em vez de ripgrep. Defina isso se o binário ripgrep incluído não estiver disponível ou bloqueado em seu ambiente. Não afeta as ferramentas Grep ou busca de arquivo |411| `CLAUDE_CODE_USE_NATIVE_FILE_SEARCH` | Defina como `1` para descobrir comandos personalizados, subagentes e estilos de saída usando APIs de arquivo Node.js em vez de ripgrep. Defina isso se o binário ripgrep agrupado não estiver disponível ou bloqueado em seu ambiente. Não afeta as ferramentas Grep ou busca de arquivo |

410| `CLAUDE_CODE_USE_POWERSHELL_TOOL` | Controla a ferramenta PowerShell. No Windows sem Git Bash, a ferramenta é ativada automaticamente; defina como `0` para desabilitá-la. No Windows com Git Bash instalado, a ferramenta está ativada por padrão para contas claude.ai e Console; defina como `1` para ativá-la em sessões Amazon Bedrock, Google Cloud's Agent Platform e Microsoft Foundry, ou `0` para desativá-la. Em Linux, macOS e WSL, defina como `1` para ativá-la, o que requer `pwsh` em seu `PATH`. Quando ativada no Windows, Claude pode executar comandos PowerShell nativamente em vez de rotear através de Git Bash. Veja [Ferramenta PowerShell](/docs/pt/tools-reference#powershell-tool) |412| `CLAUDE_CODE_USE_POWERSHELL_TOOL` | Controla a ferramenta PowerShell. No Windows sem Git Bash, a ferramenta é ativada automaticamente; defina como `0` para desabilitá-la. No Windows com Git Bash instalado, a ferramenta está ativada por padrão para contas claude.ai e Console; defina como `1` para ativá-la em sessões Amazon Bedrock, Google Cloud's Agent Platform e Microsoft Foundry, ou `0` para desativá-la. No Linux, macOS e WSL, defina como `1` para ativá-la, o que requer `pwsh` em seu `PATH`. Quando ativada no Windows, Claude pode executar comandos PowerShell nativamente em vez de rotear através de Git Bash. Veja [Ferramenta PowerShell](/docs/pt/tools-reference#powershell-tool) |

411| `CLAUDE_CODE_USE_VERTEX` | Use [Google Cloud's Agent Platform](/docs/pt/google-vertex-ai) |413| `CLAUDE_CODE_USE_VERTEX` | Use [Google Cloud's Agent Platform](/docs/pt/google-vertex-ai) |

412| `CLAUDE_CODE_WEBFETCH_CACHE_TTL_MS` | Defina como o número de milissegundos que [WebFetch](/docs/pt/tools-reference#webfetch-tool-behavior) mantém cada resposta de URL buscada em cache. O padrão é `900000`, que é 15 minutos. Aceita apenas dígitos simples; `0`, um decimal ou qualquer outra grafia mantém o padrão. Claude Code lê o valor uma vez por lançamento, para que uma mudança em um bloco `env` de configurações se aplique quando você próximo inicia `claude`. Requer Claude Code v2.1.233 ou posterior |414| `CLAUDE_CODE_WEBFETCH_CACHE_TTL_MS` | Defina como o número de milissegundos que [WebFetch](/docs/pt/tools-reference#webfetch-tool-behavior) mantém a resposta de cada URL buscada em cache. O padrão é `900000`, que é 15 minutos. Aceita apenas dígitos simples; `0`, um decimal ou qualquer outra grafia mantém o padrão. Claude Code lê o valor uma vez por lançamento, para que uma mudança em um bloco `env` de configurações se aplique quando você próximo inicia `claude`. Requer Claude Code v2.1.233 ou posterior |

413| `CLAUDE_CODE_WEBFETCH_DEADLINE_MS` | Limite superior em milissegundos em quanto tempo [WebFetch](/docs/pt/tools-reference#webfetch-tool-behavior) aguarda uma página fazer download, incluindo qualquer redirecionamento que segue. Um download que não foi concluído até então falha com um erro de prazo. O padrão é `300000`, que é cinco minutos. Defina como `0` para remover o limite. Aceita apenas dígitos simples; um decimal ou qualquer outra grafia mantém o padrão. Requer Claude Code v2.1.268 ou posterior |415| `CLAUDE_CODE_WEBFETCH_DEADLINE_MS` | Limite superior em milissegundos em quanto tempo [WebFetch](/docs/pt/tools-reference#webfetch-tool-behavior) aguarda uma página para baixar, incluindo qualquer redirecionamento que segue. Um download que não foi concluído até então falha com um erro de prazo. O padrão é `300000`, que é cinco minutos. Defina como `0` para remover o limite. Aceita apenas dígitos simples; um decimal ou qualquer outra grafia mantém o padrão. Requer Claude Code v2.1.268 ou posterior |

414| `CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS` | Quantos agentes uma execução de [workflow](/docs/pt/workflows) executa de uma vez, de `1` a `256`. Por padrão, uma execução executa até 16 agentes de uma vez, menos quando Claude Code tem menos CPUs disponíveis; chamadas `agent()` enfileiradas aguardam um slot livre. A transcrição de cada agente em execução fica na memória de Claude Code, para que valores mais altos aumentem o uso de memória. Aceita apenas dígitos simples; valores fora do intervalo e outras grafias mantêm o padrão. Requer Claude Code v2.1.269 ou posterior |416| `CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS` | Quantos agentes uma execução de [workflow](/docs/pt/workflows) executa de uma vez, de `1` a `256`. Por padrão, uma execução executa até 16 agentes de uma vez, menos quando Claude Code tem menos CPUs disponíveis; chamadas `agent()` enfileiradas aguardam um slot livre. A transcrição de cada agente em execução fica na memória de Claude Code, para que valores mais altos aumentem o uso de memória. Aceita apenas dígitos simples; valores fora do intervalo e outras grafias mantêm o padrão. Requer Claude Code v2.1.269 ou posterior |

415| `CLAUDE_CODE_WORKFLOW_PREFIX_STAGGER_MS` | Limite superior em milissegundos em quanto tempo um agente [workflow](/docs/pt/workflows) aguarda a primeira resposta de um irmão de mesmo prefixo começar antes de enviar sua própria primeira solicitação. Quando um fan-out começa vários agentes que compartilham um [prefixo de cache de prompt](/docs/pt/workflows#prompt-caching-in-a-fan-out), Claude Code mantém todos exceto o primeiro agente por até esse tempo para que o resto leia o prefixo em cache em vez de cada um processá-lo sem cache. Padrão `5000`. Defina como `0` para desabilitar a espera. Quando `DISABLE_PROMPT_CACHING` está definido, agentes nunca aguardam. Requer Claude Code v2.1.229 ou posterior |417| `CLAUDE_CODE_WORKFLOW_PREFIX_STAGGER_MS` | Limite superior em milissegundos em quanto tempo um agente de [workflow](/docs/pt/workflows) aguarda a primeira resposta de um irmão com mesmo prefixo começar antes de enviar sua própria primeira solicitação. Quando um fan-out começa vários agentes que compartilham um [prefixo de cache de prompt](/docs/pt/workflows#prompt-caching-in-a-fan-out), Claude Code mantém todos exceto o primeiro agente por até esse tempo para que o resto leia o prefixo em cache em vez de cada um processá-lo sem cache. Padrão `5000`. Defina como `0` para desabilitar a espera. Quando `DISABLE_PROMPT_CACHING` está definido, agentes nunca aguardam. Requer Claude Code v2.1.229 ou posterior |

416| `CLAUDE_CONFIG_DIR` | Substitua o diretório de configuração (padrão: `~/.claude`). Todas as configurações, histórico de sessão e plugins são armazenados sob esse caminho. Para credenciais, veja [onde Claude Code armazena credenciais](/docs/pt/authentication#credential-management). Útil para executar múltiplas contas lado a lado: por exemplo, `alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude'`. Defina em seu shell, configurações de usuário ou configurações gerenciadas. Ignorado em [configurações de projeto e local](/docs/pt/settings-reference#variables-claude-code-ignores-in-env) |418| `CLAUDE_CONFIG_DIR` | Substitua o diretório de configuração (padrão: `~/.claude`). Todas as configurações, histórico de sessão e plugins são armazenados sob esse caminho. Para credenciais, veja [onde Claude Code armazena credenciais](/docs/pt/authentication#credential-management). Útil para executar múltiplas contas lado a lado: por exemplo, `alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude'`. Defina-o em seu shell, configurações de usuário ou configurações gerenciadas. Ignorado em [configurações de projeto e local](/docs/pt/settings-reference#variables-claude-code-ignores-in-env) |

417| `CLAUDE_DISABLE_ADOPT` | Defina como `1` para parar trabalho em background em voo em vez de carregá-lo quando você coloca uma sessão em background pressionando `←` ou com [`/background`](/docs/pt/agent-view#from-inside-a-session). Claude Code pede confirmação antes de colocar em background, depois para as tarefas que de outra forma seriam carregadas. Requer Claude Code v2.1.195 ou posterior |419| `CLAUDE_DISABLE_ADOPT` | Defina como `1` para parar trabalho em segundo plano em voo em vez de carregá-lo quando você coloca uma sessão em segundo plano pressionando `←` ou com [`/background`](/docs/pt/agent-view#from-inside-a-session). Claude Code pede que você confirme antes de colocar em segundo plano, então para as tarefas que de outra forma seriam carregadas. Requer Claude Code v2.1.195 ou posterior |

418| `CLAUDE_EFFORT` | Defina automaticamente em subprocessos de ferramenta Bash e comandos hook para o [nível de effort](/docs/pt/model-config#adjust-effort-level) em efeito quando o subprocesso começa: `low`, `medium`, `high`, `xhigh` ou `max`. Corresponde ao campo `effort.level` passado para [hooks](/docs/pt/hooks). Apenas definido quando o modelo atual suporta o parâmetro effort |420| `CLAUDE_EFFORT` | Defina automaticamente em subprocessos de ferramenta Bash e comandos [hook](/docs/pt/hooks) para o nível de [esforço](/docs/pt/model-config#adjust-effort-level) em vigor quando o subprocesso começa: `low`, `medium`, `high`, `xhigh` ou `max`. Corresponde ao campo `effort.level` passado para [hooks](/docs/pt/hooks). Apenas definido quando o modelo atual suporta o parâmetro effort |

419| `CLAUDE_ENABLE_BYTE_WATCHDOG` | Defina como `1` para forçar ativação do watchdog de inatividade de streaming em nível de byte, ou defina como `0` para forçar desativação. `0` também desativa o [prazo de primeiro byte](/docs/pt/network-config#streaming-idle-watchdogs) nas conexões onde esse prazo é executado. Quando não definido, o watchdog é ativado por padrão para conexões diretas de API Anthropic e [Claude Platform on AWS](/docs/pt/claude-platform-on-aws), e para respostas de streaming em conexões [gateway](/docs/pt/gateways) alcançadas através de `ANTHROPIC_BASE_URL` ou `ANTHROPIC_AWS_BASE_URL`; antes da v2.1.222, não era executado nessas conexões de gateway, para que o watchdog em nível de evento pudesse relatar um travamento lá mesmo enquanto pings keep-alive estavam chegando. Para timeouts e como os timers interagem, veja [Watchdogs de inatividade de streaming](/docs/pt/network-config#streaming-idle-watchdogs) |421| `CLAUDE_ENABLE_BYTE_WATCHDOG` | Defina como `1` para forçar ativação do watchdog de inatividade de streaming em nível de byte, ou defina como `0` para forçar desativação. `0` também desativa o [prazo de primeiro byte](/docs/pt/network-config#streaming-idle-watchdogs) nas conexões onde esse prazo é executado. Quando não definido, o watchdog é ativado por padrão para conexões diretas da API Anthropic e [Claude Platform on AWS](/docs/pt/claude-platform-on-aws), e para respostas de streaming em conexões de [gateway](/docs/pt/gateways) alcançadas através de `ANTHROPIC_BASE_URL` ou `ANTHROPIC_AWS_BASE_URL`; antes da v2.1.222, não era executado nessas conexões de gateway, para que o watchdog em nível de evento pudesse relatar um travamento lá mesmo enquanto pings keep-alive chegavam. Para timeouts e como os timers interagem, veja [Watchdogs de inatividade de streaming](/docs/pt/network-config#streaming-idle-watchdogs) |

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

421| `CLAUDE_ENABLE_STREAM_WATCHDOG` | Defina como `0` para forçar desativação do watchdog de inatividade de streaming em nível de evento, ou defina como `1` para forçar ativação. Quando não definido, o watchdog está ativado por padrão para todos os provedores. Antes da v2.1.196, o padrão não definido era controlado pelo servidor na API Anthropic direta e desativado em outros provedores. Configure o timeout com `CLAUDE_STREAM_IDLE_TIMEOUT_MS`; para os outros timers de travamento que executam junto com este, veja [Watchdogs de inatividade de streaming](/docs/pt/network-config#streaming-idle-watchdogs) |423| `CLAUDE_ENABLE_STREAM_WATCHDOG` | Defina como `0` para forçar desativação do watchdog de inatividade de streaming em nível de evento, ou defina como `1` para forçar ativação. Quando não definido, o watchdog está ativado por padrão para todos os provedores. Antes da v2.1.196, o padrão não definido era controlado pelo servidor na API Anthropic direta e desativado em outros provedores. Configure o timeout com `CLAUDE_STREAM_IDLE_TIMEOUT_MS`; para os outros timers de travamento que executam ao lado deste, veja [Watchdogs de inatividade de streaming](/docs/pt/network-config#streaming-idle-watchdogs) |

422| `CLAUDE_ENV_FILE` | Caminho para um script de shell cujo conteúdo Claude Code executa antes de cada comando Bash no mesmo processo de shell, para que exportações no arquivo sejam visíveis ao comando. Use para persistir ativação de virtualenv ou conda entre comandos. Também populado dinamicamente por hooks [SessionStart](/docs/pt/hooks#persist-environment-variables), [Setup](/docs/pt/hooks#setup), [CwdChanged](/docs/pt/hooks#cwdchanged) e [FileChanged](/docs/pt/hooks#filechanged) |424| `CLAUDE_ENV_FILE` | Caminho para um script de shell cujo conteúdo Claude Code executa antes de cada comando Bash no mesmo processo de shell, para que exports no arquivo sejam visíveis ao comando. Use para persistir ativação de virtualenv ou conda entre comandos. Também preenchido dinamicamente por hooks [SessionStart](/docs/pt/hooks#persist-environment-variables), [Setup](/docs/pt/hooks#setup), [CwdChanged](/docs/pt/hooks#cwdchanged) e [FileChanged](/docs/pt/hooks#filechanged) |

423| `CLAUDE_JOB_DIR` | Defina por Claude Code em cada [sessão em background](/docs/pt/agent-view) para o diretório `~/.claude/jobs/<id>` dessa sessão. Comandos de shell que a sessão executa o herdam. Escreva arquivos de rascunho para [`$CLAUDE_JOB_DIR/tmp`](/docs/pt/agent-view#where-state-is-stored). Chamadas `Write` e `Edit` de Claude lá não solicitam permissão, e o diretório é removido quando a sessão é excluída |425| `CLAUDE_JOB_DIR` | Defina por Claude Code em cada [sessão em segundo plano](/docs/pt/agent-view) para o diretório `~/.claude/jobs/<id>` dessa sessão. Comandos de shell que a sessão executa o herdam. Escreva arquivos de rascunho para [`$CLAUDE_JOB_DIR/tmp`](/docs/pt/agent-view#where-state-is-stored). Chamadas `Write` e `Edit` de Claude lá não solicitam permissão, e o diretório é removido quando a sessão é excluída |

424| `CLAUDE_PID` | Claude Code define isso para seu próprio ID de processo nos subprocessos que gera: comandos de ferramenta Bash e PowerShell e comandos hook. No Linux, a integração de shell da ferramenta Bash o usa para recusar um padrão `pkill` que corresponderia ao próprio processo Claude Code; veja [a referência de erro](/docs/pt/errors#pkill-pattern-matches-the-claude-code-process). Leia-o de seus próprios scripts para identificar ou sinalizar o processo Claude Code pai deliberadamente. Requer Claude Code v2.1.214 ou posterior |426| `CLAUDE_PID` | Claude Code define isso para seu próprio ID de processo nos subprocessos que gera: comandos de ferramenta Bash e PowerShell e comandos hook. No Linux, a integração de shell da ferramenta Bash o usa para recusar um padrão `pkill` que corresponderia ao próprio processo Claude Code; veja [a referência de erro](/docs/pt/errors#pkill-pattern-matches-the-claude-code-process). Leia-o de seus próprios scripts para identificar ou sinalizar o processo Claude Code pai deliberadamente. Requer Claude Code v2.1.214 ou posterior |

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

426| `CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS` | Prazo em milissegundos para o primeiro byte de resposta de uma solicitação de streaming, nas conexões onde o [prazo de primeiro byte](/docs/pt/network-config#streaming-idle-watchdogs) é executado. Para como Claude Code o limita, o tempo extra que adiciona para corpos de solicitação grandes e como escolhe o prazo quando você deixa isso não definido, veja [Sem resposta da API](/docs/pt/errors#no-response-from-api). Requer Claude Code v2.1.242 ou posterior |428| `CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS` | Prazo em milissegundos para o primeiro byte de resposta de uma solicitação de streaming, nas conexões onde o [prazo de primeiro byte](/docs/pt/network-config#streaming-idle-watchdogs) é executado. Para como Claude Code o limita, o tempo extra que adiciona para corpos de solicitação grandes e como escolhe o prazo quando você deixa isso não definido, veja [Nenhuma resposta da API](/docs/pt/errors#no-response-from-api). Requer Claude Code v2.1.242 ou posterior |

427| `CLAUDE_STREAM_IDLE_TIMEOUT_MS` | Timeout em milissegundos antes dos watchdogs de inatividade de streaming em nível de evento e byte fecharem uma conexão travada. Quando você define essa variável explicitamente, o mínimo é `300000` (5 minutos); valores mais baixos são silenciosamente limitados para absorver pausas de pensamento estendido e buffering de proxy, e o watchdog em nível de byte limita o valor a 30 minutos. `CLAUDE_BYTE_STREAM_IDLE_TIMEOUT_MS` tem precedência sobre essa variável para o watchdog em nível de byte. Para os padrões não definidos por watchdog, veja [Watchdogs de inatividade de streaming](/docs/pt/network-config#streaming-idle-watchdogs) |429| `CLAUDE_STREAM_IDLE_TIMEOUT_MS` | Timeout em milissegundos antes que os watchdogs de inatividade de streaming em nível de evento e byte fechem uma conexão travada. Quando você define essa variável explicitamente, o mínimo é `300000` (5 minutos); valores mais baixos são silenciosamente limitados para absorver pausas de pensamento estendido e buffering de proxy, e o watchdog em nível de byte limita o valor a 30 minutos. `CLAUDE_BYTE_STREAM_IDLE_TIMEOUT_MS` tem precedência sobre essa variável para o watchdog em nível de byte. Para os padrões não definidos por watchdog, veja [Watchdogs de inatividade de streaming](/docs/pt/network-config#streaming-idle-watchdogs) |

428| `CLAUDE_SUBAGENT_BG_SHELL_MAX_MS` | Removido na v2.1.260 e agora é um no-op. Anteriormente limitava quanto tempo um [comando shell em background](/docs/pt/interactive-mode#background-bash-commands) que um [subagente](/docs/pt/sub-agents) iniciou poderia executar, em milissegundos, com um padrão de 60 minutos. Veja [as regras de tempo de vida de comando em background](/docs/pt/tools-reference#background-commands) |430| `CLAUDE_SUBAGENT_BG_SHELL_MAX_MS` | Removido na v2.1.260 e agora é um no-op. Anteriormente limitava quanto tempo um [comando de shell em segundo plano](/docs/pt/interactive-mode#background-bash-commands) que um [subagente](/docs/pt/sub-agents) iniciou poderia executar, em milissegundos, com um padrão de 60 minutos. Veja [as regras de tempo de vida de comando em segundo plano](/docs/pt/tools-reference#background-commands) |

429| `DEBUG` | Defina como `1` para ativar modo de depuração, equivalente a iniciar com [`--debug`](/docs/pt/cli-reference#cli-flags). Logs de depuração são escritos em `~/.claude/debug/<session-id>.txt`, ou no caminho definido por `CLAUDE_CODE_DEBUG_LOGS_DIR`. Apenas os valores truthy `1`, `true`, `yes` e `on` ativam modo de depuração, para que padrões de namespace como `DEBUG=express:*` definidos para outras ferramentas não o acionem |431| `DEBUG` | Defina como `1` para ativar modo de depuração, equivalente a iniciar com [`--debug`](/docs/pt/cli-reference#cli-flags). Logs de depuração são escritos em `~/.claude/debug/<session-id>.txt`, ou no caminho definido por `CLAUDE_CODE_DEBUG_LOGS_DIR`. Apenas os valores truthy `1`, `true`, `yes` e `on` ativam modo de depuração, para que padrões de namespace como `DEBUG=express:*` definidos para outras ferramentas não o acionem |

430| `DISABLE_AUTOUPDATER` | Defina como `1` para desabilitar atualizações automáticas em background. `claude update` manual ainda funciona. Use `DISABLE_UPDATES` para bloquear ambos |432| `DISABLE_AUTOUPDATER` | Defina como `1` para desabilitar atualizações automáticas em segundo plano. Manual `claude update` ainda funciona. Use `DISABLE_UPDATES` para bloquear ambos |

431| `DISABLE_AUTO_COMPACT` | Defina como `1` para desabilitar compactação automática ao se aproximar do limite de contexto. O comando manual `/compact` permanece disponível. Use quando você quer controle explícito sobre quando a compactação ocorre. Substitui a configuração [`autoCompactEnabled`](/docs/pt/settings-reference#autocompactenabled) |433| `DISABLE_AUTO_COMPACT` | Defina como `1` para desabilitar compactação automática ao se aproximar do limite de contexto. O comando manual `/compact` permanece disponível. Use quando você quer controle explícito sobre quando a compactação ocorre. Substitui a configuração [`autoCompactEnabled`](/docs/pt/settings-reference#autocompactenabled) |

432| `DISABLE_COMPACT` | Defina como `1` para desabilitar toda compactação: tanto compactação automática quanto o comando manual `/compact` |434| `DISABLE_COMPACT` | Defina como `1` para desabilitar toda compactação: tanto compactação automática quanto o comando manual `/compact` |

433| `DISABLE_COST_WARNINGS` | Defina como `1` para desabilitar mensagens de aviso de custo |435| `DISABLE_COST_WARNINGS` | Defina como `1` para desabilitar mensagens de aviso de custo |

434| `DISABLE_DOCTOR_COMMAND` | Defina como `1` para ocultar a skill [`/doctor`](/docs/pt/commands#all-commands) de verificação de configuração e seu alias `/checkup`. Útil para implantações gerenciadas onde usuários não devem executar diagnósticos de configuração de uma sessão. Não afeta o comando de terminal `claude doctor`. Antes da v2.1.205, essa variável ocultava a tela de diagnósticos `/doctor` |436| `DISABLE_DOCTOR_COMMAND` | Defina como `1` para ocultar a skill [`/doctor`](/docs/pt/commands#all-commands) de verificação de configuração e seu alias `/checkup`. Útil para implantações gerenciadas onde usuários não devem executar diagnósticos de configuração de uma sessão. Não afeta o comando de terminal `claude doctor`. Antes da v2.1.205, essa variável ocultava a tela de diagnósticos `/doctor` |

435| `DISABLE_ERROR_REPORTING` | Defina como qualquer valor não vazio, como `1`, para desativar relatório de erros. **Defini-lo como `0` ou `false` ainda desativa**, diferentemente da maioria das variáveis on/off; desconfigurar a variável para ativar relatório de erros novamente |437| `DISABLE_ERROR_REPORTING` | Defina como qualquer valor não vazio, como `1`, para desativar relatório de erros. **Defini-lo como `0` ou `false` ainda desativa**, diferentemente da maioria das variáveis on/off; desconfigurar a variável para ativar relatório de erros novamente |

436| `DISABLE_EXTRA_USAGE_COMMAND` | Defina como `1` para ocultar o comando `/usage-credits` que permite aos usuários comprar uso adicional além de limites de taxa |438| `DISABLE_EXTRA_USAGE_COMMAND` | Defina como `1` para ocultar o comando `/usage-credits` que permite aos usuários comprar uso adicional além de limites de taxa |

437| `DISABLE_FEEDBACK_COMMAND` | Defina como `1` para desabilitar o comando `/feedback` e [feedback redigido por Claude](/docs/pt/tools-reference#sendfeedback-tool-behavior). Também desabilita `/bug` e `/share`, que relatam através do mesmo caminho; antes da v2.1.212 eram aliases de `/feedback`, para que o comando fosse desabilitado sob cada nome. O nome mais antigo `DISABLE_BUG_COMMAND` também é aceito |439| `DISABLE_FEEDBACK_COMMAND` | Defina como `1` para desabilitar o comando `/feedback` e [feedback redigido por Claude](/docs/pt/tools-reference#sendfeedback-tool-behavior). Também desabilita `/bug` e `/share`, que relatam através do mesmo caminho; antes da v2.1.212, eram aliases de `/feedback`, para que o comando fosse desabilitado sob cada nome. O nome mais antigo `DISABLE_BUG_COMMAND` também é aceito |

438| `DISABLE_GROWTHBOOK` | Defina como `1` ou `true` para desabilitar busca de sinalizador de recurso GrowthBook e usar padrões de código para cada sinalizador. Isso torna [Remote Control](/docs/pt/remote-control#requirements) e os outros [recursos que precisam de busca de sinalizador de recurso](#features-that-need-feature-flag-fetching) indisponíveis. Defini-lo como `0` ou `false` deixa a busca ativada. Logging de evento de telemetria permanece ativado a menos que `DISABLE_TELEMETRY` também esteja definido |440| `DISABLE_GROWTHBOOK` | Defina como `1` ou `true` para desabilitar busca de sinalizador de recurso GrowthBook e usar padrões de código para cada sinalizador. Isso torna [Remote Control](/docs/pt/remote-control#requirements) e os outros [recursos que precisam de busca de sinalizador de recurso](#features-that-need-feature-flag-fetching) indisponíveis. Defini-lo como `0` ou `false` deixa a busca ativada. Logging de evento de telemetria permanece ativado a menos que `DISABLE_TELEMETRY` também esteja definido |

439| `DISABLE_INSTALLATION_CHECKS` | Defina como `1` para desabilitar avisos de instalação. Use apenas ao gerenciar manualmente o local de instalação, pois isso pode mascarar problemas com instalações padrão |441| `DISABLE_INSTALLATION_CHECKS` | Defina como `1` para desabilitar avisos de instalação. Use apenas ao gerenciar manualmente o local de instalação, pois isso pode mascarar problemas com instalações padrão |

440| `DISABLE_INSTALL_GITHUB_APP_COMMAND` | Defina como `1` para ocultar o comando `/install-github-app`. Já oculto ao usar provedores de terceiros (Amazon Bedrock, Google Cloud's Agent Platform ou Microsoft Foundry) |442| `DISABLE_INSTALL_GITHUB_APP_COMMAND` | Defina como `1` para ocultar o comando `/install-github-app`. Já oculto ao usar provedores de terceiros (Amazon Bedrock, Google Cloud's Agent Platform ou Microsoft Foundry) |

441| `DISABLE_INTERLEAVED_THINKING` | Defina como `1` para evitar enviar o cabeçalho beta de pensamento intercalado. Útil quando seu gateway LLM ou provedor não suporta [pensamento intercalado](https://platform.claude.com/docs/en/build-with-claude/extended-thinking#interleaved-thinking) |443| `DISABLE_INTERLEAVED_THINKING` | Defina como `1` para evitar enviar o cabeçalho beta de pensamento intercalado. Útil quando seu gateway LLM ou provedor não suporta [pensamento intercalado](https://platform.claude.com/docs/en/build-with-claude/extended-thinking#interleaved-thinking) |

442| `DISABLE_LOGIN_COMMAND` | Defina como `1` para ocultar o comando `/login`. Útil quando autenticação é tratada externamente via chaves de API ou `apiKeyHelper` |444| `DISABLE_LOGIN_COMMAND` | Defina como `1` para ocultar o comando `/login`. Útil quando a autenticação é tratada externamente via chaves de API ou `apiKeyHelper` |

443| `DISABLE_LOGOUT_COMMAND` | Defina como `1` para ocultar o comando `/logout` |445| `DISABLE_LOGOUT_COMMAND` | Defina como `1` para ocultar o comando `/logout` |

444| `DISABLE_PROMPT_CACHING` | Defina como `1` para desabilitar [cache de prompt](/docs/pt/prompt-caching#disable-prompt-caching) para todos os modelos (tem precedência sobre configurações por modelo) |446| `DISABLE_PROMPT_CACHING` | Defina como `1` para desabilitar [cache de prompt](/docs/pt/prompt-caching#disable-prompt-caching) para todos os modelos (tem precedência sobre configurações por modelo) |

445| `DISABLE_PROMPT_CACHING_FABLE` | Defina como `1` para desabilitar cache de prompt para modelos Fable |447| `DISABLE_PROMPT_CACHING_FABLE` | Defina como `1` para desabilitar cache de prompt para modelos Fable |

446| `DISABLE_PROMPT_CACHING_HAIKU` | Defina como `1` para desabilitar cache de prompt para modelos Haiku |448| `DISABLE_PROMPT_CACHING_HAIKU` | Defina como `1` para desabilitar cache de prompt para o [modelo Haiku padrão](/docs/pt/prompt-caching#disable-prompt-caching), onde quer que seja executado |

447| `DISABLE_PROMPT_CACHING_OPUS` | Defina como `1` para desabilitar cache de prompt para modelos Opus |449| `DISABLE_PROMPT_CACHING_OPUS` | Defina como `1` para desabilitar cache de prompt para o [modelo Opus padrão](/docs/pt/prompt-caching#disable-prompt-caching) |

448| `DISABLE_PROMPT_CACHING_SONNET` | Defina como `1` para desabilitar cache de prompt para modelos Sonnet |450| `DISABLE_PROMPT_CACHING_SONNET` | Defina como `1` para desabilitar cache de prompt para o [modelo Sonnet padrão](/docs/pt/prompt-caching#disable-prompt-caching) |

449| `DISABLE_TELEMETRY` | Defina como qualquer valor não vazio, como `1`, para desativar telemetria. **Defini-lo como `0` ou `false` ainda desativa**, diferentemente da maioria das variáveis on/off; desconfigurar a variável para ativar telemetria novamente. Eventos de telemetria não incluem dados de usuário como código, caminhos de arquivo ou comandos bash. Também desabilita busca de sinalizador de recurso com o mesmo efeito que `DISABLE_GROWTHBOOK`, o que torna [Remote Control](/docs/pt/remote-control#requirements) e os outros [recursos que precisam de busca de sinalizador de recurso](#features-that-need-feature-flag-fetching) indisponíveis. Veja [Desativar telemetria para sua organização](/docs/pt/managed-settings#turn-telemetry-off-for-your-organization) |451| `DISABLE_TELEMETRY` | Defina como qualquer valor não vazio, como `1`, para desativar telemetria. **Defini-lo como `0` ou `false` ainda desativa**, diferentemente da maioria das variáveis on/off; desconfigurar a variável para ativar telemetria novamente. Eventos de telemetria não incluem dados de usuário como código, caminhos de arquivo ou comandos Bash. Também desabilita [busca de sinalizador de recurso](#features-that-need-feature-flag-fetching). Veja [Desativar telemetria para sua organização](/docs/pt/managed-settings#turn-telemetry-off-for-your-organization) |

450| `DISABLE_UPDATES` | Defina como `1` para bloquear todas as atualizações, incluindo `claude update` manual e `claude install`. Mais rigoroso que `DISABLE_AUTOUPDATER`. Use ao distribuir Claude Code através de seus próprios canais e usuários não devem auto-atualizar |452| `DISABLE_UPDATES` | Defina como `1` para bloquear todas as atualizações, incluindo manual `claude update` e `claude install`. Mais rigoroso que `DISABLE_AUTOUPDATER`. Use ao distribuir Claude Code através de seus próprios canais e usuários não devem auto-atualizar |

451| `DISABLE_UPGRADE_COMMAND` | Defina como `1` para ocultar o comando `/upgrade` |453| `DISABLE_UPGRADE_COMMAND` | Defina como `1` para ocultar o comando `/upgrade` |

452| `DO_NOT_TRACK` | Defina como `1` para desativar telemetria, com o mesmo efeito que `DISABLE_TELEMETRY`, incluindo tornar [Remote Control](/docs/pt/remote-control#requirements) e os outros [recursos que precisam de busca de sinalizador de recurso](#features-that-need-feature-flag-fetching) indisponíveis. Claude Code lê essa variável como um booleano padrão, para que `0` deixe telemetria ativada e a honre como a convenção entre ferramentas reconhecida por muitos CLIs de desenvolvedor |454| `DO_NOT_TRACK` | Defina como `1` para desativar telemetria, com o mesmo efeito que `DISABLE_TELEMETRY`, incluindo em [busca de sinalizador de recurso](#features-that-need-feature-flag-fetching). Claude Code lê essa variável como um booleano padrão, para que `0` deixe telemetria ativada e a honre como a convenção entre ferramentas reconhecida por muitos CLIs de desenvolvedor |

453| `ENABLE_BETA_TRACING_DETAILED` | Defina como `1`, junto com `BETA_TRACING_ENDPOINT`, para ativar [rastreamento beta detalhado](/docs/pt/monitoring-usage#traces-beta), que adiciona atributos de span que carregam conteúdo e o span `claude_code.hook`. Sessões CLI interativas também requerem que sua organização seja adicionada à lista de permissão para o beta. Ambas as variáveis são ignoradas em [configurações de projeto e local](/docs/pt/settings-reference#variables-claude-code-ignores-in-env) |455| `ENABLE_BETA_TRACING_DETAILED` | Defina como `1`, junto com `BETA_TRACING_ENDPOINT`, para ativar [rastreamento beta detalhado](/docs/pt/monitoring-usage#traces-beta), que adiciona atributos de span que carregam conteúdo e o span `claude_code.hook`. Sessões CLI interativas também requerem que sua organização esteja na lista de permissão para o beta. Ambas as variáveis são ignoradas em [configurações de projeto e local](/docs/pt/settings-reference#variables-claude-code-ignores-in-env) |

454| `ENABLE_CLAUDEAI_MCP_SERVERS` | Defina como `false` para parar Claude Code de buscar [servidores MCP claude.ai](/docs/pt/mcp#use-mcp-servers-from-claude-ai). Ativado por padrão para usuários conectados. Para desabilitar por projeto ou por org, defina [`disableClaudeAiConnectors`](/docs/pt/settings-reference#disableclaudeaiconnectors) em configurações |456| `ENABLE_CLAUDEAI_MCP_SERVERS` | Defina como `false` para impedir que Claude Code busque [servidores MCP claude.ai](/docs/pt/mcp#use-mcp-servers-from-claude-ai). Ativado por padrão para usuários conectados. Para desabilitar por projeto ou por org, defina [`disableClaudeAiConnectors`](/docs/pt/settings-reference#disableclaudeaiconnectors) em configurações |

455| `ENABLE_PROMPT_CACHING_1H` | Defina como `1` para solicitar um [TTL de cache de prompt](/docs/pt/prompt-caching#cache-lifetime) de 1 hora em vez do padrão de 5 minutos. Destinado a usuários de chave de API, [Amazon Bedrock](/docs/pt/amazon-bedrock), [Google Cloud's Agent Platform](/docs/pt/google-vertex-ai), [Microsoft Foundry](/docs/pt/microsoft-foundry) e [Claude Platform on AWS](/docs/pt/claude-platform-on-aws). Usuários de assinatura dentro do uso incluído recebem o TTL de 1 hora automaticamente na [conversa principal](/docs/pt/prompt-caching#which-ttl-each-request-gets). Usuários de assinatura sacando [créditos de uso](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) podem defini-lo para manter o TTL de 1 hora. Escritas de cache de 1 hora são cobradas a uma taxa mais alta. Para escolher o TTL por bucket de solicitação, use `CLAUDE_CODE_PROMPT_CACHE_TTL` e `CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL`, que têm precedência sobre essa variável |457| `ENABLE_PROMPT_CACHING_1H` | Defina como `1` para solicitar um [TTL de cache de prompt](/docs/pt/prompt-caching#cache-lifetime) de 1 hora em vez do padrão de 5 minutos. Destinado a usuários de chave de API, [Amazon Bedrock](/docs/pt/amazon-bedrock), [Google Cloud's Agent Platform](/docs/pt/google-vertex-ai), [Microsoft Foundry](/docs/pt/microsoft-foundry) e [Claude Platform on AWS](/docs/pt/claude-platform-on-aws). Usuários de assinatura dentro do uso incluído recebem o TTL de 1 hora automaticamente na [conversa principal](/docs/pt/prompt-caching#which-ttl-each-request-gets). Usuários de assinatura sacando [créditos de uso](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) podem defini-lo para manter o TTL de 1 hora. Escritas de cache de 1 hora são faturadas a uma taxa mais alta. Para escolher o TTL por bucket de solicitação, use `CLAUDE_CODE_PROMPT_CACHE_TTL` e `CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL`, que têm precedência sobre essa variável |

456| `ENABLE_PROMPT_CACHING_1H_BEDROCK` | Deprecated. Use `ENABLE_PROMPT_CACHING_1H` |458| `ENABLE_PROMPT_CACHING_1H_BEDROCK` | Descontinuado. Use `ENABLE_PROMPT_CACHING_1H` |

457| `ENABLE_TOOL_SEARCH` | Controla [busca de ferramentas MCP](/docs/pt/mcp#scale-with-mcp-tool-search). Não definido, Claude Code adia todas as ferramentas MCP por padrão. Ainda as carrega antecipadamente em modelos Google Cloud's Agent Platform anteriores à geração Claude 4.5, em uma implantação Microsoft Foundry hospedada no Azure e quando `ANTHROPIC_BASE_URL` aponta para um host que não é de primeira parte. `true` sempre adia e envia o cabeçalho beta, exceto nesses mesmos modelos Agent Platform e implantações Microsoft Foundry; solicitações falham em proxies que não suportam `tool_reference`. `auto` carrega antecipadamente quando definições de ferramenta cabem em 10% de contexto. `auto:N` define um limite personalizado, como `auto:5` para 5%. `false` carrega todas as ferramentas antecipadamente. Um valor que você define a si mesmo é ignorado quando `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` está definido. Antes da v2.1.221, Claude Code desabilitava busca de ferramentas para todos os modelos em Google Cloud's Agent Platform a menos que você definisse essa variável como `true` |459| `ENABLE_TOOL_SEARCH` | Controla [busca de ferramentas MCP](/docs/pt/mcp#scale-with-mcp-tool-search). Não definido, Claude Code adia todas as ferramentas MCP por padrão. Ainda as carrega antecipadamente em modelos Google Cloud's Agent Platform anteriores à geração Claude 4.5, em uma implantação Microsoft Foundry hospedada no Azure e quando `ANTHROPIC_BASE_URL` aponta para um host que não é de primeira parte. `true` sempre adia e envia o cabeçalho beta, exceto nesses mesmos modelos Agent Platform e implantação Microsoft Foundry; solicitações falham em proxies que não suportam `tool_reference`. `auto` carrega antecipadamente quando definições de ferramenta cabem em 10% de contexto. `auto:N` define um limite personalizado, como `auto:5` para 5%. `false` carrega todas as ferramentas antecipadamente. Um valor que você define a si mesmo é ignorado quando `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` está definido. Antes da v2.1.221, Claude Code desabilitava busca de ferramentas para todos os modelos em Google Cloud's Agent Platform a menos que você definisse essa variável como `true` |

458| `FALLBACK_FOR_ALL_PRIMARY_MODELS` | Defina como qualquer valor não vazio, como `1`, para fazer Claude Code parar de tentar novamente em erros de sobrecarga repetidos para cada modelo quando nenhum modelo de fallback está configurado. **Defini-lo como `0` ou `false` ainda ativa isso**, diferentemente da maioria das variáveis on/off; desconfigurar a variável para restaurar o comportamento de retry padrão. Sem isso, Claude Code para de tentar novamente dessa forma em modelos que reconhece como Opus, Fable ou Mythos quando você autentica com uma chave de API ou um [provedor de terceiros](/docs/pt/third-party-integrations) em vez de uma assinatura Claude. No Claude Code v2.1.160 ou posterior, Claude Code muda para sua [cadeia de modelo de fallback](/docs/pt/model-config#fallback-model-chains) configurada em erros de sobrecarga repetidos para qualquer modelo primário, para que essa variável não afete a mudança para um modelo de fallback |460| `FALLBACK_FOR_ALL_PRIMARY_MODELS` | Defina como qualquer valor não vazio, como `1`, para fazer Claude Code parar de tentar novamente em erros de sobrecarga repetidos para cada modelo quando nenhum modelo fallback está configurado. **Defini-lo como `0` ou `false` ainda ativa isso**, diferentemente da maioria das variáveis on/off; desconfigurar a variável para restaurar o comportamento de tentativa padrão. Sem isso, Claude Code para de tentar dessa forma em modelos que reconhece como Opus, Fable ou Mythos quando você autentica com uma chave de API ou um [provedor de terceiros](/docs/pt/third-party-integrations) em vez de uma assinatura Claude. No Claude Code v2.1.160 ou posterior, Claude Code muda para sua [cadeia de modelo fallback](/docs/pt/model-config#fallback-model-chains) configurada em erros de sobrecarga repetidos para qualquer modelo primário, para que essa variável não afete a mudança para um modelo fallback |

459| `FORCE_AUTOUPDATE_PLUGINS` | Defina como `1` para forçar auto-atualizações de plugin mesmo quando o auto-atualizador principal é desabilitado via `DISABLE_AUTOUPDATER` |461| `FORCE_AUTOUPDATE_PLUGINS` | Defina como `1` para forçar auto-atualizações de plugin mesmo quando o auto-atualizador principal está desabilitado via `DISABLE_AUTOUPDATER` |

460| `FORCE_HYPERLINK` | Defina como `1` para ativar hiperlinks OSC 8 clicáveis quando seu terminal os suporta mas não é auto-detectado, ou `0` para desabilitá-los. Quando não definido, Claude Code ativa hiperlinks apenas quando detecta suporte de terminal. Claude Code analisa esse valor como um número, não um Booleano, para que um valor como `false`, `no` ou `off` ative hiperlinks em vez de desabilitá-los. O [badge](/docs/pt/interactive-mode#pr-review-status) de solicitação de pull ou merge request do rodapé é renderizado como um hiperlink mesmo quando Claude Code não consegue detectar suporte de terminal, como sobre SSH. Defina `0` para renderizar o badge como texto simples |462| `FORCE_HYPERLINK` | Defina como `1` para ativar hiperlinks OSC 8 clicáveis quando seu terminal os suporta mas não é auto-detectado, ou `0` para desabilitá-los. Quando não definido, Claude Code ativa hiperlinks apenas quando detecta suporte de terminal. Claude Code analisa esse valor como um número, não um Booleano, para que um valor como `false`, `no` ou `off` ative hiperlinks em vez de desabilitá-los. O [badge de PR ou merge request](/docs/pt/interactive-mode#pr-review-status) do rodapé é renderizado como um hiperlink mesmo quando Claude Code não consegue detectar suporte de terminal, como sobre SSH. Defina `0` para renderizar o badge como texto simples |

461| `FORCE_PROMPT_CACHING_5M` | Defina como `1` para forçar o TTL de cache de prompt de 5 minutos mesmo quando TTL de 1 hora se aplicaria de outra forma. Substitui `CLAUDE_CODE_PROMPT_CACHE_TTL`, `CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL`, `ENABLE_PROMPT_CACHING_1H` e as configurações `promptCacheTtl` e `subagentPromptCacheTtl` |463| `FORCE_PROMPT_CACHING_5M` | Defina como `1` para forçar o TTL de cache de prompt de 5 minutos mesmo quando TTL de 1 hora se aplicaria. Substitui `CLAUDE_CODE_PROMPT_CACHE_TTL`, `CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL`, `ENABLE_PROMPT_CACHING_1H` e as configurações `promptCacheTtl` e `subagentPromptCacheTtl` |

462| `HTTP_PROXY` | Especifique servidor proxy HTTP para conexões de rede |464| `HTTP_PROXY` | Especifique servidor proxy HTTP para conexões de rede |

463| `HTTPS_PROXY` | Especifique servidor proxy HTTPS para conexões de rede |465| `HTTPS_PROXY` | Especifique servidor proxy HTTPS para conexões de rede |

464| `IS_DEMO` | Defina como qualquer valor não vazio, como `1`, para ativar modo demo: oculta seu email e nome da organização do cabeçalho e saída `/status`, e pula onboarding. **Defini-lo como `0` ou `false` ainda ativa modo demo**, diferentemente da maioria das variáveis on/off; desconfigurar a variável para desativá-lo. Útil ao fazer stream ou gravar uma sessão |466| `IS_DEMO` | Defina como qualquer valor não vazio, como `1`, para ativar modo demo: oculta seu email e nome da organização do cabeçalho e saída `/status`, e pula onboarding. **Defini-lo como `0` ou `false` ainda ativa modo demo**, diferentemente da maioria das variáveis on/off; desconfigurar a variável para desativá-lo. Útil ao fazer streaming ou gravar uma sessão |

465| `MAX_MCP_OUTPUT_TOKENS` | Número máximo de tokens permitidos em respostas de ferramenta MCP. Claude Code exibe um aviso quando a saída excede 10.000 tokens. Ferramentas que declaram [`anthropic/maxResultSizeChars`](/docs/pt/mcp#raise-the-limit-for-a-specific-tool) usam esse limite de caracteres para conteúdo de texto, mas conteúdo de imagem dessas ferramentas ainda está sujeito a essa variável (padrão: 25000) |467| `MAX_MCP_OUTPUT_TOKENS` | Número máximo de tokens permitidos em respostas de ferramenta MCP. Claude Code exibe um aviso quando a saída excede 10.000 tokens. Ferramentas que declaram [`anthropic/maxResultSizeChars`](/docs/pt/mcp#raise-the-limit-for-a-specific-tool) usam esse limite de caracteres para conteúdo de texto, mas conteúdo de imagem dessas ferramentas ainda está sujeito a essa variável (padrão: 25000) |

466| `MAX_STRUCTURED_OUTPUT_RETRIES` | Número de tentativas que Claude Code permite quando a resposta do modelo falha na validação contra o [`--json-schema`](/docs/pt/cli-reference#cli-flags) em modo não interativo com a flag `-p`; após esse muitas tentativas falhadas sem saída válida, a execução falha. O mesmo limite se aplica quando a saída estruturada de um [subagente](/docs/pt/sub-agents) de [workflow](/docs/pt/workflows) falha na validação. Padrão 5, uma primeira tentativa mais quatro retentativas |468| `MAX_STRUCTURED_OUTPUT_RETRIES` | Número de tentativas que Claude Code permite quando a resposta do modelo falha na validação contra o [`--json-schema`](/docs/pt/cli-reference#cli-flags) em modo não interativo com a flag `-p`; após esse muitas tentativas falhadas sem saída válida, a execução falha. O mesmo limite se aplica quando a saída estruturada de um subagente de [workflow](/docs/pt/workflows) falha na validação. Padrão de 5, uma primeira tentativa mais quatro tentativas |

467| `MAX_THINKING_TOKENS` | Orçamento de token fixo para [pensamento estendido](https://platform.claude.com/docs/en/build-with-claude/extended-thinking). Claude Code o limita a um token abaixo dos tokens de saída máximos da solicitação e nunca abaixo de 1.024. Veja `CLAUDE_CODE_MAX_OUTPUT_TOKENS` para como esse limite é definido. Quando não definido e pensamento está ativado, modelos com [raciocínio adaptativo](/docs/pt/model-config#adjust-effort-level) escolhem sua própria profundidade de pensamento, e outros modelos usam o limite. Defina como `0` para desabilitar pensamento na API Anthropic, exceto em Opus 5.5, Sonnet 5.5 e modelos Fable, que não podem ter pensamento desativado. Em [provedores de terceiros](/docs/pt/third-party-integrations), `0` omite o parâmetro `thinking`. Com pensamento desativado na API Anthropic, Claude Code envia effort `high` em vez de um nível mais alto para modelos que sabe [não aceitam essa combinação](/docs/pt/errors#effort-isnt-available-with-thinking-turned-off), como Opus 5. Claude Code ignora valores não zero em modelos de raciocínio adaptativo, exceto nos modelos onde `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` desativa raciocínio adaptativo |469| `MAX_THINKING_TOKENS` | Orçamento de token fixo para [pensamento estendido](https://platform.claude.com/docs/en/build-with-claude/extended-thinking). Claude Code o limita a um token abaixo dos tokens de saída máxima da solicitação e nunca abaixo de 1.024. Veja `CLAUDE_CODE_MAX_OUTPUT_TOKENS` para como esse limite é definido. Quando não definido e pensamento está ativado, modelos com [raciocínio adaptativo](/docs/pt/model-config#adjust-effort-level) escolhem sua própria profundidade de pensamento, e outros modelos usam o limite. Defina como `0` para desabilitar pensamento na API Anthropic, exceto em Opus 5.5, Sonnet 5.5 e os modelos Fable, que não podem ter pensamento desativado. Em [provedores de terceiros](/docs/pt/third-party-integrations), `0` omite o parâmetro `thinking`. Com pensamento desativado na API Anthropic, Claude Code envia esforço `high` em vez de um nível mais alto para modelos que sabe [não aceitam essa combinação](/docs/pt/errors#effort-isnt-available-with-thinking-turned-off), como Opus 5. Claude Code ignora valores não zero em modelos de raciocínio adaptativo, exceto nos modelos onde `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` desativa raciocínio adaptativo |

468| `MCP_CLIENT_SECRET` | Segredo de cliente OAuth para servidores MCP que requerem [credenciais pré-configuradas](/docs/pt/mcp#use-pre-configured-oauth-credentials). Evita o prompt interativo ao adicionar um servidor com `--client-secret` |470| `MCP_CLIENT_SECRET` | Segredo de cliente OAuth para servidores MCP que requerem [credenciais pré-configuradas](/docs/pt/mcp#use-pre-configured-oauth-credentials). Evita o prompt interativo ao adicionar um servidor com `--client-secret` |

469| `MCP_CONNECTION_NONBLOCKING` | Controla se a inicialização aguarda servidores MCP se conectarem antes da primeira consulta. Inicialização MCP é não bloqueante por padrão: servidores se conectam em background e suas ferramentas ficam disponíveis conforme terminam. Defina como `0` para fazer Claude Code aguardar servidores se conectarem antes da primeira consulta. Servidores configurados com [`alwaysLoad: true`](/docs/pt/mcp#exempt-a-server-from-deferral) ainda fazem a inicialização aguardar independentemente, exceto quando servidos do [cache de descoberta](/docs/pt/mcp#server-status-detail), já que suas ferramentas devem estar presentes quando o primeiro prompt é construído. Em modo não interativo (`-p`) sem `--input-format stream-json`, Claude Code também aguarda servidores ainda pendentes antes do primeiro turno independentemente dessa variável. Quando você passa [`--mcp-config`](/docs/pt/cli-reference#cli-flags) explicitamente, a espera tem um prazo mais longo; veja a entrada dessa flag para a exceção de servidor em cache |471| `MCP_CONNECTION_NONBLOCKING` | Controla se a inicialização aguarda servidores MCP se conectarem antes da primeira consulta. Inicialização MCP é não bloqueante por padrão: servidores se conectam em segundo plano e suas ferramentas ficam disponíveis conforme terminam. Defina como `0` para fazer Claude Code aguardar servidores se conectarem antes da primeira consulta. Servidores configurados com [`alwaysLoad: true`](/docs/pt/mcp#exempt-a-server-from-deferral) ainda fazem a inicialização aguardar independentemente, exceto quando servidos do [cache de descoberta](/docs/pt/mcp#server-status-detail), já que suas ferramentas devem estar presentes quando o primeiro prompt é construído. Em modo não interativo (`-p`) sem `--input-format stream-json`, Claude Code também aguarda servidores ainda pendentes antes do primeiro turno independentemente dessa variável. Quando você passa [`--mcp-config`](/docs/pt/cli-reference#cli-flags) explicitamente, a espera tem um prazo mais longo; veja a entrada dessa flag para a exceção de servidor em cache |

470| `MCP_CONNECT_TIMEOUT_MS` | Quanto tempo a inicialização MCP bloqueante aguarda, em milissegundos, para o lote de conexão antes de tirar um snapshot da lista de ferramentas (padrão: 5000). Aplica-se quando `MCP_CONNECTION_NONBLOCKING=0` ou para servidores marcados [`alwaysLoad: true`](/docs/pt/mcp#exempt-a-server-from-deferral). Servidores ainda pendentes no prazo continuam se conectando em background. Distinto de `MCP_TIMEOUT`, que limita a tentativa de conexão de um servidor individual |472| `MCP_CONNECT_TIMEOUT_MS` | Quanto tempo a inicialização MCP bloqueante aguarda, em milissegundos, para o lote de conexão antes de tirar um snapshot da lista de ferramentas (padrão: 5000). Aplica-se quando `MCP_CONNECTION_NONBLOCKING=0` ou para servidores marcados [`alwaysLoad: true`](/docs/pt/mcp#exempt-a-server-from-deferral). Servidores ainda pendentes no prazo continuam se conectando em segundo plano. Distinto de `MCP_TIMEOUT`, que limita uma tentativa de conexão individual de servidor |

471| `MCP_DISCOVERY_CACHE` | Ativa ou desativa o [cache de descoberta MCP](/docs/pt/mcp#server-status-detail). Com o cache ativado, um servidor HTTP ou SSE remoto que você usou antes pode mostrar o [status `cached`](/docs/pt/mcp#server-status-detail), e Claude Code o conecta em sua primeira chamada de ferramenta em vez de na inicialização. O cache está desativado por padrão a menos que um rollout gradual o tenha ativado para sua conta. Defina como `1` para ativá-lo, ou `0` para mantê-lo desativado mesmo quando o rollout o ativou. Antes da v2.1.238, o cache estava ativado por padrão. O status `cached` requer Claude Code v2.1.221 ou posterior |473| `MCP_DISCOVERY_CACHE` | Ativa ou desativa o [cache de descoberta MCP](/docs/pt/mcp#server-status-detail). Com o cache ativado, um servidor HTTP ou SSE remoto que você usou antes pode mostrar o [status `cached`](/docs/pt/mcp#server-status-detail), e Claude Code o conecta em sua primeira chamada de ferramenta em vez de na inicialização. O cache está desativado por padrão a menos que um rollout gradual o tenha ativado para sua conta. Defina como `1` para ativá-lo, ou `0` para mantê-lo desativado mesmo quando o rollout o ativou. Antes da v2.1.238, o cache estava ativado por padrão. O status `cached` requer Claude Code v2.1.221 ou posterior |

472| `MCP_DISCOVERY_CACHE_MAX_STALE_S` | Idade máxima, em segundos, de uma entrada de [cache de descoberta](/docs/pt/mcp#server-status-detail) (padrão: 14400, ou 4 horas). Em um início onde a entrada é mais antiga que isso, Claude Code a descarta e conecta o servidor na inicialização, como faz com o cache desativado. Claude Code limita o valor a 7 dias. Antes da v2.1.238, o padrão era 86400, ou 24 horas, e Claude Code não limitava o valor |474| `MCP_DISCOVERY_CACHE_MAX_STALE_S` | Idade máxima, em segundos, de uma entrada de [cache de descoberta](/docs/pt/mcp#server-status-detail) (padrão: 14400, ou 4 horas). Em um início onde a entrada é mais antiga que isso, Claude Code a descarta e conecta o servidor na inicialização, como faz com o cache desativado. Claude Code limita o valor a 7 dias. Antes da v2.1.238, o padrão era 86400, ou 24 horas, e Claude Code não limitava o valor |

473| `MCP_DISCOVERY_CACHE_STRIKES` | Em um início onde uma entrada de [cache de descoberta](/docs/pt/mcp#server-status-detail) é mais antiga que `MCP_DISCOVERY_CACHE_TTL_S`, Claude Code a atualiza em background. Essa variável define quantas atualizações seguidas podem falhar antes de Claude Code descartar a entrada e conectar o servidor no próximo início (padrão: 1). Aumente se sua conexão de rede cair ocasionalmente, para que uma atualização falhada não descarte a entrada. Requer Claude Code v2.1.238 ou posterior |475| `MCP_DISCOVERY_CACHE_STRIKES` | Em um início onde uma entrada de [cache de descoberta](/docs/pt/mcp#server-status-detail) é mais antiga que `MCP_DISCOVERY_CACHE_TTL_S`, Claude Code a atualiza em segundo plano. Essa variável define quantas atualizações seguidas podem falhar antes que Claude Code descarte a entrada e conecte o servidor no próximo início (padrão: 1). Aumente-a se sua conexão de rede cair ocasionalmente, para que uma atualização falhada não descarte a entrada. Requer Claude Code v2.1.238 ou posterior |

474| `MCP_DISCOVERY_CACHE_TTL_S` | Segundos pelos quais Claude Code usa uma entrada de [cache de descoberta](/docs/pt/mcp#server-status-detail) sem atualizá-la (padrão: 900). Em um início onde a entrada é mais antiga que isso, Claude Code ainda a usa mas a atualiza em background. Uma vez que a entrada é mais antiga que `MCP_DISCOVERY_CACHE_MAX_STALE_S`, Claude Code a descarta. Claude Code limita o valor a `MCP_DISCOVERY_CACHE_MAX_STALE_S`, que é 4 horas por padrão. Antes da v2.1.238, Claude Code não limitava o valor |476| `MCP_DISCOVERY_CACHE_TTL_S` | Segundos pelos quais Claude Code usa uma entrada de [cache de descoberta](/docs/pt/mcp#server-status-detail) sem atualizá-la (padrão: 900). Em um início onde a entrada é mais antiga que isso, Claude Code ainda a usa mas a atualiza em segundo plano. Uma vez que a entrada é mais antiga que `MCP_DISCOVERY_CACHE_MAX_STALE_S`, Claude Code a descarta. Claude Code limita o valor a `MCP_DISCOVERY_CACHE_MAX_STALE_S`, que é 4 horas por padrão. Antes da v2.1.238, Claude Code não limitava o valor |

475| `MCP_OAUTH_CALLBACK_PORT` | Porta fixa para o callback de redirecionamento OAuth, como alternativa a `--callback-port` ao adicionar um servidor MCP com [credenciais pré-configuradas](/docs/pt/mcp#use-pre-configured-oauth-credentials) |477| `MCP_OAUTH_CALLBACK_PORT` | Porta fixa para o callback de redirecionamento OAuth, como alternativa a `--callback-port` ao adicionar um servidor MCP com [credenciais pré-configuradas](/docs/pt/mcp#use-pre-configured-oauth-credentials) |

476| `MCP_PROTOCOL_NEGOTIATION` | No [runtime de cliente MCP v2](/docs/pt/mcp#mcp-client-runtimes) apenas, se Claude Code sonda servidores para revisão de protocolo MCP 2026-07-28. Defina `auto` para sondar servidores HTTP, conector claude.ai e stdio; um servidor que não responde à sonda se conecta no protocolo anterior, como servidores SSE e WebSocket sempre fazem. Defina `legacy` para pular a sonda para cada servidor. Sem a variável, Claude Code sonda servidores HTTP, e também sonda servidores conector claude.ai em sessões onde [busca sinalizadores de recurso](#features-that-need-feature-flag-fetching). Qualquer outro valor é ignorado com um aviso no log de depuração. Requer Claude Code v2.1.221 ou posterior |478| `MCP_PROTOCOL_NEGOTIATION` | No [runtime do cliente MCP v2](/docs/pt/mcp#mcp-client-runtimes) apenas, se Claude Code sonda servidores para revisão de protocolo MCP 2026-07-28. Defina `auto` para sondar servidores HTTP, conector claude.ai e stdio; um servidor que não responde à sonda se conecta no protocolo anterior, como servidores SSE e WebSocket sempre fazem. Defina `legacy` para pular a sonda para cada servidor. Sem a variável, Claude Code sonda servidores HTTP, e também sonda servidores conector claude.ai em sessões onde [busca sinalizadores de recurso](#features-that-need-feature-flag-fetching). Qualquer outro valor é ignorado com um aviso no log de depuração. Requer Claude Code v2.1.221 ou posterior |

477| `MCP_REMOTE_SERVER_CONNECTION_BATCH_SIZE` | Número máximo de servidores MCP remotos (HTTP/SSE) para conectar em paralelo durante a inicialização (padrão: 20) |479| `MCP_REMOTE_SERVER_CONNECTION_BATCH_SIZE` | Número máximo de servidores MCP remotos (HTTP/SSE) para conectar em paralelo durante a inicialização (padrão: 20) |

478| `MCP_SDK_GENERATION` | Fixe qual [runtime de cliente MCP](/docs/pt/mcp#mcp-client-runtimes) este processo se conecta a servidores MCP com: `v1`, construído no MCP TypeScript SDK 1.x, ou `v2`, construído no [MCP TypeScript SDK 2.0](https://ts.sdk.modelcontextprotocol.io/v2/). Sem a variável, Claude Code usa v2, começando com as versões listadas naquela seção. No Claude Code v2.1.221 ou posterior, o runtime v2 verifica o emissor que um servidor OAuth MCP retorna em sua resposta de autorização e falha o sign-in com um erro que começa `Issuer mismatch in authorization response` quando não corresponde. O runtime v1 não executa essa verificação. Se você definir um valor não reconhecido, Claude Code o ignora e escreve um aviso no log de depuração. Claude Code lê o valor uma vez por processo. Requer Claude Code v2.1.218 ou posterior |480| `MCP_SDK_GENERATION` | Fixe qual [runtime do cliente MCP](/docs/pt/mcp#mcp-client-runtimes) este processo se conecta a servidores MCP com: `v1`, construído no MCP TypeScript SDK 1.x, ou `v2`, construído no [MCP TypeScript SDK 2.0](https://ts.sdk.modelcontextprotocol.io/v2/). Sem a variável, Claude Code usa v2, começando com as versões listadas nessa seção. No Claude Code v2.1.221 ou posterior, o runtime v2 verifica o emissor que um servidor OAuth MCP retorna em sua resposta de autorização e falha o sign-in com um erro que começa `Issuer mismatch in authorization response` quando não corresponde. O runtime v1 não executa essa verificação. Se você definir um valor não reconhecido, Claude Code o ignora e escreve um aviso no log de depuração. Claude Code lê o valor uma vez por processo. Requer Claude Code v2.1.218 ou posterior |

479| `MCP_SERVER_CONNECTION_BATCH_SIZE` | Número máximo de servidores MCP locais (stdio) para conectar em paralelo durante a inicialização (padrão: 3) |481| `MCP_SERVER_CONNECTION_BATCH_SIZE` | Número máximo de servidores MCP locais (stdio) para conectar em paralelo durante a inicialização (padrão: 3) |

480| `MCP_TIMEOUT` | Timeout em milissegundos para inicialização de servidor MCP (padrão: 30000, ou 30 segundos) |482| `MCP_TIMEOUT` | Timeout em milissegundos para inicialização de servidor MCP (padrão: 30000, ou 30 segundos) |

481| `MCP_TOOL_TIMEOUT` | Timeout em milissegundos para execução de ferramenta MCP (padrão: 100000000, aproximadamente 28 horas). Para um servidor HTTP, SSE ou conector claude.ai, cada solicitação também expira após 60 segundos por padrão; defina essa variável ou o `timeout` por servidor acima de 60000 para aumentar esse limite por solicitação. Um valor mais baixo ainda encurta o timeout de execução de ferramenta geral mas deixa o limite por solicitação em 60 segundos. Servidores stdio e WebSocket não têm timer por solicitação. Um campo `timeout` por servidor em `.mcp.json` substitui isso para esse servidor. Um `timeout` por servidor de pelo menos 1000 também define a janela de inatividade mínima para chamadas de ferramenta desse servidor, para que `CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT` nunca as aborte mais cedo; este piso requer Claude Code v2.1.203 ou posterior. Para a variável env, valores abaixo de 1000 são limitados a um segundo; para o campo por servidor, valores abaixo de 1000 são ignorados |483| `MCP_TOOL_TIMEOUT` | Timeout em milissegundos para execução de ferramenta MCP (padrão: 100000000, aproximadamente 28 horas). Para um servidor HTTP, SSE ou conector claude.ai, cada solicitação também expira após 60 segundos por padrão; defina essa variável ou o `timeout` por servidor acima de 60000 para aumentar esse limite por solicitação. Um valor mais baixo ainda encurta o timeout geral de execução de ferramenta mas deixa o limite por solicitação em 60 segundos. Servidores stdio e WebSocket não têm timer por solicitação. Um campo `timeout` por servidor em `.mcp.json` substitui isso para esse servidor. Um `timeout` por servidor de pelo menos 1000 também define a janela de inatividade mínima para chamadas de ferramenta desse servidor, para que `CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT` nunca as aborte mais cedo; este piso requer Claude Code v2.1.203 ou posterior. Para a variável env, valores abaixo de 1000 são limitados a um segundo; para o campo por servidor, valores abaixo de 1000 são ignorados |

482| `NO_PROXY` | Lista de domínios e IPs para os quais as solicitações serão emitidas diretamente, contornando proxy |484| `NO_PROXY` | Lista de domínios e IPs para os quais as solicitações serão emitidas diretamente, contornando proxy |

483| `OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT` | Limite padrão do SDK OpenTelemetry no comprimento do valor de atributo. Claude Code limita atributos de telemetria que carregam conteúdo ao menor entre isso e `CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH`, para que o marcador de truncamento fique dentro do limite do SDK. Claude Code lê as variantes `OTEL_LOGRECORD_ATTRIBUTE_VALUE_LENGTH_LIMIT` e `OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT` da mesma forma, e o menor valor definido se aplica a todos os sinais. Requer Claude Code v2.1.214 ou posterior. Veja [Monitoramento](/docs/pt/monitoring-usage#common-configuration-variables) |485| `OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT` | Limite padrão do SDK OpenTelemetry em comprimento de valor de atributo. Claude Code limita atributos de telemetria que carregam conteúdo ao menor entre isso e `CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH`, para que o marcador de truncamento fique dentro do limite do SDK. Claude Code lê as variantes `OTEL_LOGRECORD_ATTRIBUTE_VALUE_LENGTH_LIMIT` e `OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT` da mesma forma, e o menor valor definido se aplica a todos os sinais. Requer Claude Code v2.1.214 ou posterior. Veja [Monitoramento](/docs/pt/monitoring-usage#common-configuration-variables) |

484| `OTEL_LOG_ASSISTANT_RESPONSES` | Defina como `1` para incluir o texto de resposta do modelo em eventos de log OpenTelemetry `assistant_response`. Quando não definido, Claude Code usa o valor de `OTEL_LOG_USER_PROMPTS`. Defina como `0` para manter respostas redatadas mesmo quando `OTEL_LOG_USER_PROMPTS` está definido. Defina em seu shell, configurações de usuário ou configurações gerenciadas. Ignorado em [configurações de projeto e local](/docs/pt/settings-reference#variables-claude-code-ignores-in-env). Requer Claude Code v2.1.193 ou posterior. Veja [Monitoramento](/docs/pt/monitoring-usage#assistant-response-event) |486| `OTEL_LOG_ASSISTANT_RESPONSES` | Defina como `1` para incluir o texto de resposta do modelo em eventos de log OpenTelemetry `assistant_response`. Quando não definido, Claude Code usa o valor de `OTEL_LOG_USER_PROMPTS`. Defina como `0` para manter respostas redatadas mesmo quando `OTEL_LOG_USER_PROMPTS` está definido. Defina-o em seu shell, configurações de usuário ou configurações gerenciadas. Ignorado em [configurações de projeto e local](/docs/pt/settings-reference#variables-claude-code-ignores-in-env). Requer Claude Code v2.1.193 ou posterior. Veja [Monitoramento](/docs/pt/monitoring-usage#assistant-response-event) |

485| `OTEL_LOG_MANAGED_SETTINGS` | Defina como `1` para adicionar as configurações gerenciadas redatadas e um resumo SHA-256 das configurações antes da redação aos eventos de log OpenTelemetry `managed_settings_resolved`. Desabilitado por padrão. Defina em seu shell, configurações de usuário ou configurações gerenciadas; um valor em configurações de projeto ou local não o ativa. Requer Claude Code v2.1.274 ou posterior. Veja [Monitoramento](/docs/pt/monitoring-usage#managed-settings-resolved-event) |487| `OTEL_LOG_MANAGED_SETTINGS` | Defina como `1` para adicionar as configurações gerenciadas redatadas e um resumo SHA-256 das configurações antes da redação aos eventos de log OpenTelemetry `managed_settings_resolved`. Desabilitado por padrão. Defina-o em seu shell, configurações de usuário ou configurações gerenciadas; um valor em configurações de projeto ou local não o ativa. Requer Claude Code v2.1.274 ou posterior. Veja [Monitoramento](/docs/pt/monitoring-usage#managed-settings-resolved-event) |

486| `OTEL_LOG_RAW_API_BODIES` | Emita JSON de solicitação e resposta da API Anthropic Messages como eventos de log `api_request_body` / `api_response_body`. Defina como `1` para corpos inline truncados no limite de conteúdo, ou `file:<dir>` para escrever corpos não truncados em disco e emitir um caminho `body_ref`. `CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` configura o limite de conteúdo, 60 KB por padrão. Desabilitado por padrão; corpos incluem o histórico de conversa inteiro. Defina em seu shell, configurações de usuário ou configurações gerenciadas. Ignorado em [configurações de projeto e local](/docs/pt/settings-reference#variables-claude-code-ignores-in-env). Veja [Monitoramento](/docs/pt/monitoring-usage#api-request-body-event) |488| `OTEL_LOG_RAW_API_BODIES` | Emita JSON de solicitação e resposta da API Anthropic Messages como eventos de log `api_request_body` / `api_response_body`. Defina como `1` para corpos inline truncados no limite de conteúdo, ou `file:<dir>` para escrever corpos não truncados em disco e emitir um caminho `body_ref`. `CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` configura o limite de conteúdo, 60 KB por padrão. Desabilitado por padrão; corpos incluem todo o histórico de conversa. Defina-o em seu shell, configurações de usuário ou configurações gerenciadas. Ignorado em [configurações de projeto e local](/docs/pt/settings-reference#variables-claude-code-ignores-in-env). Veja [Monitoramento](/docs/pt/monitoring-usage#api-request-body-event) |

487| `OTEL_LOG_TOOL_CONTENT` | Defina como `1` para incluir conteúdo de ferramenta no evento de span OpenTelemetry `tool.output`. Atributos de span carregam conteúdo de ferramenta sob [seus próprios gates](/docs/pt/monitoring-usage#new-context-gates). Requer [rastreamento](/docs/pt/monitoring-usage#traces-beta). Desabilitado por padrão para proteger dados sensíveis. Defina em seu shell, configurações de usuário ou configurações gerenciadas. Ignorado em [configurações de projeto e local](/docs/pt/settings-reference#variables-claude-code-ignores-in-env), além dos valores desativados que essa seção descreve. Veja [Monitoramento](/docs/pt/monitoring-usage#tool-output-span-event) |489| `OTEL_LOG_TOOL_CONTENT` | Defina como `1` para incluir conteúdo de ferramenta no evento de span OpenTelemetry `tool.output`. Atributos de span carregam conteúdo de ferramenta sob [seus próprios portões](/docs/pt/monitoring-usage#new-context-gates). Requer [rastreamento](/docs/pt/monitoring-usage#traces-beta). Desabilitado por padrão para proteger dados sensíveis. Defina-o em seu shell, configurações de usuário ou configurações gerenciadas. Ignorado em [configurações de projeto e local](/docs/pt/settings-reference#variables-claude-code-ignores-in-env), além dos valores desativados que essa seção descreve. Veja [Monitoramento](/docs/pt/monitoring-usage#tool-output-span-event) |

488| `OTEL_LOG_TOOL_DETAILS` | Defina como `1` para incluir argumentos de entrada de ferramenta, nomes de servidor MCP, nomes de workflow redigidos pelo usuário, strings de erro bruto em falhas de ferramenta, a `category` de recusa em eventos `api_refusal` e outros detalhes de ferramenta em rastreamentos e logs OpenTelemetry. Desabilitado por padrão para proteger PII. Defina em seu shell, configurações de usuário ou configurações gerenciadas. Ignorado em [configurações de projeto e local](/docs/pt/settings-reference#variables-claude-code-ignores-in-env), além dos valores desativados que essa seção descreve. Veja [Monitoramento](/docs/pt/monitoring-usage) |490| `OTEL_LOG_TOOL_DETAILS` | Defina como `1` para incluir argumentos de entrada de ferramenta; nomes de servidor MCP; nomes de workflow redigidos pelo usuário; strings de erro bruto em falhas de ferramenta; a `category` de recusa em eventos `api_refusal`; nomes reais de agente, skill, plugin e servidor MCP em [métricas de custo e token](/docs/pt/monitoring-usage#cost-counter); e outros detalhes de ferramenta em métricas, rastreamentos e logs OpenTelemetry. Desabilitado por padrão para proteger PII. Defina-o em seu shell, configurações de usuário ou configurações gerenciadas. Ignorado em [configurações de projeto e local](/docs/pt/settings-reference#variables-claude-code-ignores-in-env), além dos valores desativados que essa seção descreve. Veja [Monitoramento](/docs/pt/monitoring-usage) |

489| `OTEL_LOG_USER_PROMPTS` | Defina como `1` para incluir texto de prompt do usuário em rastreamentos e logs OpenTelemetry. Desabilitado por padrão (prompts são redatados). Defina em seu shell, configurações de usuário ou configurações gerenciadas. Ignorado em [configurações de projeto e local](/docs/pt/settings-reference#variables-claude-code-ignores-in-env), além dos valores desativados que essa seção descreve. Veja [Monitoramento](/docs/pt/monitoring-usage) |491| `OTEL_LOG_USER_PROMPTS` | Defina como `1` para incluir texto de prompt do usuário em rastreamentos e logs OpenTelemetry. Desabilitado por padrão (prompts são redatados). Defina-o em seu shell, configurações de usuário ou configurações gerenciadas. Ignorado em [configurações de projeto e local](/docs/pt/settings-reference#variables-claude-code-ignores-in-env), além dos valores desativados que essa seção descreve. Veja [Monitoramento](/docs/pt/monitoring-usage) |

490| `OTEL_METRICS_INCLUDE_ACCOUNT_UUID` | Defina como `false` para excluir UUID de conta de atributos de métricas (padrão: incluído). Veja [Monitoramento](/docs/pt/monitoring-usage) |492| `OTEL_METRICS_INCLUDE_ACCOUNT_UUID` | Defina como `false` para excluir UUID de conta dos atributos de métricas (padrão: incluído). Veja [Monitoramento](/docs/pt/monitoring-usage) |

491| `OTEL_METRICS_INCLUDE_ENTRYPOINT` | Defina como `true` para incluir o ponto de entrada da sessão em atributos de métricas (padrão: excluído). Adicionado na v2.1.152. Veja [Monitoramento](/docs/pt/monitoring-usage) |493| `OTEL_METRICS_INCLUDE_ENTRYPOINT` | Defina como `true` para incluir o ponto de entrada da sessão em atributos de métricas (padrão: excluído). Adicionado na v2.1.152. Veja [Monitoramento](/docs/pt/monitoring-usage) |

492| `OTEL_METRICS_INCLUDE_REPOSITORY` | Defina como `true` para marcar métricas e eventos OpenTelemetry com atributos `vcs.*` identificando o repositório da sessão (padrão: excluído). Requer Claude Code v2.1.269 ou posterior. Veja [Atributos de repositório](/docs/pt/monitoring-usage#repository-attributes) |494| `OTEL_METRICS_INCLUDE_REPOSITORY` | Defina como `true` para marcar métricas e eventos OpenTelemetry com atributos `vcs.*` identificando o repositório da sessão (padrão: excluído). Requer Claude Code v2.1.269 ou posterior. Veja [Atributos de repositório](/docs/pt/monitoring-usage#repository-attributes) |

493| `OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES` | A partir da v2.1.161, Claude Code anexa chaves `OTEL_RESOURCE_ATTRIBUTES` aos rótulos de ponto de dados de métrica. Defina como `false` para excluí-las (padrão: incluído). Veja [Monitoramento](/docs/pt/monitoring-usage#multi-team-organization-support) |495| `OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES` | A partir da v2.1.161, Claude Code anexa chaves `OTEL_RESOURCE_ATTRIBUTES` aos rótulos de ponto de dados de métrica. Defina como `false` para excluí-las (padrão: incluído). Veja [Monitoramento](/docs/pt/monitoring-usage#multi-team-organization-support) |

494| `OTEL_METRICS_INCLUDE_SESSION_ID` | Defina como `false` para excluir ID de sessão de atributos de métricas (padrão: incluído). Veja [Monitoramento](/docs/pt/monitoring-usage) |496| `OTEL_METRICS_INCLUDE_SESSION_ID` | Defina como `false` para excluir ID de sessão dos atributos de métricas (padrão: incluído). Veja [Monitoramento](/docs/pt/monitoring-usage) |

495| `OTEL_METRICS_INCLUDE_VERSION` | Defina como `true` para incluir versão de Claude Code em atributos de métricas (padrão: excluído). Veja [Monitoramento](/docs/pt/monitoring-usage) |497| `OTEL_METRICS_INCLUDE_VERSION` | Defina como `true` para incluir versão de Claude Code em atributos de métricas (padrão: excluído). Veja [Monitoramento](/docs/pt/monitoring-usage) |

496| `SLASH_COMMAND_TOOL_CHAR_BUDGET` | Substitua o orçamento de caracteres para metadados de skill mostrados à [ferramenta Skill](/docs/pt/skills#control-who-invokes-a-skill). O orçamento escala dinamicamente em 1% da janela de contexto, com um fallback de 8.000 caracteres. Nome legado mantido para compatibilidade com versões anteriores |498| `SLASH_COMMAND_TOOL_CHAR_BUDGET` | Substitua o orçamento de caracteres para metadados de skill mostrados à [ferramenta Skill](/docs/pt/skills#control-who-invokes-a-skill). O orçamento escala dinamicamente em 1% da janela de contexto, com fallback de 8.000 caracteres. Nome legado mantido para compatibilidade com versões anteriores |

497| `TASK_MAX_OUTPUT_LENGTH` | Removido na v2.1.277 e agora é um no-op, junto com a ferramenta `TaskOutput` que dimensionava. Anteriormente definia o número máximo de caracteres de saída de uma [tarefa em background](/docs/pt/tools-reference#background-commands) que a ferramenta `TaskOutput` mantinha. Claude lê um arquivo de saída de tarefa em background com `Read` |499| `TASK_MAX_OUTPUT_LENGTH` | Removido na v2.1.277 e agora é um no-op, junto com a ferramenta `TaskOutput` que dimensionava. Anteriormente definia o número máximo de caracteres de saída de uma [tarefa em segundo plano](/docs/pt/tools-reference#background-commands) que a ferramenta `TaskOutput` mantinha. Claude lê a saída de uma tarefa em segundo plano com `Read` |

498| `USE_BUILTIN_RIPGREP` | Defina como `0` para usar `rg` instalado no sistema em vez de `rg` incluído com Claude Code |500| `USE_BUILTIN_RIPGREP` | Defina como `0` para usar `rg` instalado no sistema em vez de `rg` incluído com Claude Code |

499| `VERTEX_REGION_CLAUDE_3_5_HAIKU` | Substitua região para Claude 3.5 Haiku ao usar Google Cloud's Agent Platform |501| `VERTEX_REGION_CLAUDE_3_5_HAIKU` | Substitua região para Claude 3.5 Haiku ao usar Google Cloud's Agent Platform |

500| `VERTEX_REGION_CLAUDE_3_5_SONNET` | Substitua região para Claude 3.5 Sonnet ao usar Google Cloud's Agent Platform |502| `VERTEX_REGION_CLAUDE_3_5_SONNET` | Substitua região para Claude 3.5 Sonnet ao usar Google Cloud's Agent Platform |


518 520 

519Variáveis de exportador OpenTelemetry padrão (`OTEL_METRICS_EXPORTER`, `OTEL_LOGS_EXPORTER`, `OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_EXPORTER_OTLP_PROTOCOL`, `OTEL_EXPORTER_OTLP_HEADERS`, `OTEL_METRIC_EXPORT_INTERVAL`, `OTEL_RESOURCE_ATTRIBUTES` e variantes específicas de sinal) também são suportadas. Veja [Monitoramento](/docs/pt/monitoring-usage) para detalhes de configuração.521Variáveis de exportador OpenTelemetry padrão (`OTEL_METRICS_EXPORTER`, `OTEL_LOGS_EXPORTER`, `OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_EXPORTER_OTLP_PROTOCOL`, `OTEL_EXPORTER_OTLP_HEADERS`, `OTEL_METRIC_EXPORT_INTERVAL`, `OTEL_RESOURCE_ATTRIBUTES` e variantes específicas de sinal) também são suportadas. Veja [Monitoramento](/docs/pt/monitoring-usage) para detalhes de configuração.

520 522 

521Defina `CLAUDE_CODE_ENABLE_TELEMETRY` e as variáveis OpenTelemetry que ativam exportação, escolhem seu destino ou capturam conteúdo em seu shell, configurações de usuário ou configurações gerenciadas. Claude Code [as ignora em configurações de projeto e local](/docs/pt/settings-reference#variables-claude-code-ignores-in-env), além dos valores desativados que essa seção descreve. `OTEL_RESOURCE_ATTRIBUTES` e as variáveis de intervalo de exportação, timeout e compressão, como `OTEL_METRIC_EXPORT_INTERVAL`, ainda se aplicam de configurações de projeto e local.523Defina `CLAUDE_CODE_ENABLE_TELEMETRY` e as variáveis OpenTelemetry que ativam exportação, escolhem seu destino ou capturam conteúdo em seu shell, configurações de usuário ou configurações gerenciadas. Claude Code [as ignora em configurações de projeto e local](/docs/pt/settings-reference#variables-claude-code-ignores-in-env), além dos valores desativados que essa seção descreve. `OTEL_RESOURCE_ATTRIBUTES` e o intervalo de exportação, timeout e variáveis de compressão, como `OTEL_METRIC_EXPORT_INTERVAL`, ainda se aplicam de configurações de projeto e local.

522 524 

523<h2 id="features-that-need-feature-flag-fetching">525<h2 id="features-that-need-feature-flag-fetching">

524 Recursos que precisam de busca de feature-flag526 Recursos que precisam de busca de feature-flag

errors.md +62 −32

Details

322| `Transcript writes are failing (...)` | [Session saving warnings](#transcript-writes-are-failing) |322| `Transcript writes are failing (...)` | [Session saving warnings](#transcript-writes-are-failing) |

323| `Transcript saving is off — CLAUDE_CODE_SKIP_PROMPT_HISTORY is set` | [Session saving warnings](#transcript-saving-is-off-skip-prompt-history) |323| `Transcript saving is off — CLAUDE_CODE_SKIP_PROMPT_HISTORY is set` | [Session saving warnings](#transcript-saving-is-off-skip-prompt-history) |

324| `Transcript saving is off — inherited CLAUDE_CODE_CHILD_SESSION marker` | [Session saving warnings](#transcript-saving-is-off-child-session-marker) |324| `Transcript saving is off — inherited CLAUDE_CODE_CHILD_SESSION marker` | [Session saving warnings](#transcript-saving-is-off-child-session-marker) |

325| `Claude Code's fullscreen renderer didn't finish starting last time on this machine` / `Claude Code's fullscreen renderer has repeatedly failed to start on this machine` | [Configuration warnings](#fullscreen-failed-start-notice) |325| `Claude Code's fullscreen renderer didn't finish starting last time on this machine` / `Claude Code's fullscreen renderer has repeatedly failed to start on this machine` | [Fullscreen rendering](/docs/pt/fullscreen#fullscreen-renderer-didnt-finish-starting) |

326| `Claude Code exited after an unrecoverable interface error (...)` | [Configuration warnings](#exited-after-an-unrecoverable-interface-error) |326| `Claude Code exited after an unrecoverable interface error (...)` | [Configuration warnings](#exited-after-an-unrecoverable-interface-error) |

327| `Agent descriptions are over the 15.0k-token limit` | [Configuration warnings](#agent-descriptions-are-over-the-15000-token-limit) |327| `Agent descriptions are over the 15.0k-token limit` | [Configuration warnings](#agent-descriptions-are-over-the-15000-token-limit) |

328| `Not loaded: rename <path>, then restart — its name uses "<name>", a name reserved for the skills synced from your claude.ai account` | [Configuration warnings](#a-skill-command-or-workflow-wasnt-loaded-because-its-name-is-reserved) |328| `Not loaded: rename <path>, then restart — its name uses "<name>", a name reserved for the skills synced from your claude.ai account` | [Configuration warnings](#a-skill-command-or-workflow-wasnt-loaded-because-its-name-is-reserved) |


331| `Remote managed settings failed to load (<cause>)` | [Configuration warnings](#remote-managed-settings-failed-to-load) |331| `Remote managed settings failed to load (<cause>)` | [Configuration warnings](#remote-managed-settings-failed-to-load) |

332| `Managed settings were not approved; exiting without applying them.` | [Configuration warnings](#managed-settings-were-not-approved) |332| `Managed settings were not approved; exiting without applying them.` | [Configuration warnings](#managed-settings-were-not-approved) |

333| `Claude Code can't start: your organization's managed settings block the default model` / `Claude Code can't start: your organization allows only the models listed in "availableModels"` | [Configuration warnings](#managed-settings-block-the-default-model) |333| `Claude Code can't start: your organization's managed settings block the default model` / `Claude Code can't start: your organization allows only the models listed in "availableModels"` | [Configuration warnings](#managed-settings-block-the-default-model) |

334| `Your organization's managed settings allow Claude Code to use: <providers>` | [Configuration warnings](#managed-settings-dont-allow-this-api-provider) |

335| `Your organization's managed settings allow Claude Code to use no API provider at all` | [Configuration warnings](#managed-settings-dont-allow-this-api-provider) |

334| `MCP server <name> is blocked by enterprise managed policy` | [Configuration warnings](#mcp-server-is-blocked-by-enterprise-managed-policy) |336| `MCP server <name> is blocked by enterprise managed policy` | [Configuration warnings](#mcp-server-is-blocked-by-enterprise-managed-policy) |

335| `Managed settings document could not be parsed as a JSON object; none of its settings are in effect. Fix or remove it.` | [Configuration warnings](#managed-settings-document-could-not-be-parsed) |337| `Managed settings document could not be parsed as a JSON object; none of its settings are in effect. Fix or remove it.` | [Configuration warnings](#managed-settings-document-could-not-be-parsed) |

336| `Managed settings drop-in directory could not be read` | [Configuration warnings](#managed-settings-document-could-not-be-parsed) |338| `Managed settings drop-in directory could not be read` | [Configuration warnings](#managed-settings-document-could-not-be-parsed) |

339| `Unable to read managed policy settings` | [Configuration warnings](#unable-to-read-managed-policy-settings) |

337| `otelHeadersHelper failed; telemetry is not being exported. See /status: ...` | [Configuration warnings](#otelheadershelper-failed) |340| `otelHeadersHelper failed; telemetry is not being exported. See /status: ...` | [Configuration warnings](#otelheadershelper-failed) |

338| `"crossSessionInbound" must be one of "accept", "hold", "refuse"` | [Configuration warnings](#crosssessioninbound-must-be-one-of-accept-hold-refuse) |341| `"crossSessionInbound" must be one of "accept", "hold", "refuse"` | [Configuration warnings](#crosssessioninbound-must-be-one-of-accept-hold-refuse) |

339| `headersHelper not run — this workspace has no persisted trust` | [Configuration warnings](#headershelper-not-run) |342| `headersHelper not run — this workspace has no persisted trust` | [Configuration warnings](#headershelper-not-run) |


3657 Não foi possível abrir Claude Desktop3660 Não foi possível abrir Claude Desktop

3658</h3>3661</h3>

3659 3662 

3660Você executou [`/desktop`](/docs/pt/desktop#coming-from-the-cli), ou seu alias `/app`, e o comando do sistema que Claude Code usa para abrir Claude Desktop falhou. A sessão permanece no terminal.3663Você executou [`/desktop`](/docs/pt/desktop#coming-from-the-cli) ou seu alias `/app` em uma sessão, ou [`claude --desktop`](/docs/pt/cli-reference#cli-flags) em seu shell, e o comando do sistema que Claude Code usa para abrir Claude Desktop falhou. Depois de `/desktop`, a sessão permanece no terminal; `claude --desktop` imprime a mensagem sem o prefixo `Error:` e sai com status 1.

3664 

3665O texto entre parênteses nomeia o comando que falhou, com seu status de saída e a primeira linha de sua saída de erro quando a produziu. No macOS esse comando é `open`, como neste exemplo; no Windows é `rundll32`:

3661 3666 

3662```text theme={null}3667```text theme={null}

3663Error: Couldn't open Claude Desktop (`open` exited 1: LSOpenURLsWithRole() failed for the URL claude://resume?session=<session-id> with error -10814). Open Claude Desktop and run /desktop again.3668Error: Couldn't open Claude Desktop (`open` exited 1: LSOpenURLsWithRole() failed for the URL claude://resume?session=<session-id> with error -10814). Open Claude Desktop and try again.

3664```3669```

3665 3670 

3666**O que fazer:**3671**O que fazer:**

3667 3672 

3668* Abra Claude Desktop você mesmo, depois execute `/desktop` novamente3673* Abra Claude Desktop você mesmo, depois execute `/desktop` ou `claude --desktop` novamente

3669* Para ler a saída de erro completa desse comando, ative o log de debug com `/debug`, execute `/desktop` novamente e verifique o log de debug3674* Para ler a saída de erro completa do comando que falhou, ative o log de debug com `/debug` e execute `/desktop` novamente, ou execute `claude --desktop --debug-file <path>`, depois verifique o log de debug

3670 3675 

3671Antes da v2.1.275, a mensagem era `Failed to open Claude Desktop. Please try opening it manually.` e não dizia o que falhou.3676Antes da v2.1.285, a mensagem terminava `Open Claude Desktop and run /desktop again.` Antes da v2.1.275, era `Failed to open Claude Desktop. Please try opening it manually.` e não dizia o que falhou.

3672 3677 

3673<h3 id="terminal-setup-left-your-zed-keymap-unchanged">3678<h3 id="terminal-setup-left-your-zed-keymap-unchanged">

3674 /terminal-setup deixou seu mapa de teclas Zed inalterado3679 /terminal-setup deixou seu mapa de teclas Zed inalterado


3921commands path escapes plugin directory: ./commands\deploy.md — its path contains a backslash, which is not resolved reliably on this platform3926commands path escapes plugin directory: ./commands\deploy.md — its path contains a backslash, which is not resolved reliably on this platform

3922```3927```

3923 3928 

3924Antes da v2.1.251, Claude Code carregava um caminho `commands` declarado em uma entrada de marketplace mesmo quando apontava para fora do diretório do plugin. Claude Code já rejeitava caminhos declarados em `plugin.json` e os outros caminhos de componente em uma entrada de marketplace.3929Antes da v2.1.251, Claude Code carregava um caminho `commands` declarado em uma entrada de marketplace mesmo quando apontava para fora do diretório do plugin.

3925 3930 

3926Antes da v2.1.257, a verificação olhava apenas para a grafia do caminho, não para onde um symlink leva.3931Antes da v2.1.257, a verificação olhava apenas para a grafia do caminho, não para onde um symlink leva.

3927 3932 


4626terminal host process died — press Enter to restart4631terminal host process died — press Enter to restart

4627```4632```

4628 4633 

4629Se você abrir a linha antes da verificação ser executada, o rodapé mostra `This session's terminal host process died (the conversation is saved) — press Enter to restart it` e a linha fica falha.

4630 

4631Do shell, `claude attach <id>` reinicia uma sessão já marcada como falha por um host morto, e caso contrário imprime a causa e sai:4634Do shell, `claude attach <id>` reinicia uma sessão já marcada como falha por um host morto, e caso contrário imprime a causa e sai:

4632 4635 

4633```text theme={null}4636```text theme={null}


5023 5026 

5024Claude Code escreve a maioria dessas mensagens em stderr, não na conversa, e escreve a maioria delas na inicialização. Uma entrada diz assim quando sua mensagem aparece em outro lugar, como no log de depuração ou como um aviso de inicialização na visualização de conversa, ou em outro momento, como a [linha de diagnóstico de modelo não reconhecido](#unrecognized-model-id-on-a-request) no momento da solicitação.5027Claude Code escreve a maioria dessas mensagens em stderr, não na conversa, e escreve a maioria delas na inicialização. Uma entrada diz assim quando sua mensagem aparece em outro lugar, como no log de depuração ou como um aviso de inicialização na visualização de conversa, ou em outro momento, como a [linha de diagnóstico de modelo não reconhecido](#unrecognized-model-id-on-a-request) no momento da solicitação.

5025 5028 

5026<h3 id="fullscreen-failed-start-notice">

5027 O renderizador de tela cheia não terminou de iniciar

5028</h3>

5029 

5030Uma sessão anterior de [tela cheia](/docs/pt/fullscreen) nesta máquina saiu antes de terminar de iniciar, então Claude Code inicia esta sessão no renderizador clássico e imprime um destes avisos:

5031 

5032```text theme={null}

5033Claude Code's fullscreen renderer didn't finish starting last time on this machine, so this launch is using the classic renderer. It will try fullscreen again next launch; /tui default keeps the classic renderer.

5034 

5035Claude Code's fullscreen renderer has repeatedly failed to start on this machine, so it has been turned off here. Run /tui fullscreen to try it again (this also resets after an update).

5036```

5037 

5038**O que fazer:**

5039 

5040* Siga [Renderização de tela cheia](/docs/pt/fullscreen#fullscreen-renderer-didnt-finish-starting). Ele diz qual aviso você recebe, o que Claude Code faz em sessões posteriores e como tentar tela cheia novamente ou manter o renderizador clássico.

5041* Se a sessão que falhou imprimiu uma mensagem de saída, consulte [Claude Code saiu após um erro de interface irrecuperável](#exited-after-an-unrecoverable-interface-error) para ver o que ela nomeia.

5042 

5043Antes da v2.1.236, Claude Code não imprimia aviso e continuava iniciando sessões em renderização de tela cheia após uma falha de inicialização.

5044 

5045<h3 id="exited-after-an-unrecoverable-interface-error">5029<h3 id="exited-after-an-unrecoverable-interface-error">

5046 Claude Code saiu após um erro de interface irrecuperável5030 Claude Code saiu após um erro de interface irrecuperável

5047</h3>5031</h3>


5193* Se você administra as configurações, adicione um modelo que seus usuários possam executar a `availableModels`, ou estreite as entradas `deniedModels` que bloqueiam cada fallback. [Bloquear modelos ou versões específicas](/docs/pt/model-config#block-specific-models-or-versions) descreve como a opção Padrão faz downgrade5177* Se você administra as configurações, adicione um modelo que seus usuários possam executar a `availableModels`, ou estreite as entradas `deniedModels` que bloqueiam cada fallback. [Bloquear modelos ou versões específicas](/docs/pt/model-config#block-specific-models-or-versions) descreve como a opção Padrão faz downgrade

5194* Se você não as administra, envie a mensagem ao seu administrador. Seus próprios arquivos de configurações não podem ampliar uma lista `availableModels` ou `deniedModels` gerenciada5178* Se você não as administra, envie a mensagem ao seu administrador. Seus próprios arquivos de configurações não podem ampliar uma lista `availableModels` ou `deniedModels` gerenciada

5195 5179 

5180<h3 id="managed-settings-dont-allow-this-api-provider">

5181 As configurações gerenciadas não permitem este provedor de API

5182</h3>

5183 

5184As [configurações gerenciadas](/docs/pt/managed-settings) de sua organização definem uma lista [`allowedProviders`](/docs/pt/settings-reference#allowedproviders), e o provedor de API da sessão não está nela ou a sessão usa um endpoint que não está fixado da forma que essa entrada requer. Claude Code recusa na inicialização, antes de um login, ou quando a sessão próxima contata a API. A mensagem começa com os provedores permitidos:

5185 

5186```text theme={null}

5187Your organization's managed settings allow Claude Code to use: Anthropic API, Amazon Bedrock.

5188```

5189 

5190Quando a lista está vazia, a mensagem lê em vez disso:

5191 

5192```text theme={null}

5193Your organization's managed settings allow Claude Code to use no API provider at all (allowedProviders is an empty list), so it cannot start on this machine.

5194```

5195 

5196Quando cada entrada é não reconhecida, o parêntese lê `(allowedProviders lists only unrecognized entries)` em vez disso.

5197 

5198**O que fazer:**

5199 

5200* Siga as etapas `To continue:` da mensagem

5201* Se você administra as configurações, as linhas da mensagem começando com `Admins:` nomeiam a entrada a adicionar ou o valor a fixar, e a entrada [`allowedProviders`](/docs/pt/settings-reference#allowedproviders) diz qual bloco `env` da fonte pode fixá-lo

5202 

5196<h3 id="mcp-server-is-blocked-by-enterprise-managed-policy">5203<h3 id="mcp-server-is-blocked-by-enterprise-managed-policy">

5197 O servidor MCP é bloqueado pela política gerenciada da empresa5204 O servidor MCP é bloqueado pela política gerenciada da empresa

5198</h3>5205</h3>


5246* Se você administra a máquina, corrija o documento nomeado para que seja analisado como um objeto JSON, ou remova o arquivo, perfil ou valor do registro. Um `managed-settings.json` vazio conta como `{}` e não bloqueia o lançamento.5253* Se você administra a máquina, corrija o documento nomeado para que seja analisado como um objeto JSON, ou remova o arquivo, perfil ou valor do registro. Um `managed-settings.json` vazio conta como `{}` e não bloqueia o lançamento.

5247* Se não, peça ao seu administrador para corrigir o documento implantado. Nada em seus próprios arquivos de configurações causa ou limpa este erro.5254* Se não, peça ao seu administrador para corrigir o documento implantado. Nada em seus próprios arquivos de configurações causa ou limpa este erro.

5248 5255 

5256<h3 id="unable-to-read-managed-policy-settings">

5257 Não foi possível ler as configurações de política gerenciada

5258</h3>

5259 

5260Sua organização implanta [configurações gerenciadas](/docs/pt/managed-settings), e uma das fontes implantadas existe mas não pôde ser lida, por um motivo como um erro de E/S em vez do sistema operacional negar a leitura. Sem outra fonte de administrador fornecendo uma política, Claude Code sai na inicialização em vez de executar sem a política que a fonte pode carregar:

5261 

5262```text theme={null}

5263Unable to read managed policy settings.

5264This machine may require organization login enforcement, but the policy file failed to load.

5265Contact your administrator.

5266 

5267Detail: <source>: <reason>

5268```

5269 

5270No mesmo estado, fluxos de login, solicitações de API de uma sessão que já está em execução, e o servidor [`claude gateway`](/docs/pt/claude-apps-gateway) são recusados com uma variante da primeira linha que nomeia [`allowedProviders`](/docs/pt/settings-reference#allowedproviders).

5271 

5272Uma leitura que o sistema operacional negou, como em um arquivo somente raiz, não produz esta saída: [a sessão inicia sem as políticas dessa fonte](/docs/pt/managed-settings#find-entries-claude-code-dropped). Para uma fonte que não pode ser analisada, Claude Code sai com [uma mensagem diferente nomeando a fonte](#managed-settings-document-could-not-be-parsed).

5273 

5274**O que fazer:**

5275 

5276* Se você administra a máquina, corrija o problema que a linha `Detail:` nomeia para que a fonte implantada possa ser lida, ou remova a fonte

5277* Se não, envie a mensagem ao seu administrador. Nada em seus próprios arquivos de configurações causa ou limpa este erro

5278 

5279Antes da v2.1.285, apenas sessões conectadas com credenciais claude.ai ou Claude Console saíram com esta mensagem, e uma leitura que o sistema operacional negou a produziu também.

5280 

5249<h3 id="otelheadershelper-failed">5281<h3 id="otelheadershelper-failed">

5250 otelHeadersHelper falhou5282 otelHeadersHelper falhou

5251</h3>5283</h3>


5344* Corrija a regra na fonte que o aviso nomeia entre parênteses: um caminho de arquivo de configurações, ou o próprio flag `--allowed-tools`. Um caminho `claude-settings-<hash>.json` que não existe no disco representa um valor `--settings` inline. Corrija o JSON que você passa para esse flag.5376* Corrija a regra na fonte que o aviso nomeia entre parênteses: um caminho de arquivo de configurações, ou o próprio flag `--allowed-tools`. Um caminho `claude-settings-<hash>.json` que não existe no disco representa um valor `--settings` inline. Corrija o JSON que você passa para esse flag.

5345* Se a fonte lê `managed policy settings`, encaminhe o aviso a quem mantém suas configurações gerenciadas, já que você não pode limpá-lo você mesmo.5377* Se a fonte lê `managed policy settings`, encaminhe o aviso a quem mantém suas configurações gerenciadas, já que você não pode limpá-lo você mesmo.

5346 5378 

5347Claude Code não avisa sobre regras de negação e pergunta com a mesma forma: ele recusa ou solicita os comandos extras que eles correspondem em vez de aprová-los. Também não avisa sobre regras cujo subcomando vem antes do primeiro `*`, como `Bash(git commit *)`, ou regras em que nenhuma palavra além de uma opção segue o `*`, como `Bash(git *)`, ou sobre regras de prefixo `:*` como `Bash(git:*)`.

5348 

5349Em uma [sessão em segundo plano](/docs/pt/agent-view) ou com `--output-format json` ou `stream-json`, Claude Code escreve o aviso no log de depuração em vez de stderr, então a saída lida por máquina fica limpa. Execute com `--debug` para capturá-lo em `~/.claude/debug/<session-id>.txt`. Antes da v2.1.246, Claude Code aceitava essas regras sem aviso.5379Em uma [sessão em segundo plano](/docs/pt/agent-view) ou com `--output-format json` ou `stream-json`, Claude Code escreve o aviso no log de depuração em vez de stderr, então a saída lida por máquina fica limpa. Execute com `--debug` para capturá-lo em `~/.claude/debug/<session-id>.txt`. Antes da v2.1.246, Claude Code aceitava essas regras sem aviso.

5350 5380 

5351<h3 id="crosssessioninbound-must-be-one-of-accept-hold-refuse">5381<h3 id="crosssessioninbound-must-be-one-of-accept-hold-refuse">


5458 As respostas parecem ter qualidade inferior ao usual5488 As respostas parecem ter qualidade inferior ao usual

5459</h2>5489</h2>

5460 5490 

5461Se as respostas do Claude parecerem menos capazes do que você espera, mas nenhum erro for exibido, a causa geralmente é o estado da conversa em vez do modelo em si. Claude Code não muda silenciosamente versões de modelo. Ele pode mudar para um modelo de fallback em três casos específicos:5491Se as respostas do Claude parecerem menos capazes do que você espera, mas nenhum erro for exibido, a causa geralmente é o estado da conversa em vez do modelo em si. Claude Code não muda silenciosamente versões de modelo. Ele pode mudar para um modelo de fallback nestes casos:

5462 5492 

5463* Um [`--fallback-model`](/docs/pt/cli-reference#cli-flags) configurado assume o controle após um erro de disponibilidade, apenas para esse turno, com um aviso na transcrição5493* Um [`--fallback-model`](/docs/pt/cli-reference#cli-flags) configurado assume o controle após um erro de disponibilidade, apenas para esse turno, com um aviso na transcrição

5464* Uma verificação de inicialização do Amazon Bedrock ou da Agent Platform do Google Cloud encontra seu modelo padrão indisponível5494* Uma verificação de inicialização do Amazon Bedrock ou da Agent Platform do Google Cloud encontra seu modelo padrão indisponível, ou sua conta [perde acesso a ele durante a sessão](/docs/pt/amazon-bedrock#when-a-model-is-disabled-mid-session)

5465* [Fallback automático de modelo](/docs/pt/model-config#automatic-model-fallback) no Fable 5.1, Fable 5, Opus 5.5, Sonnet 5.5 e Opus 5 move a sessão para o modelo de fallback da categoria sinalizada, quando essa categoria tem um, e mostra um aviso na transcrição5495* [Fallback automático de modelo](/docs/pt/model-config#automatic-model-fallback) no Fable 5.1, Fable 5, Opus 5.5, Sonnet 5.5 e Opus 5 move a sessão para o modelo de fallback da categoria sinalizada, quando essa categoria tem um, e mostra um aviso na transcrição

5466 5496 

5467A verificação de seleção de modelo abaixo captura o segundo e terceiro casos; o primeiro aparece como um aviso de transcrição em vez de uma mudança de `/model`. [Configuração de modelo](/docs/pt/model-config) explica quando cada fallback se aplica.5497A verificação de seleção de modelo abaixo captura o segundo e terceiro casos; o primeiro aparece como um aviso de transcrição em vez de uma mudança de `/model`. [Configuração de modelo](/docs/pt/model-config) explica quando cada fallback se aplica.

Details

293 293 

294Aliases de modelo como `opus` não atuam como fixações, e nem um ID de modelo que Claude Code não reconhece.294Aliases de modelo como `opus` não atuam como fixações, e nem um ID de modelo que Claude Code não reconhece.

295 295 

296Quando essas verificações encontram um modelo que seu projeto não pode invocar, Claude Code lembra a recusa nesta máquina por até um dia, e inicia durante esse tempo pulando o modelo lembrado sem perguntar à Plataforma de Agentes novamente. Claude Code verifica uma recusa lembrada de um modelo padrão atual novamente na inicialização uma vez que dez minutos tenham passado desde a última verificação, então um padrão que seu administrador reativa volta. Para desativar a memória, defina [`CLAUDE_CODE_SKIP_MODEL_ACCESS_MEMORY=1`](/docs/pt/env-vars).

297 

298<h3 id="when-a-model-is-disabled-mid-session">

299 Quando um modelo é desativado durante a sessão

300</h3>

301 

302Se seu projeto perder acesso ao modelo em que sua sessão está sendo executada, por exemplo porque um administrador o desativa no [Model Garden](https://console.cloud.google.com/vertex-ai/model-garden), Claude Code muda a sessão para outro modelo em vez de falhar em cada solicitação, e mostra `Switched to <fallback> because <model> is not available`. Ele tenta os mesmos modelos que o fallback de inicialização: versões anteriores do mesmo nível primeiro e, para uma sessão Opus sem nenhuma versão Opus disponível, o modelo Sonnet padrão.

303 

304A mudança se aplica apenas a um nível que você não fixou, a mesma condição que o fallback de inicialização. Uma sessão em uma versão específica que você escolheu mantém seu modelo e, sem uma cadeia de modelo fallback, a solicitação falha em vez disso. No [modo automático](/docs/pt/permission-modes#enable-auto-mode-on-bedrock-agent-platform-or-foundry), Claude Code muda apenas para um modelo que o modo automático suporta na Plataforma de Agentes. Se nenhum desses modelos estiver disponível também, a solicitação falha.

305 

306Uma [cadeia de modelo fallback](/docs/pt/model-config#fallback-model-chains) que você configura substitui a mudança de nível: nessas recusas Claude Code muda para seu fallback configurado em vez disso. Para fazer com que solicitações recusadas falhem em vez de mudar, defina [`CLAUDE_CODE_DISABLE_MODEL_ACCESS_FALLBACK=1`](/docs/pt/env-vars). Uma cadeia de fallback que você configurou ainda muda nessas recusas; remova a cadeia também se quiser que cada solicitação recusada falhe.

307 

296<h2 id="iam-configuration">308<h2 id="iam-configuration">

297 Configuração de IAM309 Configuração de IAM

298</h2>310</h2>

headless.md +2 −2

Details

296 Aprovar ferramentas automaticamente296 Aprovar ferramentas automaticamente

297</h3>297</h3>

298 298 

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

300 300 

301```bash theme={null}301```bash theme={null}

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

303 --allowedTools "Bash,Read,Edit"303 --allowedTools "Bash,Read,Edit"

304```304```

305 305 

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

307 307 

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

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

hooks.md +40 −4

Details

10 Para um guia de início rápido com exemplos, consulte [Automatizar ações com hooks](/docs/pt/hooks-guide).10 Para um guia de início rápido com exemplos, consulte [Automatizar ações com hooks](/docs/pt/hooks-guide).

11</Tip>11</Tip>

12 12 

13Hooks são comandos shell definidos pelo usuário, endpoints HTTP, chamadas de ferramentas MCP, prompts LLM ou subagentos que executam automaticamente em pontos específicos do ciclo de vida do Claude Code. O Claude Code dispara os mesmos eventos de hook onde quer que seja executado: sessões no terminal, extensões de IDE, o [aplicativo Desktop](/docs/pt/desktop-quickstart) e [Claude Code na web](/docs/pt/claude-code-on-the-web). Use esta referência para consultar esquemas de eventos, opções de configuração, formatos de entrada/saída JSON e recursos avançados como hooks assíncronos, hooks HTTP e hooks de ferramentas MCP.13Hooks são comandos shell definidos pelo usuário, endpoints HTTP, chamadas de ferramentas MCP, prompts LLM ou subagentos que executam automaticamente em pontos específicos do ciclo de vida do Claude Code. O Claude Code dispara os mesmos eventos de hook onde quer que seja executado: sessões no terminal, extensões de IDE, o [aplicativo Desktop](/docs/pt/desktop-quickstart) e [sessões na nuvem](/docs/pt/claude-code-on-the-web). Use esta referência para consultar esquemas de eventos, opções de configuração, formatos de entrada/saída JSON e recursos avançados como hooks assíncronos, hooks HTTP e hooks de ferramentas MCP.

14 

15Um plugin também pode registrar hooks como funções JavaScript que o Claude Code chama em seu próprio processo, que podem desenhar na interface, bem como agir sobre eventos. Um plugin que faz isso é um [mod](/docs/pt/plugins/mods/overview), e esses hooks de função são cobertos em [Reagir a eventos](/docs/pt/plugins/mods/events) em vez de aqui. Os hooks nesta página continuam funcionando junto com mods.

16 

17| Evento | Quando dispara |

18| :- | :- |

19| `SessionStart` | Quando uma sessão começa ou é retomada |

20| `Setup` | Quando você inicia Claude Code com `--init-only`, ou com `--init` ou `--maintenance` no modo `-p`. Para preparação única em CI ou scripts |

21| `UserPromptSubmit` | Quando você envia um prompt, antes de Claude processá-lo |

22| `UserPromptExpansion` | Quando um comando digitado pelo usuário se expande em um prompt, antes de chegar a Claude. Pode bloquear a expansão |

23| `PreToolUse` | Antes de uma chamada de ferramenta ser executada. Pode bloqueá-la |

24| `PermissionRequest` | Quando uma chamada de ferramenta precisa de uma decisão de permissão |

25| `PermissionDenied` | Quando o modo automático nega uma chamada de ferramenta, incluindo negações sem um veredicto do classificador. Use JSON `hookSpecificOutput.retry: true` para informar ao modelo que ele pode tentar novamente a chamada de ferramenta negada. Claude Code ignora `retry` quando o classificador não produziu veredicto |

26| `PostToolUse` | Depois que uma chamada de ferramenta é bem-sucedida |

27| `PostToolUseFailure` | Depois que uma chamada de ferramenta falha |

28| `PostToolBatch` | Depois que um lote completo de chamadas de ferramenta paralelas é resolvido, antes da próxima chamada do modelo |

29| `Notification` | Quando Claude Code envia uma notificação |

30| `MessageDisplay` | Enquanto o texto da mensagem do assistente está sendo exibido |

31| `SubagentStart` | Quando um subagente é criado |

32| `SubagentStop` | Quando um subagente termina |

33| `TaskCreated` | Quando uma tarefa está sendo criada via `TaskCreate` |

34| `TaskCompleted` | Quando uma tarefa está sendo marcada como concluída |

35| `Stop` | Quando Claude termina de responder |

36| `StopFailure` | Quando a rodada termina devido a um erro de API |

37| `TeammateIdle` | Quando um colega de [equipe de agentes](/docs/pt/agent-teams) está prestes a ficar ocioso |

38| `InstructionsLoaded` | Quando um arquivo CLAUDE.md ou `.claude/rules/*.md` é carregado no contexto. Dispara no início da sessão e quando os arquivos são carregados lentamente durante uma sessão |

39| `ConfigChange` | Quando um arquivo de configuração muda durante uma sessão |

40| `CwdChanged` | Quando o diretório de trabalho muda, por exemplo quando Claude executa um comando `cd`. Útil para gerenciamento reativo do ambiente com ferramentas como direnv |

41| `DirectoryAdded` | Quando um diretório de trabalho é adicionado no meio da sessão via `/add-dir` ou a solicitação de controle SDK `register_repo_root` |

42| `FileChanged` | Quando um arquivo observado muda no disco. O campo `matcher` especifica quais nomes de arquivo observar |

43| `WorktreeCreate` | Quando um worktree está sendo criado via `--worktree`, `isolation: "worktree"`, ou para uma sessão em segundo plano. Substitui o comportamento padrão do git |

44| `WorktreeRemove` | Quando um worktree está sendo removido na saída da sessão, quando um subagente termina, ou quando você exclui uma sessão em segundo plano |

45| `PreCompact` | Antes da compactação de contexto |

46| `PostCompact` | Depois que a compactação de contexto é concluída |

47| `PreModelSwitch` | Antes de Claude Code aplicar uma mudança de modelo que você ou um cliente solicitou. Pode bloquear a mudança |

48| `PostModelSwitch` | Depois que o modelo da sessão muda, incluindo mudanças que Claude Code faz por conta própria, como restaurar o modelo quando você retoma uma sessão |

49| `Elicitation` | Quando um servidor MCP solicita entrada do usuário durante uma chamada de ferramenta |

50| `ElicitationResult` | Depois que um usuário responde a uma elicitação MCP, antes da resposta ser enviada de volta ao servidor |

51| `SessionEnd` | Quando uma sessão é encerrada |

14 52 

15<h2 id="hook-lifecycle">53<h2 id="hook-lifecycle">

16 Ciclo de vida do hook54 Ciclo de vida do hook


453| `Bash(git *)` | `npm test && git push` | sim | cada subcomando é verificado; `git push` corresponde |491| `Bash(git *)` | `npm test && git push` | sim | cada subcomando é verificado; `git push` corresponde |

454| `Bash(rm *)` | `echo $(rm -rf /)` | sim | comandos dentro de `$()` e backticks são verificados; `rm -rf /` corresponde |492| `Bash(rm *)` | `echo $(rm -rf /)` | sim | comandos dentro de `$()` e backticks são verificados; `rm -rf /` corresponde |

455| `Bash(rm *)` | `echo $(date)` | não | nenhum subcomando corresponde a `rm *` |493| `Bash(rm *)` | `echo $(date)` | não | nenhum subcomando corresponde a `rm *` |

456| `Bash(cat *)` | `echo before $(date) after` | não | uma substituição pode estar em qualquer posição de argumento, então o comando completo e `date` são ambos verificados; nenhum corresponde a `cat *` |

457| `Bash(git *)` | `$TOOL git push` | sim | Claude Code não pode dizer para o que o nome do comando se expande, então executa o hook |

458| `Bash(git push *)` | `echo $(date)` | sim | padrões que especificam mais do que o nome do comando executam o hook mesmo assim em `$()`, backticks ou `$VAR` |494| `Bash(git push *)` | `echo $(date)` | sim | padrões que especificam mais do que o nome do comando executam o hook mesmo assim em `$()`, backticks ou `$VAR` |

459 495 

460Quando Claude Code não pode determinar quais comandos a entrada Bash executa, ele executa seu hook independentemente do padrão. Como o filtro `if` é melhor esforço, use o [sistema de permissão](/docs/pt/permissions) em vez de um hook para impor um allow ou deny duro.496Quando Claude Code não pode determinar quais comandos a entrada Bash executa, ele executa seu hook independentemente do padrão. Como o filtro `if` é melhor esforço, use o [sistema de permissão](/docs/pt/permissions) em vez de um hook para impor um allow ou deny duro.


1938| :- | :- |1974| :- | :- |

1939| `permissionDecision` | `"allow"` pula o prompt de permissão, exceto para as [ações que nenhum modo auto-aprova](/docs/pt/permission-modes#actions-no-mode-auto-approves) e para `AskUserQuestion` e `ExitPlanMode`, que precisam de [`updatedInput` emparelhado com ele](#allow-with-updatedinput). `"deny"` impede a chamada de ferramenta. `"ask"` solicita ao usuário para confirmar. `"defer"` sai graciosamente para que a ferramenta possa ser retomada mais tarde. [Regras de negação e pergunta](/docs/pt/permissions#manage-permissions) ainda são avaliadas independentemente do que o hook retorna |1975| `permissionDecision` | `"allow"` pula o prompt de permissão, exceto para as [ações que nenhum modo auto-aprova](/docs/pt/permission-modes#actions-no-mode-auto-approves) e para `AskUserQuestion` e `ExitPlanMode`, que precisam de [`updatedInput` emparelhado com ele](#allow-with-updatedinput). `"deny"` impede a chamada de ferramenta. `"ask"` solicita ao usuário para confirmar. `"defer"` sai graciosamente para que a ferramenta possa ser retomada mais tarde. [Regras de negação e pergunta](/docs/pt/permissions#manage-permissions) ainda são avaliadas independentemente do que o hook retorna |

1940| `permissionDecisionReason` | Para `"ask"`, mostrado ao usuário mas não ao Claude. Para `"deny"`, mostrado ao Claude. Para `"allow"` e `"defer"`, escrito apenas no [log de depuração](#debug-hooks) |1976| `permissionDecisionReason` | Para `"ask"`, mostrado ao usuário mas não ao Claude. Para `"deny"`, mostrado ao Claude. Para `"allow"` e `"defer"`, escrito apenas no [log de depuração](#debug-hooks) |

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

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

1943 1979 

1944Quando vários hooks PreToolUse retornam decisões diferentes, a precedência é `deny` > `defer` > `ask` > `allow`.1980Quando vários hooks PreToolUse retornam decisões diferentes, a precedência é `deny` > `defer` > `ask` > `allow`.

hooks-guide.md +3 −1

Details

1014 1014 

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

1016 1016 

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

1018 

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

1018 1020 

1019<h3 id="hook-not-firing">1021<h3 id="hook-not-firing">

1020 Hook não dispara1022 Hook não dispara

Details

346* Solicitar ao Claude Code que execute um comando em segundo plano346* Solicitar ao Claude Code que execute um comando em segundo plano

347* Pressionar `Ctrl+B` para mover uma invocação regular da ferramenta Bash para o segundo plano. Usuários de Tmux devem pressionar `Ctrl+B` duas vezes devido à chave de prefixo do tmux.347* Pressionar `Ctrl+B` para mover uma invocação regular da ferramenta Bash para o segundo plano. Usuários de Tmux devem pressionar `Ctrl+B` duas vezes devido à chave de prefixo do tmux.

348 348 

349Quando um comando atinge seu tempo limite antes de terminar, Claude Code o move automaticamente [para o segundo plano](/docs/pt/tools-reference#background-commands) em vez de interrompê-lo, a menos que o comando comece com `sleep`. Para alterar quanto tempo os comandos são executados antes disso acontecer, defina as [variáveis de ambiente de tempo limite do Bash](/docs/pt/tools-reference#timeout-and-output-limits).349Quando um comando atinge seu tempo limite antes de terminar, Claude Code o move automaticamente [para o segundo plano](/docs/pt/tools-reference#foreground-commands-that-move-to-the-background) em vez de interrompê-lo, a menos que o comando comece com `sleep`. Se você desativou tarefas em segundo plano com [`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS`](/docs/pt/env-vars#variables) ou iniciando em [modo bare](/docs/pt/headless#start-faster-with-bare-mode), o comando para em seu tempo limite. Para alterar o tempo limite, defina as [variáveis de ambiente de tempo limite do Bash](/docs/pt/tools-reference#timeout-and-output-limits).

350 350 

351**Recursos principais:**351**Recursos principais:**

352 352 


358* No macOS e Linux, Claude Code encerra as tarefas em segundo plano em execução quando o sistema operacional sinaliza pressão de memória crítica, desde que a sessão tenha ficado ociosa por pelo menos 30 minutos e nenhuma volta ou subagente esteja em execução. Requer Claude Code v2.1.193 ou posterior358* No macOS e Linux, Claude Code encerra as tarefas em segundo plano em execução quando o sistema operacional sinaliza pressão de memória crítica, desde que a sessão tenha ficado ociosa por pelo menos 30 minutos e nenhuma volta ou subagente esteja em execução. Requer Claude Code v2.1.193 ou posterior

359 * O [log de depuração](/docs/pt/debug-your-config) diz por que as tarefas foram interrompidas, ou por que um evento de pressão as deixou em execução359 * O [log de depuração](/docs/pt/debug-your-config) diz por que as tarefas foram interrompidas, ou por que um evento de pressão as deixou em execução

360 * Defina [`CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP`](/docs/pt/env-vars) como `1` para desativar paradas por pressão de memória360 * Defina [`CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP`](/docs/pt/env-vars) como `1` para desativar paradas por pressão de memória

361* Comandos Bash e PowerShell em segundo plano têm um limite de tempo, contado a partir do momento em que o comando entra em segundo plano: 30 minutos, ou o `timeout` que Claude solicita quando inicia um comando em segundo plano, até um máximo de 2 horas. Um comando que se move para o segundo plano enquanto é executado, por exemplo com `Ctrl+B`, recebe 30 minutos a partir da mudança. Quando um comando atinge seu limite, Claude Code o interrompe e diz a Claude por quê, e Claude pode iniciá-lo novamente com um `timeout` mais longo se o trabalho ainda precisar dele. Duas variáveis de ambiente aumentam os limites, em milissegundos, e nenhuma delas pode encurtá-los:361* Comandos Bash e PowerShell em segundo plano têm um limite de tempo, contado a partir do momento em que o comando entra em segundo plano: 30 minutos, ou o `timeout` que Claude solicita quando inicia um comando em segundo plano, até um máximo de 2 horas. Um comando que se move para o segundo plano enquanto é executado, por exemplo com `Ctrl+B`, recebe 30 minutos a partir da mudança. Quando um comando atinge seu limite, Claude Code o interrompe e diz a Claude por quê, e Claude pode iniciá-lo novamente com um `timeout` mais longo se o trabalho ainda precisar dele. Para aumentar os limites, veja [Aumentar o limite de tempo para comandos em segundo plano](/docs/pt/tools-reference#raise-the-time-limit-for-background-commands) na referência de ferramentas

362 * Defina [`BASH_DEFAULT_TIMEOUT_MS`](/docs/pt/env-vars) acima de `1800000` para substituir o padrão de 30 minutos por esse valor, para comandos movidos também362* Um comando em segundo plano que um [subagente](/docs/pt/sub-agents#run-subagents-in-foreground-or-background) em primeiro plano iniciou termina quando a execução desse subagente termina, independentemente de ter terminado, falhado ou sido interrompido; veja [Quando um comando em segundo plano para](/docs/pt/tools-reference#when-a-background-command-stops) na referência de ferramentas

363 * Defina [`BASH_MAX_TIMEOUT_MS`](/docs/pt/env-vars) acima de `7200000` para aumentar o máximo de 2 horas. Definir `BASH_DEFAULT_TIMEOUT_MS` acima de `7200000` aumenta-o da mesma forma

364* Um comando em segundo plano que um [subagente](/docs/pt/sub-agents#run-subagents-in-foreground-or-background) em primeiro plano iniciou termina quando a execução desse subagente termina, independentemente de ter terminado, falhado ou sido interrompido; veja [Comandos em segundo plano](/docs/pt/tools-reference#background-commands) na referência de ferramentas

365 363 

366Para desabilitar toda a funcionalidade de tarefas em segundo plano, defina a variável de ambiente `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` como `1`. Veja [Variáveis de ambiente](/docs/pt/env-vars) para detalhes.364Para desabilitar toda a funcionalidade de tarefas em segundo plano, defina a variável de ambiente [`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS`](/docs/pt/env-vars#variables) como `1`. Iniciar em [modo bare](/docs/pt/headless#start-faster-with-bare-mode) também desativa.

367 365 

368**Comandos comuns colocados em segundo plano:**366**Comandos comuns colocados em segundo plano:**

369 367 

keybindings.md +1 −3

Details

545* Sob um layout não-latino, como Cirílico, Claude Code corresponde aos atalhos de teclado Ctrl pela posição da tecla no layout US quando o terminal usa o protocolo de teclado Kitty e relata essa posição. Em tal terminal, com um layout russo ativo, pressionar Ctrl e a tecla W física dispara `ctrl+w`. Em um terminal que não relata a posição, Claude Code corresponde ao que o terminal envia para o pressionamento de tecla: um código de controle ASCII dispara o atalho de teclado latino, e um pressionamento de tecla que chega como o caractere cirílico não corresponde a nenhum atalho de teclado545* Sob um layout não-latino, como Cirílico, Claude Code corresponde aos atalhos de teclado Ctrl pela posição da tecla no layout US quando o terminal usa o protocolo de teclado Kitty e relata essa posição. Em tal terminal, com um layout russo ativo, pressionar Ctrl e a tecla W física dispara `ctrl+w`. Em um terminal que não relata a posição, Claude Code corresponde ao que o terminal envia para o pressionamento de tecla: um código de controle ASCII dispara o atalho de teclado latino, e um pressionamento de tecla que chega como o caractere cirílico não corresponde a nenhum atalho de teclado

546* Sob layouts que reorganizam letras latinas, como AZERTY, Claude Code corresponde à letra que a tecla digita, portanto pressionar Ctrl e a tecla rotulada A dispara `ctrl+a`546* Sob layouts que reorganizam letras latinas, como AZERTY, Claude Code corresponde à letra que a tecla digita, portanto pressionar Ctrl e a tecla rotulada A dispara `ctrl+a`

547 547 

548Antes da v2.1.247, pressionar um atalho de teclado Ctrl sob um layout não-latino não disparava seu atalho de teclado em terminais que usam o protocolo de teclado Kitty, como Ghostty, Kitty, WezTerm e iTerm2.

549 

550<h3 id="chords">548<h3 id="chords">

551 Acordes549 Acordes

552</h3>550</h3>


697* Modificadores com erro de digitação, como `ctl+k`. Claude Code descarta a parte que não reconhece e aplica a vinculação ao pressionamento de tecla que permanece, `k` neste exemplo.695* Modificadores com erro de digitação, como `ctl+k`. Claude Code descarta a parte que não reconhece e aplica a vinculação ao pressionamento de tecla que permanece, `k` neste exemplo.

698* Nomes de contexto inválidos696* Nomes de contexto inválidos

699* Valores de ação inválidos, como uma ação que não é uma string ou `null`697* Valores de ação inválidos, como uma ação que não é uma string ou `null`

700* Nomes de ação desconhecidos, como um erro de digitação de uma ação registrada. Claude Code pula a vinculação e mantém qualquer vinculação padrão para essa tecla em vigor. Antes da v2.1.246, uma vinculação com um nome de ação desconhecido desativava silenciosamente essa tecla698* Nomes de ação desconhecidos, como um erro de digitação de uma ação registrada. Claude Code pula a vinculação e mantém qualquer vinculação padrão para essa tecla em vigor.

701* Conflitos de atalho reservado699* Conflitos de atalho reservado

702* Vinculações duplicadas no mesmo contexto700* Vinculações duplicadas no mesmo contexto

703 701 

llm-gateway.md +2 −0

Details

45 45 

46[Implantar um gateway LLM para sua organização](/docs/pt/llm-gateway-rollout) percorre cada etapa e mostra os arquivos de configuração para distribuir em cada uma. O gateway é uma parte da configuração da organização; para aplicação de política, visibilidade de uso e decisões de tratamento de dados, consulte [Configurar Claude Code para sua organização](/docs/pt/admin-setup).46[Implantar um gateway LLM para sua organização](/docs/pt/llm-gateway-rollout) percorre cada etapa e mostra os arquivos de configuração para distribuir em cada uma. O gateway é uma parte da configuração da organização; para aplicação de política, visibilidade de uso e decisões de tratamento de dados, consulte [Configurar Claude Code para sua organização](/docs/pt/admin-setup).

47 47 

48Para fazer um gateway alcançado através de `ANTHROPIC_BASE_URL` o único destino que uma máquina gerenciada pode usar, defina [`allowedProviders`](/docs/pt/settings-reference#allowedproviders) como `["customEndpoint"]` no mesmo arquivo de configurações gerenciadas e coloque a `ANTHROPIC_BASE_URL` do gateway nesse bloco `env` do arquivo. Claude Code então recusa uma sessão apontada para qualquer outro lugar, incluindo diretamente para Anthropic ou para o próprio proxy de um desenvolvedor, e aceita `ANTHROPIC_BASE_URL` apenas com o valor que você definir lá. Para um gateway alcançado através de uma variável de endpoint específica do provedor, como `ANTHROPIC_BEDROCK_BASE_URL`, a entrada `allowedProviders` diz qual variável fixar. Requer Claude Code v2.1.285 ou posterior.

49 

48<h2 id="subscriptions-and-gateways">50<h2 id="subscriptions-and-gateways">

49 Assinaturas e gateways51 Assinaturas e gateways

50</h2>52</h2>

Details

310 310 

311Claude Code envia a solicitação de descoberta com ambos os headers de credencial abaixo e omite um header cujo valor não se resolve. Enviar ambos os headers requer Claude Code v2.1.248 ou posterior. Versões anteriores enviam apenas `Authorization` quando `ANTHROPIC_AUTH_TOKEN` é definido e apenas `x-api-key` caso contrário.311Claude Code envia a solicitação de descoberta com ambos os headers de credencial abaixo e omite um header cujo valor não se resolve. Enviar ambos os headers requer Claude Code v2.1.248 ou posterior. Versões anteriores enviam apenas `Authorization` quando `ANTHROPIC_AUTH_TOKEN` é definido e apenas `x-api-key` caso contrário.

312 312 

313* `Authorization`: `ANTHROPIC_AUTH_TOKEN` como um token bearer, caso contrário o valor [`apiKeyHelper`](/docs/pt/llm-gateway-connect#rotate-credentials-with-apikeyhelper) como um token bearer. Nesse caso, Claude Code aguarda o helper retornar antes de enviar a solicitação.313* `Authorization`: `ANTHROPIC_AUTH_TOKEN` como um token bearer, caso contrário o valor [`apiKeyHelper`](/docs/pt/llm-gateway-connect#rotate-credentials-with-apikeyhelper) como um token bearer.

314* `x-api-key`: a chave de API que Claude Code resolveu, como `ANTHROPIC_API_KEY`. Quando um valor helper é a única credencial, este header também o carrega, para que o valor chegue em ambos os headers.314* `x-api-key`: a chave de API que Claude Code resolveu, como `ANTHROPIC_API_KEY`. Quando um valor helper é a única credencial, este header também o carrega, para que o valor chegue em ambos os headers.

315 315 

316Claude Code também envia qualquer header de `ANTHROPIC_CUSTOM_HEADERS`. Quando um header customizado tem um valor não vazio, Claude Code o envia no lugar de um header integrado de mesmo nome, correspondendo nomes case-insensitively.316Claude Code também envia qualquer header de `ANTHROPIC_CUSTOM_HEADERS`. Quando um header customizado tem um valor não vazio, Claude Code o envia no lugar de um header integrado de mesmo nome, correspondendo nomes case-insensitively.

Details

199 199 

200As [chaves de login do gateway](#choose-a-delivery-mechanism) seguem uma regra separada. Claude Code nunca as lê de configurações gerenciadas pelo servidor, então enquanto configurações gerenciadas pelo servidor são a fonte selecionada, a fonte de administrador com classificação mais alta na máquina que carrega uma chave de política ainda as fornece. Um valor em uma fonte de administrador classificada abaixo daquela, ou no registro HKCU, é ignorado.200As [chaves de login do gateway](#choose-a-delivery-mechanism) seguem uma regra separada. Claude Code nunca as lê de configurações gerenciadas pelo servidor, então enquanto configurações gerenciadas pelo servidor são a fonte selecionada, a fonte de administrador com classificação mais alta na máquina que carrega uma chave de política ainda as fornece. Um valor em uma fonte de administrador classificada abaixo daquela, ou no registro HKCU, é ignorado.

201 201 

202[`allowedProviders`](/docs/pt/settings-reference#allowedproviders) tem sua própria regra: a nota Scope da entrada diz como uma lista definida na máquina se combina com uma gerenciada pelo servidor. Requer Claude Code v2.1.285 ou posterior.

203 

202Quando uma fonte de administrador define `allowManagedMcpServersOnly` ou uma lista `allowedMcpServers` e esse valor não é o que está em vigor, `/status` e `claude doctor` nomeiam essa fonte e chave.204Quando uma fonte de administrador define `allowManagedMcpServersOnly` ou uma lista `allowedMcpServers` e esse valor não é o que está em vigor, `/status` e `claude doctor` nomeiam essa fonte e chave.

203 205 

204<h3 id="compose-every-managed-source">206<h3 id="compose-every-managed-source">


353* Um arquivo de configurações gerenciadas vazio conta como `{}`.355* Um arquivo de configurações gerenciadas vazio conta como `{}`.

354* Um valor malformado na chave de registro HKCU gravável pelo usuário nunca bloqueia o lançamento. Claude Code o relata como um aviso em `/status` e `claude doctor` em vez disso.356* Um valor malformado na chave de registro HKCU gravável pelo usuário nunca bloqueia o lançamento. Claude Code o relata como um aviso em `/status` e `claude doctor` em vez disso.

355 357 

356Se um arquivo de configurações gerenciadas, arquivo drop-in ou diretório `managed-settings.d/` não puder ser lido e nenhuma fonte de administrador fornecer uma política, sessões conectadas com credenciais claude.ai ou Claude Console saem na inicialização com uma mensagem para contatar um administrador.358Quando um arquivo de configurações gerenciadas, arquivo drop-in, diretório `managed-settings.d/`, perfil MDM ou valor de registro HKLM existe mas não pode ser lido, e nenhuma fonte de administrador fornece uma política, o que acontece depende do motivo da falha de leitura:

359 

360* Se o sistema operacional negou a leitura, por exemplo em um arquivo somente raiz, cada sessão inicia sem as políticas dessa fonte. `/status` e `claude doctor` registram a falha, e uma execução com `-p` também a imprime para stderr.

361* Para qualquer outra falha de leitura, como um erro de E/S, cada sessão sai na inicialização com [uma mensagem para contatar um administrador](/docs/pt/errors#unable-to-read-managed-policy-settings).

357 362 

358Para encontrar uma entrada descartada, procure em um de três lugares:363Para encontrar uma entrada descartada, procure em um de três lugares:

359 364 


387| Campo | Comportamento quando presente mas inválido |392| Campo | Comportamento quando presente mas inválido |

388| :- | :- |393| :- | :- |

389| `allowedMcpServers` | Aplicado como uma lista de permissões vazia até que o valor seja corrigido, portanto nenhum servidor MCP que os usuários adicionem é admitido. Servidores que sua organização entrega através de [`managedMcpServers`](/docs/pt/settings-reference#managedmcpservers) ainda carregam, e servidores `managed-mcp.json` carregam por [Como um servidor é avaliado](/docs/pt/managed-mcp#how-a-server-is-evaluated). Uma entrada individual inválida é removida e o subconjunto válido é aplicado. |394| `allowedMcpServers` | Aplicado como uma lista de permissões vazia até que o valor seja corrigido, portanto nenhum servidor MCP que os usuários adicionem é admitido. Servidores que sua organização entrega através de [`managedMcpServers`](/docs/pt/settings-reference#managedmcpservers) ainda carregam, e servidores `managed-mcp.json` carregam por [Como um servidor é avaliado](/docs/pt/managed-mcp#how-a-server-is-evaluated). Uma entrada individual inválida é removida e o subconjunto válido é aplicado. |

395| [`allowedProviders`](/docs/pt/settings-reference#allowedproviders) | Aplicado como uma lista de permissões vazia até que o valor seja corrigido, portanto cada provedor de API é recusado e Claude Code não inicia na máquina. Se apenas uma entrada individual não for um nome de provedor conhecido, Claude Code descarta e relata essa entrada e aplica o resto. |

390| `allowedHttpHookUrls` | Claude Code aplica uma [lista de permissões](/docs/pt/settings-reference#allowedhttphookurls) gerenciada vazia até que você corrija o valor, portanto um hook HTTP é executado apenas se outro arquivo de configurações listar sua URL. Se apenas uma entrada individual for inválida, Claude Code remove essa entrada e aplica o resto. |396| `allowedHttpHookUrls` | Claude Code aplica uma [lista de permissões](/docs/pt/settings-reference#allowedhttphookurls) gerenciada vazia até que você corrija o valor, portanto um hook HTTP é executado apenas se outro arquivo de configurações listar sua URL. Se apenas uma entrada individual for inválida, Claude Code remove essa entrada e aplica o resto. |

391| `httpHookAllowedEnvVars` | Claude Code aplica uma [lista de permissões](/docs/pt/settings-reference#httphookallowedenvvars) gerenciada vazia até que você corrija o valor, portanto uma variável de cabeçalho é interpolada apenas se outro arquivo de configurações a nomear. Se apenas uma entrada individual for inválida, Claude Code remove essa entrada e aplica o resto. |397| `httpHookAllowedEnvVars` | Claude Code aplica uma [lista de permissões](/docs/pt/settings-reference#httphookallowedenvvars) gerenciada vazia até que você corrija o valor, portanto uma variável de cabeçalho é interpolada apenas se outro arquivo de configurações a nomear. Se apenas uma entrada individual for inválida, Claude Code remove essa entrada e aplica o resto. |

392| `allowedChannelPlugins` | Claude Code aplica uma lista de permissões vazia até que você corrija o valor, portanto nenhum plugin de canal passado para `--channels` é admitido. Se apenas uma entrada individual for inválida, ele remove essa entrada e aplica o resto. |398| `allowedChannelPlugins` | Claude Code aplica uma lista de permissões vazia até que você corrija o valor, portanto nenhum plugin de canal passado para `--channels` é admitido. Se apenas uma entrada individual for inválida, ele remove essa entrada e aplica o resto. |


437 443 

438A maioria delas são bloqueios: o valor que um bloqueio governa, como regras de permissão ou `sandbox.network.allowedDomains`, é uma chave ordinária que qualquer nível pode definir, e o bloqueio diz ao Claude Code para honrar apenas o valor gerenciado.444A maioria delas são bloqueios: o valor que um bloqueio governa, como regras de permissão ou `sandbox.network.allowedDomains`, é uma chave ordinária que qualquer nível pode definir, e o bloqueio diz ao Claude Code para honrar apenas o valor gerenciado.

439 445 

440A tabela cobre os controles de permissão, plugin e entrega. Para qualquer chave não listada aqui, a coluna Escopo da [referência de configurações](/docs/pt/settings-reference#all-settings) diz se é apenas gerenciada; as chaves apenas gerenciadas restantes lá incluem a URL de login do gateway, versão, navegador, simulador móvel, host SSH, sessão local do Desktop, caminho binário da sandbox, preço do modelo, restrição de modelo e controles CLAUDE.md.446A tabela cobre os controles de permissão, plugin e entrega. Para qualquer chave não listada aqui, a coluna Escopo da [referência de configurações](/docs/pt/settings-reference#all-settings) diz se é apenas gerenciada.

441 447 

442| Configuração | Descrição |448| Configuração | Descrição |

443| :- | :- |449| :- | :- |

mcp.md +5 −5

Details

273 273 

274* ``⏸ Pending approval (run `claude` to approve)``: um servidor com escopo de projeto de `.mcp.json` que você ainda não aprovou. Claude Code o mostra em `claude mcp list` e `claude mcp get <name>`. Execute `claude` interativamente para revisar e aprovar.274* ``⏸ Pending approval (run `claude` to approve)``: um servidor com escopo de projeto de `.mcp.json` que você ainda não aprovou. Claude Code o mostra em `claude mcp list` e `claude mcp get <name>`. Execute `claude` interativamente para revisar e aprovar.

275* `✘ Rejected (see disabledMcpjsonServers in settings)`: um servidor `.mcp.json` que uma entrada [`disabledMcpjsonServers`](/docs/pt/settings-reference#disabledmcpjsonservers) rejeita. Claude Code o mostra apenas em `claude mcp get <name>`.275* `✘ Rejected (see disabledMcpjsonServers in settings)`: um servidor `.mcp.json` que uma entrada [`disabledMcpjsonServers`](/docs/pt/settings-reference#disabledmcpjsonservers) rejeita. Claude Code o mostra apenas em `claude mcp get <name>`.

276* `⊘ Disabled for this project (re-enable via /mcp)`: um servidor que a lista [`disabledMcpServers`](#disable-a-server-without-removing-it) do projeto nomeia. Claude Code o mostra em `claude mcp list` e `claude mcp get <name>`. Ative o servidor novamente no painel `/mcp`. Antes da v2.1.238, ambos os comandos se conectavam a um servidor desabilitado para verificar sua saúde e relatavam o resultado da conexão.276* `⊘ Disabled for this project (re-enable via /mcp)`: um servidor que a lista [`disabledMcpServers`](#disable-a-server-without-removing-it) do projeto nomeia. Claude Code o mostra em `claude mcp list` e `claude mcp get <name>`. Ative o servidor novamente no painel `/mcp`.

277 277 

278Os servidores WebSocket não aparecem na saída de `claude mcp list`. Use `claude mcp get <name>` ou o painel `/mcp` para verificá-los.278Os servidores WebSocket não aparecem na saída de `claude mcp list`. Use `claude mcp get <name>` ou o painel `/mcp` para verificá-los.

279 279 


321 321 

322* **Espaço em branco oculto**: Claude Code avisa quando um valor de configuração MCP carrega espaço em branco oculto à esquerda ou à direita, que frequentemente vem de colar um token com uma quebra de linha à direita. Claude Code verifica `command`, `url`, cada entrada `args`, e os valores e nomes de chave sob `env` e `headers`. Claude Code mostra o aviso na saída de `claude mcp list` e em `/mcp`, nomeando os campos afetados sem ecoar seus valores, por exemplo `Leading or trailing whitespace in: headers.Authorization`. Claude Code não aparenta o espaço em branco e usa os valores exatamente como escritos, portanto edite a configuração para removê-lo.322* **Espaço em branco oculto**: Claude Code avisa quando um valor de configuração MCP carrega espaço em branco oculto à esquerda ou à direita, que frequentemente vem de colar um token com uma quebra de linha à direita. Claude Code verifica `command`, `url`, cada entrada `args`, e os valores e nomes de chave sob `env` e `headers`. Claude Code mostra o aviso na saída de `claude mcp list` e em `/mcp`, nomeando os campos afetados sem ecoar seus valores, por exemplo `Leading or trailing whitespace in: headers.Authorization`. Claude Code não aparenta o espaço em branco e usa os valores exatamente como escritos, portanto edite a configuração para removê-lo.

323* **Mesmo nome em mais de um escopo**: se você definir o mesmo nome de servidor em mais de um [escopo](#mcp-installation-scopes) com endpoints diferentes, Claude Code avisa sobre o conflito na saída de `claude mcp list` e em `/mcp`. Claude Code armazena logins OAuth por endpoint, portanto quando você autentica a definição que carrega em um projeto, você ainda precisa fazer login separadamente em um projeto onde uma definição diferente carrega. Mantenha o endpoint que você quer e remova os outros com `claude mcp remove <name> --scope <scope>`. No aviso, Claude Code cita o endpoint de cada escopo como escrito em sua configuração, com referências [`${VAR}`](#environment-variable-expansion-in-mcp-json) não expandidas, portanto nunca mostra um valor resolvido como uma chave de API.323* **Mesmo nome em mais de um escopo**: se você definir o mesmo nome de servidor em mais de um [escopo](#mcp-installation-scopes) com endpoints diferentes, Claude Code avisa sobre o conflito na saída de `claude mcp list` e em `/mcp`. Claude Code armazena logins OAuth por endpoint, portanto quando você autentica a definição que carrega em um projeto, você ainda precisa fazer login separadamente em um projeto onde uma definição diferente carrega. Mantenha o endpoint que você quer e remova os outros com `claude mcp remove <name> --scope <scope>`. No aviso, Claude Code cita o endpoint de cada escopo como escrito em sua configuração, com referências [`${VAR}`](#environment-variable-expansion-in-mcp-json) não expandidas, portanto nunca mostra um valor resolvido como uma chave de API.

324* **Nomes reservados**: Claude Code reserva os nomes de seus servidores integrados, incluindo `workspace`, `claude-in-chrome`, `computer-use`, `Claude Preview`, e `Claude Browser`. Se sua configuração definir um servidor com um nome reservado, Claude Code o pula no tempo de carregamento e mostra um aviso pedindo que você o renomeie. `claude mcp add` rejeita um nome reservado com um erro. `Claude Preview` e `Claude Browser` ambos nomeiam o servidor integrado que o [painel de visualização do aplicativo de desktop Claude Code](/docs/pt/desktop#preview-your-app) usa. Antes da v2.1.205, `Claude Browser` não era reservado, portanto um servidor configurado pelo usuário poderia se registrar sob esse nome.324* **Nomes reservados**: Claude Code reserva os nomes de seus servidores integrados, incluindo `workspace`, `claude-in-chrome`, `computer-use`, `Claude Preview`, e `Claude Browser`. Se sua configuração definir um servidor com um nome reservado, Claude Code o pula no tempo de carregamento e mostra um aviso pedindo que você o renomeie. `claude mcp add` rejeita um nome reservado com um erro. `Claude Preview` e `Claude Browser` ambos nomeiam o servidor integrado que o [painel de visualização do aplicativo de desktop Claude Code](/docs/pt/desktop#preview-your-app) usa.

325* **Variável de ambiente ausente**: se uma referência [`${VAR}`](#environment-variable-expansion-in-mcp-json) na configuração de um servidor nomeia uma variável que não está definida e não tem `:-default`, Claude Code avisa na saída de `claude mcp list` e em `/mcp`, nomeando a variável, e ainda carrega o servidor com o texto `${VAR}` não expandido. Defina a variável ou adicione um fallback `${VAR:-default}`. Em uma URL remota do servidor e `headers`, algumas variáveis de credenciais [leem como vazias](#credential-variables-that-read-as-empty) em vez disso, sem aviso.325* **Variável de ambiente ausente**: se uma referência [`${VAR}`](#environment-variable-expansion-in-mcp-json) na configuração de um servidor nomeia uma variável que não está definida e não tem `:-default`, Claude Code avisa na saída de `claude mcp list` e em `/mcp`, nomeando a variável, e ainda carrega o servidor com o texto `${VAR}` não expandido. Defina a variável ou adicione um fallback `${VAR:-default}`. Em uma URL remota do servidor e `headers`, algumas variáveis de credenciais [leem como vazias](#credential-variables-that-read-as-empty) em vez disso, sem aviso.

326 326 

327<h4 id="tool-availability">327<h4 id="tool-availability">


417 Failed first connections417 Failed first connections

418</h4>418</h4>

419 419 

420Quando a primeira conexão de um servidor HTTP ou SSE falha com um erro transitório, como uma resposta 5xx, uma conexão recusada, ou um tempo limite, Claude Code tenta novamente até três vezes. Se a conexão ainda falhar, Claude Code marca o servidor como com falha. Claude Code tenta novamente dessa forma na inicialização e quando um servidor é adicionado no meio da sessão. Isso inclui um servidor que Claude Code adiciona a uma [sessão em nuvem](/docs/pt/claude-code-on-the-web) de sua configuração e um servidor que você adiciona com o [`setMcpServers()`](/docs/pt/agent-sdk/typescript) do Agent SDK.420Quando a primeira conexão de um servidor HTTP ou SSE falha com um erro transitório, como uma resposta 5xx, uma conexão recusada, ou um tempo limite, Claude Code tenta novamente até três vezes. Se a conexão ainda falhar, Claude Code marca o servidor como com falha.

421 421 

422Claude Code não tenta novamente nestes casos:422Claude Code não tenta novamente nestes casos:

423 423 


553 553 

554Os servidores de plugin aparecem em `/mcp` com indicadores mostrando que vêm de plugins.554Os servidores de plugin aparecem em `/mcp` com indicadores mostrando que vêm de plugins.

555 555 

556Para um servidor stdio de um plugin, `claude mcp get` imprime `Command: stdio`, uma linha `Args:` vazia, e cada variável de ambiente como `NAME=[REDACTED]`. Os valores são ocultados porque podem carregar credenciais.

557 

556**Nomes de ferramentas MCP de plugin**:558**Nomes de ferramentas MCP de plugin**:

557 559 

558As ferramentas de um servidor MCP agrupado em plugin incluem tanto o nome do plugin quanto a chave do servidor em seu nome chamável. A forma completa é `mcp__plugin_<plugin-name>_<server-name>__<tool-name>`, onde qualquer caractere fora de `A-Z`, `a-z`, `0-9`, `_`, e `-` é substituído por `_`. Para o servidor `database-tools` agrupado em um plugin nomeado `my-plugin`, uma ferramenta `query` é chamável como:560As ferramentas de um servidor MCP agrupado em plugin incluem tanto o nome do plugin quanto a chave do servidor em seu nome chamável. A forma completa é `mcp__plugin_<plugin-name>_<server-name>__<tool-name>`, onde qualquer caractere fora de `A-Z`, `a-z`, `0-9`, `_`, e `-` é substituído por `_`. Para o servidor `database-tools` agrupado em um plugin nomeado `my-plugin`, uma ferramenta `query` é chamável como:


1458* Os nomes de propriedades de nível superior devem ter de 1 a 64 caracteres e usar apenas letras ASCII e dígitos, `_`, `.` e `-`1460* Os nomes de propriedades de nível superior devem ter de 1 a 64 caracteres e usar apenas letras ASCII e dígitos, `_`, `.` e `-`

1459* O esquema deve ser válido em relação ao meta-esquema JSON Schema draft 2020-12. Claude Code aplica essa verificação a esquemas que não declaram `$schema` e esquemas que declaram draft 2020-12. Um esquema que declara qualquer outro dialeto ignora essa verificação, embora a verificação de nome de propriedade acima ainda se aplique1461* O esquema deve ser válido em relação ao meta-esquema JSON Schema draft 2020-12. Claude Code aplica essa verificação a esquemas que não declaram `$schema` e esquemas que declaram draft 2020-12. Um esquema que declara qualquer outro dialeto ignora essa verificação, embora a verificação de nome de propriedade acima ainda se aplique

1460 1462 

1461Claude Code executa as verificações após a [reescrita do combinador de nível raiz](#tool-input-schemas-with-a-root-level-combinator), no esquema que realmente enviaria.

1462 

1463Quando Claude Code exclui uma ferramenta, registra o motivo no log do servidor e informa ao Claude quais ferramentas foram excluídas e por quê, para que você possa perguntar ao Claude por que uma ferramenta está faltando. Se você corrigir o esquema no servidor, a ferramenta reaparece na próxima vez que Claude Code carregar as ferramentas do servidor.1463Quando Claude Code exclui uma ferramenta, registra o motivo no log do servidor e informa ao Claude quais ferramentas foram excluídas e por quê, para que você possa perguntar ao Claude por que uma ferramenta está faltando. Se você corrigir o esquema no servidor, a ferramenta reaparece na próxima vez que Claude Code carregar as ferramentas do servidor.

1464 1464 

1465Claude Code ativa a exclusão através de um sinalizador de recurso que busca da Anthropic. Em uma [implantação onde a busca de sinalizadores está desativada](/docs/pt/env-vars#features-that-need-feature-flag-fetching), ou em uma máquina cujos sinalizadores nunca chegaram, como uma máquina isolada, Claude Code ainda executa as verificações e registra no log do servidor qual ferramenta seria rejeitada, mas envia o esquema da ferramenta para a API mesmo assim. A API rejeita uma solicitação que inclua esse esquema com [um erro 400 nomeando a ferramenta por sua posição](/docs/pt/errors#tool-input-schema-is-invalid). Antes da v2.1.216, nenhuma implantação executava essas verificações.1465Claude Code ativa a exclusão através de um sinalizador de recurso que busca da Anthropic. Em uma [implantação onde a busca de sinalizadores está desativada](/docs/pt/env-vars#features-that-need-feature-flag-fetching), ou em uma máquina cujos sinalizadores nunca chegaram, como uma máquina isolada, Claude Code ainda executa as verificações e registra no log do servidor qual ferramenta seria rejeitada, mas envia o esquema da ferramenta para a API mesmo assim. A API rejeita uma solicitação que inclua esse esquema com [um erro 400 nomeando a ferramenta por sua posição](/docs/pt/errors#tool-input-schema-is-invalid). Antes da v2.1.216, nenhuma implantação executava essas verificações.

Details

360 360 

361 O que acontece a seguir diz onde o problema está:361 O que acontece a seguir diz onde o problema está:

362 362 

363 * O comando inicia e aguarda entrada: o servidor em si funciona. Execute `claude mcp get <name>` e confirme que o comando mostrado lá corresponde ao que você acabou de executar. Se o comando mostrado diferir do que você digitou, você provavelmente omitiu o separador `--` antes do comando do servidor. Remova o servidor e readicione-o com `--` no lugar. Se você escreveu `.mcp.json` à mão, verifique sua sintaxe e localização.363 * O comando inicia e aguarda entrada: o servidor em si funciona.

364 

365 Execute `claude mcp get <name>` e confirme que o comando mostrado lá corresponde ao que você acabou de executar. Se o comando mostrado diferir do que você digitou, você provavelmente omitiu o separador `--` antes do comando do servidor. Remova o servidor e readicione-o com `--` no lugar. Se você escreveu `.mcp.json` à mão, verifique sua sintaxe e localização. Antes da v2.1.285, `claude mcp get` não imprimia nenhuma linha `Command` para uma entrada stdio salva sem um campo `type`, como uma entrada `.mcp.json` escrita à mão. Nessas versões, execute `claude mcp list` em vez disso, que imprime a linha de comando de qualquer forma.

364 * O comando erros: a mensagem nomeia o que está faltando, como Node.js ou um navegador.366 * O comando erros: a mensagem nomeia o que está faltando, como Node.js ou um navegador.

365 </Accordion>367 </Accordion>

366 368 

model-config.md +10 −5

Details

39| **`sonnet`** | Usa o modelo Sonnet mais recente para tarefas diárias de codificação |39| **`sonnet`** | Usa o modelo Sonnet mais recente para tarefas diárias de codificação |

40| **`opus`** | Usa o modelo Opus mais recente para tarefas de raciocínio complexo |40| **`opus`** | Usa o modelo Opus mais recente para tarefas de raciocínio complexo |

41| **`haiku`** | Usa o modelo Haiku rápido e eficiente para tarefas simples |41| **`haiku`** | Usa o modelo Haiku rápido e eficiente para tarefas simples |

42| **`sonnet[1m]`** | Usa Sonnet com uma [janela de contexto de 1 milhão de tokens](https://platform.claude.com/docs/en/build-with-claude/context-windows#context-window-sizes-by-model) para sessões longas. Sem efeito quando `sonnet` já é resolvido para Sonnet 5.5 ou Sonnet 5 com sua janela nativa de 1M; atrás de um [gateway LLM](/docs/pt/llm-gateway), seleciona a janela de 1M para esse modelo |42| **`sonnet[1m]`** | Usa Sonnet com uma [janela de contexto de 1 milhão de tokens](https://platform.claude.com/docs/en/build-with-claude/context-windows#context-window-sizes-by-model) para sessões longas. Sem efeito quando `sonnet` já é resolvido para Sonnet 5.5 ou Sonnet 5 com sua janela nativa de 1M |

43| **`opus[1m]`** | Usa Opus com uma [janela de contexto de 1 milhão de tokens](https://platform.claude.com/docs/en/build-with-claude/context-windows#context-window-sizes-by-model) para sessões longas |43| **`opus[1m]`** | Usa Opus com uma [janela de contexto de 1 milhão de tokens](https://platform.claude.com/docs/en/build-with-claude/context-windows#context-window-sizes-by-model) para sessões longas |

44| **`opusplan`** | Modo especial que usa `opus` durante o Plan Mode, depois muda para `sonnet` para execução |44| **`opusplan`** | Modo especial que usa `opus` durante o Plan Mode, depois muda para `sonnet` para execução |

45 45 


521 Cadeias de modelo de fallback521 Cadeias de modelo de fallback

522</h3>522</h3>

523 523 

524Quando o modelo primário está sobrecarregado, indisponível ou retorna outro erro de servidor não repetível, Claude Code pode alternar para um modelo de fallback em vez de falhar na solicitação. Autenticação, faturamento, limite de taxa, tamanho de solicitação e erros de transporte, e uma [negação pela verificação de política da sua organização](/docs/pt/errors#automatic-retries), nunca acionam uma alternância; esses seguem sua manipulação normal de repetição e erro.524Quando o modelo primário está sobrecarregado, indisponível ou retorna outro erro de servidor não repetível, Claude Code pode alternar para um modelo de fallback em vez de falhar na solicitação. Autenticação, faturamento, limite de taxa, tamanho de solicitação e erros de transporte, e uma [negação pela verificação de política da sua organização](/docs/pt/errors#automatic-retries), nunca acionam uma alternância; esses seguem sua manipulação normal de repetição e erro. Ele alterna quando [Amazon Bedrock](/docs/pt/amazon-bedrock#when-a-model-is-disabled-mid-session) ou [Google Cloud's Agent Platform](/docs/pt/google-vertex-ai#when-a-model-is-disabled-mid-session) recusa um modelo que sua conta não pode invocar, o que Claude Code trata como o modelo estar indisponível em vez de um erro de autenticação.

525 525 

526Configure um ou mais modelos de fallback e Claude Code os tenta em ordem, mostrando um aviso quando alterna. A alternância dura apenas para o turno atual, portanto sua próxima mensagem tenta o modelo primário primeiro novamente. Claude Code limita cadeias a três modelos após remoção de duplicatas e ignora entradas extras.526Configure um ou mais modelos de fallback e Claude Code os tenta em ordem, mostrando um aviso quando alterna. A alternância dura apenas para o turno atual, portanto sua próxima mensagem tenta o modelo primário primeiro novamente. Claude Code limita cadeias a três modelos após remoção de duplicatas e ignora entradas extras.

527 527 


775 775 

776Claude Code verifica esses requisitos de plano apenas quando se conecta diretamente à Anthropic API. Se você apontar `ANTHROPIC_BASE_URL` para um [gateway LLM](/docs/pt/llm-gateway#subscriptions-and-gateways) e seu login claude.ai salvo permanecer a credencial ativa, Claude Code não verifica seus créditos de uso do plano. As opções `[1m]` permanecem disponíveis em `/model`, e o gateway decide se a solicitação é bem-sucedida. Antes da v2.1.229, Claude Code rejeitava `/model sonnet[1m]` nessa configuração quando não conseguia confirmar créditos de uso na conta.776Claude Code verifica esses requisitos de plano apenas quando se conecta diretamente à Anthropic API. Se você apontar `ANTHROPIC_BASE_URL` para um [gateway LLM](/docs/pt/llm-gateway#subscriptions-and-gateways) e seu login claude.ai salvo permanecer a credencial ativa, Claude Code não verifica seus créditos de uso do plano. As opções `[1m]` permanecem disponíveis em `/model`, e o gateway decide se a solicitação é bem-sucedida. Antes da v2.1.229, Claude Code rejeitava `/model sonnet[1m]` nessa configuração quando não conseguia confirmar créditos de uso na conta.

777 777 

778<span id="context-window-behind-a-gateway" />

779 

780Se você definir `ANTHROPIC_BASE_URL` para um [gateway LLM](/docs/pt/llm-gateway) ou outro proxy, Claude Code dá a cada modelo que reconhece a mesma janela de contexto que o modelo tem na Anthropic API. Fable 5.1, Fable 5, Sonnet 5 e posterior, e Opus 4.7 e posterior recebem a janela de 1M sem nenhuma variante `[1m]` para selecionar, e um modelo que alcança 1M apenas através de sua variante `[1m]`, como Opus 4.6, é executado em 200K sem ela. Claude Code não pode detectar um limite inferior que o gateway ou o servidor atrás dele impõe. Se seu gateway rejeita solicitações acima de 200K tokens, execute [`/autocompact 200k`](#set-the-auto-compact-window) para que as sessões compactem nesse limite.

781 

778Para desativar contexto de 1M, defina `CLAUDE_CODE_DISABLE_1M_CONTEXT=1`. Claude Code remove variantes de modelo de 1M do seletor de modelo. Em modelos com uma janela nativa de 1M, como Sonnet 5 e os modelos Fable, também trata o modelo como tendo uma janela de contexto de 200K:782Para desativar contexto de 1M, defina `CLAUDE_CODE_DISABLE_1M_CONTEXT=1`. Claude Code remove variantes de modelo de 1M do seletor de modelo. Em modelos com uma janela nativa de 1M, como Sonnet 5 e os modelos Fable, também trata o modelo como tendo uma janela de contexto de 200K:

779 783 

780* Com compactação automática ativada, sessões compactam no limite de 200K através de [compactação automática](#set-the-auto-compact-window). Definir a janela de compactação automática acima de 200K não levanta a retenção, porque Claude Code limita essa janela à janela de contexto do modelo.784* Com compactação automática ativada, sessões compactam no limite de 200K através de [compactação automática](#set-the-auto-compact-window). Definir a janela de compactação automática acima de 200K não levanta a retenção, porque Claude Code limita essa janela à janela de contexto do modelo.


803 807 

804Na Anthropic API, Sonnet 5.5 e Sonnet 5 sempre são executados com a janela de contexto de 1M. Não há variante de 200K, nenhum sufixo `[1m]` para selecionar e nenhum crédito de uso necessário em nenhum plano. Sessões compactam automaticamente antes da janela preencher, em cerca de 967K tokens por padrão; defina [`CLAUDE_CODE_AUTO_COMPACT_WINDOW`](/docs/pt/env-vars) para escolher um limite diferente.808Na Anthropic API, Sonnet 5.5 e Sonnet 5 sempre são executados com a janela de contexto de 1M. Não há variante de 200K, nenhum sufixo `[1m]` para selecionar e nenhum crédito de uso necessário em nenhum plano. Sessões compactam automaticamente antes da janela preencher, em cerca de 967K tokens por padrão; defina [`CLAUDE_CODE_AUTO_COMPACT_WINDOW`](/docs/pt/env-vars) para escolher um limite diferente.

805 809 

806Duas configurações orçam a janela em 200K:810Claude Code dá a Sonnet 5.5 e Sonnet 5 a mesma janela de 1M atrás de um [gateway LLM](/docs/pt/llm-gateway) ou outro `ANTHROPIC_BASE_URL` personalizado. Se seu gateway impõe um limite inferior, consulte [a janela de contexto atrás de um gateway](#context-window-behind-a-gateway).

811 

812Esta configuração orça a janela em 200K em vez disso:

807 813 

808* **Gateway LLM**: quando `ANTHROPIC_BASE_URL` aponta para um [gateway](/docs/pt/llm-gateway), Claude Code não pode verificar suporte a 1M. Para usar a janela completa, selecione Sonnet 5.5 (1M context) no seletor de modelo, que mapeia para `sonnet[1m]`, ou execute `/model claude-sonnet-5[1m]` para Sonnet 5.

809* **`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`**: mantém sessões em cada modelo com uma janela nativa de 1M em uma janela de 200K; consulte [Contexto estendido](#extended-context) para como a retenção é aplicada. Útil para implantações que precisam limitar contexto.814* **`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`**: mantém sessões em cada modelo com uma janela nativa de 1M em uma janela de 200K; consulte [Contexto estendido](#extended-context) para como a retenção é aplicada. Útil para implantações que precisam limitar contexto.

810 815 

811<h2 id="context-window-and-auto-compaction">816<h2 id="context-window-and-auto-compaction">


841* [Sessões em nuvem](/docs/pt/claude-code-on-the-web) compactam conforme a conversa se aproxima do limite do modelo846* [Sessões em nuvem](/docs/pt/claude-code-on-the-web) compactam conforme a conversa se aproxima do limite do modelo

842* Sonnet 4.6 e Opus 4.6 sem [contexto estendido](#extended-context) compactam no limite de 200K, e assim fazem Opus 4.8 e posteriores quando executam com uma janela de contexto de 200K, como no Amazon Bedrock, na Plataforma de Agentes do Google Cloud e no Microsoft Foundry847* Sonnet 4.6 e Opus 4.6 sem [contexto estendido](#extended-context) compactam no limite de 200K, e assim fazem Opus 4.8 e posteriores quando executam com uma janela de contexto de 200K, como no Amazon Bedrock, na Plataforma de Agentes do Google Cloud e no Microsoft Foundry

843* Quando você define [`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`](/docs/pt/env-vars), modelos com uma janela nativa de 1M, como Sonnet 5 e os modelos Fable, compactam no limite de 200K848* Quando você define [`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`](/docs/pt/env-vars), modelos com uma janela nativa de 1M, como Sonnet 5 e os modelos Fable, compactam no limite de 200K

844* Modelos executando com uma janela nativa de 1M, como Sonnet 5, os modelos Fable e Opus 4.7 e posteriores na API Anthropic, compactam antes da janela se encher, em aproximadamente 967K tokens por padrão. No Amazon Bedrock, na Plataforma de Agentes do Google Cloud e no Microsoft Foundry, [Fixar modelos para implantações de terceiros](#pin-models-for-third-party-deployments) diz quais modelos executam com essa janela; para as configurações que orçam Sonnet 5.5 e Sonnet 5 em 200K em vez disso, consulte [Janela de contexto Sonnet 5.5 e Sonnet 5](#sonnet-5-5-and-sonnet-5-context-window)849* Modelos executando com uma janela nativa de 1M compactam antes da janela se encher, em aproximadamente 967K tokens por padrão. Na API Anthropic, estes incluem Sonnet 5, os modelos Fable e Opus 4.7 e posteriores. No Amazon Bedrock, na Plataforma de Agentes do Google Cloud e no Microsoft Foundry, consulte [Fixar modelos para implantações de terceiros](#pin-models-for-third-party-deployments) para saber quais modelos executam com essa janela. Atrás de uma `ANTHROPIC_BASE_URL` personalizada, consulte [a janela de contexto atrás de um gateway](#context-window-behind-a-gateway)

845* Sessões em um ID de modelo que Claude Code não reconhece, como um alias de [gateway LLM](/docs/pt/llm-gateway), compactam na janela de contexto que Claude Code assume para o ID; consulte [Corrigir a janela para um gateway ou ID de modelo personalizado](#correct-the-window-for-a-gateway-or-custom-model-id)850* Sessões em um ID de modelo que Claude Code não reconhece, como um alias de [gateway LLM](/docs/pt/llm-gateway), compactam na janela de contexto que Claude Code assume para o ID; consulte [Corrigir a janela para um gateway ou ID de modelo personalizado](#correct-the-window-for-a-gateway-or-custom-model-id)

846 851 

847<h3 id="correct-the-window-for-a-gateway-or-custom-model-id">852<h3 id="correct-the-window-for-a-gateway-or-custom-model-id">

Details

1430* `error.type`: por que Claude Code parou a sessão. Presente apenas em eventos `refused`:1430* `error.type`: por que Claude Code parou a sessão. Presente apenas em eventos `refused`:

1431 * `"helper_failed"`: uma [execução de auxiliar de política falhou](/docs/pt/settings-reference#helper-failures)1431 * `"helper_failed"`: uma [execução de auxiliar de política falhou](/docs/pt/settings-reference#helper-failures)

1432 * `"policy_invalid"`: as configurações gerenciadas contêm um erro que para Claude Code de iniciar, ou uma fonte de admin falhou em carregar, então Claude Code não pode verificar a imposição de login da organização1432 * `"policy_invalid"`: as configurações gerenciadas contêm um erro que para Claude Code de iniciar, ou uma fonte de admin falhou em carregar, então Claude Code não pode verificar a imposição de login da organização

1433 * `"provider_not_allowed"`: a sessão usaria um provedor de API, ou enviaria o tráfego de um provedor para um host, que a lista [`allowedProviders`](/docs/pt/settings-reference#allowedproviders) gerenciada não permite. Requer Claude Code v2.1.285 ou posterior

1433 * `"consent_rejected"`: o usuário rejeitou o [diálogo de aprovação de segurança](/docs/pt/server-managed-settings#security-approval-dialogs) para configurações gerenciadas pelo servidor1434 * `"consent_rejected"`: o usuário rejeitou o [diálogo de aprovação de segurança](/docs/pt/server-managed-settings#security-approval-dialogs) para configurações gerenciadas pelo servidor

1434 * `"force_refresh_failed"`: a busca de configurações que [`forceRemoteSettingsRefresh`](/docs/pt/settings-reference#forceremotesettingsrefresh) requer falhou1435 * `"force_refresh_failed"`: a busca de configurações que [`forceRemoteSettingsRefresh`](/docs/pt/settings-reference#forceremotesettingsrefresh) requer falhou

1435 * `"gateway_rejected"`: um [gateway de aplicativos Claude](/docs/pt/claude-apps-gateway) respondeu ao carregamento de configurações gerenciadas com HTTP 4031436 * `"gateway_rejected"`: um [gateway de aplicativos Claude](/docs/pt/claude-apps-gateway) respondeu ao carregamento de configurações gerenciadas com HTTP 403

Details

246| `storage.googleapis.com` | Instalador nativo e atualizador automático nativo em versões anteriores a 2.1.116 |246| `storage.googleapis.com` | Instalador nativo e atualizador automático nativo em versões anteriores a 2.1.116 |

247| `registry.npmjs.org` | Instalações de plugins (buscando pacotes de plugins de origem npm e instalando dependências de pacotes Node.js de plugins), servidores MCP iniciados com `npx` e o registro de pacotes para instalações npm e bun do próprio Claude Code |247| `registry.npmjs.org` | Instalações de plugins (buscando pacotes de plugins de origem npm e instalando dependências de pacotes Node.js de plugins), servidores MCP iniciados com `npx` e o registro de pacotes para instalações npm e bun do próprio Claude Code |

248| `bridge.claudeusercontent.com` | Ponte WebSocket da [extensão Claude no Chrome](/docs/pt/chrome) |248| `bridge.claudeusercontent.com` | Ponte WebSocket da [extensão Claude no Chrome](/docs/pt/chrome) |

249| `*.frame.claudeusercontent.com` | Leituras de conteúdo de [Artifact](/docs/pt/artifacts). A CLI busca os arquivos de um artifact deste host quando Claude abre um, e apenas quando a ferramenta Artifact está [disponível](/docs/pt/artifacts#availability) para sua conta. Para desativar a ferramenta e remover este requisito, defina [`"enableArtifact": false`](/docs/pt/settings-reference#enableartifact) ou [`CLAUDE_CODE_DISABLE_ARTIFACT=1`](/docs/pt/env-vars); Claude Code também honra a configuração [`disableArtifact`](/docs/pt/settings-reference#disableartifact) descontinuada. Consulte [Desabilitar artifacts](/docs/pt/artifacts#disable-artifacts) para saber como essas configurações interagem |249| `*.frame.claudeusercontent.com` | Leituras de conteúdo de [Artifact](/docs/pt/artifacts). A CLI busca os arquivos de um artifact deste host quando Claude abre um, e apenas quando a ferramenta Artifact está [disponível](/docs/pt/artifacts#availability) para sua conta. Para desativar a ferramenta e remover este requisito, defina [`"enableArtifact": false`](/docs/pt/settings-reference#enableartifact) ou [`CLAUDE_CODE_DISABLE_ARTIFACT=1`](/docs/pt/env-vars) |

250| `github.com` | Clonagem de [marketplaces de plugins](/docs/pt/plugins/overview) e plugins hospedados no GitHub, incluindo o marketplace oficial da Anthropic, via HTTPS ou SSH. Para clonar fontes `owner/repo` do GitHub apenas via HTTPS, defina [`CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1`](/docs/pt/env-vars) |250| `github.com` | Clonagem de [marketplaces de plugins](/docs/pt/plugins/overview) e plugins hospedados no GitHub, incluindo o marketplace oficial da Anthropic, via HTTPS ou SSH. Para clonar fontes `owner/repo` do GitHub apenas via HTTPS, defina [`CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1`](/docs/pt/env-vars) |

251| `raw.githubusercontent.com` | Feed de changelog para [`/release-notes`](/docs/pt/commands). Em sessões interativas, Claude Code também o busca em segundo plano na inicialização quando seu changelog em cache ainda não cobre a versão em execução, como na primeira inicialização após uma atualização; sessões não interativas e em nuvem nunca o buscam |251| `raw.githubusercontent.com` | Feed de changelog para [`/release-notes`](/docs/pt/commands). Em sessões interativas, Claude Code também o busca em segundo plano na inicialização quando seu changelog em cache ainda não cobre a versão em execução, como na primeira inicialização após uma atualização; sessões não interativas e em nuvem nunca o buscam |

252| `*-review.googlesource.com` | Pesquisa de alteração Gerrit em checkouts `googlesource.com`. Quando uma sessão de guia Claude Desktop Code inicia ou retoma em um checkout [confiável](/docs/pt/permissions#project-allow-rules-and-workspace-trust) cujo `origin` é um host `googlesource.com`, Claude Code pergunta anonimamente ao servidor `-review` desse host pela alteração aberta correspondente ao `Change-Id` do HEAD, uma vez por inicialização ou retomada. Outros tipos de sessão pulam a pesquisa, e nenhum outro host Gerrit é contatado. Opcional: desabilite com [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](/docs/pt/env-vars) |252| `*-review.googlesource.com` | Pesquisa de alteração Gerrit em checkouts `googlesource.com`. Quando uma sessão de guia Claude Desktop Code inicia ou retoma em um checkout [confiável](/docs/pt/permissions#project-allow-rules-and-workspace-trust) cujo `origin` é um host `googlesource.com`, Claude Code pergunta anonimamente ao servidor `-review` desse host pela alteração aberta correspondente ao `Change-Id` do HEAD, uma vez por inicialização ou retomada. Outros tipos de sessão pulam a pesquisa, e nenhum outro host Gerrit é contatado. Opcional: desabilite com [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](/docs/pt/env-vars) |

Details

86| Como você executa Claude Code | Modo de permissão inicial integrado |86| Como você executa Claude Code | Modo de permissão inicial integrado |

87| :- | :- |87| :- | :- |

88| Qualquer arquivo de configurações define `disableAutoMode` como `"disable"` | `default` |88| Qualquer arquivo de configurações define `disableAutoMode` como `"disable"` | `default` |

89| `claude -p` ou o [Agent SDK](/docs/pt/agent-sdk/permissions) | `default` |89| `claude -p` ou o [Agent SDK](/docs/pt/agent-sdk/permissions#permission-modes) | `default` em sessões que [buscam sinalizadores de recurso](/docs/pt/env-vars#features-that-need-feature-flag-fetching). Em sessões que não buscam, como em um provedor de terceiros ou com telemetria desativada, `auto` com Claude Code v2.1.285 ou posterior e `default` em versões anteriores. Uma sessão em uma organização cuja política retém o padrão `auto` inicia em `default` em vez disso |

90| Em um terminal ou através da [extensão VS Code](/docs/pt/vs-code) | `auto` com Claude Code v2.1.283 ou posterior; em versões anteriores, `auto` em planos Pro, Max ou Team em sessões que [buscam sinalizadores de recurso](/docs/pt/env-vars#features-that-need-feature-flag-fetching), e `default` caso contrário |90| Em um terminal ou através da [extensão VS Code](/docs/pt/vs-code) | `auto` com Claude Code v2.1.283 ou posterior; em versões anteriores, `auto` em planos Pro, Max ou Team em sessões que [buscam sinalizadores de recurso](/docs/pt/env-vars#features-that-need-feature-flag-fetching), e `default` caso contrário |

91 91 

92Em sua [primeira sessão após uma instalação ou upgrade](/docs/pt/env-vars#first-session-after-an-install-or-upgrade), Claude Code pode escolher o modo de permissão inicial antes de seus sinalizadores de recurso chegarem. Essa sessão pode iniciar em um modo de permissão diferente do que a tabela fornece, e sua próxima sessão corresponde à tabela.92Em sua [primeira sessão após uma instalação ou upgrade](/docs/pt/env-vars#first-session-after-an-install-or-upgrade), Claude Code pode escolher o modo de permissão inicial antes de seus sinalizadores de recurso chegarem. Essa sessão pode iniciar em um modo de permissão diferente do que a tabela fornece, e sua próxima sessão corresponde à tabela.


98* Em um terminal, uma vez, no topo da sessão98* Em um terminal, uma vez, no topo da sessão

99* Na extensão VS Code, como um cartão na tela de nova conversa que permanece até você descartá-lo99* Na extensão VS Code, como um cartão na tela de nova conversa que permanece até você descartá-lo

100 100 

101Nos planos Pro, Max e Team, se seu `~/.claude/settings.json` define um `defaultMode` diferente de `auto` e nenhum outro arquivo de configurações define um, suas sessões continuam iniciando nesse modo. Claude Code pergunta uma vez, no terminal ou na extensão VS Code, se você quer alterar a configuração para modo automático. Se você recusar, sua configuração permanece como está.101Se seu `~/.claude/settings.json` define um `defaultMode` diferente de `auto` e nenhum outro arquivo de configurações define um, suas sessões continuam iniciando nesse modo. Nos planos Pro, Max e Team, e em sessões que [não buscam sinalizadores de recurso](/docs/pt/env-vars#features-that-need-feature-flag-fetching), Claude Code pergunta uma vez, no terminal ou na extensão VS Code, se você quer alterar a configuração para modo automático. Se você recusar, sua configuração permanece como está.

102 102 

103<h3 id="start-in-a-different-mode">103<h3 id="start-in-a-different-mode">

104 Inicie em um modo de permissão diferente104 Inicie em um modo de permissão diferente


291 Elimine prompts de permissão com modo automático291 Elimine prompts de permissão com modo automático

292</h2>292</h2>

293 293 

294O modo automático permite que Claude execute sem prompts de permissão rotineiros. Um modelo classificador separado revisa as ações antes de serem executadas, bloqueando qualquer coisa que escale além da sua solicitação, direcione infraestrutura não reconhecida ou pareça impulsionada por conteúdo hostil que Claude leu. [Regras de solicitação](/docs/pt/permissions#manage-permissions) explícitas ainda forçam um prompt.294O modo automático permite que Claude execute sem prompts de permissão rotineiros. Um modelo classificador separado revisa as ações antes de serem executadas, bloqueando qualquer coisa que escale além do seu pedido, direcione infraestrutura não reconhecida ou pareça impulsionada por conteúdo hostil que Claude leu. [Regras de solicitação](/docs/pt/permissions#manage-permissions) explícitas ainda forçam um prompt.

295 295 

296Com Claude Code v2.1.283 ou posterior, o modo automático é o [modo de permissão inicial integrado](#which-mode-a-session-starts-in) para sessões de terminal interativo e VS Code em todos os planos e provedores. Em versões anteriores, é o modo de permissão inicial integrado apenas nos planos Pro, Max e Team.296Com Claude Code v2.1.283 ou posterior, o modo automático é o [modo de permissão inicial integrado](#which-mode-a-session-starts-in) para sessões de terminal interativo e VS Code em todos os planos e provedores. Em versões anteriores, é o modo de permissão inicial integrado apenas nos planos Pro, Max e Team.

297 297 

298O classificador também revisa cada mensagem que Claude envia para outro agente com [`SendMessage`](/docs/pt/tools-reference), seja texto simples ou uma mensagem estruturada de [equipe de agentes](/docs/pt/agent-teams), antes que Claude Code a entregue, tanto no modo automático quanto no [modo de plano enquanto o classificador revisa comandos](#analyze-before-you-edit-with-plan-mode); a revisão de envio requer Claude Code v2.1.222 ou posterior.298O classificador também revisa cada mensagem que Claude envia para outro agente com [`SendMessage`](/docs/pt/tools-reference), seja texto simples ou uma mensagem estruturada de [equipe de agentes](/docs/pt/agent-teams), antes que Claude Code a entregue, tanto no modo automático quanto no [modo de plano enquanto o classificador revisa comandos](#analyze-before-you-edit-with-plan-mode); a revisão de envio requer Claude Code v2.1.222 ou posterior.

299 299 

300Por padrão, o classificador não revisa remoções de `rm` e `rmdir` direcionadas a um caminho crítico, como `rm -rf /` ou `rm -rf ~`. [Caminhos críticos](#critical-paths) aborda o que acontece com eles em cada modo de permissão.300Por padrão, o classificador não revisa remoções de `rm` e `rmdir` direcionadas a um caminho crítico, como `rm -rf /` ou `rm -rf ~`. [Caminhos críticos](#critical-paths) cobre o que acontece com eles em cada modo de permissão.

301 301 

302O modo automático também incentiva Claude a continuar trabalhando sem parar para fazer perguntas de esclarecimento, embora Claude ainda pergunte quando sua solicitação ou uma skill dependa explicitamente disso. Para um comportamento mais autônomo em um modo que ainda o solicita, defina o [Estilo de saída proativo](/docs/pt/output-styles) em vez disso.302O modo automático também incentiva Claude a continuar trabalhando sem parar para fazer perguntas de esclarecimento, embora Claude ainda pergunte quando seu prompt ou uma skill depende explicitamente disso. Para um comportamento mais autônomo em um modo que ainda o solicita, defina o [estilo de saída Proativo](/docs/pt/output-styles) em vez disso.

303 303 

304<Warning>304<Warning>

305 O modo automático reduz prompts de permissão, mas não garante segurança. Use-o para tarefas em que você confia na direção geral, não como substituto para revisão em operações sensíveis.305 O modo automático reduz prompts de permissão, mas não garante segurança. Use-o para tarefas em que você confia na direção geral, não como substituto para revisão em operações sensíveis.


312* **Modelo**: na API Anthropic e [Claude Platform on AWS](/docs/pt/claude-platform-on-aws), Claude Opus 4.6 ou posterior, Sonnet 4.6 ou posterior, ou um [modelo Fable](/docs/pt/model-config#work-with-fable). No Amazon Bedrock, na Agent Platform do Google Cloud, no Microsoft Foundry e em sessões [gateway de aplicativos Claude](/docs/pt/claude-apps-gateway) conectadas, apenas Claude Sonnet 5 ou posterior, Opus 4.7 ou posterior e os modelos Fable. Modelos mais antigos, incluindo Sonnet 4.5, Opus 4.5, Haiku e modelos claude-3, não são suportados em nenhum provedor.312* **Modelo**: na API Anthropic e [Claude Platform on AWS](/docs/pt/claude-platform-on-aws), Claude Opus 4.6 ou posterior, Sonnet 4.6 ou posterior, ou um [modelo Fable](/docs/pt/model-config#work-with-fable). No Amazon Bedrock, na Agent Platform do Google Cloud, no Microsoft Foundry e em sessões [gateway de aplicativos Claude](/docs/pt/claude-apps-gateway) conectadas, apenas Claude Sonnet 5 ou posterior, Opus 4.7 ou posterior e os modelos Fable. Modelos mais antigos, incluindo Sonnet 4.5, Opus 4.5, Haiku e modelos claude-3, não são suportados em nenhum provedor.

313* **Provedor**: disponível por padrão na API Anthropic, Claude Platform on AWS, Amazon Bedrock, Agent Platform do Google Cloud, Microsoft Foundry e sessões gateway de aplicativos Claude conectadas.313* **Provedor**: disponível por padrão na API Anthropic, Claude Platform on AWS, Amazon Bedrock, Agent Platform do Google Cloud, Microsoft Foundry e sessões gateway de aplicativos Claude conectadas.

314 314 

315Se Claude Code relatar o modo automático como indisponível, primeiro verifique esses requisitos e se algum arquivo de configurações define [`disableAutoMode`](/docs/pt/settings-reference#disableautomode). A Anthropic também pode ter desativado o modo automático no servidor, ou o servidor pode ter rejeitado o modo automático para sua conta. Uma sessão que recebeu uma dessas respostas mantém o modo automático desativado até o final da sessão, portanto, inicie uma nova sessão mais tarde.315Se Claude Code relatar o modo automático como indisponível, primeiro verifique esses requisitos e se algum arquivo de configurações define [`disableAutoMode`](/docs/pt/settings-reference#disableautomode). A Anthropic também pode ter desativado o modo automático no servidor, ou o servidor pode ter rejeitado o modo automático para sua conta. Uma sessão que recebeu uma dessas respostas mantém o modo automático desativado até que a sessão termine, então inicie uma nova sessão depois.

316 316 

317Uma mensagem separada que nomeia um modelo e diz que o modo automático "não pode determinar a segurança" de uma ação significa que uma solicitação do classificador falhou. Essa falha geralmente é transitória, mas no Amazon Bedrock pode se repetir até que sua conta possa invocar o modelo nomeado. Consulte a [referência de erros](/docs/pt/errors#auto-mode-cannot-determine-the-safety-of-an-action) para as causas e o que fazer.317Uma mensagem separada que nomeia um modelo e diz que o modo automático "não pode determinar a segurança" de uma ação significa que uma solicitação do classificador falhou. Essa falha geralmente é transitória, mas no Amazon Bedrock pode se repetir até que sua conta possa invocar o modelo nomeado. Consulte a [referência de erros](/docs/pt/errors#auto-mode-cannot-determine-the-safety-of-an-action) para as causas e o que fazer.

318 318 

319Se você definir `defaultMode: "auto"` em [configurações](/docs/pt/settings-reference#all-settings) e uma sessão de terminal iniciar em modo Manual sem erro, a configuração provavelmente está em `.claude/settings.json` ou `.claude/settings.local.json`. `auto` não entra em vigor nesses arquivos. Mova-o para `~/.claude/settings.json`. Para uma conversa que a extensão VS Code iniciou, verifique a lista própria da extensão em [Alternar modos de permissão](#switch-permission-modes) em vez disso.319Se você definir `defaultMode: "auto"` em [configurações](/docs/pt/settings-reference#all-settings) e uma sessão de terminal iniciar em modo Manual sem erro, a configuração provavelmente está em `.claude/settings.json` ou `.claude/settings.local.json`. `auto` não entra em vigor nesses arquivos. Mova-o para `~/.claude/settings.json`. Para uma conversa que a extensão VS Code iniciou, verifique a lista própria da extensão em [Alternar modos de permissão](#switch-permission-modes) em vez disso.

320 320 

321<h3 id="enable-auto-mode-on-bedrock-agent-platform-or-foundry">321<h3 id="enable-auto-mode-on-bedrock-agent-platform-or-foundry">

322 Modo automático no Bedrock, Agent Platform ou Foundry322 Modo automático em Bedrock, Agent Platform ou Foundry

323</h3>323</h3>

324 324 

325No [Amazon Bedrock](/docs/pt/amazon-bedrock), [Agent Platform do Google Cloud](/docs/pt/google-vertex-ai), [Microsoft Foundry](/docs/pt/microsoft-foundry) e sessões [gateway de aplicativos Claude](/docs/pt/claude-apps-gateway) conectadas, o modo automático está disponível por padrão. Com Claude Code v2.1.283 ou posterior, também é o [modo de permissão inicial integrado](#which-mode-a-session-starts-in) para sessões de terminal interativo e [VS Code](/docs/pt/vs-code). Para escolher o modo de permissão inicial você mesmo, defina `permissions.defaultMode` conforme [Iniciar em um modo de permissão diferente](#start-in-a-different-mode) descreve, ou escolha um modo de permissão do indicador de modo da extensão VS Code.325Em [Amazon Bedrock](/docs/pt/amazon-bedrock), [Agent Platform do Google Cloud](/docs/pt/google-vertex-ai), [Microsoft Foundry](/docs/pt/microsoft-foundry) e sessões [gateway de aplicativos Claude](/docs/pt/claude-apps-gateway) conectadas, o modo automático está disponível por padrão. Quando nada mais define um modo de permissão, também é o [modo de permissão inicial integrado](#which-mode-a-session-starts-in), nas versões que a tabela dessa seção lista. Para escolher o modo de permissão inicial você mesmo, defina `permissions.defaultMode` como [Iniciar em um modo de permissão diferente](#start-in-a-different-mode) descreve, ou escolha um modo de permissão do indicador de modo da extensão VS Code.

326 326 

327Apenas Claude Sonnet 5 ou posterior, Opus 4.7 ou posterior e os modelos Fable são suportados nesses provedores. Em qualquer outro modelo, a sessão inicia em Manual em vez disso.327Apenas Claude Sonnet 5 ou posterior, Opus 4.7 ou posterior e os modelos Fable são suportados nesses provedores. Em qualquer outro modelo, a sessão inicia em Manual em vez disso.

328 328 

329Para impedir que desenvolvedores usem o modo automático, defina `disableAutoMode` como `"disable"` em [configurações gerenciadas](/docs/pt/managed-settings). Isso remove `auto` do ciclo `Shift+Tab`, e uma sessão iniciada com `--permission-mode auto` inicia em Manual em vez disso. Uma sessão já em execução no modo automático o deixa quando a configuração chega a essa sessão de uma [fonte implantada por administrador](/docs/pt/managed-settings#which-managed-source-claude-code-uses) e mostra `auto mode disabled by settings`. Antes da v2.1.251, uma sessão em execução mantinha o modo automático até o final.329Para impedir que desenvolvedores usem o modo automático, defina `disableAutoMode` como `"disable"` em [configurações gerenciadas](/docs/pt/managed-settings). Isso remove `auto` do ciclo `Shift+Tab` e uma sessão iniciada com `--permission-mode auto` inicia em Manual em vez disso. Uma sessão já em execução no modo automático o deixa quando a configuração chega a essa sessão de uma [fonte implantada por administrador](/docs/pt/managed-settings#which-managed-source-claude-code-uses) e mostra `auto mode disabled by settings`. Antes de v2.1.251, uma sessão em execução mantinha o modo automático até que terminasse.

330 330 

331Na v2.1.158 até v2.1.206, o modo automático estava desativado nesses provedores até você definir `CLAUDE_CODE_ENABLE_AUTO_MODE=1`, e Claude Code ignorava `defaultMode: "auto"` nesses provedores a menos que a variável também fosse definida. A variável ainda é aceita para compatibilidade e não tem efeito a partir da v2.1.207 em diante.331Em v2.1.158 até v2.1.206, o modo automático estava desativado nesses provedores até você definir `CLAUDE_CODE_ENABLE_AUTO_MODE=1`, e Claude Code ignorava `defaultMode: "auto"` nesses provedores a menos que a variável também fosse definida. A variável ainda é aceita para compatibilidade e não tem efeito a partir de v2.1.207 em diante.

332 332 

333<h3 id="server-side-classifier-review">333<h3 id="server-side-classifier-review">

334 Revisão do classificador no servidor334 Revisão do classificador no servidor

335</h3>335</h3>

336 336 

337No modo automático, Claude Code pode pedir ao servidor para verificar as ações que [a ordem de decisão](#how-the-classifier-evaluates-actions) envia para revisão, como parte das solicitações de modelo da sessão, em vez de enviar suas próprias solicitações do classificador. Essas sessões solicitam:337No modo automático, Claude Code pode pedir ao servidor para verificar as ações que [a ordem de decisão](#how-the-classifier-evaluates-actions) envia para revisão, como parte das solicitações de modelo da sessão, em vez de enviar suas próprias solicitações do classificador. Essas sessões pedem:

338 338 

339* **Uma conexão direta com a API Anthropic**: em uma sessão de terminal interativo, em todos os planos claude.ai e em contas que usam a API Claude, conforme a Anthropic implementa. Requer Claude Code v2.1.271 ou posterior nos planos Pro, Max e Team, e v2.1.278 ou posterior nos planos Enterprise e contas da API Claude. A partir da v2.1.282, uma sessão que [não busca sinalizadores de recursos](/docs/pt/env-vars#features-that-need-feature-flag-fetching), por exemplo porque você desativou a telemetria, solicita o servidor por padrão em qualquer tipo de sessão.339* **Uma conexão direta com a API Anthropic**: em uma sessão de terminal interativo, em todos os planos claude.ai e em contas que usam a API Claude, conforme a Anthropic implementa. Requer Claude Code v2.1.271 ou posterior nos planos Pro, Max e Team, e v2.1.278 ou posterior nos planos Enterprise e contas da API Claude. A partir de v2.1.282, uma sessão que [não busca sinalizadores de recursos](/docs/pt/env-vars#features-that-need-feature-flag-fetching), por exemplo porque você desativou a telemetria, pede ao servidor por padrão em qualquer tipo de sessão.

340* **Um provedor de nuvem, gateway LLM ou proxy**: no [Claude Platform on AWS](/docs/pt/claude-platform-on-aws), Amazon Bedrock, Agent Platform do Google Cloud e Microsoft Foundry, e sempre que você aponta `ANTHROPIC_BASE_URL` para um [gateway LLM ou proxy](/docs/pt/llm-gateway), independentemente do seu plano. Solicitar por padrão requer Claude Code v2.1.278 ou posterior.340* **Um provedor de nuvem, ou um gateway LLM ou proxy**: em [Claude Platform on AWS](/docs/pt/claude-platform-on-aws), Amazon Bedrock, Agent Platform do Google Cloud e Microsoft Foundry, e sempre que você aponta `ANTHROPIC_BASE_URL` para um [gateway LLM ou proxy](/docs/pt/llm-gateway), qualquer que seja seu plano. Pedir por padrão requer Claude Code v2.1.278 ou posterior.

341* **Uma sessão [gateway de aplicativos Claude](/docs/pt/claude-apps-gateway) conectada**: requer Claude Code v2.1.280 ou posterior341* **Uma sessão [gateway de aplicativos Claude](/docs/pt/claude-apps-gateway) conectada**: requer Claude Code v2.1.280 ou posterior

342 342 

343Onde o servidor revisa as ações, seus vereditos as decidem. Dois outros resultados são possíveis:343Onde o servidor revisa as ações, seus vereditos as decidem. Dois outros resultados são possíveis:

344 344 

345* **O servidor não revisa a sessão**: uma resposta é concluída sem resultados de revisão, ou o servidor responde que não revisa essa sessão. As causas mais comuns são um gateway LLM ou proxy que descarta a solicitação de revisão ou os resultados, e uma plataforma, região ou credencial que ainda não tem verificações no servidor. Claude Code volta para suas próprias solicitações do classificador. Uma vez que esse fallback se mantém pelo resto da sessão, ele mostra um [aviso sobre cobranças de solicitação do classificador](/docs/pt/auto-mode-classifier-billing) em contas onde essas solicitações são cobradas.345* **O servidor não revisa a sessão**: uma resposta é concluída sem resultados de revisão, ou o servidor responde que não revisa essa sessão. As causas mais comuns são um gateway LLM ou proxy que descarta a solicitação de revisão ou os resultados, e uma plataforma, região ou credencial que ainda não tem verificações no servidor. Claude Code volta para suas próprias solicitações do classificador. Uma vez que esse fallback se mantém pelo resto da sessão, ele mostra um [aviso sobre cobranças de solicitação do classificador](/docs/pt/auto-mode-classifier-billing) em contas onde essas solicitações são cobradas.

346* **O servidor não fornece um veredito para uma ação**: Claude Code nega a ação em vez de executá-la sem revisão. Em qualquer conexão, isso acontece quando a resposta termina antes dos resultados de revisão chegarem ou os resultados chegam em um formato que Claude Code não consegue ler. Um gateway LLM ou proxy que encurta respostas ou reescreve os resultados pode causar qualquer um. Em uma conexão direta com a API Anthropic, também acontece quando a verificação do servidor falha para a ação, por exemplo, por timeout. [O servidor não retornou um veredito de segurança](/docs/pt/errors#the-server-returned-no-safety-verdict) aborda a mensagem de negação, o que acontece quando negações se repetem e o que fazer.346* **O servidor não dá veredito para uma ação**: Claude Code nega a ação em vez de executá-la sem revisão. Em qualquer conexão, isso acontece quando a resposta termina antes dos resultados de revisão chegarem ou os resultados chegam em uma forma que Claude Code não consegue ler. Um gateway LLM ou proxy que corta respostas ou reescreve os resultados pode causar qualquer um. Em uma conexão direta com a API Anthropic, também acontece quando a verificação do servidor falha para a ação, por exemplo ao expirar. [O servidor não retornou veredito de segurança](/docs/pt/errors#the-server-returned-no-safety-verdict) cobre a mensagem de negação, o que acontece quando negações se repetem e o que fazer.

347 347 

348Para pular a solicitação ao servidor e sempre usar as próprias solicitações do classificador de Claude Code, defina [`CLAUDE_CODE_AUTO_MODE_SERVER=0`](/docs/pt/env-vars). Em uma conexão direta com a API Anthropic, a variável requer Claude Code v2.1.281 ou posterior. Defini-la como `1` lá ativa a revisão do servidor em uma sessão que ainda não a tem, como uma sessão `-p` ou Agent SDK, a menos que você também tenha definido `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`. Se você definir `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1` e deixar `CLAUDE_CODE_AUTO_MODE_SERVER` indefinido, Claude Code também para de solicitar o servidor, exceto conforme [Desabilitar capacidades de pré-lançamento](/docs/pt/llm-gateway-protocol#disable-pre-release-capabilities) descreve.348Para pular pedir ao servidor e sempre usar as próprias solicitações do classificador de Claude Code, defina [`CLAUDE_CODE_AUTO_MODE_SERVER=0`](/docs/pt/env-vars). Em uma conexão direta com a API Anthropic, a variável requer Claude Code v2.1.281 ou posterior. Defini-la como `1` lá ativa a revisão do servidor em uma sessão que não a tem ainda, como uma sessão `-p` ou Agent SDK, a menos que você também tenha definido `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`. Se você definir `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1` e deixar `CLAUDE_CODE_AUTO_MODE_SERVER` indefinido, Claude Code também para de pedir ao servidor, exceto como [Desabilitar capacidades de pré-lançamento](/docs/pt/llm-gateway-protocol#disable-pre-release-capabilities) descreve.

349 349 

350<h3 id="what-the-classifier-blocks-by-default">350<h3 id="what-the-classifier-blocks-by-default">

351 O que o classificador bloqueia por padrão351 O que o classificador bloqueia por padrão

352</h3>352</h3>

353 353 

354O classificador confia em seu diretório de trabalho e nos remotos que foram configurados para ele quando a sessão iniciou. Um remoto adicionado ou redirecionado durante a sessão com `git remote add` ou `git remote set-url` não é confiável, e tudo mais é tratado como externo até você [configurar infraestrutura confiável](/docs/pt/auto-mode-config). Antes da v2.1.200, remotos adicionados no meio da sessão também eram confiáveis.354O classificador confia em seu diretório de trabalho e nos remotos que foram configurados para ele quando a sessão iniciou. Um remoto adicionado ou reorientado durante a sessão com `git remote add` ou `git remote set-url` não é confiável, e tudo mais é tratado como externo até você [configurar infraestrutura confiável](/docs/pt/auto-mode-config). Antes de v2.1.200, remotos adicionados no meio da sessão também eram confiáveis.

355 355 

356**Bloqueado por padrão**:356**Bloqueado por padrão**:

357 357 


363* Modificação de infraestrutura compartilhada363* Modificação de infraestrutura compartilhada

364* Destruição irreversível de arquivos que existiam antes da sessão364* Destruição irreversível de arquivos que existiam antes da sessão

365* Force push365* Force push

366* Fazer commit ou fazer push de uma alteração que enviaria segredos ou dados sensíveis para fora do repositório quando executado, ou ampliar o que uma implantação expõe. Isso abrange um fluxo de trabalho CI ou configuração de implantação que passa um segredo para um destino que ainda não o recebe, um script ou etapa de configuração que lê um armazenamento de segredos e envia os dados para fora, e uma alteração de configuração que amplia o que uma implantação publica, como um registro, visibilidade, artefato ou configuração de sourcemap. A verificação se aplica em qualquer branch, se aplica mesmo quando o repositório é público e dispara quando a alteração é feita commit ou push, independentemente de esse commit ou push disparar o pipeline; limpá-la requer nomear o efeito de execução, não apenas o commit ou push. Antes da v2.1.211, essa verificação era limitada ao branch padrão: um push lá era bloqueado quando carregava conteúdo sensível, alterações encobertas ou mal descritas em relação ao que você pediu, conteúdo portado de fora do repositório ou roteado em torno de uma revisão que você pediu366* Fazer commit ou fazer push de uma alteração que enviaria segredos ou dados sensíveis fora do repositório quando executado, ou ampliaria o que uma implantação expõe. Isso cobre um fluxo de trabalho CI ou configuração de implantação que passa um segredo para um destino que ainda não o recebe, um script ou etapa de configuração que lê um armazenamento de segredos e envia os dados para fora, e uma mudança de configuração que amplia o que uma implantação publica, como um registro, visibilidade, artefato ou configuração de sourcemap. A verificação se aplica em qualquer branch, se aplica mesmo quando o repositório é público e dispara quando a alteração é feita commit ou push, independentemente de esse commit ou push disparar o pipeline; limpá-la requer nomear o efeito de execução, não apenas o commit ou push. Antes de v2.1.211, essa verificação era limitada ao branch padrão em vez disso: um push lá era bloqueado quando carregava conteúdo sensível, alterações encobertas ou mal descritas em relação ao que você pediu, conteúdo portado de fora do repositório ou roteado em torno de uma revisão que você pediu

367* `git reset --hard`, `git checkout -- .`, `git restore .`, `git clean -fd`, `git stash drop` ou `git stash clear`, que o classificador presume descartaria alterações não confirmadas367* `git reset --hard`, `git checkout -- .`, `git restore .`, `git clean -fd`, `git stash drop` ou `git stash clear`, que o classificador presume descartaria alterações não confirmadas

368* `git commit --amend` quando o commit no HEAD não foi criado nesta sessão368* `git commit --amend` quando o commit no HEAD não foi criado nesta sessão

369* A partir da v2.1.198, `git commit --amend` quando o commit no HEAD já foi feito push. Uma reword apenas de mensagem não é bloqueada: `--amend -m` sem nada recém-preparado, em um commit que Claude criou durante esta sessão369* A partir de v2.1.198, `git commit --amend` quando o commit no HEAD já foi feito push. Uma reword apenas de mensagem não é bloqueada: `--amend -m` sem nada recém-preparado, em um commit que Claude criou durante esta sessão

370* `terraform destroy`, `pulumi destroy`, `cdk destroy` ou `terragrunt destroy`, e aplicar um plano que destrói recursos370* `terraform destroy`, `pulumi destroy`, `cdk destroy` ou `terragrunt destroy`, e aplicar um plano que destrói recursos

371* Escrita em um gerenciador de segredos, ou alteração de registros DNS ou certificados TLS371* Escrita em um gerenciador de segredos, ou alteração de registros DNS ou certificados TLS

372* Mesclagem de uma solicitação de pull que nenhum humano aprovou, aprovação da própria solicitação de pull de Claude ou desabilitação de verificações CI372* Mesclagem de uma solicitação de pull que nenhum humano aprovou, aprovação da própria solicitação de pull de Claude ou desabilitação de verificações CI

373* Postagem de um comentário que é em si um comando para automação, como `atlantis apply` ou `/deploy` ou `/merge` de um bot373* Postagem de um comentário que é em si um comando para automação, como `atlantis apply` ou `/deploy` ou `/merge` de um bot

374* Alternância, ramificação ou exclusão de um sinalizador de recurso de produção374* Alternância, ramificação ou exclusão de um sinalizador de recurso de produção

375* Aplicação de alterações de infraestrutura a um escopo IaC protegido, ou drenagem e remoção de nós de cluster375* Aplicação de alterações de infraestrutura a um escopo IaC protegido, ou drenagem e remoção de nós de cluster

376* Escritas em um cluster de computação compartilhado que vão além do recurso que você nomeou, como um seletor de rótulo ou `--all` que captura trabalhos de outros usuários376* Escritas em um cluster de computação compartilhado que vão além do recurso que você nomeou, como um seletor de rótulo ou `--all` que pega trabalhos de outros usuários

377* Criação de recursos Kubernetes que executam em cada nó ou interceptam tráfego de cluster, como DaemonSets e webhooks de admissão377* Criação de recursos Kubernetes que executam em cada nó ou interceptam tráfego de cluster, como DaemonSets e webhooks de admissão

378* Shells interativos ou port-forwards para um destino remoto sensível378* Shells interativos ou port-forwards para um alvo remoto sensível

379* Abertura de um túnel ou shell reverso que torna um serviço local acessível da internet pública379* Abertura de um túnel ou shell reverso que torna um serviço local acessível da internet pública

380* Impressão de uma credencial ou token ao vivo na transcrição ou em um arquivo380* Impressão de uma credencial ou token ao vivo na transcrição ou em um arquivo

381* Acesso a um local listado como um local de dados sensíveis em seu [ambiente](/docs/pt/auto-mode-config#define-trusted-infrastructure), ou cópia de dados para fora de um. A partir da v2.1.198, isso também bloqueia o envio de dados de um para um público que a entrada exclui381* Acesso a um local listado como local de dados sensíveis em seu [ambiente](/docs/pt/auto-mode-config#define-trusted-infrastructure), ou cópia de dados de um. A partir de v2.1.198, isso também bloqueia envio de dados de um para um público que a entrada exclui

382* Roteamento de uma instalação de pacote em torno de seu registro de pacotes interno para um registro público. A partir da v2.1.198, isso também se aplica quando você disse a Claude que um registro interno ou espelho existe na conversa, não apenas quando um está listado em seu ambiente382* Roteamento de uma instalação de pacote em torno de seu registro de pacotes interno para um registro público. A partir de v2.1.198, isso também se aplica quando você disse a Claude que um registro interno ou espelho existe na conversa, não apenas quando um está listado em seu ambiente

383* Execução de um comando com um sinalizador que desativa uma proteção de segurança, como `--insecure`383* Execução de um comando com um sinalizador que desativa uma proteção de segurança, como `--insecure`

384* Lançamento de um loop de agente autônomo que executa sem aprovação humana ou sandbox, como um iniciado com `--dangerously-skip-permissions` ou `--no-sandbox`. A partir da v2.1.198, isso também abrange a execução de um agente de terceiros ou harness de avaliação com isolamento e aprovação por ação desabilitados, como um runner iniciado com `--yes-always`384* Lançamento de um loop de agente autônomo que executa sem aprovação humana ou sandbox, como um iniciado com `--dangerously-skip-permissions` ou `--no-sandbox`. A partir de v2.1.198, isso também cobre execução de um agente de terceiros ou harness de avaliação com isolamento e aprovação por ação desabilitados, como um runner iniciado com `--yes-always`

385* Ações do [Claude no Chrome](/docs/pt/chrome) que poderiam enviar conteúdo da página, cookies ou credenciais fora da origem385* [Claude em Chrome](/docs/pt/chrome) ações de navegador que poderiam enviar conteúdo de página, cookies ou credenciais fora de origem

386 386 

387Várias dessas categorias dependem de entradas de [ambiente](/docs/pt/auto-mode-config#define-trusted-infrastructure), como destinos remotos sensíveis e escopos IaC protegidos, que você pode restringir a nomes concretos.387Várias dessas categorias dependem de entradas de [ambiente](/docs/pt/auto-mode-config#define-trusted-infrastructure), como alvos remotos sensíveis e escopos IaC protegidos, que você pode restringir a nomes concretos.

388 388 

389Claude Code v2.1.198 e posterior também bloqueiam estes por padrão:389Claude Code v2.1.198 e posterior também bloqueiam esses por padrão:

390 390 

391* Exclusão de arquivos em `/tmp`, `$TMPDIR` ou outro diretório compartilhado de rascunho ou cache por wildcard, glob ou filtro de idade em vez de por um caminho nomeado específico391* Exclusão de arquivos em `/tmp`, `$TMPDIR` ou outro diretório compartilhado de rascunho ou cache por wildcard, glob ou filtro de idade em vez de por um caminho nomeado específico

392* Inclusão de detalhes sensíveis em conteúdo enviado, carregado, publicado ou escrito para outras pessoas ou sistemas compartilhados, quando sua própria mensagem não autorizou esses detalhes para esse destinatário. Corpos de PR e issue, mensagens de commit e comentários contam como esse tipo de conteúdo de saída quando o repositório está fora do limite de confiança ou é público, incluindo repositórios públicos de sua própria organização; caminhos de arquivo internos, nomes de código, dados de resposta de API ao vivo, como emails ou identificadores de conta, e identificadores de infraestrutura contam como detalhes sensíveis. O escopo de PR, issue e mensagem de commit requer Claude Code v2.1.200 ou posterior. Dados pessoais ao vivo de uma resposta de API em um corpo de PR ou issue, como um endereço de email, um identificador de conta ou organização, ou uma métrica de uso, requer que você nomeie esses detalhes e o destinatário independentemente da visibilidade ou limite de confiança do repositório. Essa verificação requer Claude Code v2.1.203 ou posterior392* Inclusão de detalhes sensíveis em conteúdo enviado, carregado, publicado ou escrito para outras pessoas ou sistemas compartilhados, quando sua própria mensagem não autorizou esses detalhes para esse destinatário. Corpos de PR e problema, mensagens de commit e comentários contam como esse tipo de conteúdo de saída quando o repositório está fora do limite de confiança ou é público, incluindo seus próprios repositórios públicos da organização; caminhos de arquivo internos, nomes de código, dados de resposta de API ao vivo como emails ou identificadores de conta e identificadores de infraestrutura contam como detalhes sensíveis. O escopo de PR, problema e mensagem de commit requer Claude Code v2.1.200 ou posterior. Dados pessoais ao vivo de uma resposta de API em um corpo de PR ou problema, como um endereço de email, um identificador de conta ou organização ou uma métrica de uso, requer que você nomeie esses detalhes e o destinatário independentemente da visibilidade ou limite de confiança do repositório. Essa verificação requer Claude Code v2.1.203 ou posterior

393* Envio de pressionamentos de tecla para o próprio painel tmux de Claude Code para conduzir sua própria interface, que o classificador trata como Claude alterando suas próprias permissões ou supervisão393* Envio de pressionamentos de tecla para o próprio painel tmux de Claude Code para conduzir sua própria interface, que o classificador trata como Claude alterando suas próprias permissões ou supervisão

394 394 

395Claude Code v2.1.200 e posterior também bloqueiam estes por padrão:395Claude Code v2.1.200 e posterior também bloqueiam esses por padrão:

396 396 

397* Comentário, exclusão ou falha forçada de um teste ou asserção que protege comportamento de segurança, como autenticação, controle de acesso, validação de entrada ou sandboxing397* Comentário, exclusão ou falha forçada de um teste ou asserção que protege comportamento de segurança, como autenticação, controle de acesso, validação de entrada ou sandboxing

398* Exclusão ou desmontagem de um recurso com estado que Claude não criou na sessão, quando nenhuma regra de exclusão mais específica se aplica e você não nomeou esse recurso398* Exclusão ou desmontagem de um recurso com estado que Claude não criou na sessão, quando nenhuma regra de exclusão mais específica se aplica e você não nomeou esse recurso

399* Redirecionamento de uma URL de base de API, endpoint de proxy, receptor de webhook ou espelho de registro para um host de terceiros que não se encaixa na tarefa, incluindo em arquivos de exemplo como `.env.example`399* Reorientação de uma URL de base de API, endpoint de proxy, receptor de webhook ou espelho de registro para um host de terceiros que não se encaixa na tarefa, incluindo em arquivos de exemplo como `.env.example`

400* Alteração de para onde os pushes vão com `git remote set-url` ou `git remote add`, a menos que você tenha nomeado o novo remoto400* Alteração de para onde os pushes vão com `git remote set-url` ou `git remote add`, a menos que você tenha nomeado o novo remoto

401* Envio de segredos ou dados pessoais ou confiados para um repositório conhecido como público, ou envio de material confidencial lá que não faz parte do próprio trabalho desse repositório. O próprio assunto de um repositório de dotfiles é a única exceção para dados pessoais ou confiados, e conteúdo de um repositório privado chegando a qualquer superfície pública é bloqueado da mesma forma; ambos os refinamentos requerem Claude Code v2.1.203 ou posterior. Antes da v2.1.203, dados pessoais eram agrupados com material confidencial e bloqueados apenas quando não faziam parte do próprio trabalho desse repositório. Quando a visibilidade de um repositório não é estabelecida, o classificador não bloqueia apenas nisso; ele julga o conteúdo contra as outras regras em vez disso401* Envio de segredos ou dados pessoais ou confiados para um repositório conhecido como público, ou envio de material confidencial lá que não faz parte do próprio trabalho desse repositório. O próprio assunto de um repositório de dotfiles é a única exceção para dados pessoais ou confiados, e conteúdo de um repositório privado chegando a qualquer superfície pública é bloqueado da mesma forma; ambos os refinamentos requerem Claude Code v2.1.203 ou posterior. Antes de v2.1.203, dados pessoais eram agrupados com material confidencial e bloqueados apenas quando não faziam parte do próprio trabalho desse repositório. Quando a visibilidade de um repositório não é estabelecida, o classificador não bloqueia apenas nisso; ele julga o conteúdo contra as outras regras em vez disso

402* Abertura de uma solicitação de pull contra um repositório ou organização diferente, fork com `gh repo fork` ou push para um repositório de terceiros, a menos que você tenha nomeado esse alvo externo402* Abertura de uma solicitação de pull contra um repositório ou organização diferente, bifurcação com `gh repo fork` ou push para um repositório de terceiros, a menos que você tenha nomeado esse alvo externo

403 403 

404Claude Code v2.1.203 e posterior também bloqueiam estes por padrão:404Claude Code v2.1.203 e posterior também bloqueiam esses por padrão:

405 405 

406* Conteúdo de um armazenamento local sensível, ou de um arquivo cujo nome, caminho ou tipo o marca como sensível, entrando em um commit, um push, texto de PR ou issue, um gist ou paste, ou uma publicação de pacote, a menos que você tenha nomeado tanto a origem quanto o destino. Transcrições de sessão e logs de conversa, pastas de ponto de credencial e configuração como chaves SSH, credenciais de nuvem, perfis de navegador e histórico de shell, e exportações de dados do usuário contam, e o repositório ser privado não o limpa406* Conteúdo de um armazenamento local sensível, ou de um arquivo cujo nome, caminho ou tipo o marca como sensível, entrando em um commit, um push, texto de PR ou problema, um gist ou paste ou uma publicação de pacote, a menos que você tenha nomeado tanto a origem quanto o destino. Transcrições de sessão e logs de conversa, pastas de ponto de credencial e configuração como chaves SSH, credenciais de nuvem, perfis de navegador e histórico de shell, e exportações de dados do usuário contam, e o repositório ser privado não o limpa

407 407 

408Claude Code v2.1.205 e posterior também bloqueiam estes por padrão:408Claude Code v2.1.205 e posterior também bloqueiam esses por padrão:

409 409 

410* Escrita em transcrições de sessão de Claude Code, os arquivos de histórico `.jsonl` em `~/.claude/projects/` ou seu diretório de configuração configurado, seja diretamente ou através de um comando de shell. A regra também abrange as linhas de metadados que Claude Code acrescenta a cada entrada de transcrição para suas próprias verificações. Ler uma transcrição não é bloqueado410* Escrita em transcrições de sessão de Claude Code, os arquivos de histórico `.jsonl` sob `~/.claude/projects/` ou seu diretório de configuração configurado, seja diretamente ou através de um comando de shell. A regra também cobre as linhas de metadados que Claude Code acrescenta a cada entrada de transcrição para suas próprias verificações. Ler uma transcrição não é bloqueado

411* Uma exclusão forçada recursiva como `rm -rf "$VAR"` ou `Remove-Item -Recurse -Force $dir` cujo alvo é uma variável de shell que não é atribuída em nenhum lugar na conversa que o classificador vê, ou um glob enraizado em tal variável. O valor veio apenas da saída de comando anterior, que o classificador nunca recebe, portanto o classificador não pode verificar o alvo de exclusão contra as outras regras de exclusão. O bloqueio é limpo quando você nomeia o caminho exato sendo excluído, ou quando Claude re-executa a exclusão com o caminho literal resolvido escrito no comando. Exclusões cujo alvo o classificador pode resolver não são afetadas.411* Uma exclusão forçada recursiva como `rm -rf "$VAR"` ou `Remove-Item -Recurse -Force $dir` cujo alvo é uma variável de shell que não é atribuída em nenhum lugar na conversa que o classificador vê, ou um glob enraizado em tal variável. O valor veio apenas da saída de comando anterior, que o classificador nunca recebe, então o classificador não consegue verificar o alvo de exclusão contra as outras regras de exclusão. O bloqueio se limpa quando você nomeia o caminho exato sendo excluído, ou quando Claude re-executa a exclusão com o caminho literal resolvido escrito no comando. Exclusões cujo alvo o classificador consegue resolver não são afetadas.

412 412 

413 Um glob diretamente sob a variável, como em `rm -rf "$VAR"/*`, é um [caminho crítico](#critical-paths) em vez disso. Alvos `Remove-Item` que são um `*` simples ou terminam em `/*` ou `\*` nunca chegam ao classificador: Claude Code [os nega imediatamente](#remove-item-in-powershell).413 Um glob diretamente sob a variável, como em `rm -rf "$VAR"/*`, é um [caminho crítico](#critical-paths) em vez disso. Alvos `Remove-Item` que são um `*` simples ou terminam em `/*` ou `\*` nunca chegam ao classificador: Claude Code [os nega imediatamente](#remove-item-in-powershell).

414 414 

415Claude Code v2.1.257 e posterior também bloqueiam estes por padrão:415Claude Code v2.1.257 e posterior também bloqueiam esses por padrão:

416 416 

417* Solicitação de credenciais do endpoint de metadados da instância de nuvem, como `169.254.169.254`, ou autenticação explícita de uma chamada de nuvem, cluster ou registro com a identidade de conta de serviço ou nó da máquina417* Solicitação de credenciais do endpoint de metadados da instância de nuvem, como `169.254.169.254`, ou autenticação explícita de uma chamada de nuvem, cluster ou registro com a identidade de conta de serviço ou nó da máquina

418* Alcance de um host público por uma rota diferente de uma solicitação direta, como um túnel, um shell reverso, ou uma configuração de resolvedor ou proxy reescrita para apontar para fora418* Alcance de um host público por uma rota diferente de uma solicitação direta, como um túnel, um shell reverso ou uma configuração de resolvedor ou proxy reescrita para apontar para fora

419* Leitura de credenciais que pertencem ao host em vez de à sua tarefa, como certificados de nó ou auth de registro de contêiner do nó419* Leitura de credenciais que pertencem ao host em vez de à sua tarefa, como certificados de nó ou auth de registro de contêiner do nó

420* Conexão ou varredura de contêineres, pods ou VMs irmãos que Claude não iniciou, ou o nó sob o contêiner420* Conexão ou varredura de contêineres, pods ou VMs irmãos que Claude não iniciou, ou o nó sob o contêiner

421 421 

422Se Claude Code executar em algum lugar que se destine a permitir um desses, descreva essa configuração em uma entrada [Host containment](/docs/pt/auto-mode-config#define-trusted-infrastructure) em `autoMode.environment`.422Se Claude Code executar em algum lugar que se destine a permitir um desses, descreva essa configuração em uma entrada [Host containment](/docs/pt/auto-mode-config#define-trusted-infrastructure) em `autoMode.environment`.

423 423 

424Claude Code v2.1.261 e posterior também bloqueiam estes por padrão:424Claude Code v2.1.261 e posterior também bloqueiam esses por padrão:

425 425 

426* Postagem ou escrita de um link para um serviço público de paste, diagrama ou compartilhamento de dados em uma mensagem, texto de PR ou issue, um documento, ou em qualquer outro lugar onde o link será aberto ou buscado, quando a própria URL carrega o conteúdo sendo compartilhado, a menos que você tenha nomeado esse serviço426* Postagem ou escrita de um link para um serviço público de paste, diagrama ou compartilhamento de dados em uma mensagem, texto de PR ou problema, um documento ou em qualquer outro lugar onde o link será aberto ou buscado, quando a própria URL carrega o conteúdo sendo compartilhado, a menos que você tenha nomeado esse serviço

427 427 

428**Permitido por padrão**:428**Permitido por padrão**:

429 429 


431* Instalação de dependências declaradas em seus arquivos de lock ou manifestos431* Instalação de dependências declaradas em seus arquivos de lock ou manifestos

432* Leitura de `.env` e envio de credenciais para sua API correspondente432* Leitura de `.env` e envio de credenciais para sua API correspondente

433* Solicitações HTTP somente leitura433* Solicitações HTTP somente leitura

434* Push para qualquer branch do repositório em que você está trabalhando, incluindo o branch padrão. Um branch não padrão cujo nome o marca como um alvo de implantação ou publicação, como `production` ou `gh-pages`, não é coberto: o classificador julga um push lá em seus próprios termos. O conteúdo do push ainda é verificado contra as outras regras, [regras `permissions.deny`](/docs/pt/permissions#manage-permissions) ainda podem bloquear comandos push [conforme escrito](/docs/pt/permissions#bash-rule-limits) em todos os modos, e a proteção de branch própria do remoto ainda se aplica. Antes da v2.1.211, apenas pushes para o branch em que você iniciou, branches que Claude criou e pushes rotineiros para o branch padrão eram permitidos por padrão, e antes da v2.1.203 qualquer push direto para o branch padrão era bloqueado434* Push para qualquer branch do repositório em que você está trabalhando, incluindo o branch padrão. Um branch não padrão cujo nome o marca como alvo de implantação ou publicação, como `production` ou `gh-pages`, não é coberto: o classificador julga um push lá em seus próprios termos. O conteúdo do push ainda é verificado contra as outras regras, [regras `permissions.deny`](/docs/pt/permissions#manage-permissions) ainda podem bloquear comandos push [como escritos](/docs/pt/permissions#bash-rule-limits) em todos os modos, e a proteção de branch própria do remoto ainda se aplica. Antes de v2.1.211, apenas pushes para o branch em que você iniciou, branches que Claude criou e pushes rotineiros para o branch padrão eram permitidos por padrão, e antes de v2.1.203 qualquer push direto para o branch padrão era bloqueado

435* Exclusão dos trabalhos exatos que Claude criou anteriormente na mesma sessão435* Exclusão dos trabalhos exatos que Claude criou anteriormente na mesma sessão

436* Leitura, revisão ou escrita de código relacionado à segurança, configs e modelos de ameaça como parte de sua tarefa436* Leitura, revisão ou escrita de código, configs e modelos de ameaça relacionados à segurança como parte de sua tarefa

437* Mensagens entre agentes trabalhando juntos na mesma sessão multi-agente437* Mensagens entre agentes trabalhando juntos na mesma sessão multi-agente

438* Envio de dados para os domínios confiáveis, buckets e serviços que você lista em [`environment`](/docs/pt/auto-mode-config#define-trusted-infrastructure). Isso abrange apenas fluxo de dados, não operações destrutivas ou de credencial na mesma infraestrutura438* Envio de dados para os domínios, buckets e serviços confiáveis que você lista em [`environment`](/docs/pt/auto-mode-config#define-trusted-infrastructure). Isso cobre apenas fluxo de dados, não operações destrutivas ou de credencial na mesma infraestrutura

439* [Claude no Chrome](/docs/pt/chrome) navegação para um domínio interno confiável, localhost ou uma URL que você nomeou439* [Claude em Chrome](/docs/pt/chrome) navegação para um domínio interno confiável, localhost ou uma URL que você nomeou

440 440 

441Comandos em sandbox não obtêm acesso à rede por padrão. Claude nomeia os hosts que um comando precisa no próprio comando, o classificador os revisa com o comando, e uma lista aprovada abre esses hosts apenas para esse comando. [Domínios permitidos por comando](/docs/pt/sandboxing#per-command-allowed-domains-in-auto-mode) aborda o que uma lista pode e não pode abrir e o que acontece quando um comando alcança um host não listado.441Comandos em sandbox não obtêm acesso à rede por padrão. Claude nomeia os hosts que um comando precisa no próprio comando, o classificador os revisa com o comando, e uma lista aprovada abre esses hosts apenas para esse comando. [Domínios permitidos por comando](/docs/pt/sandboxing#per-command-allowed-domains-in-auto-mode) cobre o que uma lista pode e não pode abrir e o que acontece quando um comando alcança um host não listado.

442 442 

443Execute `claude auto-mode defaults` para imprimir as listas de regras completas como JSON. Se ações rotineiras forem bloqueadas, um administrador pode adicionar repositórios, buckets e serviços confiáveis via configuração `autoMode.environment`: consulte [Configurar modo automático](/docs/pt/auto-mode-config).443Execute `claude auto-mode defaults` para imprimir as listas de regras completas como JSON. Se ações rotineiras forem bloqueadas, um administrador pode adicionar repositórios, buckets e serviços confiáveis via configuração `autoMode.environment`: consulte [Configurar modo automático](/docs/pt/auto-mode-config).

444 444 

445Push para qualquer branch do repositório em que você está trabalhando e criação de uma solicitação de pull que corresponde à sua solicitação executam sem um prompt, a menos que o push ou solicitação de pull caia sob a [lista bloqueada](#what-the-classifier-blocks-by-default), como segredos ou dados sensíveis saindo do repositório, ou uma solicitação de pull que direciona um repositório ou organização diferente. Para exigir um checkpoint humano antes desses comandos enquanto permanece no modo automático, adicione regras `permissions.ask`, que correspondem ao comando [conforme escrito](/docs/pt/permissions#bash-rule-limits): consulte [Limites comuns](/docs/pt/auto-mode-config#common-boundaries).445Push para qualquer branch do repositório em que você está trabalhando e criação de uma solicitação de pull que corresponde ao seu pedido executam sem um prompt, a menos que o push ou solicitação de pull caia sob a [lista bloqueada](#what-the-classifier-blocks-by-default), como segredos ou dados sensíveis saindo do repositório, ou uma solicitação de pull que direciona um repositório ou organização diferente. Para exigir um checkpoint humano antes desses comandos enquanto permanece no modo automático, adicione regras `permissions.ask`, que correspondem ao comando [como escrito](/docs/pt/permissions#bash-rule-limits): consulte [Limites comuns](/docs/pt/auto-mode-config#common-boundaries).

446 446 

447<h3 id="first-read-outside-the-working-directories">447<h3 id="first-read-outside-the-working-directories">

448 A primeira leitura fora dos diretórios de trabalho448 A primeira leitura fora dos diretórios de trabalho


455Qualquer que seja sua resposta, Claude continua trabalhando:455Qualquer que seja sua resposta, Claude continua trabalhando:

456 456 

457* **Sim, e continue permitindo qualquer leitura fora dos diretórios de trabalho**: a leitura executa, leituras posteriores fora dos diretórios de trabalho executam como antes, e Claude Code registra sua resposta para que o prompt não apareça novamente457* **Sim, e continue permitindo qualquer leitura fora dos diretórios de trabalho**: a leitura executa, leituras posteriores fora dos diretórios de trabalho executam como antes, e Claude Code registra sua resposta para que o prompt não apareça novamente

458* **Não, e bloqueie leituras fora dos diretórios de trabalho a partir de agora**: a leitura é recusada, e Claude Code define [`permissions.blockReadsOutsideWorkingDirectories`](/docs/pt/settings-reference#permissions-blockreadsoutsideworkingdirectories) como `true` em suas configurações de usuário, o que faz as ferramentas de arquivo recusarem tais leituras em todas as sessões posteriores e em todos os modos de permissão. Para deixar Claude ler tal caminho mais tarde, adicione seu diretório com `/add-dir` ou remova a configuração.458* **Não, e bloqueie leituras fora dos diretórios de trabalho a partir de agora**: a leitura é recusada, e Claude Code define [`permissions.blockReadsOutsideWorkingDirectories`](/docs/pt/settings-reference#permissions-blockreadsoutsideworkingdirectories) como `true` em suas configurações de usuário, o que faz as ferramentas de arquivo recusarem tais leituras em cada sessão posterior e em cada modo de permissão. Para deixar Claude ler tal caminho depois, adicione seu diretório com `/add-dir` ou remova a configuração.

459* **Não, e pergunte novamente na próxima vez**: a leitura é recusada, e a próxima leitura fora dos diretórios de trabalho solicita novamente459* **Não, e pergunte novamente na próxima vez**: a leitura é recusada, e a próxima leitura fora dos diretórios de trabalho solicita novamente

460* **Sim, mas pergunte novamente na próxima vez**: a leitura executa, nada é salvo, e a próxima leitura fora dos diretórios de trabalho solicita novamente460* **Sim, mas pergunte novamente na próxima vez**: a leitura executa, nada é salvo, e a próxima leitura fora dos diretórios de trabalho solicita novamente

461 461 


463 Limites que você declara na conversa463 Limites que você declara na conversa

464</h3>464</h3>

465 465 

466O classificador trata limites que você declara na conversa como um sinal de bloqueio. Se você disser a Claude "não faça push" ou "aguarde até eu revisar antes de implantar", o classificador bloqueia ações correspondentes mesmo quando as regras padrão as permitiriam. Um limite permanece em vigor até você levantá-lo em uma mensagem posterior. O próprio julgamento de Claude de que uma condição foi atendida não o levanta.466O classificador trata limites que você declara na conversa como um sinal de bloqueio. Se você disser a Claude "não faça push" ou "espere até eu revisar antes de implantar", o classificador bloqueia ações correspondentes mesmo quando as regras padrão as permitiriam. Um limite permanece em vigor até você levantá-lo em uma mensagem posterior. O próprio julgamento de Claude de que uma condição foi atendida não o levanta.

467 467 

468Limites não são armazenados como regras. O classificador os relê da transcrição em cada verificação, portanto um limite pode ser perdido se [compactação de contexto](/docs/pt/costs#reduce-token-usage) remover a mensagem que o declarou. Para uma garantia firme, adicione uma [regra de negação](/docs/pt/permissions#permission-rule-syntax) em vez disso.468Limites não são armazenados como regras. O classificador os relê da transcrição em cada verificação, então um limite pode ser perdido se [compactação de contexto](/docs/pt/costs#reduce-token-usage) remover a mensagem que o declarou. Para uma garantia difícil, adicione uma [regra de negação](/docs/pt/permissions#permission-rule-syntax) em vez disso.

469 469 

470<h3 id="approvals-you-state-in-conversation">470<h3 id="approvals-you-state-in-conversation">

471 Aprovações que você declara na conversa471 Aprovações que você declara na conversa


473 473 

474Se você disser a Claude que uma ação bloqueada é permitida, o classificador lê isso como sua aprovação e pode limpar o bloqueio. Como você o expressou decide se a ação executa e até onde a aprovação chega:474Se você disser a Claude que uma ação bloqueada é permitida, o classificador lê isso como sua aprovação e pode limpar o bloqueio. Como você o expressou decide se a ação executa e até onde a aprovação chega:

475 475 

476* **Nomeie a ação e seus detalhes**: sua mensagem tem que nomear a ação e a coisa específica que a torna perigosa, como o branch de um force push. Nomear apenas o verbo não limpa nada, portanto "você pode fazer force-push" deixa o bloqueio em vigor.476* **Nomeie a ação e seus detalhes**: sua mensagem tem que nomear a ação e a coisa específica que a torna perigosa, como o branch de um force push. Nomear apenas o verbo não limpa nada, então "você pode fazer force-push" deixa o bloqueio em vigor.

477* **Espere que cubra uma ação**: uma aprovação cobre a ação destrutiva que você nomeou, portanto uma ação posterior é bloqueada novamente a menos que você tenha concedido a aprovação como permanente. Para parar de aprovar um padrão rotineiro uma ação por vez, adicione-o a [`autoMode.allow`](/docs/pt/auto-mode-config#override-the-block-and-allow-rules).477* **Espere que cubra uma ação**: uma aprovação cobre a ação destrutiva que você nomeou, então uma ação posterior é bloqueada novamente a menos que você tenha concedido a aprovação como permanente. Para parar de aprovar um padrão rotineiro uma ação por vez, adicione-o a [`autoMode.allow`](/docs/pt/auto-mode-config#override-the-block-and-allow-rules).

478* **Alguns bloqueios permanecem em vigor**: [a ordem de precedência do classificador](/docs/pt/auto-mode-config#override-the-block-and-allow-rules) estabelece quais bloqueios sua aprovação pode alcançar. Para executar uma etapa que não limpará, [deixe o modo automático](#switch-permission-modes) e responda ao prompt de permissão.478* **Alguns bloqueios permanecem em vigor**: [a ordem de precedência do classificador](/docs/pt/auto-mode-config#override-the-block-and-allow-rules) estabelece quais bloqueios sua aprovação pode alcançar. Para executar uma etapa que não limpará, [deixe o modo automático](#switch-permission-modes) e responda ao prompt de permissão.

479 479 

480<h3 id="when-auto-mode-falls-back">480<h3 id="when-auto-mode-falls-back">


486* **Uma ação bloqueada**: Claude Code mostra uma notificação e lista a ação em `/permissions` sob a aba **Recently denied**, onde você pode pressionar `r` para tentar novamente com uma aprovação manual.486* **Uma ação bloqueada**: Claude Code mostra uma notificação e lista a ação em `/permissions` sob a aba **Recently denied**, onde você pode pressionar `r` para tentar novamente com uma aprovação manual.

487* **Bloqueios repetidos**: se o classificador bloqueia uma ação 3 vezes seguidas ou 20 vezes no total, o modo automático pausa e Claude Code retoma a solicitação. Aprovar a ação solicitada retoma o modo automático. Consulte [Limites de bloqueio repetido](#repeated-block-thresholds) para como os bloqueios são contados.487* **Bloqueios repetidos**: se o classificador bloqueia uma ação 3 vezes seguidas ou 20 vezes no total, o modo automático pausa e Claude Code retoma a solicitação. Aprovar a ação solicitada retoma o modo automático. Consulte [Limites de bloqueio repetido](#repeated-block-thresholds) para como os bloqueios são contados.

488* **Sem veredito do classificador**: quando uma verificação de segurança separada do modo automático recusa a própria solicitação do classificador, ou a resposta do classificador não analisa, Claude Code nega a ação sem a notificação ou a entrada **Recently denied**. Consulte [Auto mode cannot determine the safety of an action](/docs/pt/errors#auto-mode-cannot-determine-the-safety-of-an-action) para a mensagem que cada caso mostra e o que fazer.488* **Sem veredito do classificador**: quando uma verificação de segurança separada do modo automático recusa a própria solicitação do classificador, ou a resposta do classificador não analisa, Claude Code nega a ação sem a notificação ou a entrada **Recently denied**. Consulte [Auto mode cannot determine the safety of an action](/docs/pt/errors#auto-mode-cannot-determine-the-safety-of-an-action) para a mensagem que cada caso mostra e o que fazer.

489* **Sem veredito do servidor**: sob [revisão do classificador no servidor](#server-side-classifier-review), Claude Code nega uma ação para a qual o servidor não fornece um veredito, e para a volta após dez respostas seguidas sem veredito. Consulte [O servidor não retornou um veredito de segurança](/docs/pt/errors#the-server-returned-no-safety-verdict).489* **Sem veredito do servidor**: sob [revisão do classificador no servidor](#server-side-classifier-review), Claude Code nega uma ação que o servidor não dá veredito, e para a volta após dez respostas seguidas sem veredito. Consulte [O servidor não retornou veredito de segurança](/docs/pt/errors#the-server-returned-no-safety-verdict).

490* **Uma mudança de modo durante uma verificação**: se você alternar modos de permissão enquanto uma verificação do classificador está pendente, Claude Code descarta um veredito que o novo modo não teria solicitado. Você é solicitado para aprovação em vez disso, ou a ação é negada automaticamente no [modo `dontAsk`](#allow-only-pre-approved-tools-with-dontask-mode).490* **Uma mudança de modo durante uma verificação**: se você mudar modos de permissão enquanto uma verificação do classificador está pendente, Claude Code descarta um veredito que o novo modo não teria solicitado. Você é solicitado para aprovação em vez disso, ou a ação é auto-negada em [modo `dontAsk`](#allow-only-pre-approved-tools-with-dontask-mode).

491 491 

492<h4 id="repeated-block-thresholds">492<h4 id="repeated-block-thresholds">

493 Limites de bloqueio repetido493 Limites de bloqueio repetido


495 495 

496Os limites de 3 bloqueios seguidos e 20 bloqueios no total não são configuráveis. O contador total persiste para a sessão e redefine apenas quando seu próprio limite dispara um fallback. Claude Code não conta uma negação para nenhum limite quando uma verificação de segurança separada do modo automático recusa a própria solicitação do classificador.496Os limites de 3 bloqueios seguidos e 20 bloqueios no total não são configuráveis. O contador total persiste para a sessão e redefine apenas quando seu próprio limite dispara um fallback. Claude Code não conta uma negação para nenhum limite quando uma verificação de segurança separada do modo automático recusa a própria solicitação do classificador.

497 497 

498Uma execução `-p` [não interativa](/docs/pt/headless) sem um [`--permission-prompt-tool`](/docs/pt/cli-reference#cli-flags) não tem um prompt para voltar. Quando bloqueios repetidos atingem um limite, a ação não executa e Claude continua trabalhando. Claude Code não para a execução.498Uma execução `-p` [não interativa](/docs/pt/headless) sem um [`--permission-prompt-tool`](/docs/pt/cli-reference#cli-flags) não tem prompt para voltar. Quando bloqueios repetidos atingem um limite, a ação não executa e Claude continua trabalhando. Claude Code não para a execução.

499 499 

500Bloqueios repetidos geralmente significam que o classificador está perdendo contexto sobre sua infraestrutura. Use `/feedback` para relatar falsos positivos, ou tenha um administrador [configurar infraestrutura confiável](/docs/pt/auto-mode-config).500Bloqueios repetidos geralmente significam que o classificador está perdendo contexto sobre sua infraestrutura. Use `/feedback` para relatar falsos positivos, ou tenha um administrador [configurar infraestrutura confiável](/docs/pt/auto-mode-config).

501 501 


503 Como o modo automático avalia ações503 Como o modo automático avalia ações

504</h3>504</h3>

505 505 

506As seções a seguir abrangem a ordem em que Claude Code avalia uma ação, como o classificador revisa o trabalho de subagentes e quais chamadas do classificador adicionam em custo e latência.506As seções a seguir cobrem a ordem em que Claude Code avalia uma ação, como o classificador revisa o trabalho de subagentes e quais chamadas do classificador adicionam em custo e latência.

507 507 

508<span id="how-the-classifier-evaluates-actions" />508<span id="how-the-classifier-evaluates-actions" />

509 509 


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

513 513 

514 1. Ações que correspondem a suas [regras de permitir, solicitar ou negar](/docs/pt/permissions#manage-permissions) resolvem imediatamente, com essas exceções:514 1. Ações que correspondem a suas [regras de permitir, solicitar ou negar](/docs/pt/permissions#manage-permissions) resolvem imediatamente, com essas exceções:

515 * Escritas em [caminhos protegidos](#protected-paths) são roteadas para o classificador mesmo quando uma regra de permissão corresponde515 * Escritas em [caminhos protegidos](#protected-paths) são roteadas para o classificador mesmo quando uma regra de permitir corresponde

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

517 * Ferramentas MCP marcadas [`requiresUserInteraction`](/docs/pt/mcp#require-approval-for-a-specific-tool) o solicitam diretamente mesmo quando uma regra de permissão corresponde, e também ferramentas de conector [sua organização definiu como `ask`](/docs/pt/mcp#organization-controls-on-connector-tools) em sessões onde essa configuração chega a Claude Code517 * Ferramentas MCP marcadas [`requiresUserInteraction`](/docs/pt/mcp#require-approval-for-a-specific-tool) o solicitam diretamente mesmo quando uma regra de permitir corresponde, e também ferramentas de conector [sua organização definiu como `ask`](/docs/pt/mcp#organization-controls-on-connector-tools) em sessões onde essa configuração chega a Claude Code

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

519 * Regras de solicitação que correspondem no conteúdo de um comando, como `Bash(git push *)`, voltam para um prompt de permissão519 * Regras de solicitação que correspondem no conteúdo de um comando, como `Bash(git push *)`, voltam para um prompt de permissão

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

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

522 * Em uma sessão com [revisão do classificador no servidor](#server-side-classifier-review), ações somente leitura e comandos de shell [em sandbox](/docs/pt/sandboxing#sandbox-modes) aguardam essa revisão e são bloqueados se a sinalizam522 * Em uma sessão com [revisão do classificador no servidor](#server-side-classifier-review), ações somente leitura e comandos de shell [em sandbox](/docs/pt/sandboxing#sandbox-modes) esperam por essa revisão e são bloqueados se a sinalizam

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

524 3. Tudo mais vai para o classificador, além de [remoções de caminho crítico](#critical-paths) sob seu tratamento padrão. As ferramentas de conector e `requiresUserInteraction` ferramentas MCP que o solicitam diretamente na etapa 1 nunca chegam ao classificador, portanto nem uma aprovação exigida pela organização nem uma etapa de consentimento é auto-aprovada524 3. Tudo mais vai para o classificador, além de [remoções de caminho crítico](#critical-paths) sob seu tratamento padrão. As ferramentas de conector e ferramentas MCP `requiresUserInteraction` que o solicitam diretamente na etapa 1 nunca chegam ao classificador também, então nem uma aprovação exigida pela org nem uma etapa de consentimento é auto-aprovada

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

526 526 

527 Ao entrar no modo automático, regras de permissão amplas que concedem execução de código arbitrário são descartadas:527 Um [mod](/docs/pt/plugins/mods/overview) que você instala que conecta `tool.check` pode aprovar uma ação antes da etapa 3, e o classificador não verifica uma ação que o mod aprova. Consulte [Estender permissões com hooks](/docs/pt/permissions#extend-permissions-with-hooks).

528 

529 Ao entrar no modo automático, regras de permitir amplas que concedem execução de código arbitrário são descartadas:

528 530 

529 * `Bash(*)` ou `PowerShell(*)` em branco531 * `Bash(*)` ou `PowerShell(*)` em branco

530 * Intérpretes com wildcard como `Bash(python*)`532 * Intérpretes com wildcard como `Bash(python*)`

531 * Comandos de execução do gerenciador de pacotes533 * Comandos de execução do gerenciador de pacotes

532 * Regras `Agent`534 * Regras `Agent`

533 * [`Monitor`](/docs/pt/tools-reference#monitor-tool) regras de permissão, porque Claude Code executa comandos Monitor através do shell535 * [`Monitor`](/docs/pt/tools-reference#monitor-tool) regras de permitir, porque Claude Code executa comandos Monitor através do shell

534 536 

535 Regras estreitas como `Bash(npm test)` permanecem em vigor. Claude Code restaura as regras descartadas quando você deixa o modo automático. Antes da v2.1.236, Claude Code deixou regras de permissão `Monitor` em vigor no modo automático, portanto uma regra que correspondesse à ferramenta inteira aprovava comandos Monitor sem revisão do classificador.537 Regras estreitas como `Bash(npm test)` permanecem em vigor. Claude Code restaura as regras descartadas quando você deixa o modo automático. Antes de v2.1.236, Claude Code deixou regras de permitir `Monitor` em vigor no modo automático, então uma regra que correspondesse à ferramenta inteira aprovava comandos Monitor sem revisão do classificador.

536 538 

537 Claude Code também executa `git status` em si antes de um comando que descartaria trabalho não confirmado, como `git reset --hard` ou `rm -rf`, e mostra ao classificador se há trabalho preparado, modificado ou não rastreado presente. Claude Code relata arquivos não rastreados nessa verificação mesmo quando a configuração git do repositório define `status.showUntrackedFiles=no`.539 Claude Code também executa `git status` em si antes de um comando que descartaria trabalho não confirmado, como `git reset --hard` ou `rm -rf`, e mostra ao classificador se há trabalho preparado, modificado ou não rastreado presente. Claude Code relata arquivos não rastreados nessa verificação mesmo quando a configuração git do repositório define `status.showUntrackedFiles=no`.

538 540 

539 Nas solicitações do classificador enviadas pelo próprio Claude Code, o classificador vê mensagens do usuário, chamadas de ferramenta diferentes de lookups somente leitura como leituras de arquivo e buscas, e seu conteúdo CLAUDE.md. Resultados de ferramentas são removidos dessas solicitações, portanto conteúdo hostil em um arquivo ou página da web não pode manipular o classificador diretamente.541 Nas solicitações do classificador enviadas pelo próprio Claude Code, o classificador vê mensagens do usuário, chamadas de ferramenta diferentes de lookups somente leitura como leituras de arquivo e buscas, e seu conteúdo CLAUDE.md. Resultados de ferramenta são removidos dessas solicitações, então conteúdo hostil em um arquivo ou página da web não consegue manipular o classificador diretamente.

540 542 

541 Você pode anotar o resultado de uma chamada com um campo [`classifierContext` do hook PostToolUse](/docs/pt/hooks#annotate-a-result-for-the-auto-mode-classifier), que o classificador lê como contexto fornecido pela aplicação. O campo requer Claude Code v2.1.236 ou posterior.543 Você pode anotar o resultado de uma chamada com um [campo `classifierContext` do hook PostToolUse](/docs/pt/hooks#annotate-a-result-for-the-auto-mode-classifier), que o classificador lê como contexto fornecido pela aplicação. O campo requer Claude Code v2.1.236 ou posterior.

542 544 

543 Uma sonda separada no servidor escaneia resultados de ferramentas recebidas e sinaliza conteúdo suspeito antes que Claude o leia. Para mais sobre como essas camadas funcionam juntas, consulte o [anúncio do modo automático](https://claude.com/blog/auto-mode) e o [aprofundamento de engenharia](https://www.anthropic.com/engineering/claude-code-auto-mode).545 Uma sonda separada no servidor escaneia resultados de ferramenta de entrada e sinaliza conteúdo suspeito antes que Claude o leia. Para mais sobre como essas camadas funcionam juntas, consulte o [anúncio do modo automático](https://claude.com/blog/auto-mode) e o [aprofundamento de engenharia](https://www.anthropic.com/engineering/claude-code-auto-mode).

544 </Accordion>546 </Accordion>

545 547 

546 <Accordion title="Como o modo automático lida com subagentes">548 <Accordion title="Como o modo automático lida com subagentes">

547 O classificador verifica o trabalho de [subagentes](/docs/pt/sub-agents) em três pontos:549 O classificador verifica o trabalho de [subagente](/docs/pt/sub-agents) em três pontos:

548 550 

549 1. Antes de um subagente iniciar, a descrição da tarefa delegada é avaliada, portanto uma tarefa que parece perigosa é bloqueada no tempo de spawn.551 1. Antes de um subagente iniciar, a descrição da tarefa delegada é avaliada, então uma tarefa que parece perigosa é bloqueada no tempo de spawn.

550 2. Enquanto o subagente executa, cada uma de suas ações passa pela mesma [ordem de decisão](#how-the-classifier-evaluates-actions) que na sessão pai, com as mesmas regras de bloqueio e permissão. Qualquer `permissionMode` no frontmatter do subagente é ignorado.552 2. Enquanto o subagente executa, cada uma de suas ações passa pela mesma [ordem de decisão](#how-the-classifier-evaluates-actions) como na sessão pai, com as mesmas regras de bloqueio e permitir. Qualquer `permissionMode` no frontmatter do subagente é ignorado.

551 3. Quando o subagente termina, o classificador revisa seu trabalho e seu relatório final antes que o pai leia o relatório. Quando o classificador sinaliza o trabalho ou relatório do subagente, ou uma verificação de segurança de API separada recusa a revisão, o relatório ainda é entregue, precedido por um aviso de segurança. Quando o classificador está indisponível para a revisão, o relatório chega com uma nota para verificar o trabalho do subagente antes de agir com base nele.553 3. Quando o subagente termina, o classificador revisa seu trabalho e seu relatório final antes que o pai leia o relatório. Quando o classificador sinaliza o trabalho ou relatório do subagente, ou uma verificação de segurança de API separada recusa a revisão, o relatório ainda é entregue, precedido por um aviso de segurança. Quando o classificador não está disponível para a revisão, o relatório chega com uma nota para verificar o trabalho do subagente antes de agir sobre ele.

552 </Accordion>554 </Accordion>

553 555 

554 <Accordion title="Custo e latência">556 <Accordion title="Custo e latência">

555 O classificador executa em Claude Sonnet 5 por padrão em vez de em sua seleção `/model`. Um modelo classificador que a Anthropic configura no servidor tem precedência sobre esse padrão. Quando o modelo de sua sessão é Claude Sonnet 4.6, ou quando [`availableModels`](/docs/pt/model-config#restrict-model-selection) exclui Sonnet 5, o classificador executa no modelo de sua sessão em vez disso, ou em um modelo Opus quando a sessão executa em um [modelo Fable](/docs/pt/model-config#work-with-fable); em provedores diferentes da API Anthropic, esse fallback Opus é o modelo Opus padrão do provedor.557 O classificador executa em Claude Sonnet 5 por padrão em vez de em sua seleção `/model`. Um modelo classificador que a Anthropic configura no servidor tem precedência sobre esse padrão. Quando o modelo de sua sessão é Claude Sonnet 4.6, ou quando [`availableModels`](/docs/pt/model-config#restrict-model-selection) exclui Sonnet 5, o classificador executa no modelo de sua sessão em vez disso, ou em um modelo Opus quando a sessão executa em um [modelo Fable](/docs/pt/model-config#work-with-fable); em provedores diferentes da API Anthropic, esse fallback Opus é o modelo Opus padrão do provedor.

556 558 

557 A primeira solicitação de modo automático da sessão valida o padrão Sonnet 5: se a solicitação for bem-sucedida, Sonnet 5 permanece o modelo classificador da sessão, e se falhar porque o modelo não está disponível, a sessão usa o fallback em vez disso. Depois que essa validação se resolve, o modelo do classificador não muda para a sessão.559 A primeira solicitação de modo automático da sessão valida o padrão Sonnet 5: se a solicitação for bem-sucedida, Sonnet 5 permanece o modelo classificador da sessão, e se falhar porque o modelo não está disponível, a sessão usa o fallback em vez disso.

558 560 

559 Em planos Enterprise e em contas que usam a API Claude, [Claude Platform on AWS](/docs/pt/claude-platform-on-aws), Amazon Bedrock, Agent Platform do Google Cloud ou Microsoft Foundry, chamadas do classificador contam para seu uso de token. Cada verificação envia uma porção da transcrição mais a ação pendente, adicionando uma volta antes da execução. Leituras e edições de diretório de trabalho fora de caminhos protegidos pulam o classificador, portanto a sobrecarga vem principalmente de comandos de shell e operações de rede. Onde o servidor revisa as ações como parte das solicitações de modelo da sessão, não há chamadas do classificador separadas para contar; consulte [Revisão do classificador no servidor](#server-side-classifier-review).561 Em planos Enterprise e em contas que usam a API Claude, [Claude Platform on AWS](/docs/pt/claude-platform-on-aws), Amazon Bedrock, Agent Platform do Google Cloud ou Microsoft Foundry, chamadas do classificador contam para seu uso de token. Cada verificação envia uma porção da transcrição mais a ação pendente, adicionando uma volta antes da execução. Leituras e edições de diretório de trabalho fora de caminhos protegidos pulam o classificador, então a sobrecarga vem principalmente de comandos de shell e operações de rede. Onde o servidor revisa as ações como parte das solicitações de modelo da sessão, não há chamadas do classificador separadas para contar; consulte [Revisão do classificador no servidor](#server-side-classifier-review).

560 562 

561 Acesso à rede em sandbox não adiciona solicitações do classificador por conexão. O classificador julga [os hosts que um comando nomeia](/docs/pt/sandboxing#per-command-allowed-domains-in-auto-mode) junto com o comando em uma revisão, e Claude Code verifica cada conexão contra a lista aprovada sem chamar o classificador novamente.563 Acesso de rede em sandbox não adiciona solicitações do classificador por conexão. O classificador julga [os hosts que um comando nomeia](/docs/pt/sandboxing#per-command-allowed-domains-in-auto-mode) junto com o comando em uma revisão, e Claude Code verifica cada conexão contra a lista aprovada sem chamar o classificador novamente.

562 </Accordion>564 </Accordion>

563</AccordionGroup>565</AccordionGroup>

564 566 


667* `.yarn`669* `.yarn`

668* `.mvn`670* `.mvn`

669* `.claude`, exceto por `.claude/worktrees` onde Claude armazena seus próprios git worktrees671* `.claude`, exceto por `.claude/worktrees` onde Claude armazena seus próprios git worktrees

672* Um diretório que você carregou com [`--plugin-dir`](/docs/pt/plugins/mods/create#change-a-mod-with-claude), porque Claude Code recarrega e executa o código de um mod a partir dele quando um arquivo muda

670 673 

671Arquivos protegidos:674Arquivos protegidos:

672 675 

permissions.md +14 −3

Details

602 602 

603Os [hooks do Claude Code](/docs/pt/hooks-guide) permitem registrar comandos de shell personalizados que avaliam permissões em tempo de execução. Quando Claude Code faz uma chamada de ferramenta, os hooks PreToolUse são executados antes do prompt de permissão, para todas as ferramentas exceto [`EndConversation`](/docs/pt/tools-reference#endconversation-tool-behavior). A saída do hook pode negar a chamada de ferramenta, forçar um prompt ou pular o prompt para deixar a chamada prosseguir.603Os [hooks do Claude Code](/docs/pt/hooks-guide) permitem registrar comandos de shell personalizados que avaliam permissões em tempo de execução. Quando Claude Code faz uma chamada de ferramenta, os hooks PreToolUse são executados antes do prompt de permissão, para todas as ferramentas exceto [`EndConversation`](/docs/pt/tools-reference#endconversation-tool-behavior). A saída do hook pode negar a chamada de ferramenta, forçar um prompt ou pular o prompt para deixar a chamada prosseguir.

604 604 

605As decisões do hook não contornam as regras de permissão. Claude Code avalia regras deny e ask independentemente do que um hook PreToolUse retorna: uma regra deny correspondente bloqueia a chamada, e uma regra ask correspondente ainda solicita mesmo quando o hook retornou `"allow"` ou `"ask"`. Isto preserva a precedência deny-first descrita em [Gerenciar permissões](#manage-permissions), incluindo regras deny definidas em configurações gerenciadas.605As decisões do hook PreToolUse não contornam as regras de permissão. Claude Code avalia regras deny e ask independentemente do que um hook PreToolUse retorna: uma regra deny correspondente bloqueia a chamada, e uma regra ask correspondente ainda solicita mesmo quando o hook retornou `"allow"` ou `"ask"`. Isto preserva a precedência deny-first descrita em [Gerenciar permissões](#manage-permissions), incluindo regras deny definidas em configurações gerenciadas.

606 

607Essa precedência cobre hooks em arquivos de configuração e no `hooks/hooks.json` de um plugin. Um [mod](/docs/pt/plugins/mods/overview) que você instala e que faz hook em `tool.check` responde após as regras e os hooks PreToolUse terem decidido, e sua resposta pode substituir a deles:

608 

609* **Regras Ask**: o mod pode aprovar uma chamada que uma regra ask solicitaria

610* **Um bloqueio de um hook `PreToolUse`**: o mod pode aprovar a chamada, a menos que o hook esteja em configurações gerenciadas

611* **O classificador de modo automático**: em [modo automático](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode), uma chamada que o mod aprova é executada sem uma verificação de classificador

612* **Regras Deny**: em uma máquina com configurações gerenciadas, ou quando você está conectado com um plano Team ou Enterprise, as regras deny têm precedência sobre o mod por padrão, e sua organização pode alterar isso. Em qualquer outro lugar, o mod pode aprovar uma chamada que uma regra deny recusa.

613 

614Veja [Decidir se confia em um mod](/docs/pt/plugins/mods/overview#decide-whether-to-trust-a-mod), ou [Gerenciar mods para sua organização](/docs/pt/plugins/mods/admin#know-what-happens-by-default) se você implantar configurações gerenciadas.

606 615 

607As ferramentas MCP marcadas como [`requiresUserInteraction`](/docs/pt/mcp#require-approval-for-a-specific-tool) também ainda solicitam quando um hook retorna `"allow"`, assim como as ferramentas connector [que sua organização definiu como `ask`](/docs/pt/mcp#organization-controls-on-connector-tools) em sessões onde essa configuração chega ao Claude Code.616As ferramentas MCP marcadas como [`requiresUserInteraction`](/docs/pt/mcp#require-approval-for-a-specific-tool) também ainda solicitam quando um hook retorna `"allow"`, assim como as ferramentas connector [que sua organização definiu como `ask`](/docs/pt/mcp#organization-controls-on-connector-tools) em sessões onde essa configuração chega ao Claude Code.

608 617 


720 729 

721O mesmo se aplica entre escopos de configurações: se as configurações de usuário permitirem uma permissão e as configurações de projeto a negarem, a regra de negação a bloqueia. O inverso também é verdadeiro: uma negação no nível de usuário bloqueia uma permissão no nível de projeto, porque as regras de negação de qualquer escopo são avaliadas antes das regras de permissão.730O mesmo se aplica entre escopos de configurações: se as configurações de usuário permitirem uma permissão e as configurações de projeto a negarem, a regra de negação a bloqueia. O inverso também é verdadeiro: uma negação no nível de usuário bloqueia uma permissão no nível de projeto, porque as regras de negação de qualquer escopo são avaliadas antes das regras de permissão.

722 731 

732Esta precedência é entre arquivos de configurações e argumentos de linha de comando. Para saber se uma regra de negação se aplica a um [mod](/docs/pt/plugins/mods/overview) que você instala, consulte [Estender permissões com hooks](#extend-permissions-with-hooks).

733 

723Os hosts de incorporação podem fornecer política gerenciada adicional por meio da opção `managedSettings` do SDK, incluindo regras de permissão de permissão, a menos que o administrador defina os bloqueios `allowManaged*Only`; [Entregar política para sessões do Claude Desktop](/docs/pt/claude-apps-gateway#deliver-policy-to-claude-desktop-sessions) aborda quando a política do incorporador se aplica.734Os hosts de incorporação podem fornecer política gerenciada adicional por meio da opção `managedSettings` do SDK, incluindo regras de permissão de permissão, a menos que o administrador defina os bloqueios `allowManaged*Only`; [Entregar política para sessões do Claude Desktop](/docs/pt/claude-apps-gateway#deliver-policy-to-claude-desktop-sessions) aborda quando a política do incorporador se aplica.

724 735 

725<h2 id="project-allow-rules-and-workspace-trust">736<h2 id="project-allow-rules-and-workspace-trust">


766| [Hooks](/docs/pt/hooks) em arquivos de configurações, o bloco [`env`](/docs/pt/settings-reference#env) e comandos auxiliares como [`apiKeyHelper`](/docs/pt/settings-reference#apikeyhelper), e os [hooks](/docs/pt/hooks#hooks-in-skills-and-agents) de uma skill de projeto e [`allowed-tools`](/docs/pt/skills#pre-approve-tools-for-a-skill) | Usado | Usado. A confiança do workspace nunca bloqueia `allowed-tools` de uma skill em nenhuma sessão |777| [Hooks](/docs/pt/hooks) em arquivos de configurações, o bloco [`env`](/docs/pt/settings-reference#env) e comandos auxiliares como [`apiKeyHelper`](/docs/pt/settings-reference#apikeyhelper), e os [hooks](/docs/pt/hooks#hooks-in-skills-and-agents) de uma skill de projeto e [`allowed-tools`](/docs/pt/skills#pre-approve-tools-for-a-skill) | Usado | Usado. A confiança do workspace nunca bloqueia `allowed-tools` de uma skill em nenhuma sessão |

767| Regras `permissions.allow` e `additionalDirectories` em `.claude/settings.json` | Não usado até você aceitar o diálogo de confiança, que aparece novamente listando-os | Não usado. Claude Code imprime um aviso [`this workspace has not been trusted`](/docs/pt/errors#workspace-has-not-been-trusted) para stderr |778| Regras `permissions.allow` e `additionalDirectories` em `.claude/settings.json` | Não usado até você aceitar o diálogo de confiança, que aparece novamente listando-os | Não usado. Claude Code imprime um aviso [`this workspace has not been trusted`](/docs/pt/errors#workspace-has-not-been-trusted) para stderr |

768| Hooks de frontmatter em um [subagent](/docs/pt/sub-agents#hooks-in-subagent-frontmatter) de projeto, um plugin [`@skills-dir`](/docs/pt/plugins/loading#plugins-shared-through-a-repository) de projeto, e entradas [`extraKnownMarketplaces`](/docs/pt/settings-reference#extraknownmarketplaces) do repositório ou um diretório `--add-dir` | Não usado, e nenhum diálogo é oferecido | Não usado |779| Hooks de frontmatter em um [subagent](/docs/pt/sub-agents#hooks-in-subagent-frontmatter) de projeto, um plugin [`@skills-dir`](/docs/pt/plugins/loading#plugins-shared-through-a-repository) de projeto, e entradas [`extraKnownMarketplaces`](/docs/pt/settings-reference#extraknownmarketplaces) do repositório ou um diretório `--add-dir` | Não usado, e nenhum diálogo é oferecido | Não usado |

769| [`mcpServers`](/docs/pt/sub-agents#scope-mcp-servers-to-a-subagent) inline no frontmatter de um subagent do repositório ou um diretório `--add-dir`. Antes da v2.1.238, Claude Code carregava esses servidores em ambas as situações | Não usado, e nenhum diálogo é oferecido | Não usado |780| Inline [`mcpServers`](/docs/pt/sub-agents#scope-mcp-servers-to-a-subagent) no frontmatter de um subagent do repositório ou um diretório `--add-dir` | Não usado, e nenhum diálogo é oferecido | Não usado |

770| Servidores em `.mcp.json`, incluindo aqueles que o repositório [aprova em suas próprias configurações](/docs/pt/mcp#project-server-approvals-and-workspace-trust) | Claude Code pergunta antes de conectá-los. As aprovações do próprio repositório não contam | Conectado sem perguntar, aprovado ou não. O SDK os carrega apenas quando `settingSources` inclui configurações de projeto. `claude mcp list` na mesma pasta ainda relata tal servidor como pendente |781| Servidores em `.mcp.json`, incluindo aqueles que o repositório [aprova em suas próprias configurações](/docs/pt/mcp#project-server-approvals-and-workspace-trust) | Claude Code pergunta antes de conectá-los. As aprovações do próprio repositório não contam | Conectado sem perguntar, aprovado ou não. O SDK os carrega apenas quando `settingSources` inclui configurações de projeto. `claude mcp list` na mesma pasta ainda relata tal servidor como pendente |

771| Um [`headersHelper`](/docs/pt/mcp#trust-a-folder-before-its-headershelper-runs) em um servidor em `.mcp.json`. Antes da v2.1.238, Claude Code executava o auxiliar em ambas as situações | Não executado até você aceitar o diálogo de confiança, que aparece novamente nomeando onde o auxiliar é declarado. Claude Code conecta o servidor apenas com seus `headers` estáticos até então | Não executado. Claude Code conecta o servidor com seus `headers` estáticos e imprime uma linha [`headersHelper not run`](/docs/pt/errors#headershelper-not-run) por servidor para stderr |782| Um [`headersHelper`](/docs/pt/mcp#trust-a-folder-before-its-headershelper-runs) em um servidor em `.mcp.json` | Não executado até você aceitar o diálogo de confiança, que aparece novamente nomeando onde o auxiliar é declarado. Claude Code conecta o servidor com seus `headers` estáticos até então | Não executado. Claude Code conecta o servidor com seus `headers` estáticos e imprime uma linha [`headersHelper not run`](/docs/pt/errors#headershelper-not-run) por servidor para stderr |

772 783 

773Para as linhas que precisam dessa pasta exata confiada, confie nela manualmente: defina `projects["<path>"].hasTrustDialogAccepted` como `true` em `~/.claude.json`, onde `<path>` é a raiz do repositório, ou a pasta em si fora de um repositório. Claude Code imprime a chave exata na linha de log de depuração para um hook de subagent ignorado ou servidor MCP inline, no aviso stderr para regras de permissão ignoradas, e na linha `headersHelper not run` para um auxiliar ignorado.784Para as linhas que precisam dessa pasta exata confiada, confie nela manualmente: defina `projects["<path>"].hasTrustDialogAccepted` como `true` em `~/.claude.json`, onde `<path>` é a raiz do repositório, ou a pasta em si fora de um repositório. Claude Code imprime a chave exata na linha de log de depuração para um hook de subagent ignorado ou servidor MCP inline, no aviso stderr para regras de permissão ignoradas, e na linha `headersHelper not run` para um auxiliar ignorado.

774 785 

Details

29Cada subcomando compartilha estes códigos de saída, argumentos de plugin e valores de escopo:29Cada subcomando compartilha estes códigos de saída, argumentos de plugin e valores de escopo:

30 30 

31* **Códigos de saída**: `0` em caso de sucesso e `1` em caso de falha. `validate` adiciona saída `2` para um erro inesperado, e `eval` adiciona os códigos listados em [sua seção](#plugin-eval).31* **Códigos de saída**: `0` em caso de sucesso e `1` em caso de falha. `validate` adiciona saída `2` para um erro inesperado, e `eval` adiciona os códigos listados em [sua seção](#plugin-eval).

32* **Argumentos de plugin**: um argumento `<plugin>` é um `name` de plugin ou `name@marketplace`. Quando dois marketplaces oferecem o mesmo nome, use a forma qualificada.32* **Argumentos de plugin**: um argumento `<plugin>` é um `name` de plugin ou `name@marketplace`. Quando dois marketplaces oferecem o mesmo nome, use a forma qualificada. `configure` aceita apenas a forma qualificada.

33* **Escopos**: `--scope` aceita `user`, `project` ou `local`, e nomeia o arquivo de configurações que o comando escreve. `update` também aceita `managed`.33* **Escopos**: `--scope` aceita `user`, `project` ou `local`, e nomeia o arquivo de configurações que o comando escreve. `update` também aceita `managed`.

34 34 

35<h3 id="plugin-init">35<h3 id="plugin-init">


87| Flag | Descrição |87| Flag | Descrição |

88| :- | :- |88| :- | :- |

89| `-s, --scope <scope>` | Escopo de instalação: `user`, `project` ou `local`. Padrão é `user` |89| `-s, --scope <scope>` | Escopo de instalação: `user`, `project` ou `local`. Padrão é `user` |

90| `--config <key=value>` | Defina uma opção [`userConfig`](/docs/pt/plugins/manifest-reference) que o manifesto do plugin declara. Repita a flag para cada opção. Requer Claude Code v2.1.147 ou posterior |90| `--config <key=value>` | Defina uma opção [`userConfig`](/docs/pt/plugins/manifest-reference) que o manifesto do plugin declara. Repita a flag para cada opção. Requer Claude Code v2.1.147 ou posterior. Uma chave escrita como `<server>.<key>` define uma configuração que um [servidor MCP empacotado](/docs/pt/plugins/components#include-a-packaged-mcpb-server) declara em sua própria `user_config`, para um arquivo de pacote enviado dentro do plugin. A forma `<server>.<key>` requer Claude Code v2.1.285 ou posterior |

91| `-y, --yes` | Aceite o comando de instalação exibido sem o prompt `Run this command now?`. Ignorado quando o comando é executado dentro de uma sessão Claude Code, como da ferramenta Bash ou um hook. Requer Claude Code v2.1.229 ou posterior |91| `-y, --yes` | Aceite o comando de instalação exibido sem o prompt `Run this command now?`. Ignorado quando o comando é executado dentro de uma sessão Claude Code, como da ferramenta Bash ou um hook. Requer Claude Code v2.1.229 ou posterior |

92| `--accept-command <sha256>` | Aceite o comando de instalação exibido cujo `sha256` uma execução anterior [`--json`](#plugin-json-result) relatou em `shownCommand`, no lugar de `-y`. Não pode ser combinado com `-y`. Veja [Aceitar um comando de instalação exibido](#accept-a-displayed-install-command). Requer Claude Code v2.1.271 ou posterior |92| `--accept-command <sha256>` | Aceite o comando de instalação exibido cujo `sha256` uma execução anterior [`--json`](#plugin-json-result) relatou em `shownCommand`, no lugar de `-y`. Não pode ser combinado com `-y`. Veja [Aceitar um comando de instalação exibido](#accept-a-displayed-install-command). Requer Claude Code v2.1.271 ou posterior |

93| `--json` | Imprima o resultado como um objeto JSON na última linha de stdout em vez da mensagem legível por humanos, para uso em scripts. Veja [Formato de resultado JSON](#plugin-json-result). Requer Claude Code v2.1.268 ou posterior |93| `--json` | Imprima o resultado como um objeto JSON na última linha de stdout em vez da mensagem legível por humanos, para uso em scripts. Veja [Formato de resultado JSON](#plugin-json-result). Requer Claude Code v2.1.268 ou posterior |


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

300| `--json` | Imprima a lista como JSON |300| `--json` | Imprima a lista como JSON |

301| `--available` | Também liste plugins que seus marketplaces oferecem que você não instalou. Não tem efeito sem `--json` |301| `--available` | Também liste plugins que seus marketplaces oferecem que você não instalou. Não tem efeito sem `--json` |

302| `--data-size [plugin]` | Meça o [diretório de dados salvos](#what-an-uninstall-deletes-and-keeps) de cada plugin instalado, ou apenas o do plugin nomeado, dado como `name@marketplace`. Não tem efeito sem `--json`. Se o nome não tem registro de instalação, o comando imprime `--data-size names a plugin that is not installed` e sai com `1` em vez de imprimir a lista. Requer Claude Code v2.1.285 ou posterior |

302 303 

303Claude Code agrupa a saída legível por humanos por como cada plugin carrega:304Claude Code agrupa a saída legível por humanos por como cada plugin carrega:

304 305 


330| `notes` | array of strings | Avisos de autoria para um plugin que carregou e funciona |331| `notes` | array of strings | Avisos de autoria para um plugin que carregou e funciona |

331| `errorDetails` | array of objects | Um objeto por entrada `errors`, fornecendo seu `type` de diagnóstico e os nomes aos quais se refere, como o plugin, marketplace, servidor ou arquivo. Requer Claude Code v2.1.268 ou posterior |332| `errorDetails` | array of objects | Um objeto por entrada `errors`, fornecendo seu `type` de diagnóstico e os nomes aos quais se refere, como o plugin, marketplace, servidor ou arquivo. Requer Claude Code v2.1.268 ou posterior |

332| `noteDetails` | array of objects | Os mesmos objetos de detalhe para cada entrada `notes`. Requer Claude Code v2.1.268 ou posterior |333| `noteDetails` | array of objects | Os mesmos objetos de detalhe para cada entrada `notes`. Requer Claude Code v2.1.268 ou posterior |

334| `hasUserConfig` | boolean | Presente e `true` quando o plugin carregou e seu manifesto declara opções [`userConfig`](/docs/pt/plugins/manifest-reference#user-configuration). Ausente para um plugin que falhou ao carregar, qualquer que seja seu manifesto declare. Valores salvos nunca são incluídos. Requer Claude Code v2.1.285 ou posterior |

335| `projectEnabled` | boolean | Se o `.claude/settings.json` compartilhado do projeto ativa o plugin. Apenas installs de marketplace. Requer Claude Code v2.1.285 ou posterior |

336| `dataDirSize` | object | Com `--data-size`, o tamanho do [diretório de dados salvos](#what-an-uninstall-deletes-and-keeps) do plugin como `bytes` e `human`; ausente quando o diretório está faltando ou vazio. Apenas installs de marketplace. Requer Claude Code v2.1.285 ou posterior |

337| `dataDirUnreadable` | boolean | Com `--data-size`, `true` quando o diretório de dados salvos existe mas não conseguiu ser medido. Apenas installs de marketplace. Requer Claude Code v2.1.285 ou posterior |

333 338 

334Com `--json --available`, Claude Code imprime um objeto em vez de um array. Seu campo `installed` contém o array de objetos de plugin instalado, e seu campo `available` contém um objeto por plugin de marketplace não instalado com os campos abaixo.339Com `--json --available`, Claude Code imprime um objeto em vez de um array. Seu campo `installed` contém o array de objetos de plugin instalado, e seu campo `available` contém um objeto por plugin de marketplace não instalado com os campos abaixo.

335 340 


373 378 

374Para um plugin que não está carregado, Claude Code imprime ``Plugin "formatter" not found. Run `claude plugin list` to see installed plugins, or pass --plugin-dir <path> to load one from disk.`` e sai com `1`.379Para um plugin que não está carregado, Claude Code imprime ``Plugin "formatter" not found. Run `claude plugin list` to see installed plugins, or pass --plugin-dir <path> to load one from disk.`` e sai com `1`.

375 380 

381<h3 id="plugin-configure">

382 plugin configure

383</h3>

384 

385Mostre as opções [`userConfig`](/docs/pt/plugins/manifest-reference#user-configuration) de um plugin instalado e quais estão definidas, ou salve valores canalizados em stdin. Requer Claude Code v2.1.285 ou posterior.

386 

387```bash theme={null}

388claude plugin configure <plugin>

389```

390 

391| Flag | Descrição |

392| :- | :- |

393| `--values-stdin` | Leia valores de opção de stdin como um objeto JSON de strings de linha única e salve-os. Opções que você deixa de fora mantêm seus valores salvos |

394| `--json` | Imprima o resultado como um objeto JSON em stdout. Sem `--values-stdin`, o objeto carrega o `schema` e `choices` das opções, seus `inputs` iniciais, e os nomes de opções `configured` e `unconfigured`. Com `--values-stdin`, carrega os nomes de opções `saved` e, quando conseguem ser lidos novamente, os nomes `unconfigured` |

395 

396Sem flags, o comando lista cada opção com até três rótulos: `required` ou `optional`, depois `sensitive` para uma opção que o manifesto declara sensível, depois `set` ou `not set`. Não imprime valores salvos. Com `--json`, a saída inclui os valores salvos de opções que não são sensíveis, e nunca o texto de uma sensível.

397 

398Para salvar valores, escreva-os em um arquivo como um objeto JSON que mapeia chaves de opção para valores de string, depois passe o arquivo em stdin. Substitua `formatter@my-marketplace` pelo id do seu próprio plugin conforme `claude plugin list` o mostra. Este exemplo define uma opção nomeada `api_url` de um arquivo `values.json` que contém `{"api_url": "https://example.com"}`:

399 

400```bash theme={null}

401claude plugin configure formatter@my-marketplace --values-stdin < values.json

402```

403 

404Claude Code valida cada valor contra o tipo declarado da opção e imprime `Configuration saved. Restart Claude Code to apply it.` Se você passar uma chave que o manifesto não declara, ou um valor que falha na validação, o comando não salva nada, imprime `Failed to save configuration:` com o motivo, e sai com `1`. Com `--json`, um valor recusado também imprime um objeto em stdout cujo campo `refused` carrega a `message` e, quando uma opção é culpada, sua chave `option`.

405 

406Passe o id completo `name@marketplace` do plugin, conforme `claude plugin list` o mostra. `configure` não aceita um `name` simples. Quando nenhum plugin carregado tem esse id, o comando imprime `No installed plugin has the id "<plugin>".` e sai com `1`.

407 

408Para as configurações de um servidor MCP empacotado, veja [`plugin install --config`](#plugin-install) ou o item **Configure** em `/plugin`.

409 

376<h3 id="plugin-prune">410<h3 id="plugin-prune">

377 plugin prune411 plugin prune

378</h3>412</h3>

Details

791 791 

792Hooks em `hooks/hooks.json` e na chave de manifesto `hooks` ambos carregam. Para cada evento e sua carga útil, consulte [Eventos de hook](/docs/pt/hooks#hook-events).792Hooks em `hooks/hooks.json` e na chave de manifesto `hooks` ambos carregam. Para cada evento e sua carga útil, consulte [Eventos de hook](/docs/pt/hooks#hook-events).

793 793 

794Para escrever hooks como funções JavaScript que são executadas dentro do Claude Code e podem desenhar em sua interface, liste um arquivo de módulo sob uma chave `modules` no mesmo `hooks/hooks.json`. Um plugin com um é um mod. Consulte [Criar um mod](/docs/pt/plugins/mods/create).

795 

794<h4 id="when-plugin-hooks-fire">796<h4 id="when-plugin-hooks-fire">

795 Quando os hooks do plugin disparam797 Quando os hooks do plugin disparam

796</h4>798</h4>


868 870 

869O servidor usa seu nome do `name` no manifesto do pacote.871O servidor usa seu nome do `name` no manifesto do pacote.

870 872 

873Um manifesto próprio do pacote pode declarar configurações que o servidor precisa do usuário em um bloco `user_config`. Um servidor agrupado com uma configuração obrigatória que não tem valor salvo não inicia. A aba **Errors** de `/plugin` mostra `Bundled MCP server "<name>" was not started: it needs configuration`.

874 

875Os usuários fornecem os valores de uma de duas maneiras:

876 

877* **Em `/plugin`**: selecione o plugin na aba **Installed** e escolha **Configure**

878* **Na instalação, a partir do shell**: passe [`--config <server>.<key>=<value>`](/docs/pt/plugins/cli-reference#plugin-install) para `claude plugin install`. Requer Claude Code v2.1.285 ou posterior, e funciona apenas para um pacote empacotado dentro do plugin.

879 

871Para transportes e autenticação, consulte [MCP](/docs/pt/mcp#plugin-provided-mcp-servers).880Para transportes e autenticação, consulte [MCP](/docs/pt/mcp#plugin-provided-mcp-servers).

872 881 

873<h3 id="lsp-servers">882<h3 id="lsp-servers">


1071 Quando o diálogo de configuração aparece1080 Quando o diálogo de configuração aparece

1072</h3>1081</h3>

1073 1082 

1074O diálogo aparece apenas na interface interativa `/plugin`. Ele abre para qualquer opção que ainda não está definida quando o usuário faz qualquer um dos seguintes:1083O diálogo faz parte da interface interativa `/plugin`. Quando o usuário faz qualquer um dos seguintes, ele abre para qualquer opção que ainda não está definida:

1075 1084 

1076* Instala o plugin em `/plugin`1085* Instala o plugin em `/plugin`

1077* Executa `/plugin install <plugin>@<marketplace>` dentro de uma sessão1086* Executa `/plugin install <plugin>@<marketplace>` dentro de uma sessão


1079 1088 

1080Para abrir o mesmo diálogo a qualquer momento, o usuário executa `/plugin configure <plugin>@<marketplace>`.1089Para abrir o mesmo diálogo a qualquer momento, o usuário executa `/plugin configure <plugin>@<marketplace>`.

1081 1090 

1082O comando shell `claude plugin install` nunca solicita valores `userConfig`. Para definir valores do shell, passe cada um como `--config KEY=VALUE`. Quando opções permanecem indefinidas, o comando imprime uma linha `userConfig options not yet set` que nomeia ambas as formas de defini-las. [O diálogo `userConfig` nunca aparece](/docs/pt/plugins/troubleshooting#the-userconfig-dialog-never-appears) cita a linha.1091O diálogo Manage plugins da extensão VS Code [Manage plugins dialog](/docs/pt/vs-code#install-plugins) solicita opções não definidas como um formulário após uma instalação, e um ícone de engrenagem na linha do plugin abre o formulário novamente com todas as opções.

1092 

1093O comando shell `claude plugin install` nunca solicita valores `userConfig`. Para definir valores do shell, passe cada um como `--config KEY=VALUE` quando você instalar, ou redirecione um objeto JSON para [`claude plugin configure --values-stdin`](/docs/pt/plugins/cli-reference#plugin-configure) depois.

1094 

1095Quando opções permanecem indefinidas, `claude plugin install` imprime uma linha `userConfig options not yet set`. Para o texto exato da linha, consulte [O diálogo `userConfig` nunca aparece](/docs/pt/plugins/troubleshooting#the-userconfig-dialog-never-appears).

1083 1096 

1084Para os campos de opção, onde cada valor é armazenado, como um componente referencia um valor salvo e quais campos rejeitam `${user_config.*}`, consulte [Configuração do usuário](/docs/pt/plugins/manifest-reference#user-configuration).1097Para os campos de opção, onde cada valor é armazenado, como um componente referencia um valor salvo e quais campos rejeitam `${user_config.*}`, consulte [Configuração do usuário](/docs/pt/plugins/manifest-reference#user-configuration).

1085 1098 

Details

72 A última frase do resumo diz se o plugin é utilizável nesta sessão:72 A última frase do resumo diz se o plugin é utilizável nesta sessão:

73 73 

74 * **Active now**: `Plugin is now active.` Nenhuma recarga é necessária.74 * **Active now**: `Plugin is now active.` Nenhuma recarga é necessária.

75 * **Active, but a server needs setup**: `Plugin is now active.` é seguido por `Its bundled MCP server needs configuration before it can start`. O [servidor MCP empacotado](/docs/pt/plugins/components#include-a-packaged-mcpb-server) do plugin não pode iniciar até que você defina suas opções. Selecione o plugin na aba **Installed** em `/plugin` e escolha **Configure** para definir as opções do servidor.

75 * **Reload needed**: `Run /reload-plugins to activate.` O painel fecha e o Claude Code executa essa recarga para você. Se a recarga [invalidasse o cache de prompt](/docs/pt/prompt-caching#enabling-or-disabling-a-plugin), ela avisa e deixa o plugin pendente. Execute `/reload-plugins --force` para ativá-lo mesmo assim, o que custa uma solicitação sem cache.76 * **Reload needed**: `Run /reload-plugins to activate.` O painel fecha e o Claude Code executa essa recarga para você. Se a recarga [invalidasse o cache de prompt](/docs/pt/prompt-caching#enabling-or-disabling-a-plugin), ela avisa e deixa o plugin pendente. Execute `/reload-plugins --force` para ativá-lo mesmo assim, o que custa uma solicitação sem cache.

76 * **Load failed**: `The plugin couldn't be loaded`. Abra a aba **Errors** em `/plugin` para saber o motivo e depois veja [Após instalação: plugin não funcionando](/docs/pt/plugins/troubleshooting#plugin-installed-but-not-working).77 * **Load failed**: `The plugin couldn't be loaded`. Abra a aba **Errors** em `/plugin` para saber o motivo e depois veja [Após instalação: plugin não funcionando](/docs/pt/plugins/troubleshooting#plugin-installed-but-not-working).

77 </Step>78 </Step>


248Um 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:249Um 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:

249 250 

250* **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.251* **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.

251* **SSH**: o host já deve estar em seu arquivo `known_hosts` e a chave deve funcionar sem um prompt de frase-passe, porque os prompts de impressão digital do host e frase-passe também são suprimidos.252* **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.

252* **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`](/docs/pt/env-vars#variables) para pular essa verificação e sempre clonar sobre HTTPS.253* **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`](/docs/pt/env-vars#variables) para pular essa verificação e sempre clonar sobre HTTPS.

253 254 

254As mesmas credenciais se aplicam quando você executa `/plugin install`, `/plugin marketplace update` e `claude plugin update`.255As mesmas credenciais se aplicam quando você executa `/plugin install`, `/plugin marketplace update` e `claude plugin update`.


288 289 

289* Digite para filtrar por nome ou descrição.290* Digite para filtrar por nome ou descrição.

290* Pressione **Space** para habilitar ou desabilitar o plugin selecionado, e **f** para favoritá-lo.291* Pressione **Space** para habilitar ou desabilitar o plugin selecionado, e **f** para favoritá-lo.

291* Pressione **Enter** para abrir os detalhes de um plugin. O menu lá oferece **Disable plugin** ou **Enable plugin**, **Update now** e **Uninstall**. Plugins que aceitam configurações também oferecem **Configure options**.292* Pressione **Enter** para abrir os detalhes de um plugin.

293 

294Um menu de detalhes de plugin oferece **Disable plugin** ou **Enable plugin**, **Update now** e **Uninstall**. Dois itens adicionais aparecem para plugins que aceitam configurações, e um plugin pode mostrar ambos:

295 

296* **Configure options**: mostrado quando o manifesto do plugin declara opções [`userConfig`](/docs/pt/plugins/manifest-reference#user-configuration). Abre o diálogo para essas opções

297* **Configure**: mostrado quando o plugin inclui um [servidor MCP empacotado](/docs/pt/plugins/components#include-a-packaged-mcpb-server). Define as configurações `user_config` próprias desse servidor

292 298 

293A aba também pode mostrar plugins em escopo **Managed**. Sua organização os instalou através de [configurações gerenciadas](/docs/pt/settings#settings-files), e você não pode habilitá-los, desabilitá-los ou desinstalá-los aqui.299A aba também pode mostrar plugins em escopo **Managed**. Sua organização os instalou através de [configurações gerenciadas](/docs/pt/settings#settings-files), e você não pode habilitá-los, desabilitá-los ou desinstalá-los aqui.

294 300 

Details

146| [`dependencies`](#dependencies) | Array de strings ou objetos | Plugins que devem estar habilitados para este funcionar |146| [`dependencies`](#dependencies) | Array de strings ou objetos | Plugins que devem estar habilitados para este funcionar |

147| [`settings`](#settings) | Object | Configurações que Claude Code aplica enquanto o plugin está habilitado. Apenas `agent` e `subagentStatusLine` têm efeito |147| [`settings`](#settings) | Object | Configurações que Claude Code aplica enquanto o plugin está habilitado. Apenas `agent` e `subagentStatusLine` têm efeito |

148| [`userConfig`](#user-configuration) | Object | Valores que Claude Code solicita ao usuário quando o plugin está habilitado |148| [`userConfig`](#user-configuration) | Object | Valores que Claude Code solicita ao usuário quando o plugin está habilitado |

149| `types` | Caminho | Um arquivo `.d.ts` que declara os valores `$.state` e os nomes `$` de um [mod](/docs/pt/plugins/mods/reference#files) |

149| [`channels`](#channels) | Array de objetos | Canais de mensagem que o plugin fornece, cada um vinculado a um de seus servidores MCP |150| [`channels`](#channels) | Array de objetos | Canais de mensagem que o plugin fornece, cada um vinculado a um de seus servidores MCP |

150| `skills` | Caminho, ou array de caminhos | Diretórios para escanear em busca de skills, cada um um diretório de pastas `<name>/SKILL.md` ou uma pasta contendo `SKILL.md` diretamente. `"."` nomeia a raiz do plugin. Adiciona ao scan padrão `skills/` |151| `skills` | Caminho, ou array de caminhos | Diretórios para escanear em busca de skills, cada um um diretório de pastas `<name>/SKILL.md` ou uma pasta contendo `SKILL.md` diretamente. `"."` nomeia a raiz do plugin. Adiciona ao scan padrão `skills/` |

151| [`commands`](#commands) | Caminho, array de caminhos, ou objeto | Arquivos de comando `.md` planos, diretórios deles, ou um mapa de objeto de nome de comando para `source` ou `content`. Substitui o scan padrão `commands/` |152| [`commands`](#commands) | Caminho, array de caminhos, ou objeto | Arquivos de comando `.md` planos, diretórios deles, ou um mapa de objeto de nome de comando para `source` ou `content`. Substitui o scan padrão `commands/` |


170 171 

171Claude Code namespaces cada componente sob ele, então um agente `reviewer` no plugin `deploy-tools` aparece como `deploy-tools:reviewer`.172Claude Code namespaces cada componente sob ele, então um agente `reviewer` no plugin `deploy-tools` aparece como `deploy-tools:reviewer`.

172 173 

174`claude plugin validate` também verifica que o nome não passa como um dos próprios plugins da Anthropic. A verificação ignora maiúsculas e minúsculas e trata qualquer sequência de separadores como um:

175 

176| Nome | Resultado |

177| :- | :- |

178| Começa com `claude-`, `anthropic-`, `anthropics-` ou `cc-plugin-` | Erro |

179| É `claude`, `anthropic`, `anthropics`, `claude-code` ou `claude-mods` | Erro |

180| Coloca `official` ao lado de `claude` ou `anthropic`, como `official-claude-tools` | Erro |

181| Tem `claude`, `anthropic` ou `anthropics` como uma palavra inteira em qualquer outro lugar, como `mcp-for-claude` | Aviso |

182 

183A mensagem de erro é `Plugin name "<name>" is reserved: it passes as one of Anthropic's own`, e o aviso é `Plugin name "<name>" reads as one of Anthropic's own`. `claude plugin init` e `claude plugin tag` recusam um nome que gera o erro. Apenas esses comandos verificam o nome. Claude Code ainda instala e carrega um plugin cujo nome eles recusam.

184 

173<h3 id="displayname">185<h3 id="displayname">

174 `displayName`186 `displayName`

175</h3>187</h3>

Details

484| `Author name cannot be empty` | Error | `owner.name` |484| `Author name cannot be empty` | Error | `owner.name` |

485| `Plugin name cannot contain spaces. Use kebab-case (e.g., "my-plugin")` | Error | `plugins[i].name` |485| `Plugin name cannot contain spaces. Use kebab-case (e.g., "my-plugin")` | Error | `plugins[i].name` |

486| `Plugin name cannot contain control or bidirectional-formatting characters` | Error | `plugins[i].name` |486| `Plugin name cannot contain control or bidirectional-formatting characters` | Error | `plugins[i].name` |

487| `Plugin name "x" is reserved: it passes as one of Anthropic's own` | Error | `plugins[i].name`. Veja o [`name`](/docs/pt/plugins/manifest-reference#name) do manifesto para os nomes reservados |

488| `Plugin name "x" reads as one of Anthropic's own` | Warning | `plugins[i].name` |

487| `Claude Code cannot install plugins from marketplace "x". Each part of a plugin id (plugin@marketplace) may use only the letters a-z and A-Z, digits, ".", "_" and "-", and must start with a letter or digit. Change the marketplace's "name".` | Error | `name` |489| `Claude Code cannot install plugins from marketplace "x". Each part of a plugin id (plugin@marketplace) may use only the letters a-z and A-Z, digits, ".", "_" and "-", and must start with a letter or digit. Change the marketplace's "name".` | Error | `name` |

488| `Claude Code cannot install plugin "x". Each part of a plugin id (plugin@marketplace) may use only the letters a-z and A-Z, digits, ".", "_" and "-", and must start with a letter or digit. Change this entry's "name".` | Error | `plugins[i].name` |490| `Claude Code cannot install plugin "x". Each part of a plugin id (plugin@marketplace) may use only the letters a-z and A-Z, digits, ".", "_" and "-", and must start with a letter or digit. Change this entry's "name".` | Error | `plugins[i].name` |

489| `Duplicate plugin name "x" found in marketplace` | Error | Duas entradas compartilham um `name` |491| `Duplicate plugin name "x" found in marketplace` | Error | Duas entradas compartilham um `name` |

plugins/mods/admin.md +375 −0 created

Details

1> ## Documentation Index

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

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

4 

5# Gerenciar mods para sua organização

6 

7> Controle mods do Claude Code com configurações gerenciadas: interrompa mods instalados pelo usuário, permita apenas os seus, revise o que um mod pode fazer e aplique política com seu próprio mod.

8 

9Um [mod](/docs/pt/plugins/mods/overview) é um plugin que executa código dentro do Claude Code com as permissões do usuário que o instalou. Mods não são sandboxed. Através de [configurações gerenciadas](/docs/pt/managed-settings), você decide se mods são executados nas máquinas dos seus usuários, quais são e em que ordem. Você também pode instalar um mod seu que monitora ou recusa o que outros mods fazem.

10 

11Esta página é para a pessoa que implanta configurações gerenciadas para Claude Code, seja como um arquivo, através de MDM ou do console de administração do claude.ai. Mods estão ativados por padrão no Claude Code v2.1.287 e posterior. Comece com a seção que corresponde ao que você veio fazer:

12 

13* **Mantenha os mods próprios dos usuários fora, com ou sem mods seus**: [Interrompa mods instalados pelo usuário de serem carregados](#stop-user-installed-mods-from-loading)

14* **Veja o que seus usuários obtêm quando você não muda nada**: [Saiba o que acontece por padrão](#know-what-happens-by-default)

15* **Deixe mods ativados com outras limitações**: [Escolha quanto permitir](#choose-how-much-to-allow)

16 

17<Note>

18 Estes casos são cobertos em outras páginas:

19 

20 * **Você não implantou configurações gerenciadas antes**: comece com [Implantar configurações gerenciadas](/docs/pt/managed-settings)

21 * **Você quer controlar quais plugins os usuários podem instalar**: veja [Gerenciar plugins para sua organização](/docs/pt/plugins/org)

22</Note>

23 

24<h2 id="stop-user-installed-mods-from-loading">

25 Interrompa mods instalados pelo usuário de serem carregados

26</h2>

27 

28Para impedir que cada mod que seus usuários tragam seja carregado, defina a opção `allowManagedModsOnly` no [guard integrado](#know-what-happens-by-default), um mod de política que Claude Code carrega antes de cada mod que um usuário instala. A opção vai em configurações gerenciadas sob `pluginConfigs`, com chave `cc-plugin-sec-default@builtin`:

29 

30```json managed-settings.json theme={null}

31{

32 "pluginConfigs": {

33 "cc-plugin-sec-default@builtin": {

34 "options": {

35 "allowManagedModsOnly": true

36 }

37 }

38 }

39}

40```

41 

42Com a opção definida em configurações gerenciadas:

43 

44* **Nenhum mod que um usuário traz é carregado**: isso cobre um mod em um plugin que o usuário instalou, um mod carregado com `--plugin-dir` e um mod [que Claude escreveu durante uma sessão](/docs/pt/plugins/mods/create#ask-claude-for-a-mod)

45* **Os mods da sua organização ainda são carregados**: um mod que [conta como da sua organização](#install-your-organizations-mods) não é verificado. Todos os outros mods contam como de um usuário e não são carregados. Isso inclui um mod em um plugin que você habilita de um GitHub ou outro marketplace remoto, e um que sua organização ativa para seus membros no claude.ai. Se nenhum contar como seu, nenhum mod instalado é carregado.

46* **Os usuários não podem desfazer**: o guard lê a opção apenas de configurações gerenciadas, então a mesma entrada em um arquivo de configurações de usuário, projeto ou local, ou em um arquivo passado com `--settings`, não muda nada

47* **Um arquivo ou política MDM cobre cada provedor**: quando você entrega a opção como um arquivo ou através de MDM, funciona da mesma forma no Amazon Bedrock, na Agent Platform do Google Cloud e no Microsoft Foundry. Para entrega do console de administração do claude.ai, veja [Disponibilidade de plataforma](/docs/pt/server-managed-settings#platform-availability)

48* **As outras personalizações dos usuários continuam funcionando**: seus [hooks em arquivos de configurações](/docs/pt/hooks), linhas de status e `/goal` não são afetados

49* **Mods integrados continuam em execução**: mods integrados ao Claude Code, como suporte a `AGENTS.md`, cada um tem [seu próprio switch](/docs/pt/plugins/mods/overview#mods-built-into-claude-code)

50 

51Para confirmar a opção na máquina de um usuário, inicie Claude Code lá com `--plugin-dir` e o caminho de um diretório que contém um mod, como `claude --plugin-dir ./first-mod`. Os hooks do mod não são executados, e a transcrição e o log de depuração têm a [mensagem do guard](/docs/pt/plugins/mods/troubleshoot#messages-from-the-built-in-guard), que nomeia o mod e `allowManagedModsOnly`. Se o mod for carregado, veja [Verificar que uma política está em vigor](/docs/pt/managed-settings#check-that-a-policy-is-in-force) e as [regras que decidem se uma opção entra em vigor](#set-options-on-the-built-in-guard).

52 

53Se você definiu `CLAUDE_CODE_ENABLE_FUNCTION_HOOKS` como `0` durante acesso antecipado, substitua-o por esta opção. Claude Code v2.1.287 e posterior ignora a variável em qualquer valor, então um `0` lá deixa mods ativados.

54 

55<h2 id="know-what-happens-by-default">

56 Saiba o que acontece por padrão

57</h2>

58 

59Sem suas próprias configurações de mod, isto é o que seus usuários obtêm:

60 

61* **Mods estão ativados.** Um usuário pode instalar um plugin que contém um mod de qualquer marketplace que suas configurações de plugin permitam, ou carregar um de um diretório com `--plugin-dir`.

62* **Um guard integrado é executado primeiro.** Claude Code carrega um mod integrado chamado `sec-default@builtin` antes de cada mod que um usuário instala. Os usuários não podem desativá-lo. `/plugin` e o log de depuração o listam como `cc-plugin-sec-default`. O guard é carregado quando qualquer um destes é verdadeiro:

63 

64 * A máquina tem configurações gerenciadas

65 * O usuário está conectado ao Claude Code com um plano Team ou Enterprise

66 

67 Um usuário que se autentica com uma chave de API, ou através do Amazon Bedrock, da Agent Platform do Google Cloud ou do Microsoft Foundry, obtém o guard apenas em uma máquina que tem configurações gerenciadas.

68* **O guard protege o que você gerencia.** Um mod de um usuário não pode mudar o que seus hooks gerenciados recebem ou decidem, o prompt do sistema, seu `CLAUDE.md` gerenciado e outras instruções gerenciadas, o que qualquer mod lê como configurações, ou as ferramentas e descrições de seus servidores MCP gerenciados.

69* **Tudo mais é permitido.** O guard não adiciona outras restrições. Um mod de um usuário ainda pode ler e escrever arquivos, iniciar processos, fazer solicitações de rede, reescrever chamadas de ferramentas e prompts, negar uma chamada de ferramenta, aprovar uma que de outra forma solicitaria, e desenhar na interface, tudo com as permissões desse usuário.

70* **Regras de negação e seus hooks gerenciados têm precedência.** Onde o guard é carregado, um mod de um usuário não pode aprovar uma chamada que uma regra `deny` recusa, qualquer que seja o arquivo de configurações que contém a regra. Um bloqueio de um hook `PreToolUse` em configurações gerenciadas também é final. Ambos se aplicam às chamadas de ferramentas do Claude. Nenhum se aplica às chamadas próprias [`$.fs` e `$.process` de um mod](/docs/pt/plugins/mods/api#reach-files-processes-and-the-network): com `Read(.env)` negado, um mod ainda pode ler esse arquivo com `$.fs.read` ou iniciar um programa que o faça. Para limitar essas chamadas, impeça o mod de ser carregado ou hook a chamada em um [mod de política](#enforce-a-policy-with-a-mod-of-your-own).

71* **Outras verificações de permissão podem ser substituídas.** Um mod de um usuário que aprova chamadas de ferramentas pode aprovar uma chamada que uma regra `ask` solicitaria, ou que um hook `PreToolUse` fora de configurações gerenciadas bloqueou. Em modo automático, uma chamada que o mod aprova é executada sem uma verificação de classificador.

72 

73A fonte do guard é pública no [diretório `mods/sec-default` do repositório Claude Code](https://github.com/anthropics/claude-code/tree/main/mods/sec-default).

74 

75<h3 id="know-which-controls-still-apply">

76 Saiba quais controles ainda se aplicam

77</h3>

78 

79Mods não substituem os controles que você já tem:

80 

81* **Hooks de configurações continuam funcionando.** Hooks de comando, HTTP, prompt e agente em arquivos de configurações e em `hooks/hooks.json` de plugins são executados como antes, ao lado de mods. Nada sobre eles está descontinuado.

82* **Regras de negação têm precedência onde o guard é carregado.** Um mod de um usuário não pode aprovar uma chamada que uma regra `deny` recusa, a menos que você defina [`allowModsToOverrideDenyRules`](#set-options-on-the-built-in-guard).

83* **Hooks gerenciados são executados primeiro.** Um hook `PreToolUse` em configurações gerenciadas é executado antes de qualquer mod ver a chamada de ferramenta, e seu bloqueio é final. Se um mod então reescrever a chamada, seus hooks gerenciados são executados novamente na chamada reescrita, então um bloqueio ainda se aplica. Hooks `PreToolUse` de outros arquivos de configurações e de plugins são executados após o último mod, então um mod que retorna seu próprio resultado no lugar de executar a ferramenta impede que aqueles sejam executados. Veja [A ordem em que mods são executados](/docs/pt/plugins/mods/events#the-order-mods-run-in).

84* **Política de rede cobre `$.http.fetch`.** Se sua organização desativa busca na web, ou tráfego de rede não essencial é desativado para a sessão, Claude Code recusa uma solicitação de rede que um mod faz com `$.http.fetch`. A política não cobre um programa que o mod inicia com `$.process.run`. Esse programa alcança a rede com o acesso próprio do usuário.

85* **Controles de plugin cobrem mods.** Um mod é um plugin, então as [configurações que restringem o que os usuários podem instalar](/docs/pt/plugins/org#restrict-what-users-can-install), como `strictKnownMarketplaces`, decidem se ele pode ser instalado.

86* **Mods não podem mudar o prompt de permissão.** Um mod pode restylar muito da interface do Claude Code, mas não o prompt de permissão, então não pode mudar o que um prompt mostra. Um mod ainda pode aprovar ou negar uma chamada de ferramenta antes do prompt aparecer, como [Saiba o que acontece por padrão](#know-what-happens-by-default) descreve.

87* **Prompts de confiança vêm primeiro.** Em uma sessão interativa em um diretório que o usuário ainda não confiou, nenhum mod é carregado até que ele responda ao prompt de confiança.

88* **`--safe-mode` desativa mods instalados, incluindo os seus.** Inicie uma sessão com `claude --safe-mode` para verificar se um mod causou um problema.

89 

90Nenhum desses controles faz sandbox de um mod. Um mod que você permite é executado como o usuário, com o acesso do usuário a arquivos, processos e a rede.

91 

92<h2 id="decide-whether-to-leave-mods-on">

93 Decida se deixa mods ativados

94</h2>

95 

96Um mod pode fazer mais do que as outras partes de um plugin porque é executado dentro do Claude Code. Ele vê cada prompt e chamada de ferramenta, pode mudá-los e pode permitir ou negar uma chamada de ferramenta antes de um prompt de permissão aparecer.

97 

98O que um usuário pode carregar como um mod depende dos controles de plugin que você já tem:

99 

100| Seus controles de plugin hoje | O que um usuário pode carregar como um mod |

101| :- | :- |

102| Nenhum | Um mod de qualquer marketplace, de qualquer diretório com `--plugin-dir`, ou que Claude escreve durante uma sessão |

103| Uma lista de permissão de marketplace | Um mod dos marketplaces que você permite, ou de qualquer diretório com `--plugin-dir`. Um mod que Claude escreve durante uma sessão é carregado apenas quando a lista de permissão [inclui `skills-dir`](/docs/pt/plugins/org#keep-skills-directory-plugins-loading). |

104| Uma lista de permissão de marketplace e `disableSideloadFlags` | Um mod dos marketplaces que você permite |

105 

106[Gerenciar plugins para sua organização](/docs/pt/plugins/org) lista cada forma como um plugin é carregado e a configuração que controla cada uma.

107 

108Para verificar os mods em um marketplace antes de seus usuários instalá-los, veja [Revise o que um mod pode fazer](#review-what-a-mod-can-do). Para manter os mods dos usuários fora até ter feito isso, veja [Interrompa mods instalados pelo usuário de serem carregados](#stop-user-installed-mods-from-loading).

109 

110<h3 id="review-what-a-mod-can-do">

111 Revise o que um mod pode fazer

112</h3>

113 

114Você pode ver o que um mod é capaz de fazer sem executá-lo. Em seu shell, execute `claude plugin validate` no diretório do plugin:

115 

116```bash theme={null}

117claude plugin validate ./some-mod

118```

119 

120Duas linhas na saída descrevem o código do mod:

121 

122```text theme={null}

123 ❯ ./register.js hooks: session.start, tool.call, ui.render{component=Pane}

124 ❯ ./register.js calls: $.fs.read, $.http.fetch, $.store.set, $.ui.open

125```

126 

127A linha `hooks:` lista os eventos que o mod recebe. A linha `calls:` lista os métodos da API de mods que seu código chama. A [API de mods](/docs/pt/plugins/mods/api), escrita como `$` no código de um mod, é como um mod alcança arquivos, processos e a rede. Claude Code recusa carregar um mod que usa a API de mods de uma forma que este comando não consegue ler.

128 

129Procure na linha `calls:` por estes:

130 

131| Chamada | O que significa |

132| :- | :- |

133| `$.fs.read`, `$.fs.write` | Lê ou escreve arquivos em qualquer lugar que o usuário possa |

134| `$.process.run`, `$.process.spawn` | Inicia programas como o usuário |

135| `$.http.fetch` | Faz solicitações de rede |

136| `$.env.get`, `$.settings.read` | Lê variáveis de ambiente e configurações, que podem conter chaves de API. Uma linha `env reads:` na saída nomeia cada variável. |

137| `$.env.set` | Define uma variável de ambiente para Claude Code e para cada comando e servidor MCP que ele inicia depois, o que pode mudar o que esses programas executam. Uma linha `env writes:` nomeia cada variável. |

138| `$.mcp.call` | Chama uma ferramenta em um servidor MCP conectado, sob as regras de permissão da sessão |

139| `$.model.complete` | Usa o plano ou chave de API do usuário para chamadas de modelo |

140| `$.prompt.submit` | Envia um prompt e pode enviá-lo como as próprias palavras do usuário |

141| `$.session.send` | Envia uma mensagem que outra sessão ou subagente do Claude lê |

142 

143Na linha `hooks:`, [`tool.call`](/docs/pt/plugins/mods/reference#tools) e [`prompt.submit`](/docs/pt/plugins/mods/reference#prompts-and-what-claude-reads) significam que o mod vê cada chamada de ferramenta e cada prompt, e pode mudá-los. [`session.append`](/docs/pt/plugins/mods/reference#session) significa que o mod pode reescrever cada linha da conversa antes de ser armazenada. [`ui.render{component=AskUserQuestion}`](/docs/pt/plugins/mods/interface#change-what-claude-code-already-draws) significa que o mod pode redesenhar o diálogo que Claude usa para fazer uma pergunta ao usuário. `tool.check` significa que o mod pode aprovar ou negar uma chamada de ferramenta antes de um prompt de permissão aparecer. [Saiba o que acontece por padrão](#know-what-happens-by-default) lista quais de suas regras e hooks têm precedência sobre sua resposta.

144 

145<h2 id="choose-how-much-to-allow">

146 Escolha quanto permitir

147</h2>

148 

149Políticas de mod variam de nenhum mod instalado a qualquer mod que um usuário escolha, com seu próprio mod verificando os outros, e cada uma é algumas configurações gerenciadas. Encontre a política que você quer na primeira coluna e defina o que a segunda coluna nomeia. [Implantar configurações gerenciadas](/docs/pt/managed-settings) cobre onde as configurações gerenciadas vivem.

150 

151| O que você quer | Configurações |

152| :- | :- |

153| Nenhum mod instalado, com hooks intocados | Defina [`allowManagedModsOnly`](#set-options-on-the-built-in-guard) e não implante mods seus |

154| Nenhum mod instalado e nenhum hook, incluindo seus hooks gerenciados | Defina `disableAllHooks` como `true` |

155| Apenas mods da sua organização | Defina a opção [`allowManagedModsOnly`](#stop-user-installed-mods-from-loading) do guard, e [instale seus mods](#install-your-organizations-mods) para que contem como seus |

156| Qualquer mod de marketplaces que você aprova | Mantenha suas [restrições de marketplace](/docs/pt/plugins/org#restrict-what-users-can-install), e defina `disableSideloadFlags` como `true` |

157| Qualquer mod, com seu próprio mod verificando os outros | [Instale seu mod](#install-your-organizations-mods), e liste-o com `sec-default@builtin` em `prependPlugins` |

158 

159O que cada configuração faz:

160 

161* **`allowManagedModsOnly`**: uma opção no guard integrado. Mods próprios dos usuários não são carregados, e seus hooks de configurações, linhas de status e `/goal` continuam funcionando. [Interrompa mods instalados pelo usuário de serem carregados](#stop-user-installed-mods-from-loading) lista o que cobre.

162* **`allowManagedHooksOnly`**: uma configuração mais ampla. Apenas [mods da sua organização](#install-your-organizations-mods) e mods integrados ao Claude Code são carregados. Um mod que um usuário instalou por si só não é. A configuração também bloqueia hooks em arquivos de configurações próprios dos usuários. Leia [O que é executado sob `allowManagedHooksOnly`](/docs/pt/settings-reference#what-runs-under-allowmanagedhooksonly) antes de defini-la.

163* **`disableAllHooks`**: a configuração mais ampla. Em configurações gerenciadas, ela interrompe os mods em cada plugin instalado, incluindo os seus, e desativa cada hook em arquivos de configurações, então um hook `PreToolUse` em suas configurações gerenciadas não bloqueia mais nada. Linhas de status personalizadas e `/goal` também param de funcionar. Leia [`disableAllHooks`](/docs/pt/settings-reference#disableallhooks) antes de defini-la.

164* **`disableSideloadFlags`**: rejeita `--plugin-dir` e `--plugin-url` na inicialização, então ninguém carrega um mod de um diretório, e impede que mods que Claude escreve durante uma sessão sejam carregados. A configuração também rejeita `--agents` e `--mcp-config`. Leia [`disableSideloadFlags`](/docs/pt/settings-reference#disablesideloadflags) antes de defini-la.

165 

166Mods integrados ao Claude Code, como suporte a `AGENTS.md`, não são afetados por essas configurações. Cada um tem [seu próprio switch](/docs/pt/plugins/mods/overview#mods-built-into-claude-code).

167 

168Um usuário cujo mod não foi carregado encontra a razão em seu log de depuração. [Mensagens de recusa](/docs/pt/plugins/mods/troubleshoot#refusal-messages) lista as linhas para `allowManagedHooksOnly` e `disableAllHooks`, e [Mensagens do guard integrado](/docs/pt/plugins/mods/troubleshoot#messages-from-the-built-in-guard) tem a linha para `allowManagedModsOnly`.

169 

170<h3 id="set-options-on-the-built-in-guard">

171 Defina opções no guard integrado

172</h3>

173 

174O guard integrado leva duas opções. Defina-as em configurações gerenciadas sob `pluginConfigs`, com chave `cc-plugin-sec-default@builtin`, como o exemplo em [Interrompa mods instalados pelo usuário de serem carregados](#stop-user-installed-mods-from-loading) faz.

175 

176A tabela fornece o que seus usuários obtêm com cada opção não definida e com ela definida como `true`:

177 

178| Opção | Não definida | `true` |

179| :- | :- | :- |

180| `allowManagedModsOnly` | Mods próprios dos usuários são carregados | Apenas [mods da sua organização](#install-your-organizations-mods), e mods integrados ao Claude Code, são carregados. Claude Code recusa cada outro mod, incluindo um que um usuário instalou ou nomeou com `--plugin-dir`. |

181| `allowModsToOverrideDenyRules` | Regras de negação têm precedência sobre mods dos usuários | Um mod de um usuário que aprova chamadas de ferramentas pode aprovar uma chamada que uma regra `deny` recusa |

182 

183Estas regras decidem se uma opção entra em vigor:

184 

185* **O id tem uma ortografia aqui**: Claude Code lê as opções apenas sob `cc-plugin-sec-default@builtin`. `prependPlugins` aceita `sec-default@builtin` também, e `pluginConfigs` não.

186* **Apenas configurações gerenciadas contam**: a mesma entrada em um arquivo de configurações de usuário, projeto ou local, ou em um arquivo passado com `--settings`, nem define uma opção nem afrouxe uma

187* **O guard tem que ser carregado**: se você definir `prependPlugins`, [nomeie o guard na lista](#install-your-organizations-mods). Onde o guard não é carregado, nenhuma opção se aplica.

188* **O guard falha fechado**: se o guard não conseguir ler configurações gerenciadas, ele recusa cada mod de um usuário ao carregar. Se não conseguir verificar as regras de negação para uma chamada que um mod de um usuário aprovou, ele recusa a chamada.

189 

190As [mensagens do guard integrado](/docs/pt/plugins/mods/troubleshoot#messages-from-the-built-in-guard) são o que seus usuários veem quando qualquer opção se aplica.

191 

192<h2 id="run-your-organization’s-own-mods">

193 Execute mods próprios da sua organização

194</h2>

195 

196Você pode implantar mods seus para cada usuário, escolher onde são executados em relação aos mods dos usuários, e usar um para aplicar uma política.

197 

198<h3 id="install-your-organizations-mods">

199 Instale mods da sua organização e defina a ordem

200</h3>

201 

202Os mods da sua organização são carregados onde mods dos usuários não são e podem ser executados antes deles, então Claude Code tem que ser capaz de dizer que um mod veio de você. Ele trata um mod como da sua organização apenas quando todos estes são verdadeiros:

203 

204* `enabledPlugins` gerenciado define o plugin do mod como `true`

205* Configurações gerenciadas nomeiam o [marketplace](/docs/pt/plugins/create-marketplace) do plugin como um diretório na máquina do usuário, por caminho absoluto. Uma entrada `extraKnownMarketplaces` faz isso e registra o marketplace para o usuário também.

206* O marketplace lista o plugin por um caminho relativo, então Claude Code [o carrega no lugar](/docs/pt/plugins/loading#in-place-and-copied-plugins) daquele diretório

207 

208Para atender a eles, tenha seu gerenciamento de dispositivo copiar o diretório do marketplace para o mesmo caminho em cada máquina. Faça o diretório e cada diretório acima dele graváveis apenas por um administrador, como o arquivo de configurações gerenciadas é. Qualquer um que possa escrever lá pode reescrever seu mod. Configurações gerenciadas que você entrega do console de administração do claude.ai podem carregar as chaves, mas não podem colocar o diretório em uma máquina.

209 

210O diretório contém o manifesto do marketplace e o plugin:

211 

212```text theme={null}

213/opt/acme/claude-plugins/

214├── .claude-plugin/

215│ └── marketplace.json

216└── plugins/

217 └── acme-guard/

218 ├── .claude-plugin/

219 │ └── plugin.json

220 └── hooks/

221 ├── hooks.json

222 └── register.js

223```

224 

225O manifesto lista o plugin por seu caminho relativo àquele diretório:

226 

227```json /opt/acme/claude-plugins/.claude-plugin/marketplace.json theme={null}

228{

229 "name": "acme-tools",

230 "owner": { "name": "Acme" },

231 "plugins": [

232 { "name": "acme-guard", "source": "./plugins/acme-guard", "description": "Acme policy mod" }

233 ]

234}

235```

236 

237Um plugin que Claude Code copia em seu cache conta como de um usuário, mesmo quando `enabledPlugins` gerenciado o habilita. Isso cobre cada plugin de uma fonte GitHub, git, URL ou npm. Seu mod é executado entre mods dos usuários, `prependPlugins` e `appendPlugins` o pulam, e ele não é carregado sob `allowManagedModsOnly` ou `allowManagedHooksOnly`. O log de depuração do usuário tem uma linha que começa com o id do plugin e `is enabled by managed settings, but`.

238 

239Claude Code levanta um evento cada vez que está prestes a agir, como executar uma ferramenta, e o passa para cada mod por sua vez. Um mod que conta como seu [é executado antes dos mods dos usuários](/docs/pt/plugins/mods/events#the-order-mods-run-in) mesmo quando você não o lista em lugar nenhum. Para definir seu lugar, liste seu id em uma de duas configurações. O id é o nome do plugin, `@`, e o nome do marketplace, como `acme-guard@acme-tools`.

240 

241* **`prependPlugins`**: seu mod vê cada evento antes de qualquer mod de um usuário e cada resultado depois. Pode mudar o evento, recusá-lo ou pular os mods dos usuários.

242* **`appendPlugins`**: seu mod é executado após cada mod de um usuário, então vê apenas os eventos que aqueles mods passam, na forma que os passam

243 

244Este exemplo declara o marketplace `acme-tools` em `/opt/acme/claude-plugins`, habilita `acme-guard` dele, e executa esse mod primeiro, com o guard integrado depois:

245 

246```json managed-settings.json theme={null}

247{

248 "extraKnownMarketplaces": {

249 "acme-tools": {

250 "source": { "source": "directory", "path": "/opt/acme/claude-plugins" }

251 }

252 },

253 "enabledPlugins": { "acme-guard@acme-tools": true },

254 "prependPlugins": ["acme-guard@acme-tools", "sec-default@builtin"]

255}

256```

257 

258Cada chave faz um trabalho:

259 

260* **`extraKnownMarketplaces`**: nomeia o diretório que contém o marketplace `acme-tools`. `path` é o caminho absoluto do diretório que contém `.claude-plugin/marketplace.json`.

261* **`enabledPlugins`**: ativa `acme-guard` para cada usuário que recebe essas configurações gerenciadas

262* **`prependPlugins`**: coloca `acme-guard` primeiro e o guard integrado segundo, ambos antes de qualquer mod que um usuário instala. Claude Code segue a ordem que você lista.

263 

264Para confirmar que a máquina de um usuário recebeu as configurações, veja [Verificar que uma política está em vigor](/docs/pt/managed-settings#check-that-a-policy-is-in-force).

265 

266Para confirmar onde o mod é executado, inicie uma sessão naquela máquina com `claude --debug` e procure no [log de depuração](/docs/pt/plugins/mods/troubleshoot#read-the-debug-log) pelo id do mod:

267 

268* **`hooks module acme-guard@acme-tools loaded`, com `tier prepend`**: o mod conta como da sua organização e é executado primeiro

269* **A mesma linha com `tier user`**: Claude Code o trata como um mod de um usuário. Uma segunda linha, `prependPlugins names acme-guard@acme-tools, which is not an enabled managed plugin with a hooks module; skipped`, diz que a lista o pulou.

270 

271Estas regras decidem quais ids nas duas listas entram em vigor:

272 

273* **A lista substitui o padrão**: quando você define `prependPlugins` em configurações gerenciadas, nomeie `sec-default@builtin` nela para manter o guard integrado. O guard é integrado e não precisa de uma entrada `enabledPlugins`.

274* **Seus próprios ids devem contar como seus**: em configurações gerenciadas, Claude Code pula um id cujo plugin não atende às três condições para um mod da organização

275* **Repositórios não podem defini-los**: Claude Code lê ambas as configurações apenas de configurações gerenciadas e nunca de um arquivo de configurações de um repositório. Um usuário pode defini-los em `~/.claude/settings.json` para ordenar seus próprios mods apenas em uma máquina sem configurações gerenciadas, e apenas quando não estão conectados com um plano Team ou Enterprise. Em qualquer outro lugar, Claude Code ignora ambas as chaves em configurações de usuário. Uma lista lá nem adiciona nem remove o guard integrado.

276 

277<h3 id="enforce-a-policy-with-a-mod-of-your-own">

278 Aplique uma política com um mod seu

279</h3>

280 

281Para manter cada mod de um usuário fora, você não precisa de um mod seu. Defina [`allowManagedModsOnly`](#stop-user-installed-mods-from-loading). Escreva um mod de política quando você quer admitir alguns mods dos usuários e recusar outros, ou para registrar o que mods fazem.

282 

283Cada vez que outro mod está prestes a ser carregado, seu mod recebe a lista que `claude plugin validate` imprime, em um evento nomeado [`plugin.register`](/docs/pt/plugins/mods/reference#other-mods). Um mod em `prependPlugins` pode ler essa lista e recusar o mod. Também pode [fazer hook de qualquer chamada de API de mods por nome](/docs/pt/plugins/mods/api#reach-files-processes-and-the-network) para registrar ou recusar essa chamada para cada outro mod. O nome é o método sem o `$.`, então um hook em `fs.write` vê cada chamada `$.fs.write`.

284 

285Este mod de política recusa qualquer mod de um usuário cujo próprio código chama `$.process.run` ou `$.process.spawn`. Também mantém um log de auditoria, escrevendo cada chamada de ferramenta e cada arquivo que um mod escreve no log de depuração. Porque é executado primeiro, o log registra o que foi solicitado, antes de qualquer mod de um usuário mudá-lo. Salve-o como `acme-guard/hooks/register.js`:

286 

287```javascript acme-guard/hooks/register.js theme={null}

288// Os métodos que nenhum mod de um usuário pode chamar, cada um soletrado namespace.method

289const BLOCKED_CALLS = ['process.run', 'process.spawn']

290 

291export function register(on) {

292 // É executado cada vez que outro mod está prestes a ser carregado

293 on('plugin.register', async ($, e, next) => {

294 // Mantenha as chamadas naquele código do mod que estão na lista bloqueada

295 const blocked = e.uses.calls.filter((call) => BLOCKED_CALLS.includes(call))

296 if (e.tier === 'user' && blocked.length > 0) {

297 // Retornar refuse impede o mod de ser carregado, e o texto é a razão

298 return { refuse: 'Acme policy: mods may not call ' + blocked.join(', ') }

299 }

300 // Deixe cada outro mod ser carregado

301 return next(e)

302 })

303 

304 // Registre cada chamada de ferramenta, então deixe-a prosseguir inalterada

305 on('tool.call', async ($, e, next) => {

306 $.ui.log('audit tool.call ' + e.tool, { to: 'debug' })

307 return next(e)

308 })

309 

310 // Registre qual mod escreveu um arquivo, então o caminho, entre aspas porque o mod o escolheu

311 on('fs.write', async ($, e, next) => {

312 $.ui.log('audit fs.write by ' + next.origin.plugin + ' ' + JSON.stringify(e.path), { to: 'debug' })

313 return next(e)

314 })

315}

316```

317 

318O arquivo registra três hooks:

319 

320* **`plugin.register`**: decide se outro mod é carregado. Recusa um mod de um usuário que chama um método bloqueado e passa cada outro mod adiante.

321* **`tool.call`**: escreve uma linha como `audit tool.call Bash` no log de depuração para cada chamada de ferramenta, e não muda nada

322* **`fs.write`**: escreve uma linha como `audit fs.write by reader "/tmp/notes.md"` para cada chamada `$.fs.write` que outro mod faz, e não muda nada. O nome do mod vem primeiro e o caminho é entre aspas, então um caminho que um mod escolhe não pode passar por outro campo da linha.

323 

324O hook `plugin.register` lê dois campos do evento:

325 

326* **`e.tier`**: onde o mod seria executado, um de `prepend`, `user`, `append` ou `builtin`. Cada mod que uma pessoa instala é `user`.

327* **`e.uses.calls`**: os métodos da API de mods que o mod chama, cada um soletrado `namespace.method` como `process.run`, sem o `$.` que `claude plugin validate` imprime

328 

329Quando um usuário instala um mod que chama `$.process.run`, o mod não é carregado, e seu log de depuração tem uma linha que termina com `refused by acme-guard:` e sua razão. A recusa também alcança a transcrição em uma [sessão que recarrega a quente um diretório de plugin](/docs/pt/plugins/mods/troubleshoot#find-out-why-a-mod-does-nothing). Para bloquear uma chamada sem recusar o mod inteiro, retorne `{ deny: 'your reason' }` de um hook no nome daquela chamada.

330 

331Para enviar as linhas de auditoria para algum lugar que não seja o log de depuração, chame `$.http.fetch` dos mesmos hooks.

332 

333Uma sessão pode ser executada sem seu mod. Se a thread de trabalho que executa mods instalados [falhar três vezes](/docs/pt/plugins/mods/troubleshoot#mods-that-run-in-the-hooks-worker-are-off-for-this-session), Claude Code descarrega cada mod que não é integrado, incluindo o seu, até que o usuário execute `/reload-plugins` ou inicie uma nova sessão. E um usuário que inicia Claude Code com `--safe-mode` é executado sem mods instalados, incluindo os seus.

334 

335[Criar um mod](/docs/pt/plugins/mods/create) cobre os arquivos que um mod precisa. [Teste um mod que julga outros mods](/docs/pt/plugins/mods/test#test-a-mod-that-judges-other-mods) tem um arquivo de teste para este mod de política.

336 

337<h4 id="refuse-mods-when-your-check-fails">

338 Recuse mods quando sua verificação falha

339</h4>

340 

341Se seu hook `plugin.register` lança ou passa seu limite de tempo, Claude Code pula o hook, então a verificação falha aberta e o mod que estava verificando é carregado. Para falhar fechado e recusar mods dos usuários, mova a verificação para uma função nomeada e adicione um manipulador `.catch` que retorna a recusa. Esta versão do arquivo mostra apenas o hook `plugin.register`, então mantenha os dois hooks de auditoria da primeira versão em `register`:

342 

343```javascript acme-guard/hooks/register.js theme={null}

344const BLOCKED_CALLS = ['process.run', 'process.spawn']

345 

346// A mesma verificação de antes, movida para uma função de sua própria

347async function checkMod($, e, next) {

348 const blocked = e.uses.calls.filter((call) => BLOCKED_CALLS.includes(call))

349 if (e.tier === 'user' && blocked.length > 0) {

350 return { refuse: 'Acme policy: mods may not call ' + blocked.join(', ') }

351 }

352 return next(e)

353}

354 

355export function register(on) {

356 // O manipulador é executado apenas quando checkMod lança ou passa seu limite de tempo

357 on('plugin.register', checkMod).catch(async ($, e, next) => {

358 // Deixe mods da sua organização e mods integrados serem carregados

359 if (e.tier !== 'user') return next(e)

360 // Recuse o mod do usuário que não pôde ser verificado

361 return { refuse: 'Acme policy check failed, so this mod was not loaded' }

362 })

363}

364```

365 

366Com o manipulador em vigor, um mod que estava sendo verificado quando a verificação lançou ou expirou não é carregado, e a linha de recusa carrega a segunda razão, como em `refused by acme-guard: Acme policy check failed, so this mod was not loaded`. O manipulador passa cada mod fora do tier `user` para `next(e)`, então uma verificação falhada não interrompe os mods que sua organização lista. [Manipule um hook que falha](/docs/pt/plugins/mods/events#handle-a-hook-that-fails) cobre `.catch` para outros eventos.

367 

368<h2 id="next-steps">

369 Próximos passos

370</h2>

371 

372* [Segurança de plugin](/docs/pt/plugins/security): o que qualquer plugin pode fazer na máquina de um usuário e como revisar um antes de ser instalado

373* [Visão geral de mods](/docs/pt/plugins/mods/overview): o que é um mod e como se compara a hooks, skills e servidores MCP

374* [A ordem em que mods são executados](/docs/pt/plugins/mods/events#the-order-mods-run-in): como `prependPlugins` e `appendPlugins` se encaixam com mods dos usuários

375* [Configurações e variáveis de ambiente](/docs/pt/plugins/mods/reference#settings-and-environment-variables): cada configuração nomeada nesta página em uma tabela

plugins/mods/api.md +218 −0 created

Details

1> ## Documentation Index

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

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

4 

5# Use the mods API

6 

7> Chame a mods API de um mod Claude Code para adicionar comandos e ferramentas, chamar um modelo, executar trabalho em um temporizador, enviar mensagens para outras sessões e acessar arquivos e a rede.

8 

9A mods API é o conjunto de métodos que um mod chama para agir: adicionar comandos e ferramentas, chamar um modelo, executar trabalho entre eventos e acessar o sistema de arquivos, processos e a rede. Cada hook a recebe como seu primeiro argumento, `$`, com os métodos agrupados em namespaces como `$.ui` e `$.fs`. [Events](/docs/pt/plugins/mods/events) decidem quando um hook é executado, e a mods API é o que o hook chama uma vez que o faz.

10 

11Construa seu [primeiro mod](/docs/pt/plugins/mods/create) antes de começar aqui. Para cada método, veja [mods API methods](/docs/pt/plugins/mods/reference#mods-api-methods) ou leia [os tipos para sua compilação](/docs/pt/plugins/mods/create#get-the-types-for-your-build).

12 

13<h2 id="add-a-command-or-a-tool">

14 Adicione um comando ou uma ferramenta

15</h2>

16 

17Um mod pode adicionar um comando para o usuário executar e uma ferramenta para Claude chamar. Registre ambos em um hook [`session.start`](/docs/pt/plugins/mods/reference#session). Claude Code aguarda esse hook antes do primeiro prompt, então o que você registra está disponível desde o primeiro turno.

18 

19<h3 id="add-a-command">

20 Adicione um comando

21</h3>

22 

23Um comando é para o usuário. Registre-o e, em seguida, manipule [`command.run`](/docs/pt/plugins/mods/reference#commands-and-configuration) para seu nome. Este exemplo adiciona um comando `/standup` que leva um número opcional de dias:

24 

25```javascript theme={null}

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

27 // Add /standup to the command list, with the description the user sees there

28 await $.command.register({ name: 'standup', description: 'Summarize what changed today', argumentHint: '[days]' })

29 return next(e)

30})

31 

32// The matcher limits the hook to /standup, so other commands don't reach it

33on('command.run', { command: 'standup' }, async ($, e) => {

34 // e.args is the text typed after the command name, or an empty string

35 return { text: 'Summary for the last ' + (e.args || '1') + ' day(s): ...' }

36})

37```

38 

39Após a sessão iniciar, `/standup` aparece com sua descrição na lista que você vê quando digita `/`. O `argumentHint` aparece no prompt após você digitar o comando e um espaço, como em `/standup [days]`. Quando você executa `/standup 3`, o segundo hook retorna `Summary for the last 3 day(s): ...`, e a transcrição mostra esse texto após o nome do plugin. O hook nunca chama `next`, porque o comando não tem comportamento além do seu.

40 

41O `text` que você retorna é impresso na transcrição e Claude o lê. Para não imprimir nada, como um comando que apenas abre um [pane](/docs/pt/plugins/mods/interface#pick-where-to-draw), retorne `{}`. Para permitir que o comando seja executado enquanto Claude está trabalhando, adicione `immediate: true` ao registro.

42 

43Escolha um nome que nenhum comando integrado use. Digite `/` em uma sessão para vê-los. `$.command.register` lança uma exceção para um nome ocupado, com uma mensagem como `"/focus" refused: it is the built-in /focus"`. Um hook que lança uma exceção é ignorado, então o resto do seu hook `session.start` também não é executado. Registre comandos por último nesse hook ou envolva a chamada em `try` e `catch`.

44 

45<h3 id="add-a-tool">

46 Adicione uma ferramenta

47</h3>

48 

49Uma ferramenta é para Claude. Registre-a com um nome, uma descrição que Claude lê e um JSON Schema para sua entrada. Claude a vê sob um nome mais longo feito de `mcp__`, o nome do seu plugin, dois sublinhados e o nome que você registrou. Você manipula suas chamadas em um hook [`tool.call`](/docs/pt/plugins/mods/events#guard-or-change-a-tool-call) filtrado para esse nome completo. Este exemplo, de um plugin chamado `my-mod`, registra `ticket`, então o nome completo é `mcp__my-mod__ticket`. Ele dá a Claude uma ferramenta que procura um ticket em um rastreador de problemas:

50 

51```javascript theme={null}

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

53 await $.tool.register({

54 name: 'ticket',

55 // Claude decides when to call the tool from this description

56 description: 'Look up a ticket by its id and return its title and status',

57 // The arguments Claude has to send: one required string named id

58 inputSchema: { type: 'object', properties: { id: { type: 'string' } }, required: ['id'] },

59 })

60 return next(e)

61})

62 

63// The full tool name is mcp__, the plugin's name, and the registered name

64on('tool.call', { tool: 'mcp__my-mod__ticket' }, async ($, e) => {

65 // The tool's arguments are fields of e, so the id is e.id

66 const response = await $.http.fetch('https://tickets.example.com/api/' + encodeURIComponent(e.id))

67 // Return a result either way, so Claude learns when the lookup failed

68 return { result: response.ok ? response.text : 'Lookup failed with status ' + response.status }

69})

70```

71 

72Quando você pergunta sobre um ticket, Claude pode chamar `mcp__my-mod__ticket` com seu id. O segundo hook busca o ticket e retorna o corpo da resposta, que Claude lê como o resultado da ferramenta. Quando o servidor responde com um status de erro, Claude lê `Lookup failed with status` e o número.

73 

74<h2 id="call-a-model">

75 Chame um modelo

76</h2>

77 

78Um mod pode fazer uma pergunta a um modelo por conta própria, fora da conversa, para um pequeno trabalho como classificar ou resumir um pedaço de texto. `$.model.complete` envia um prompt para um modelo com as credenciais da sua sessão e resolve para a resposta. Ele não tem histórico de conversa.

79 

80Este hook responde a um comando `/triage`, [registrado como um comando](#add-a-command), pedindo a um pequeno modelo para rotular o texto digitado após ele:

81 

82```javascript theme={null}

83on('command.run', { command: 'triage' }, async ($, e) => {

84 const r = await $.model.complete({

85 model: 'haiku',

86 // The system prompt sets the job, and the prompt carries the text to label

87 system: 'Reply with one word: bug, feature, or question.',

88 prompt: e.args,

89 // One word needs few tokens, and the call gives up after 15 seconds

90 maxTokens: 20,

91 timeoutMs: 15000,

92 })

93 // r.text exists only when the model answered, so check r.isAnswered first

94 const label = r.isAnswered ? r.text.trim() : 'unknown'

95 return { text: 'Label: ' + label }

96})

97```

98 

99Quando você executa `/triage the export button does nothing`, o mod envia esse texto para o modelo e imprime sua resposta, como `Label: bug`. A conversa de Claude não faz parte da solicitação. Quando o modelo não responde, o rótulo é `unknown`.

100 

101Uma falha da Claude API não rejeita a chamada, então verifique `r.isAnswered` e leia `r.reason` quando for `false`. A chamada rejeita apenas para uma solicitação que Claude Code não enviará, como um modelo que sua organização bloqueia. [Os tipos para sua compilação](/docs/pt/plugins/mods/create#get-the-types-for-your-build) listam as outras opções, como `effort`, e os [limites](/docs/pt/plugins/mods/reference#limits) fornecem o padrão `maxTokens`.

102 

103`$.model.fork({ prompt })` faz uma pergunta sobre a conversa atual, com o mesmo modelo e prompt do sistema, então a Claude API serve a maior parte dela do cache de prompt.

104 

105Essas chamadas usam o plano ou chave de API do usuário.

106 

107<h2 id="run-work-in-the-background">

108 Execute trabalho em segundo plano

109</h2>

110 

111Trabalho que sobrevive a um evento, como verificar algo uma vez por minuto, é executado em um temporizador que você inicia a partir de `session.start`. Um hook em si é executado para um evento e tem um limite de tempo de 10 segundos de seu próprio tempo de execução. O tempo gasto aguardando `next` ou uma chamada da mods API não conta, exceto um `$.clock.sleep`. `$.clock.every` e `$.clock.after` substituem `setInterval` e `setTimeout`, com o atraso em milissegundos primeiro: `$.clock.after(5000, fn)` chama `fn` uma vez, cinco segundos a partir de agora. Cada um retorna um temporizador com um método `cancel()`, e `await $.clock.now()` fornece a hora em milissegundos.

112 

113Este hook procura as verificações de uma solicitação de pull uma vez por minuto e mostra o resultado sob o prompt. `summarize` é uma função sua que transforma a saída JSON do comando em algumas palavras:

114 

115```javascript theme={null}

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

117 // Call the function every 60,000 milliseconds, starting one minute from now

118 $.clock.every(60_000, async () => {

119 const status = await $.process.run(['gh', 'pr', 'checks', '--json', 'state'])

120 // Replace the line under the prompt with the latest summary

121 $.ui.status('checks: ' + summarize(status.stdout))

122 })

123 // Return without waiting for the timer, so the session starts right away

124 return next(e)

125})

126```

127 

128A sessão inicia como de costume. Um minuto depois, uma linha aparece sob o prompt com um `⚠`, o nome do mod e depois `checks:` e seu resumo. É substituído uma vez por minuto depois disso. O callback do temporizador é executado fora de qualquer evento, então continua funcionando entre turnos e não inicia um. Se o callback lançar uma exceção, o erro vai para o [debug log](/docs/pt/plugins/mods/troubleshoot#read-the-debug-log) e o temporizador é executado novamente no próximo intervalo.

129 

130<h3 id="show-something-without-starting-a-turn">

131 Mostre algo sem iniciar um turno

132</h3>

133 

134Um trabalho em segundo plano pode mostrar ao usuário algo sem iniciar um turno. Cada uma dessas chamadas coloca texto em um lugar diferente:

135 

136| Chamada | O que o usuário vê |

137| :- | :- |

138| `$.ui.status(text)` | Uma linha sob o prompt que permanece até você alterá-la. Começa com `⚠` e o nome do mod, como em `⚠ my-mod: checks: 3 passing`. |

139| `$.ui.toast(text)` | Uma pequena caixa no canto superior direito, com o nome do mod acima do texto, que desaparece após alguns segundos |

140| `$.ui.log(text)` | Uma linha fraca na transcrição que Claude não lê. Começa com `●` e o nome do mod, como em `● my-mod: build finished`. |

141 

142<h3 id="start-a-turn-from-a-background-job">

143 Inicie um turno a partir de um trabalho em segundo plano

144</h3>

145 

146Quando um trabalho em segundo plano encontra algo que precisa da atenção de Claude, ele pode iniciar um turno enviando um prompt com `$.prompt.submit({ text })`. Claude lê o texto após uma frase que nomeia seu mod como o remetente. Para enviá-lo como as próprias palavras do usuário, sem essa frase, adicione `asUser: true`. A chamada aguarda até que a sessão esteja ociosa e depois inicia um novo turno. Ela resolve quando esse turno inicia, então não `await` em um manipulador que é executado enquanto Claude está trabalhando.

147 

148<h3 id="stop-background-work">

149 Pare o trabalho em segundo plano

150</h3>

151 

152O trabalho em segundo plano para de duas maneiras. Os temporizadores param quando o módulo é recarregado. Para trabalho de longa duração dentro de um hook, [`next.signal`](/docs/pt/plugins/mods/reference#the-hook-function) é um `AbortSignal` que aborta quando o evento que seu hook está manipulando é abandonado, por exemplo quando o usuário interrompe, então passe-o para qualquer coisa de longa duração.

153 

154<h2 id="send-and-receive-messages-between-sessions">

155 Envie e receba mensagens entre sessões

156</h2>

157 

158Um mod pode enviar uma mensagem em texto simples para outra de suas sessões ou para um dos subagentes desta sessão e observar as mensagens que chegam e saem. `$.session.send({ to, text })` envia uma, a mesma entrega que a ferramenta SendMessage faz. `to` é `{ sessionId }` para uma sessão, `{ agentId }` para um subagente de `$.agent.list()` ou o endereço de string de onde uma mensagem recebida veio. A chamada resolve uma vez que a mensagem é enfileirada, com `{ isDelivered: true }`. Quando nada foi entregue, ela resolve com `{ isDelivered: false, reason }`, e `reason` diz por quê.

159 

160Este hook responde a um comando `/ping`, [registrado como um comando](#add-a-command), pedindo à sessão cujo id você digita após ele um status:

161 

162```javascript theme={null}

163on('command.run', { command: 'ping' }, async ($, e) => {

164 // e.args is the session id typed after /ping

165 const sent = await $.session.send({ to: { sessionId: e.args }, text: 'Status? One line.' })

166 // The call resolves either way, so check isDelivered to learn what happened

167 if (!sent.isDelivered) $.ui.toast('Not delivered: ' + sent.reason)

168 // An empty result prints nothing in this session's transcript

169 return {}

170})

171```

172 

173Quando a mensagem é enfileirada, nada aparece em sua sessão e o Claude da outra sessão lê `Status? One line.` Quando nada foi entregue, uma pequena caixa no canto superior direito fornece o motivo e desaparece após alguns segundos.

174 

175Dois eventos permitem que um mod observe as mensagens. Retorne `next(e)` de ambos para passar cada mensagem inalterada:

176 

177| Evento | Dispara quando | Campos úteis |

178| :- | :- | :- |

179| `session.receive` | Uma mensagem chega para esta sessão, antes de Claude lê-la | `e.text` e `e.origin.kind`, como `peer` ou `peer-send-message` para outra sessão ou agente, `task-notification` ou `scheduled-trigger`. Retorne `{ consumed: reason }` para mantê-la longe de Claude. |

180| `session.send` | Uma mensagem está prestes a sair, da ferramenta SendMessage ou de um mod | `e.to`, `e.text` e `e.origin.kind`, que é `model` ou `plugin` |

181 

182Uma sessão definida para [recusar mensagens de entrada](/docs/pt/cross-session-messaging#control-inbound-messages) recusa uma mensagem antes de `session.receive` disparar, então um hook nunca a vê. Uma mensagem que é mantida para sua aprovação chega ao hook primeiro, então um mod pode ler uma mensagem que você ainda não aprovou. O `next(e)` do hook rejeita quando a mensagem não é entregue.

183 

184O nome do remetente em uma mensagem recebida é o que o remetente escreveu, então não baseie uma decisão nele.

185 

186<h2 id="reach-files-processes-and-the-network">

187 Acesse arquivos, processos e a rede

188</h2>

189 

190Um mod acessa o sistema de arquivos, processos e a rede através da mods API, com as mesmas permissões do usuário executando Claude Code. O próprio módulo de hooks não tem APIs Node.js, nenhum global de temporizador como `setTimeout` e nenhum acesso à rede ou arquivo próprio. APIs JavaScript padrão e web como `URL`, `TextEncoder`, `AbortController` e `crypto.subtle` estão disponíveis. Cada namespace abaixo cobre um tipo de acesso:

191 

192| Namespace | O que faz |

193| :- | :- |

194| `$.fs` | `read(path)`, `write(path, text)`, `exists(path)`, `stat(path)` e `list(path)` funcionam em arquivos e diretórios |

195| `$.process` | `run(['git', 'status'])` inicia um comando e resolve quando ele sai. `spawn` transmite a saída de um comando de longa duração. |

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

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

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

199| `$.settings` | `read` o que os arquivos de configurações e a política gerenciada contêm |

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

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

202 

203Arquivos e processos têm algumas regras próprias:

204 

205* **Paths**: um caminho relativo está sob o diretório de trabalho da sessão

206* **`$.fs.list`**: retorna as entradas de um diretório como `{ name, kind, size, isLink }` e não desce em subdiretórios

207* **`$.process.run`**: leva uma lista de argumentos e não usa shell. Ele resolve para `{ exitCode, stdout, stderr }` qualquer que seja o código de saída. Ele rejeita se o programa não puder iniciar ou ainda estiver em execução no tempo limite, que é 30 segundos por padrão, então envolva em `try` e `catch`.

208 

209Cada uma dessas chamadas é em si um evento, nomeado para seu namespace e método sem o `$.`, como `fs.read` para `$.fs.read`. Um mod [anterior na cadeia](/docs/pt/plugins/mods/events#the-order-mods-run-in) pode observar, reescrever ou recusar sua chamada, que é como uma organização restringe o que os mods alcançam.

210 

211<h2 id="next-steps">

212 Próximas etapas

213</h2>

214 

215* [React to events](/docs/pt/plugins/mods/events): hook tool calls, prompts, and turns

216* [Draw in the interface](/docs/pt/plugins/mods/interface): show what your mod collects in a pane or above the prompt

217* [Test a mod](/docs/pt/plugins/mods/test): stub any of these calls in a test

218* [Mods reference](/docs/pt/plugins/mods/reference): every event, every mods API method, and the limits

plugins/mods/create.md +395 −0 created

Details

1> ## Documentation Index

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

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

4 

5# Criar um mod

6 

7> Peça ao Claude para escrever um mod do Claude Code a partir de uma descrição, ou escreva um você mesmo que conte chamadas de ferramentas e adicione um comando. Aprenda o loop de recarga e validação.

8 

9Um mod é um [plugin](/docs/pt/plugins/overview) do Claude Code com um arquivo de entrada, chamado de hooks module: um arquivo JavaScript ou TypeScript cujas funções o Claude Code chama quando eventos acontecem. Existem duas maneiras de fazer um:

10 

11* **Peça ao Claude para escrever**: [descreva o que você quer](#ask-claude-for-a-mod) em uma sessão do Claude Code

12* **Escreva você mesmo**: [siga o tutorial](#write-a-mod-yourself) para aprender como o código de um mod funciona. Você não precisa de Node.js, um bundler ou uma etapa de compilação, porque o Claude Code carrega arquivos `.js` e `.ts` diretamente.

13 

14Se você ainda não decidiu se um mod é a ferramenta certa, leia primeiro a [comparação na visão geral](/docs/pt/plugins/mods/overview#compare-mods-settings-hooks-skills-and-mcp-servers).

15 

16<Note>

17 Mods requerem Claude Code v2.1.287 ou posterior. Em seu shell, execute `claude --version` para verificar. Para ver se mods podem ser carregados para você, consulte [Verificar se mods podem ser carregados](/docs/pt/plugins/mods/troubleshoot#check-whether-mods-can-load).

18</Note>

19 

20<h2 id="ask-claude-for-a-mod">

21 Peça ao Claude para um mod

22</h2>

23 

24Descreva o mod que você quer em uma sessão interativa do Claude Code, e Claude o escreve. Claude trabalha a partir de uma [skill](/docs/pt/skills) integrada chamada `plugin-authoring`, que diz a ele onde escrever o mod, quais eventos e métodos sua versão tem, e como o mod é carregado. Claude pode carregar a skill quando você pede um mod, ou você pode carregá-la você mesmo executando `/plugin-authoring` no prompt do Claude Code.

25 

26O mod é executado assim que você o aprova, exceto em [sessões onde um mod que Claude escreve não pode ser carregado](#sessions-that-skip-the-approval).

27 

28<Steps>

29 <Step title="Descreva o mod">

30 Peça pelo mod com suas próprias palavras, por exemplo `make a mod that shows the current git branch above the prompt`. Claude escreve o mod em um diretório próprio na pasta de mods da sessão, que é `~/.claude/dev-mods/` seguido pelo ID da sessão. O caminho completo de um mod se parece com `~/.claude/dev-mods/3f2a9c1e-5b7d-4e8a-9c21-6d0f4b8a7e13/git-branch/`.

31 

32 <Note>

33 Nos [modos de permissão](/docs/pt/permission-modes#protected-paths) `default` e `acceptEdits`, o Claude Code pergunta antes que Claude crie cada um dos arquivos do mod, porque `~/.claude` é um caminho protegido. Aprove cada arquivo conforme ele aparecer.

34 </Note>

35 </Step>

36 

37 <Step title="Aprove o mod">

38 Quando Claude salva o primeiro arquivo, o Claude Code pergunta se deve ativar o hot reloading para a sessão. O hot reloading executa os mods que Claude escreve nesta sessão e pega cada mudança posterior.

39 

40 Escolha uma destas respostas:

41 

42 * **Enable for this session**: os mods na pasta de mods da sessão são carregados quando a rodada termina, e recarregam no final de cada rodada que os altera. Sua resposta dura para a sessão, inclusive depois que você a retoma.

43 * **Not now**: nada é carregado por enquanto. Os arquivos permanecem onde Claude os escreveu, e os mods são carregados na próxima vez que essa sessão inicia. Para evitar que um mod seja carregado, delete seu diretório.

44 </Step>

45 

46 <Step title="Verifique se o mod foi carregado">

47 Execute `/plugin` no prompt do Claude Code e pressione Tab até que a aba **Installed** seja selecionada. Ela lista o mod, e você pode desativá-lo lá.

48 </Step>

49 

50 <Step title="Experimente o mod">

51 Use 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.

52 </Step>

53</Steps>

54 

55<h3 id="use-the-mod-in-other-sessions">

56 Use o mod em outras sessões

57</h3>

58 

59Um mod que Claude escreveu é carregado apenas na sessão que o criou, e o Claude Code deleta a pasta de mods dessa sessão uma vez que é mais antiga que [`cleanupPeriodDays`](/docs/pt/settings-reference#cleanupperioddays). Para manter o mod, copie seu diretório para fora da pasta de mods para um lugar seu, como `~/mods/git-branch`. Depois escolha como carregá-lo:

60 

61* **Em uma sessão que você inicia**: em seu shell, execute `claude --plugin-dir ~/mods/git-branch`

62* **Para outras pessoas**: [adicione-o a um marketplace](#share-your-mod) para que possam instalá-lo

63 

64<h3 id="sessions-that-skip-the-approval">

65 Sessões onde um mod que Claude escreve não pode ser carregado

66</h3>

67 

68Um mod que Claude escreve é carregado apenas depois que você o aprova, em um workspace confiável onde mods podem ser executados. Nestas sessões ele não é carregado:

69 

70* **Ninguém está lá para aprovar**: a sessão não pode mostrar um prompt, como em uma execução `claude -p` ou [modo `dontAsk`](/docs/pt/permission-modes)

71* **O workspace não é confiável**: você não aceitou o prompt de confiança para o diretório

72* **Mods estão parados**: você iniciou com `--safe-mode` ou `--bare`, você definiu `disableAllHooks`, ou as [configurações gerenciadas](/docs/pt/plugins/mods/admin#choose-how-much-to-allow) da sua organização bloqueiam

73 

74<h2 id="write-a-mod-yourself">

75 Escreva um mod você mesmo

76</h2>

77 

78Neste tutorial você constrói um mod chamado `first-mod` que conta as chamadas de ferramentas que Claude faz, mostra a contagem ao lado do spinner enquanto Claude trabalha, e adiciona um comando `/tally` que a imprime. Você então lê as declarações de tipo que o Claude Code escreve ao lado do seu mod e executa `claude plugin validate`. Juntas elas mostram os eventos e métodos que sua versão oferece e o que o Claude Code lê do seu código.

79 

80Esta gravação mostra o mod finalizado. O spinner conta chamadas de ferramentas, `/tally` imprime a contagem, e uma edição no código entra em efeito enquanto a sessão é executada:

81 

82<Frame>

83 <video autoPlay muted loop playsInline controls className="w-full dark:hidden" src="https://mintcdn.com/claude-code/dgiVO_Od1X1faduV/images/mods-first-mod-light.mp4?fit=max&auto=format&n=dgiVO_Od1X1faduV&q=85&s=eb561134afa90375777408453ba51c77" aria-label="In a Claude Code session, the prompt 'list the files here and read the README' is typed and sent. The spinner reads 'Thinking · tool calls: 1' and the count rises as Claude works. The /tally command prints 'first-mod: Claude has made 3 tool calls since this mod loaded'. A line says first-mod reloaded and lists its four hooks. On the next prompt the spinner reads 'Thinking · tools used: 1'." data-path="images/mods-first-mod-light.mp4" />

84 

85 <video autoPlay muted loop playsInline controls className="w-full hidden dark:block" src="https://mintcdn.com/claude-code/dgiVO_Od1X1faduV/images/mods-first-mod-dark.mp4?fit=max&auto=format&n=dgiVO_Od1X1faduV&q=85&s=09779dadc7ef66c2b1e2da0c2e31ac72" aria-label="In a Claude Code session, the prompt 'list the files here and read the README' is typed and sent. The spinner reads 'Thinking · tool calls: 1' and the count rises as Claude works. The /tally command prints 'first-mod: Claude has made 3 tool calls since this mod loaded'. A line says first-mod reloaded and lists its four hooks. On the next prompt the spinner reads 'Thinking · tools used: 1'." data-path="images/mods-first-mod-dark.mp4" />

86</Frame>

87 

88Você escreve três arquivos:

89 

90```text theme={null}

91first-mod/

92├── .claude-plugin/

93│ └── plugin.json

94└── hooks/

95 ├── hooks.json

96 └── register.js

97```

98 

99* **`plugin.json`**: o [manifest](/docs/pt/plugins/manifest-reference) do plugin

100* **`hooks.json`**: [aponta para seu arquivo de código](/docs/pt/plugins/mods/reference#files)

101* **`register.js`**: seu código, chamado de hooks module

102 

103<Steps>

104 <Step title="Crie o diretório do plugin">

105 Crie os dois diretórios que contêm os arquivos:

106 

107 <Tabs>

108 <Tab title="Bash ou Zsh">

109 ```bash theme={null}

110 mkdir -p first-mod/.claude-plugin first-mod/hooks

111 ```

112 </Tab>

113 

114 <Tab title="PowerShell">

115 ```powershell theme={null}

116 New-Item -ItemType Directory -Force first-mod\.claude-plugin, first-mod\hooks

117 ```

118 </Tab>

119 </Tabs>

120 </Step>

121 

122 <Step title="Escreva o manifest">

123 Um mod é um plugin, e um mod precisa de um [manifest](/docs/pt/plugins/manifest-reference). O manifest deste mod não tem campos especiais. Salve isto como `first-mod/.claude-plugin/plugin.json`:

124 

125 ```json first-mod/.claude-plugin/plugin.json theme={null}

126 {

127 "name": "first-mod",

128 "version": "0.1.0",

129 "description": "Counts Claude's tool calls, shows the count beside the spinner, and adds a /tally command",

130 "author": { "name": "Your Name" }

131 }

132 ```

133 </Step>

134 

135 <Step title="Diga ao Claude Code onde seu código está">

136 Quando o Claude Code carrega um plugin, ele lê o `hooks/hooks.json` do plugin. A chave `modules` naquele arquivo dá o caminho para seu código, e tê-la é o que torna o plugin um mod. Liste um caminho, relativo a `hooks.json`. Aqui ele aponta para `register.js`, que você escreve no próximo passo.

137 

138 Salve isto como `first-mod/hooks/hooks.json`:

139 

140 ```json first-mod/hooks/hooks.json theme={null}

141 {

142 "description": "The first-mod hooks module",

143 "modules": ["./register.js"]

144 }

145 ```

146 </Step>

147 

148 <Step title="Escreva o código">

149 Este arquivo é o código do mod, chamado de hooks module. Quando o mod é carregado, o Claude Code chama a função `register` que o arquivo exporta e passa a ela uma função chamada [`on`](/docs/pt/plugins/mods/reference#the-hook-function). Cada chamada a `on` registra um manipulador de evento, chamado de hook, para o evento que ele nomeia.

150 

151 Salve isto como `first-mod/hooks/register.js`:

152 

153 ```javascript first-mod/hooks/register.js theme={null}

154 // The count, shared by the hooks below

155 let calls = 0

156 

157 // Claude Code calls this once when the mod loads

158 export function register(on) {

159 // Runs when the session starts, before your first prompt

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

161 // Add the /tally command

162 await $.command.register({

163 name: 'tally',

164 description: 'Show how many tool calls Claude has made',

165 })

166 // Let the session start as usual

167 return next(e)

168 })

169 

170 // Runs each time Claude is about to use a tool

171 on('tool.call', async ($, e, next) => {

172 calls += 1

173 // Ask Claude Code to draw the interface again, so the new count shows

174 $.ui.invalidate('ui.render')

175 // Let the tool run as usual

176 return next(e)

177 })

178 

179 // Runs when you type /tally, and only then, because of the matcher

180 on('command.run', { command: 'tally' }, async () => {

181 // The text to print in the transcript

182 return { text: 'Claude has made ' + calls + ' tool calls since this mod loaded' }

183 })

184 

185 // Runs each time Claude Code draws the spinner

186 on('ui.render', { component: 'Spinner' }, async ($, e, next) => {

187 // Keep Claude Code's spinner, with the count added after its word

188 return next({ ...e, props: { ...e.props, suffix: ' · tool calls: ' + calls + '…' } })

189 })

190 }

191 ```

192 

193 O arquivo mantém uma contagem em `calls` e registra quatro hooks:

194 

195 * **[`session.start`](/docs/pt/plugins/mods/reference#session)** é executado quando a sessão inicia, antes do seu primeiro prompt, e novamente cada vez que o mod recarrega. Ele adiciona o comando `/tally` ao Claude Code.

196 * **[`tool.call`](/docs/pt/plugins/mods/reference#tools)** é executado cada vez que Claude está prestes a usar uma ferramenta. Ele adiciona um a `calls` e pede ao Claude Code para desenhar a interface novamente.

197 * **[`command.run`](/docs/pt/plugins/mods/reference#commands-and-configuration)** é executado quando você digita `/tally`. Ele retorna o texto a ser impresso.

198 * **[`ui.render`](/docs/pt/plugins/mods/reference#interface)** é executado cada vez que o Claude Code desenha o spinner. Ele adiciona a contagem após a palavra do spinner.

199 

200 [Como o mod de exemplo funciona](#how-the-example-mod-works) explica os três argumentos que cada hook recebe e o que cada um retorna.

201 </Step>

202 

203 <Step title="Carregue o mod">

204 Inicie o Claude Code com a flag `--plugin-dir`, que carrega um diretório de plugin para uma sessão sem instalá-lo:

205 

206 ```bash theme={null}

207 claude --plugin-dir ./first-mod

208 ```

209 </Step>

210 

211 <Step title="Experimente o mod">

212 Peça ao Claude para fazer algo que leve algumas chamadas de ferramentas, como `list the files here and read the README`. Enquanto Claude trabalha, a palavra do spinner é seguida por uma contagem que sobe, como em `Thinking · tool calls: 2…`. Quando Claude termina, digite `/tally` e pressione Enter. A transcrição mostra `first-mod: Claude has made 2 tool calls since this mod loaded`, com sua própria contagem. O Claude Code coloca o nome do plugin na frente do texto do comando.

213 

214 Para verificar o comando sem uma sessão interativa, execute-o em modo não interativo:

215 

216 ```bash theme={null}

217 claude -p "/tally" --plugin-dir ./first-mod

218 ```

219 

220 ```text theme={null}

221 first-mod: Claude has made 0 tool calls since this mod loaded

222 ```

223 

224 Se `/tally` não estiver na lista de comandos, o módulo não foi carregado. Consulte [Descubra por que um mod não faz nada](/docs/pt/plugins/mods/troubleshoot#find-out-why-a-mod-does-nothing).

225 </Step>

226 

227 <Step title="Altere o código enquanto a sessão é executada">

228 Deixe a sessão aberta. Em `register.js`, altere `' · tool calls: '` para `' · tools used: '` no hook `ui.render` e salve. A linha destacada é a que muda:

229 

230 ```javascript first-mod/hooks/register.js {4} theme={null}

231 // Runs each time Claude Code draws the spinner

232 on('ui.render', { component: 'Spinner' }, async ($, e, next) => {

233 // Keep Claude Code's spinner, with the count added after its word

234 return next({ ...e, props: { ...e.props, suffix: ' · tools used: ' + calls + '…' } })

235 })

236 ```

237 

238 Uma linha na transcrição diz que `first-mod` recarregou e lista seus hooks, e o próximo spinner usa o novo texto, como em `Thinking · tools used: 1…`.

239 </Step>

240</Steps>

241 

242<h3 id="how-the-example-mod-works">

243 Como o mod de exemplo funciona

244</h3>

245 

246Cada função que você passa a `on` é um hook, que é um manipulador de evento. O Claude Code passa a cada hook os mesmos três argumentos:

247 

248* **A API de mods**, chamada `$`: cada método que um mod pode chamar para alcançar fora de si mesmo, em [namespaces](/docs/pt/plugins/mods/reference#mods-api-methods) como `$.ui` e `$.command`

249* **O evento**, chamado `e`: a [entrada do evento](/docs/pt/plugins/mods/reference#events) como dados simples, como o nome e argumentos de uma chamada de ferramenta

250* **O próximo manipulador**, chamado [`next`](/docs/pt/plugins/mods/events#how-a-hook-handles-an-event): uma função que passa o evento para os outros mods e depois para o comportamento próprio do Claude Code, e retorna o resultado

251 

252Os hooks em `first-mod` lidam com seus eventos das três maneiras que um hook pode:

253 

254* **Observar**: o hook `session.start` registra o comando, e o hook `tool.call` conta a chamada e pede um redesenho. Ambos retornam `next(e)`, então a sessão inicia e a ferramenta é executada como usual.

255* **Responder**: o hook `command.run` retorna seu próprio resultado e nunca chama `next`. O segundo argumento a `on`, `{ command: 'tally' }`, é um filtro, chamado de [matcher](/docs/pt/plugins/mods/events#filter-which-events-a-hook-handles), então o hook é executado apenas para `/tally`.

256* **Reescrever**: o hook `ui.render` chama `next` com uma cópia de `e` cujo `suffix` contém a contagem, então o Claude Code desenha seu spinner usual com seu texto após a palavra

257 

258O Claude Code observa um diretório carregado com `--plugin-dir` e hot-recarrega o hooks module quando um arquivo nele muda. Cada recarga executa `register` novamente, então `calls` volta a `0` e `/tally` começa a contar novamente. Para manter um valor entre recargas, consulte [Manter estado](/docs/pt/plugins/mods/interface#keep-state).

259 

260<h2 id="keep-working-on-a-mod">

261 Continue trabalhando em um mod

262</h2>

263 

264Uma vez que um mod é carregado, você pode fazer Claude alterá-lo, verificar seu código contra as definições de tipo para sua versão, listar os eventos e chamadas que o Claude Code encontra nele, e testá-lo.

265 

266<h3 id="change-a-mod-with-claude">

267 Altere um mod com Claude

268</h3>

269 

270Para alterar um mod que você já tem, inicie a sessão com `--plugin-dir` apontado para o diretório do mod, para que o que Claude escreve seja carregado na mesma sessão:

271 

272```bash theme={null}

273claude --plugin-dir ./first-mod

274```

275 

276Depois peça pela mudança, por exemplo `add a /tally-reset command to this mod that sets the tally back to zero`. Claude edita o hooks module, executa `claude plugin validate`, e corrige o que ele relata. Um diretório que você carrega com `--plugin-dir` é um [caminho protegido](/docs/pt/permission-modes#protected-paths), então nos modos `default` e `acceptEdits` você é solicitado a aprovar cada edição de Claude ao mod. A tabela de caminhos protegidos dá o resultado para os outros modos de permissão.

277 

278Os arquivos que Claude salva durante sua rodada recarregam quando a rodada termina, então você pode tentar `/tally-reset` assim que Claude terminar.

279 

280<h3 id="get-the-types-for-your-build">

281 Obtenha definições de tipo para sua versão

282</h3>

283 

284Cada vez que o Claude Code carrega ou recarrega um mod de um diretório que você passa a `--plugin-dir`, ou um mod [que Claude escreveu para você](#ask-claude-for-a-mod), ele escreve arquivos de declaração TypeScript, terminando em `.d.ts`, em `.claude-plugin/types/` dentro do diretório do mod. Eles descrevem os eventos exatos, métodos da API de mods e elementos na versão do Claude Code que você está executando, então seu editor pode autocompletar e verificar tipos em seus hooks. Para navegar pelas declarações online, leia [`mods/types/claude-code.d.ts`](https://github.com/anthropics/claude-code/blob/main/mods/types/claude-code.d.ts) no repositório do Claude Code, cuja primeira linha nomeia a versão que a escreveu. O diretório contém estes arquivos:

285 

286| Caminho | O que declara |

287| :- | :- |

288| `claude-code/index.d.ts` | Cada evento e sua entrada e resultado, cada namespace e método da API de mods, e os elementos que cada superfície pode desenhar |

289| `claude-code-tools/index.d.ts` | As entradas e resultados das ferramentas integradas, para que verificar `e.tool === 'Bash'` restrinja `e` |

290| `claude-code-mcp/index.d.ts` | As entradas das ferramentas MCP que foram conectadas a última vez que você salvou um arquivo no mod |

291| `index.d.ts` em um diretório nomeado para um plugin | O que esse plugin adiciona à API de mods. Há um diretório para cada plugin que seu `plugin.json` lista em `dependencies`. |

292| `tsconfig.json` | Opções de compilador que se adequam a um hooks module |

293 

294Se seu mod não tem seu próprio `tsconfig.json`, o Claude Code adiciona um na raiz do mod que estende o gerado, então seu editor e `tsc -p ./first-mod` verificam tipos do mod sem mais configuração.

295 

296Os eventos e métodos podem mudar entre releases, então confie nesses arquivos sobre qualquer página, inclusive esta, quando discordarem.

297 

298`claude-code/index.d.ts` é a referência mais completa para sua compilação, com um comentário e um exemplo para cada método da API de mods. Para procurar algo, pesquise o arquivo por seu nome, como `'tool.call'`.

299 

300<h3 id="check-what-claude-code-reads-from-your-mod">

301 Verifique o que o Claude Code lê do seu mod

302</h3>

303 

304Para ver seu mod da maneira que o Claude Code o vê, sem executar seu código ou iniciar uma sessão, use `claude plugin validate`. Ele verifica o manifest e executa a mesma análise estática no código-fonte do hooks module que o Claude Code executa quando carrega um mod. Em seu shell, execute-o no diretório do mod:

305 

306```bash theme={null}

307claude plugin validate ./first-mod

308```

309 

310Para `first-mod`, a saída inclui estas linhas.

311 

312```text theme={null}

313 ❯ ./register.js hooks: session.start, tool.call, command.run{command=tally}, ui.render{component=Spinner}

314 ❯ ./register.js calls: $.command.register, $.ui.invalidate

315 

316✔ Validation passed

317```

318 

319A linha `hooks:` lista os eventos que seu módulo conecta, cada um com seu filtro entre chaves. A linha `calls:` lista cada método da API de mods que ele chama. Um módulo que lê ou define variáveis de ambiente também obtém linhas `env reads:` e `env writes:`, e um que usa [`$.state`](/docs/pt/plugins/mods/interface#keep-state) obtém `state reads:` e `state writes:`.

320 

321Se um evento que você pretendia conectar está faltando na primeira linha, o Claude Code não chamará esse hook também. A causa usual é um nome de evento digitado incorretamente, que o comando relata como um erro como `"tool.calls" is not an event`.

322 

323Siga estas regras para que a análise estática possa encontrar cada hook e chamada:

324 

325* Soletra cada chamada da API de mods completamente: `$`, o namespace, depois o método, como em `$.store.get('notes')`. Você pode passar `$` para uma função declarada no nível superior do mesmo arquivo, e para uma função sua chamada `loadNotes`, a linha `calls:` então lê `$.store.get (via loadNotes)`. Passar `$` para um método, uma função definida dentro do hook, ou uma função que você importa de outro de seus arquivos falha na validação. As funções `read` e `update` que [`$.state`](/docs/pt/plugins/mods/interface#keep-state) usa são as importações que podem levá-lo. Não atribua `$` ou um de seus namespaces a uma variável, desestruture-o, ou indexe-o com um nome computado. `const ui = $.ui` falha com `$.ui is used as a value`.

326* Escreva o nome do evento em cada chamada `on` como um literal de string, como `'tool.call'`. Uma variável, ou um loop sobre uma lista de nomes, falha com `the event name passed to on() is not a string literal`.

327* Dentro de `register`, não declare uma segunda variável ou parâmetro chamado `on`. A validação falha com `"on" is declared again (shadowed)`.

328* Importe apenas de arquivos dentro do diretório do plugin, por caminho relativo. A única importação nua permitida é `claude-code`, para tipos e alguns auxiliares.

329* Use declarações `import` no topo do arquivo, como em `import { name } from './file.js'`. Um `import()` dinâmico falha com `a dynamic import(); a hooks module imports its own files with an import declaration`.

330* Escreva cada arquivo como um módulo ES, com `import` e não `require`. A [referência](/docs/pt/plugins/mods/reference#files) lista as extensões de arquivo que o Claude Code carrega.

331 

332<h3 id="test-the-mod">

333 Teste o mod

334</h3>

335 

336Você pode escrever testes automatizados para um mod e executá-los de seu shell com `claude plugin test`, sem sessão, sign-in ou rede. Um teste levanta os eventos que seus hooks lidam e verifica o que os hooks fizeram.

337 

338Este teste levanta duas chamadas de ferramentas, executa `/tally`, e verifica que a resposta conta ambas. Salve-o como `first-mod/tests/first-mod.test.ts`:

339 

340```typescript first-mod/tests/first-mod.test.ts theme={null}

341import { expect, test } from 'claude-code/testing'

342 

343test('/tally reports the tool calls the mod has seen', async ($, on) => {

344 // Answer each tool call in Claude Code's place, so no tool runs

345 on('tool.call', () => ({ result: 'ok' }))

346 

347 // Raise two tool calls, which the mod's tool.call hook counts

348 await $.tool.call({ tool: 'Bash', command: 'ls' })

349 await $.tool.call({ tool: 'Read', file_path: 'README.md' })

350 

351 // Run /tally and check the text its hook returns

352 const answer = await $.command.run({ command: 'tally', args: '' })

353 expect(answer.text).toBe('Claude has made 2 tool calls since this mod loaded')

354})

355```

356 

357Em seu shell, execute os testes do diretório `first-mod`:

358 

359```bash theme={null}

360claude plugin test

361```

362 

363A saída nomeia cada teste e se passou, com tempos que variam de execução para execução:

364 

365```text theme={null}

366tests/first-mod.test.ts:

367(pass) /tally reports the tool calls the mod has seen [22.87ms]

368 

369 1 pass

370 0 fail

371Ran 1 test across 1 file. [0.19s]

372```

373 

374[Teste um mod](/docs/pt/plugins/mods/test) cobre stubbing de uma chamada de modelo ou da loja, e testes de temporizadores e desenhos.

375 

376<h2 id="share-your-mod">

377 Compartilhe seu mod

378</h2>

379 

380Um mod é um plugin, então você o versiona no manifest e as pessoas o instalam e atualizam com os comandos `/plugin`. Para dá-lo a outras pessoas, [adicione-o a um marketplace](/docs/pt/plugins/publish).

381 

382Antes de fazer isso, verifique o `name` do plugin: `claude plugin validate` falha em um nome que [parece um dos próprios da Anthropic](/docs/pt/plugins/manifest-reference#name), como um que começa com `claude-`. Os eventos e métodos podem mudar entre releases, então seu README é o lugar para dizer qual versão do Claude Code você testou.

383 

384Continue desenvolvendo contra o diretório com `--plugin-dir`, não contra uma cópia instalada. O Claude Code armazena em cache um plugin instalado por versão, então suas edições não chegam à cópia instalada até que você aumente a versão e instale novamente.

385 

386<h2 id="next-steps">

387 Próximos passos

388</h2>

389 

390* [Desenhe na interface](/docs/pt/plugins/mods/interface): abra um painel, desenhe acima do prompt, e adicione botões e campos de texto

391* [Reaja a eventos](/docs/pt/plugins/mods/events): conecte chamadas de ferramentas, prompts e rodadas

392* [Use a API de mods](/docs/pt/plugins/mods/api): adicione comandos e ferramentas, chame um modelo, e execute trabalho em um temporizador

393* [Teste um mod](/docs/pt/plugins/mods/test): stub do que o Claude Code responderia, e teste temporizadores e desenhos

394* [Solucione problemas de um mod](/docs/pt/plugins/mods/troubleshoot): as razões pelas quais um mod não faz nada, e o log de depuração

395* [Leia a fonte de mods integrados](/docs/pt/plugins/mods/overview#read-the-source-of-built-in-mods): plugins completos, cada um com seu hooks module e testes

plugins/mods/events.md +336 −0 created

Details

1> ## Documentation Index

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

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

4 

5# Reagir a eventos com um mod

6 

7> Manipule eventos do Claude Code a partir de um mod: observe, reescreva ou responda chamadas de ferramentas, prompts e turnos, filtre quais eventos um hook manipula e planeje para outros mods.

8 

9Um hook é um manipulador de eventos: uma função que Claude Code executa quando um evento nomeado acontece. Claude Code dispara um evento em cada ponto onde está prestes a agir, como quando executa uma ferramenta, envia um prompt, faz uma solicitação ao modelo ou inicia ou encerra uma sessão. Seu hook é executado antes de Claude Code agir, portanto pode observar o evento, reescrevê-lo ou respondê-lo no lugar de Claude Code. Você registra um hook com [`on(eventName, handler)`](/docs/pt/plugins/mods/reference#the-hook-function).

10 

11Construa seu [primeiro mod](/docs/pt/plugins/mods/create) antes de começar aqui. Para cada evento e seus campos exatos, consulte a [referência](/docs/pt/plugins/mods/reference#events) ou leia [os tipos para sua compilação](/docs/pt/plugins/mods/create#get-the-types-for-your-build).

12 

13<h2 id="how-a-hook-handles-an-event">

14 Como um hook manipula um evento

15</h2>

16 

17Um hook fica entre um evento e o que Claude Code faria sobre ele, portanto pode observar o evento, reescrevê-lo ou respondê-lo por si mesmo. Ele recebe três argumentos: a [API de mods](/docs/pt/plugins/mods/api) como `$`, o evento como `e` e o próximo manipulador como `next`. Os manipuladores de um evento formam uma cadeia de middleware. `next(e)` chama o próximo manipulador, que é o hook de outro mod ou, no final da cadeia, o comportamento próprio de Claude Code, e é resolvido para o resultado. O que seu hook faz com `next` decide qual dos três ele faz.

18 

19<h3 id="observe-an-event">

20 Observe um evento

21</h3>

22 

23Para observar um evento sem alterá-lo, faça seu trabalho e retorne `next(e)`. Este hook registra cada ferramenta que Claude está prestes a usar:

24 

25```javascript theme={null}

26on('tool.call', async ($, e, next) => {

27 // Executa antes da ferramenta

28 $.ui.log('Claude is about to use ' + e.tool)

29 // Passe o evento adiante inalterado

30 return next(e)

31})

32```

33 

34Antes de cada ferramenta ser executada, uma linha fraca como `● my-mod: Claude is about to use Bash` aparece na transcrição, onde `my-mod` é o nome do seu plugin. A ferramenta é executada como seria sem o mod.

35 

36Para agir após o evento, `await next(e)`, faça seu trabalho e retorne o resultado. Este hook registra cada ferramenta após sua execução:

37 

38```javascript theme={null}

39on('tool.call', async ($, e, next) => {

40 // Deixe a ferramenta ser executada e aguarde seu resultado

41 const result = await next(e)

42 // Executa após a ferramenta

43 $.ui.log(e.tool + ' finished')

44 // Devolva o resultado inalterado

45 return result

46})

47```

48 

49A linha agora aparece após cada ferramenta terminar. Claude lê o mesmo resultado de qualquer forma, porque o hook retorna o que `next(e)` foi resolvido.

50 

51<h3 id="rewrite-an-event">

52 Reescreva um evento

53</h3>

54 

55Para alterar o que Claude Code age, como o texto de um prompt, chame `next` com uma cópia modificada do evento. O evento em si é imutável: é congelado em cada profundidade e atribuir a um campo lança um erro. Este hook corta cada prompt antes de ser enviado:

56 

57```javascript theme={null}

58on('prompt.submit', async ($, e, next) => {

59 // Passe uma cópia do evento com seu texto alterado

60 return next({ ...e, text: e.text.trim() })

61})

62```

63 

64Manipuladores posteriores e Claude Code recebem o prompt cortado e nunca veem o original. Você também pode alterar o resultado: `await next(e)`, depois retorne uma cópia do resultado com um campo substituído.

65 

66<h3 id="answer-an-event">

67 Responda a um evento

68</h3>

69 

70Para manipular um evento você mesmo, retorne um resultado sem chamar `next`. Isso interrompe a cadeia, portanto mods posteriores e o comportamento próprio de Claude Code não são executados. Este hook recusa cada comando Bash:

71 

72```javascript theme={null}

73on('tool.call', { tool: 'Bash' }, async () => {

74 // Nenhuma chamada para next, portanto o comando nunca é executado

75 return { deny: 'Bash is turned off in this project. Use the file tools.' }

76})

77```

78 

79Quando Claude tenta um comando Bash, o comando não é executado e Claude lê o texto `deny` como o resultado da ferramenta. Cada evento tem sua própria forma de resultado, que a [referência de eventos](/docs/pt/plugins/mods/reference#events) lista.

80 

81<h3 id="filter-which-events-a-hook-handles">

82 Filtre quais eventos um hook manipula

83</h3>

84 

85Para executar um hook apenas para alguns eventos, passe um filtro como o segundo argumento para `on`. Claude Code chama o filtro de matcher. É um objeto cujos campos são comparados com os do evento, e o hook é executado apenas quando cada campo corresponde. Um campo pode ser um valor, uma matriz de valores permitidos ou uma expressão regular.

86 

87Cada linha neste exemplo registra a mesma função, `hook`, para um conjunto mais estreito de chamadas de ferramentas:

88 

89```javascript theme={null}

90// Uma string corresponde a um valor: apenas chamadas Bash

91on('tool.call', { tool: 'Bash' }, hook)

92// Uma matriz corresponde a qualquer valor nela: chamadas Edit e Write

93on('tool.call', { tool: ['Edit', 'Write'] }, hook)

94// Uma expressão regular corresponde por padrão: cada ferramenta de um servidor MCP

95on('tool.call', { tool: /^mcp__github__/ }, hook)

96```

97 

98`hook` é executado uma vez para uma chamada Bash, Edit ou Write, e uma vez para uma chamada a uma ferramenta cujo nome começa com `mcp__github__`. Uma chamada para qualquer outra ferramenta, como Read, não corresponde a nenhuma das três, portanto `hook` não é executado para ela.

99 

100O nome do evento pode ser um wildcard. `'classic.*'` corresponde a cada [evento de hook de configurações](#hook-the-settings-hook-events). `'*'` corresponde a cada evento exceto os [eventos de telemetria](/docs/pt/plugins/mods/reference#telemetry), que você conecta por nome ou como `'telemetry.*'`.

101 

102Registre cada evento uma vez por matcher. Se você chamar `on` duas vezes para `session.start` sem um matcher, o módulo falhará ao carregar com `on("session.start") is registered twice without a matcher`. Coloque tudo o que seu mod faz no início da sessão em um hook.

103 

104<h2 id="hook-what-claude-is-doing">

105 Hook o que Claude está fazendo

106</h2>

107 

108Conecte esses eventos para ver ou alterar uma chamada de ferramenta, um prompt ou um turno conforme acontece. Para cada evento e o que um hook pode retornar, consulte a [referência de eventos](/docs/pt/plugins/mods/reference#events).

109 

110<h3 id="guard-or-change-a-tool-call">

111 Guarde ou altere uma chamada de ferramenta

112</h3>

113 

114Um hook `tool.call` vê cada ferramenta que Claude está prestes a usar, portanto pode recusar a chamada, alterar seus argumentos ou deixá-la passar. `tool.call` dispara quando Claude Code está prestes a executar uma ferramenta, incluindo chamadas que um subagenteaz e chamadas para ferramentas MCP. `e.tool` é o nome da ferramenta e os argumentos da ferramenta são campos de `e`, como `e.command` para Bash. Quando você chama `next(e)`, Claude Code executa a verificação de permissão e depois a ferramenta.

115 

116Este hook recusa um comando Bash que força um push e diz a Claude por quê:

117 

118```javascript theme={null}

119// O matcher limita o hook a chamadas Bash, portanto e.command é o comando do shell

120on('tool.call', { tool: 'Bash' }, async ($, e, next) => {

121 if (/git push .*--force/.test(e.command)) {

122 // Retornar sem chamar next responde ao evento, portanto o comando nunca é executado

123 return { deny: 'Force pushes are not allowed in this repository. Push to a new branch instead.' }

124 }

125 // Cada outro comando passa para a verificação de permissão e depois para Bash

126 return next(e)

127})

128```

129 

130Quando Claude tenta `git push --force`, o comando não é executado e nenhum prompt de permissão aparece, porque o hook nunca chama `next`. Claude lê o texto `deny` como o resultado da ferramenta, portanto escreva-o como uma instrução que Claude pode agir. Cada outro comando Bash é executado como seria sem o mod.

131 

132Para agir após uma ferramenta ter sido executada, `await next(e)`, faça seu trabalho e retorne o que `next` lhe deu. Este hook registra cada arquivo `.mdx` que Claude altera, com [`$.ui.log`](/docs/pt/plugins/mods/api#show-something-without-starting-a-turn), que adiciona uma linha fraca à transcrição que Claude não lê:

133 

134```javascript theme={null}

135on('tool.call', { tool: ['Edit', 'Write'] }, async ($, e, next) => {

136 // Aguarde a verificação de permissão e a ferramenta, e mantenha o que produziram

137 const result = await next(e)

138 // Uma chamada recusada volta como { deny }, e uma falhada tem isError definido

139 const changed = !result.deny && !result.isError

140 if (changed && e.file_path.endsWith('.mdx')) $.ui.log('Claude changed ' + e.file_path)

141 // Retorne o resultado como veio, portanto Claude lê o que a ferramenta retornou

142 return result

143})

144```

145 

146Depois que Claude edita ou escreve um arquivo `.mdx`, uma linha fraca na transcrição nomeia o arquivo. Nada é registrado para outro tipo de arquivo ou para uma chamada que foi recusada ou falhou. A visualização de Claude da chamada não muda, porque o hook retorna o resultado que recebeu.

147 

148Para alterar uma chamada, passe argumentos alterados para `next`. Para tentar novamente uma chamada, chame `next(e)` novamente: um hook que vê `isError` no primeiro resultado pode executar a ferramenta uma segunda vez e retornar esse resultado. Para responder a uma chamada você mesmo, retorne um objeto com um campo `result`, como `{ result: 'Skipped by my-mod' }`, sem chamar `next`. Quando você faz isso, nenhum prompt de permissão aparece e a ferramenta não é executada, portanto o resultado que você retorna é tudo que Claude aprende sobre o que aconteceu.

149 

150Hooks nas [configurações gerenciadas](/docs/pt/server-managed-settings) de sua organização são executados antes de qualquer hook `tool.call` de mod, e um bloqueio de um deles é final.

151 

152<h4 id="hold-a-tool-call-until-the-user-decides">

153 Mantenha uma chamada de ferramenta até o usuário decidir

154</h4>

155 

156Um hook pode pausar uma chamada de ferramenta e perguntar ao usuário o que fazer antes de prosseguir. Um hook `tool.call` pode `await` antes de chamar `next` ou retornar, e a chamada de ferramenta permanece pendente até então. Para fazer a pergunta ao usuário, chame `$.ui.ask`. Ele mostra sua pergunta acima de uma lista numerada de suas opções, no diálogo que Claude usa para lhe fazer uma pergunta, e é resolvido para o rótulo que o usuário escolhe. Após suas opções, o diálogo adiciona uma linha para digitar uma resposta diferente e uma linha **Chat about this**.

157 

158O padrão `RISKY` neste exemplo corresponde a `rm -r`, `rm -rf`, `git reset --hard` e `git push` com `--force`, e perde outras grafias como `git push -f`. Este módulo pergunta antes de executar um comando Bash que corresponde ao padrão:

159 

160```javascript theme={null}

161const RISKY = /\brm\s+-rf?\b|\bgit\s+reset\s+--hard\b|\bgit\s+push\b.*--force/

162 

163export function register(on) {

164 on('tool.call', { tool: 'Bash' }, async ($, e, next) => {

165 // Deixe cada outro comando passar sem uma pergunta

166 if (!RISKY.test(e.command)) return next(e)

167 // Comece a partir da resposta segura, portanto uma pergunta que ninguém responde recusa o comando

168 let answer = 'Refuse'

169 try {

170 // A chamada de ferramenta aguarda aqui até o usuário escolher um dos dois rótulos

171 answer = await $.ui.ask('Run this command? ' + e.command, ['Run it', 'Refuse'])

172 } catch {

173 // O usuário descartou a pergunta ou esta é uma execução claude -p sem ninguém para perguntar

174 }

175 if (answer !== 'Run it') {

176 // Responda sem chamar next, portanto o comando não é executado

177 return { deny: 'The user declined this command. Ask before trying a different approach.' }

178 }

179 return next(e)

180 })

181}

182```

183 

184Quando Claude tenta um comando como `rm -rf build`, a pergunta aparece com o comando nela, e o comando aguarda a resposta:

185 

186* **O usuário escolhe Run it**: o hook chama `next(e)` e a verificação de permissão usual ainda é executada após ele

187* **O usuário escolhe Refuse**: o comando não é executado e Claude lê o texto `deny`

188* **O usuário digita uma resposta**: `$.ui.ask` é resolvido para o texto digitado. O hook o compara com `Run it`, portanto qualquer outro texto recusa o comando.

189* **Ninguém responde**: `$.ui.ask` rejeita quando o usuário descarta a pergunta ou escolhe **Chat about this**, e em uma execução `claude -p`, portanto o bloco `catch` deixa a resposta em `Refuse`

190 

191Mantenha a espera dentro de uma chamada de API de mods como `$.ui.ask`, porque esse tempo não conta contra o [limite de tempo de 10 segundos](/docs/pt/plugins/mods/reference#limits) do hook. O tempo gasto aguardando uma promessa sua conta. Claude Code pula um hook que expira, portanto o comando mantido seria executado.

192 

193<h3 id="rewrite-or-add-to-a-prompt">

194 Reescreva ou adicione a um prompt

195</h3>

196 

197Um hook `prompt.submit` vê cada prompt antes do turno começar, portanto pode reescrever o texto ou adicionar a ele. `e.text` é o que foi digitado.

198 

199| Para fazer isso | Retorne isto |

200| :- | :- |

201| Reescreva o prompt. A mensagem na transcrição mostra o novo texto. | `next({ ...e, text: newText })` |

202| Adicione texto apenas que Claude lê, após o prompt | `next({ ...e, context: [...(e.context ?? []), extraText] })` |

203| Impeça que o prompt seja enviado | `{ drop: 'the reason' }` |

204 

205Este hook adiciona o nome da ramificação atual para Claude sempre que um prompt menciona uma solicitação de pull:

206 

207```javascript theme={null}

208on('prompt.submit', async ($, e, next) => {

209 // Passe um prompt que não menciona uma solicitação de pull como está

210 if (!/\bPR\b|pull request/i.test(e.text)) return next(e)

211 const git = await $.process.run(['git', 'branch', '--show-current'])

212 // Fora de um repositório git o comando falha, portanto não há ramificação para adicionar

213 if (git.exitCode !== 0) return next(e)

214 // Mantenha qualquer contexto que um hook anterior adicionou e adicione mais uma linha para Claude

215 return next({ ...e, context: [...(e.context ?? []), 'Current branch: ' + git.stdout.trim()] })

216})

217```

218 

219Quando você envia um prompt como `open a PR for this change`, sua mensagem parece a mesma na transcrição e Claude também lê uma linha como `Current branch: feature/auth` após ela. Um prompt que não menciona uma solicitação de pull passa inalterado e `git` não é executado.

220 

221[Outros eventos](/docs/pt/plugins/mods/reference#prompts-and-what-claude-reads) cobrem o resto do que Claude lê: `prompt.section` para cada seção do prompt do sistema, `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 solicitações [invalida o cache de prompt](/docs/pt/prompt-caching).

222 

223<h3 id="follow-a-turn">

224 Siga um turno

225</h3>

226 

227Um turno é tudo o que Claude faz em resposta a um prompt. Conecte `turn.start`, `turn.step` e `turn.complete` para seguir um:

228 

229| Evento | Quando dispara | O que um hook pode fazer |

230| :- | :- | :- |

231| `turn.start` | Um turno começa | Observe. `e.turnId` identifica o turno nos outros dois eventos. |

232| `turn.step` | Claude Code está prestes a enviar uma solicitação ao modelo. Um turno com chamadas de ferramentas tem várias. `e.agentId` é definido para uma solicitação de um subagenteaz. | Leia o uso de token de cada solicitação, envie-o para um modelo diferente com `next({ ...e, model })` ou responda sem chamar o modelo |

233| `turn.complete` | O turno terminou, incluindo um turno que o usuário interrompeu, onde `e.isAborted` é `true`. `e.answer` é o texto final de Claude, `e.durationMs` quanto tempo levou e `e.usage` os totais de token do turno. Um turno de um subagenteaz dispara com `e.agentId` definido. | Observe ou retorne um objeto com um campo `text`, como `{ text: 'Done in 12 seconds' }`, para mostrar uma linha sob a resposta |

234 

235Escreva um hook `turn.step` como um gerador assíncrono, porque o evento flui. `yield* next(e)` encaminha a resposta conforme flui e é avaliado para o resultado terminado. Este hook registra quanto de cada solicitação a API Claude serviu do [cache de prompt](/docs/pt/prompt-caching):

236 

237```javascript theme={null}

238// function* torna o hook um gerador, que pode passar a resposta adiante pedaço por pedaço

239on('turn.step', async function* ($, e, next) {

240 // Envie a solicitação, encaminhe cada pedaço conforme chega e mantenha o resultado terminado

241 const result = yield* next(e)

242 // Pule um resultado que não relata contagens de token

243 if (result.usage) {

244 $.ui.log('cache read ' + result.usage.cache_read_input_tokens + ' · wrote ' + result.usage.cache_creation_input_tokens)

245 }

246 // Retorne o resultado inalterado, portanto o turno continua como usual

247 return result

248})

249```

250 

251A resposta de Claude flui para a tela como faria sem o mod. Após cada solicitação terminar, uma linha fraca na transcrição fornece o número de tokens lidos do cache e o número escrito nele. Um turno com chamadas de ferramentas tem várias solicitações, portanto adiciona várias linhas.

252 

253`result.usage` contém as quatro contagens de token que a API Claude relata para uma solicitação, mais o `model` que respondeu: `input_tokens`, `output_tokens`, `cache_read_input_tokens` e `cache_creation_input_tokens`. O hook é executado para solicitações de subagenteaz também, portanto verifique `e.agentId` quando você quer apenas a conversa principal.

254 

255<h3 id="hook-the-settings-hook-events">

256 Hook os eventos de hook de configurações

257</h3>

258 

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

260 

261Este hook usa `Stop`, que dispara quando Claude termina de responder, para registrar onde a transcrição da sessão é salva:

262 

263```javascript theme={null}

264on('classic.Stop', async ($, e, next) => {

265 // e tem os mesmos campos que um hook Stop em um arquivo de configurações lê de stdin

266 $.ui.log('Transcript saved at ' + e.transcript_path)

267 // Passe o evento adiante, portanto hooks Stop em seus arquivos de configurações ainda são executados

268 return next(e)

269})

270```

271 

272Cada vez que Claude termina de responder, uma linha fraca na transcrição fornece o caminho do arquivo de transcrição. O hook retorna `next(e)`, portanto observa o evento e não muda nada sobre como o turno termina.

273 

274<h2 id="run-alongside-other-mods">

275 Execute ao lado de outros mods

276</h2>

277 

278Vários mods podem conectar o mesmo evento e qualquer um deles pode falhar. Se seu mod bloqueia chamadas de ferramentas, verifique sua posição na cadeia e o que acontece quando seu hook falha.

279 

280<h3 id="the-order-mods-run-in">

281 A ordem em que os mods são executados

282</h3>

283 

284Hooks no mesmo evento formam uma cadeia de middleware. Cada `next` de um mod chama o hook do mod seguinte, e o último `next` atinge o comportamento próprio de Claude Code. O primeiro mod é o mais externo: vê o evento antes dos outros e o resultado após eles, e decide se os outros são executados. Um mod posterior não pode impedir que um anterior veja um evento.

285 

286Claude Code ordena a cadeia por onde cada mod vem:

287 

2881. O guard integrado `sec-default@builtin`, um mod integrado em Claude Code que `/plugin` lista como `cc-plugin-sec-default`, onde [ele carrega](/docs/pt/plugins/mods/admin#know-what-happens-by-default), mods que sua organização lista em [`prependPlugins`](/docs/pt/plugins/mods/admin#install-your-organizations-mods) e depois qualquer outro mod que conta como de sua organização e não está em `appendPlugins`

2892. Mods que você instala

2903. Mods que sua organização lista em `appendPlugins`

2914. Outros mods integrados em Claude Code

292 

293Entre os mods que você instala, um mod é executado antes dos mods que lista em `dependencies` em seu manifesto. Dentro de um módulo, hooks são executados na ordem em que `register` chamou `on`.

294 

295<h4 id="where-settings-hooks-run-in-the-order">

296 Onde hooks de configurações são executados na ordem

297</h4>

298 

299Os hooks `PreToolUse` configurados em arquivos de configurações também são executados durante uma chamada de ferramenta, em pontos fixos na cadeia de mods:

300 

301* **Hooks `PreToolUse` de configurações gerenciadas**: são executados antes do hook `tool.call` do primeiro mod, e um bloqueio de um deles é final, portanto nenhum mod vê a chamada.

302* **Hooks `PreToolUse` de cada outro arquivo de configurações e de `hooks/hooks.json` de plugins**: são executados após o último mod chamar `next`, como parte do comportamento próprio de Claude Code. Um mod que responde `tool.call` sem chamar `next` os impede de serem executados, e um mod que chama `next` vê sua decisão no resultado que retorna.

303 

304[`tool.check`](/docs/pt/plugins/mods/reference#tools) é o evento onde Claude Code decide se uma chamada de ferramenta pode ser executada. Dispara após esses hooks e as regras de permissão terem decidido, e `next(e)` é resolvido para sua decisão. Um hook em `tool.check` pode retornar uma decisão diferente, como `{ decision: 'allow' }`, portanto pode aprovar uma chamada que um hook no segundo grupo bloqueou. [Estenda permissões com hooks](/docs/pt/permissions#extend-permissions-with-hooks) lista quais decisões prevalecem sobre um mod.

305 

306<h3 id="handle-a-hook-that-fails">

307 Manipule um hook que falha

308</h3>

309 

310Um hook que falha não quebra a sessão e você pode decidir o que acontece em seu lugar. Quando um hook sem um manipulador `.catch` lança, expira ou retorna um resultado da forma errada, o que acontece a seguir depende se ele tinha chamado `next`:

311 

312* **Falhou antes de chamar `next`**: Claude Code o pula e o próximo manipulador é executado em seu lugar

313* **Falhou após `next` ser resolvido**: esse resultado permanece e nada é executado uma segunda vez

314 

315Uma linha nomeia o mod, o evento e o motivo, como `my-mod: tool.call hook skipped: threw Error: boom`. Onde você o lê depende da sessão, como [Descubra por que um mod não faz nada](/docs/pt/plugins/mods/troubleshoot#find-out-why-a-mod-does-nothing) lista. Um hook `ui.render` cujo desenho não valida é relatado diferentemente, como [Construa uma árvore a partir de elementos](/docs/pt/plugins/mods/interface#build-a-tree-from-elements) descreve.

316 

317Para fazer um hook que bloqueia chamadas falhar fechado, adicione um manipulador de erro `.catch` que responda em seu lugar. Aqui, `guard` é sua função de hook:

318 

319```javascript theme={null}

320// on retorna um registro e .catch anexa um manipulador a esse hook

321on('tool.call', { tool: 'Bash' }, guard).catch(async ($, e, next) => {

322 // next.error.kind é 'throw' ou 'timeout', que diz como guard falhou

323 return { deny: 'The command guard failed, so this command was not run: ' + next.error.kind }

324})

325```

326 

327Enquanto `guard` funciona, o manipulador nunca é executado. Quando `guard` lança ou expira em uma chamada Bash, Claude Code chama o manipulador com o mesmo evento. O manipulador retorna `{ deny }`, portanto o comando não é executado e Claude lê o texto com `throw` ou `timeout` no final. Sem o manipulador, Claude Code pularia `guard` e executaria o comando. O manipulador tem [um segundo](/docs/pt/plugins/mods/reference#limits) para responder.

328 

329<h2 id="next-steps">

330 Próximos passos

331</h2>

332 

333* [Use a API de mods](/docs/pt/plugins/mods/api): adicione comandos e ferramentas, chame um modelo e execute trabalho em um temporizador

334* [Desenhe na interface](/docs/pt/plugins/mods/interface): mostre o que seus hooks coletam em um painel ou acima do prompt

335* [Teste um mod](/docs/pt/plugins/mods/test): levante qualquer um desses eventos de um teste

336* [Referência de mods](/docs/pt/plugins/mods/reference): cada evento, cada método de API de mods e os limites

plugins/mods/interface.md +867 −0 created

Details

1> ## Documentation Index

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

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

4 

5# Desenhar na interface com um mod

6 

7> Desenhe painéis, uma faixa acima do prompt, botões e campos de texto a partir de um mod Claude Code, manipule pressionamentos e entrada, e mantenha o estado entre redesenhos e sessões.

8 

9Um mod pode desenhar sua própria interface no Claude Code e alterar partes da interface que o Claude Code já desenha. Cada lugar onde um mod pode desenhar é chamado de [site de renderização](/docs/pt/plugins/mods/reference#render-sites), como um painel, a faixa acima do prompt ou o spinner. O Claude Code dispara o evento [`ui.render`](/docs/pt/plugins/mods/reference#interface) cada vez que está prestes a desenhar um site de renderização, e seu hook para esse evento retorna o que desenhar lá.

10 

11Este mapa mostra onde um mod pode desenhar em uma sessão de terminal:

12 

13<img src="https://mintcdn.com/claude-code/dgiVO_Od1X1faduV/images/mods-screen-map.svg?fit=max&auto=format&n=dgiVO_Od1X1faduV&q=85&s=5fda26b6609c62b68c6f9e528c1590ea" className="dark:hidden" alt="Mapa de uma sessão de terminal Claude Code. Um mod pode adicionar um painel como uma barra lateral à direita, um toast no canto superior direito da transcrição, uma linha de log na transcrição, uma faixa acima do prompt e uma linha de status sob o prompt. Um mod pode redesenhar mensagens, linhas de chamada de ferramenta e o spinner. O prompt é do próprio Claude Code." width="600" height="336" data-path="images/mods-screen-map.svg" />

14 

15<img src="https://mintcdn.com/claude-code/dgiVO_Od1X1faduV/images/mods-screen-map-dark.svg?fit=max&auto=format&n=dgiVO_Od1X1faduV&q=85&s=5b4161581a1bd2c0450b0c8b57bc1225" className="hidden dark:block" alt="Mapa de uma sessão de terminal Claude Code. Um mod pode adicionar um painel como uma barra lateral à direita, um toast no canto superior direito da transcrição, uma linha de log na transcrição, uma faixa acima do prompt e uma linha de status sob o prompt. Um mod pode redesenhar mensagens, linhas de chamada de ferramenta e o spinner. O prompt é do próprio Claude Code." width="600" height="336" data-path="images/mods-screen-map-dark.svg" />

16 

17Em um terminal mais estreito, o painel fica acima do prompt em vez de ao lado da transcrição.

18 

19Construa seu [primeiro mod](/docs/pt/plugins/mods/create) antes de começar aqui. Comece com o exemplo trabalhado, que constrói um painel com duas abas e um contador, depois leia a seção para cada parte que você deseja alterar.

20 

21<Note>

22 Para procurar uma propriedade ou limite, consulte a [referência](/docs/pt/plugins/mods/reference#render-sites).

23</Note>

24 

25<h2 id="build-a-pane-with-tabs">

26 Construir um painel com abas

27</h2>

28 

29Nesta seção você constrói um mod que adiciona um comando `/hello-tabs` e o comando abre um painel. Um painel é uma barra lateral ao lado da transcrição em um terminal fullscreen amplo, ou uma região enquadrada acima do prompt caso contrário. Este painel mostra duas abas, e a segunda aba tem um botão que adiciona um ao contador. A contagem ainda está lá depois que você reinicia o Claude Code.

30 

31O mod finalizado se parece com isto. A gravação abre o painel, muda para a segunda aba, pressiona o botão algumas vezes e retorna à primeira aba:

32 

33<Frame>

34 <video autoPlay muted loop playsInline controls className="w-full dark:hidden" src="https://mintcdn.com/claude-code/dgiVO_Od1X1faduV/images/mods-hello-tabs-light.mp4?fit=max&auto=format&n=dgiVO_Od1X1faduV&q=85&s=49d520094d87b5b44bfe50fa49677f06" aria-label="O comando /hello-tabs é digitado no prompt Claude Code e um painel enquadrado abre acima dele, com '1: One' e '2: Two' na parte superior e o texto 'This is the first tab.' A segunda aba mostra um botão 'Add one' ao lado de 'Count: 1', e a contagem sobe para 3. O painel então retorna à primeira aba." data-path="images/mods-hello-tabs-light.mp4" />

35 

36 <video autoPlay muted loop playsInline controls className="w-full hidden dark:block" src="https://mintcdn.com/claude-code/dgiVO_Od1X1faduV/images/mods-hello-tabs-dark.mp4?fit=max&auto=format&n=dgiVO_Od1X1faduV&q=85&s=ff7a14d713d6e5d3b0000efa8522ea4b" aria-label="O comando /hello-tabs é digitado no prompt Claude Code e um painel enquadrado abre acima dele, com '1: One' e '2: Two' na parte superior e o texto 'This is the first tab.' A segunda aba mostra um botão 'Add one' ao lado de 'Count: 1', e a contagem sobe para 3. O painel então retorna à primeira aba." data-path="images/mods-hello-tabs-dark.mp4" />

37</Frame>

38 

39O Claude Code não tem um elemento de abas integrado, então as abas são dois botões em uma linha. O mod acompanha qual está ativo e desenha o conteúdo dessa aba sob a linha.

40 

41<Steps>

42 <Step title="Criar o plugin">

43 Um mod é um plugin com um manifesto, um `hooks.json` que aponta para seu código, e o arquivo de código. [Criar um mod](/docs/pt/plugins/mods/create#write-a-mod-yourself) explica cada um. Crie um diretório chamado `hello-tabs` com diretórios `.claude-plugin` e `hooks` dentro dele, depois salve os dois primeiros arquivos.

44 

45 Salve o manifesto como `hello-tabs/.claude-plugin/plugin.json`:

46 

47 ```json hello-tabs/.claude-plugin/plugin.json theme={null}

48 {

49 "name": "hello-tabs",

50 "version": "0.1.0",

51 "description": "Opens a pane with two tabs and a counter",

52 "author": { "name": "Your Name" }

53 }

54 ```

55 

56 Nomeie seu ponto de entrada em `hello-tabs/hooks/hooks.json`:

57 

58 ```json hello-tabs/hooks/hooks.json theme={null}

59 {

60 "modules": ["./register.js"]

61 }

62 ```

63 </Step>

64 

65 <Step title="Escrever o código">

66 O código faz três trabalhos, um em cada hook:

67 

68 * Adiciona o comando `/hello-tabs`

69 * Abre o painel quando você executa esse comando

70 * Desenha o conteúdo do painel: a linha de abas e o corpo da aba aberta

71 

72 Duas variáveis no nível do módulo, `tab` e `count`, mantêm o estado do painel.

73 

74 Salve isto como `hello-tabs/hooks/register.js`:

75 

76 ```javascript hello-tabs/hooks/register.js theme={null}

77 // The pane's id, used to open the pane and to recognize it when drawing

78 const PANE = 'hello-tabs'

79 

80 // What the pane shows: which tab is open, and the counter's value

81 let tab = 'one'

82 let count = 0

83 

84 export function register(on) {

85 // Runs before your first prompt, and again after a reload

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

87 await $.command.register({ name: 'hello-tabs', description: 'Open the hello-tabs pane' })

88 // Load the count an earlier session saved, if there is one

89 const saved = await $.store.get('count')

90 if (typeof saved === 'number') count = saved

91 return next(e)

92 })

93 

94 // Runs when you type /hello-tabs

95 on('command.run', { command: 'hello-tabs' }, async ($) => {

96 // Open the pane, give it the keyboard, and let Esc close it

97 await $.ui.open({ id: PANE, title: 'Hello tabs', focus: true, closeOnEscape: true })

98 // Print nothing in the transcript

99 return {}

100 })

101 

102 // Runs each time Claude Code draws a pane

103 on('ui.render', { component: 'Pane' }, async ($, e, next) => {

104 // Leave other mods' panes alone

105 if (e.requestId !== PANE) return next(e)

106 // Get the elements this app can draw

107 const { Box, Text, Button } = $.ui.resolve(e)

108 // Ask Claude Code to run this hook again

109 const redraw = () => $.ui.invalidate('ui.render')

110 

111 // One tab: a button that switches to its tab when pressed

112 const tabButton = (name, label, hotkey) =>

113 Button({

114 key: 'tab-' + name,

115 label,

116 hotkey,

117 plain: true,

118 // Dim the tab that isn't open

119 dimColor: tab !== name,

120 onPress: () => {

121 tab = name

122 redraw()

123 },

124 })

125 

126 // What goes under the tabs, depending on which one is open

127 const body =

128 tab === 'one'

129 ? [Text({ children: ['This is the first tab.'] })]

130 : [

131 Box({

132 flexDirection: 'row',

133 columnGap: 2,

134 children: [

135 Button({

136 key: 'more',

137 label: 'Add one',

138 hotkey: 'a',

139 onPress: async () => {

140 count += 1

141 redraw()

142 // Save the count so it's there after a restart

143 await $.store.set('count', count)

144 },

145 }),

146 Text({ children: ['Count: ' + count] }),

147 ],

148 }),

149 ]

150 

151 // The whole pane: the row of tabs, a blank line, then the body

152 return Box({

153 flexDirection: 'column',

154 children: [

155 Box({

156 flexDirection: 'row',

157 columnGap: 3,

158 children: [tabButton('one', 'One', '1'), tabButton('two', 'Two', '2')],

159 }),

160 Text({ children: [' '] }),

161 ...body,

162 ],

163 })

164 })

165 }

166 ```

167 

168 Cada hook também faz algo que o código não deixa claro:

169 

170 * **[`session.start`](/docs/pt/plugins/mods/reference#session)** também lê a contagem salva de [`$.store`](#keep-state), um armazenamento de chave-valor que persiste entre sessões.

171 * **[`command.run`](/docs/pt/plugins/mods/api#add-a-command)** apenas diz ao Claude Code que o painel existe. Abrir um painel não desenha nada por si só: o Claude Code então dispara `ui.render` para perguntar o que colocar nele.

172 * **`ui.render`** retorna a árvore de elementos, uma `Box` que contém outras caixas, texto e botões, e a constrói novamente a partir de `tab` e `count` cada vez que é executada.

173 

174 Pressionar um botão executa seu callback `onPress`, que altera uma variável e chama `redraw`. O Claude Code então executa o hook `ui.render` novamente, e o hook constrói uma nova árvore a partir dos novos valores. Cada desenho interativo usa esse ciclo de renderização: um callback altera o estado e o hook renderiza novamente a partir do novo estado.

175 </Step>

176 

177 <Step title="Abrir o painel">

178 Em seu shell, inicie o Claude Code com `claude --plugin-dir ./hello-tabs`. No prompt Claude Code, execute `/hello-tabs`. Um painel abre com `1: One` e `2: Two` na parte superior. Pressione `2`, depois pressione `a`, o atalho de teclado para **Add one**, algumas vezes. A contagem sobe.

179 </Step>

180 

181 <Step title="Verificar se a contagem foi salva">

182 Pressione Esc para fechar o painel, depois saia da sessão. Em seu shell, inicie o Claude Code novamente com o mesmo comando `claude --plugin-dir ./hello-tabs` e no prompt Claude Code execute `/hello-tabs`. A contagem está onde você a deixou.

183 

184 Para limpar a contagem, faça o mod chamar `$.store.delete('count')`. [Manter estado](#keep-state) cobre quanto tempo cada tipo de valor dura.

185 </Step>

186</Steps>

187 

188<h2 id="pick-where-to-draw">

189 Escolher onde desenhar

190</h2>

191 

192Um hook `ui.render` é executado para cada site de renderização a menos que você o restrinja ao que deseja desenhar. Para escolher o site de renderização, passe um filtro, chamado de [matcher](/docs/pt/plugins/mods/events#filter-which-events-a-hook-handles), como o segundo argumento para `on`. `{ component: 'Pane' }` executa o hook apenas para painéis. No hook, `e.component` nomeia o site, `e.surface` diz qual app está desenhando, e `e.props` contém os dados do próprio site. Para um painel, `e.requestId` é o `id` que você abriu com.

193 

194Dois sites estão vazios até um mod preenchê-los, o painel e a faixa. Selecione uma aba para ver o que cada um é e como desenhar nele:

195 

196<Tabs>

197 <Tab title="Pane">

198 Um painel é uma barra lateral ao lado da transcrição em um terminal fullscreen amplo, ou uma região enquadrada acima do prompt caso contrário. Com vários painéis abertos, cada um recebe uma aba que mostra seu título.

199 

200 Um painel aparece quando seu mod chama `$.ui.open` com um `id` que você escolhe, como em `$.ui.open({ id: 'hello-tabs' })`. [Abrir um painel no momento certo](#open-a-pane-at-the-right-time) cobre os outros campos e quando um painel espera por um terminal mais amplo.

201 

202 Para desenhar em seu painel, filtre em `{ component: 'Pane' }` e verifique se `e.requestId` é seu `id`.

203 </Tab>

204 

205 <Tab title="Band above the prompt">

206 A faixa é uma tira diretamente acima da entrada do prompt. Ela está sempre lá, e cada mod a compartilha.

207 

208 Seu hook retorna uma árvore para mostrar algo na faixa, ou `next(e)` para não mostrar nada. Uma árvore substitui o que os mods [depois do seu](/docs/pt/plugins/mods/events#the-order-mods-run-in) desenham lá. Para manter o deles, coloque o resultado de `await next(e)` entre os filhos de uma [`Box`](#build-a-tree-from-elements) em sua árvore.

209 

210 Para desenhar na faixa, filtre em `{ component: 'AbovePrompt' }`.

211 </Tab>

212</Tabs>

213 

214<h3 id="change-what-claude-code-already-draws">

215 Alterar o que o Claude Code já desenha

216</h3>

217 

218O Claude Code desenha a maior parte de sua interface por si só: mensagens, linhas de chamada de ferramenta, o spinner e muito mais. Cada uma dessas partes é um site de renderização também, então um mod pode restylar ou substituí-la. Para alterar uma, filtre seu hook `ui.render` em seu nome desta tabela:

219 

220| Site | O que é |

221| :- | :- |

222| `UserMessage`, `AssistantMessage` | Uma mensagem na transcrição |

223| `ToolUse`, `ToolResult`, `ToolGroup` | A linha de uma chamada de ferramenta, seu resultado e uma execução dobrada de chamadas |

224| `CommandOutput` | A linha que um comando imprimiu |

225| `AskUserQuestion` | O diálogo que o Claude abre para fazer uma pergunta a você |

226| `Spinner`, `ToolProgress`, `TurnDuration` | Linhas de status para uma volta: a linha que anima enquanto o Claude trabalha, a linha de progresso ao vivo de uma ferramenta em execução e a linha que fecha uma volta |

227| `InfoNotice`, `SessionMode`, `PromptHint` | Linhas de status sob o logo, os rótulos de modo no rodapé e a linha de dica sob o prompt |

228 

229Em um site que o Claude Code já desenha, seu hook tem três escolhas: alterar um detalhe, substituir o desenho ou deixá-lo em paz. Selecione uma aba para ver cada um aplicado ao spinner. Os exemplos leem uma variável `calls` que outro hook conta, como no [mod do tutorial](/docs/pt/plugins/mods/create#write-a-mod-yourself).

230 

231<Tabs>

232 <Tab title="Change a detail">

233 Para manter o desenho do Claude Code e alterar uma parte dele, passe para `next` uma cópia do evento com `props` alteradas. Este hook altera o texto após a palavra do spinner:

234 

235 ```javascript theme={null}

236 on('ui.render', { component: 'Spinner' }, async ($, e, next) => {

237 // Keep Claude Code's spinner, and change the text after its word

238 return next({ ...e, props: { ...e.props, suffix: ' · tool calls: ' + calls + '…' } })

239 })

240 ```

241 

242 O spinner mantém sua animação e sua palavra, e seu texto segue a palavra:

243 

244 ```text theme={null}

245 Thinking · tool calls: 2…

246 ```

247 </Tab>

248 

249 <Tab title="Replace the drawing">

250 Para desenhar algo do seu próprio no lugar do site, retorne uma árvore e não chame `next`. Este hook desenha uma linha de texto onde o spinner seria:

251 

252 ```javascript theme={null}

253 on('ui.render', { component: 'Spinner' }, async ($, e) => {

254 const { Text } = $.ui.resolve(e)

255 // No call to next, so this line is drawn in the spinner's place

256 return Text({ children: ['Claude has made ' + calls + ' tool calls'] })

257 })

258 ```

259 

260 Enquanto o Claude trabalha, sua linha mostra e o spinner do Claude Code não:

261 

262 ```text theme={null}

263 Claude has made 2 tool calls

264 ```

265 </Tab>

266 

267 <Tab title="Leave it alone">

268 Para deixar o site como o Claude Code o desenha, retorne `next(e)`. Um hook frequentemente faz isso para alguns eventos e não para outros. Este hook deixa o spinner em paz até haver uma chamada para contar:

269 

270 ```javascript theme={null}

271 on('ui.render', { component: 'Spinner' }, async ($, e, next) => {

272 // Nothing to show yet, so pass the event on unchanged

273 if (calls === 0) return next(e)

274 return next({ ...e, props: { ...e.props, suffix: ' · tool calls: ' + calls + '…' } })

275 })

276 ```

277 

278 Antes da primeira chamada de ferramenta, o spinner se parece com a forma como é sem o mod:

279 

280 ```text theme={null}

281 Thinking…

282 ```

283 </Tab>

284</Tabs>

285 

286O prompt de permissão não é um site de renderização, então um mod não pode alterar o que mostra. O diálogo de pergunta, `AskUserQuestion`, é um, então um mod pode alterar isso.

287 

288O terminal e o app Desktop não disparam todos os mesmos sites. `Pane`, `AbovePrompt`, `Spinner` e os sites de transcrição funcionam em ambos. Algumas outras linhas de status são disparadas apenas no terminal. A [tabela de sites de renderização](/docs/pt/plugins/mods/reference#render-sites) lista onde cada um é disparado.

289 

290<h3 id="open-a-pane-at-the-right-time">

291 Abrir um painel no momento certo

292</h3>

293 

294Um painel aparece apenas quando seu mod o abre. Como e quando você o abre decide se ele toma o foco do teclado, quanto espaço ele pede e se aparece em um terminal estreito.

295 

296Para abrir um painel, chame [`$.ui.open`](/docs/pt/plugins/mods/reference#mods-api-methods) com um `id` que você escolhe. O `id` é o nome do painel: seu hook `ui.render` verifica, e você o passa novamente para fechar o painel.

297 

298```javascript theme={null}

299await $.ui.open({ id: 'hello-tabs', title: 'Hello tabs', focus: true })

300```

301 

302Para fechar o painel, chame `$.ui.close` com o `id` que você abriu com:

303 

304```javascript theme={null}

305await $.ui.close({ id: 'hello-tabs' })

306```

307 

308Além de `id`, `$.ui.open` leva estes campos opcionais:

309 

310| Campo | O que faz |

311| :- | :- |

312| `title` | O rótulo da aba do painel quando mais de um painel está aberto |

313| `focus` | Solicita [foco do teclado](#know-which-keys-your-mod-can-receive) |

314| `closeOnEscape` | Faz Esc fechar o painel. Passe `true` ou deixe o campo de fora, porque o Claude Code recusa `false`. |

315| `holdToasts` | Mantém toasts, os pequenos avisos de [`$.ui.toast`](/docs/pt/plugins/mods/api#show-something-without-starting-a-turn), até o painel fechar |

316| `rows` | A altura para pedir quando o painel fica acima do prompt. O padrão é um terço do espaço. |

317| `columns` | A largura para pedir quando o painel fica ao lado da transcrição |

318 

319Para deixar um comando abrir o painel enquanto o Claude está trabalhando, adicione `immediate: true` quando você [registra o comando](/docs/pt/plugins/mods/api#add-a-command). Sem isso, um comando digitado durante uma volta espera a volta terminar.

320 

321<h4 id="when-a-pane-waits-for-a-wider-terminal">

322 Quando um painel espera por um terminal mais amplo

323</h4>

324 

325Um painel que seu mod abre sem ser solicitado não aparece em um terminal estreito, então não pode assumir uma tela pequena. Se aparece depende do que o abriu:

326 

327* **Aberto por algo que o usuário fez**, como um comando que executou ou um botão que pressionou, o painel aparece em qualquer largura

328* **Aberto por seu mod agindo por si só**, como de um timer ou um hook [`turn.start`](/docs/pt/plugins/mods/events#follow-a-turn), o painel aparece apenas em um terminal com pelo menos 144 colunas de largura. Depois que o usuário abriu esse painel uma vez por si só, 110 colunas é suficiente.

329 

330Quando o painel aparece, `$.ui.open` resolve para `{ isPlaced: true }`. Quando o painel está esperando, `isPlaced` é `false` e `reason` é uma string que diz por quê. Um painel esperando aparece quando o usuário o abre ou amplia o terminal. Para dizer que algo está disponível sem abrir um painel, chame `$.ui.toast('Your message')`, que mostra um pequeno aviso que desaparece após alguns segundos.

331 

332<h2 id="build-a-tree-from-elements">

333 Construir uma árvore a partir de elementos

334</h2>

335 

336O que um hook `ui.render` retorna é uma árvore de elementos: uma descrição do que desenhar, feita de caixas, texto e controles aninhados um dentro do outro. Você descreve o desenho, e o Claude Code o renderiza no terminal ou no app Desktop.

337 

338Para obter os elementos, chame `$.ui.resolve(e)` em seu hook, como em `const { Box, Text, Button } = $.ui.resolve(e)`. Cada elemento é uma função. Você passa propriedades para ela, e coloca os elementos e strings que vão dentro dela em `children`.

339 

340A maioria dos desenhos usa quatro elementos. Selecione uma aba para ver cada um e como o terminal o desenha:

341 

342<Tabs>

343 <Tab title="Text">

344 `Text` desenha uma string, com estilo opcional como `bold` e `color`:

345 

346 ```javascript theme={null}

347 Text({ children: ['This is the first tab.'] })

348 ```

349 

350 ```text theme={null}

351 This is the first tab.

352 ```

353 </Tab>

354 

355 <Tab title="Box">

356 `Box` organiza o que está dentro dela, em uma linha ou uma coluna. Esta coloca um botão e uma linha de texto lado a lado, duas colunas separadas:

357 

358 ```javascript theme={null}

359 Box({

360 flexDirection: 'row',

361 columnGap: 2,

362 children: [

363 Button({ key: 'more', label: 'Add one', onPress: addOne }),

364 Text({ children: ['Count: 0'] }),

365 ],

366 })

367 ```

368 

369 ```text theme={null}

370 [ Add one ] Count: 0

371 ```

372 </Tab>

373 

374 <Tab title="Button">

375 `Button` é um controle que o usuário pode pressionar. Ele executa seu callback `onPress`. Com `plain: true` não tem colchetes e mostra seu atalho de teclado:

376 

377 ```javascript theme={null}

378 Button({ key: 'more', label: 'Add one', onPress: addOne })

379 Button({ key: 'tab-one', label: 'One', hotkey: '1', plain: true, onPress: showTabOne })

380 ```

381 

382 ```text theme={null}

383 [ Add one ]

384 1: One

385 ```

386 </Tab>

387 

388 <Tab title="Input">

389 `Input` é um campo de texto. Ele executa seu callback `onSubmit` com o texto quando o usuário pressiona Enter:

390 

391 ```javascript theme={null}

392 Input({

393 key: 'new-note',

394 label: 'Note',

395 placeholder: 'Type a note and press Enter',

396 value: '',

397 submitLabel: 'add',

398 onSubmit: addNote,

399 })

400 ```

401 

402 ```text theme={null}

403 Note: Type a note and press Enter ⏎ add

404 ```

405 </Tab>

406</Tabs>

407 

408Esta tabela lista cada elemento:

409 

410| Elemento | O que desenha | Onde |

411| :- | :- | :- |

412| `Box` | Um contêiner flex. Leva propriedades de layout como `flexDirection`, `columnGap`, `padding`, `borderStyle` e `width`. | Em todos os lugares |

413| `Text` | Texto estilizado. Leva `color`, `bold`, `dimColor`, `italic` e `wrap`. Uma `color` é uma chave de tema ou uma cor como `'red'`. Um `wrap` é `'wrap'`, `'truncate'`, `'truncate-start'`, `'truncate-middle'` ou `'truncate-end'`. | Em todos os lugares |

414| `Button` | Um controle que chama `onPress` | Em todos os lugares |

415| `Link`, `Code`, `Markdown` | Um link com `href` e um `label` opcional, um bloco de código e texto formatado da forma que as respostas do Claude são. `Markdown` leva seu conteúdo em uma propriedade `text`, não em `children`, e precisa de uma `key` quando você passa `onLinkPress`. | Em todos os lugares |

416| `Input`, `Select` | Um campo de texto e um seletor | Terminal, Desktop |

417| `Svg` | Um documento SVG | Desktop |

418| `Client` | Uma região desenhada por um segundo arquivo seu, para animação e entrada de ponteiro. Esse arquivo não recebe API de mods. Ele alcança seus hooks apenas postando dados, que chegam como um evento `ui.message`. | Terminal, Desktop |

419| `Raster`, `Image` | Uma [grade de células coloridas](#draw-a-grid-of-colored-cells) e uma imagem | Terminal |

420 

421Se seu módulo é um arquivo `.tsx` ou `.jsx`, você pode escrever a árvore como JSX. Desestruture os elementos de `$.ui.resolve(e)` primeiro, porque um módulo de hooks não tem globais de elementos.

422 

423Se uma árvore usa um elemento que o app não tem, uma propriedade que um elemento não leva, ou um filho onde nenhum vai, o Claude Code desenha sua própria versão do site.

424 

425Em uma sessão iniciada com `--plugin-dir`, uma linha de transcrição diz assim, como `ui.render (Pane) refused: Text prop "bogusProp" is not allowed; the engine drew its own`. O [log de depuração](/docs/pt/plugins/mods/troubleshoot#read-the-debug-log) registra como `ui.render (Pane): a hook returned a tree that does not validate` com a mesma razão. Nada mais aparece na sessão, então quando um desenho não aparece, verifique essa linha ou o log.

426 

427<h3 id="draw-a-grid-of-colored-cells">

428 Desenhar uma grade de células coloridas

429</h3>

430 

431Para um mapa de calor, um sparkline ou um tabuleiro de jogo no terminal, desenhe um `Raster` e não uma `Box` para cada célula. Um `Raster` leva uma `key`, seu tamanho em `columns` e `rows`, e `cells`, que empacota cada célula em uma string. Cada célula é três números: o ponto de código do caractere, sua cor e sua cor de fundo. Uma cor é um número hexadecimal com dois dígitos cada para vermelho, verde e azul, como `0xc62828` para um vermelho, ou `0x01000000` para o padrão do terminal.

432 

433O app Desktop não tem `Raster`, então verifique `e.surface` e desenhe texto lá. Este corpo de painel desenha um mapa de calor de três por dois:

434 

435```javascript theme={null}

436// The value that means "use the terminal's default color"

437const DEFAULT_COLOR = 0x01000000

438 

439// Pack rows of [character, color] pairs into the one string a Raster takes

440// One cell is three numbers: the character's code point, its color, and its background

441function cellsOf(rows) {

442 const numbers = rows.flat().flatMap(([char, color]) => [char.codePointAt(0), color, DEFAULT_COLOR])

443 return new Uint8Array(Uint32Array.from(numbers).buffer).toBase64()

444}

445 

446on('ui.render', { component: 'Pane' }, async ($, e, next) => {

447 // Draw only in the pane opened with the id 'heat'

448 if (e.requestId !== 'heat') return next(e)

449 const { Box, Text, Raster } = $.ui.resolve(e)

450 // Two rows of three cells, each a block character and its color

451 const rows = [

452 [['█', 0x2e7d32], ['█', 0xf9a825], ['█', 0xc62828]],

453 [['█', 0x2e7d32], ['█', 0x2e7d32], ['█', 0xf9a825]],

454 ]

455 if (e.surface !== 'terminal') {

456 return Text({ children: ['The heat map needs the terminal.'] })

457 }

458 return Box({

459 flexDirection: 'column',

460 children: [Raster({ key: 'grid', columns: 3, rows: 2, cells: cellsOf(rows) })],

461 })

462})

463```

464 

465No terminal, o painel mostra a grade:

466 

467<img src="https://mintcdn.com/claude-code/dgiVO_Od1X1faduV/images/mods-heat-map.svg?fit=max&auto=format&n=dgiVO_Od1X1faduV&q=85&s=b91bcce3bad74bc851149133d4acc5d5" alt="Um painel no terminal que contém uma pequena grade de blocos coloridos, duas linhas de três. A linha superior é verde, âmbar e vermelho. A linha inferior é verde, verde e âmbar." width="360" height="132" data-path="images/mods-heat-map.svg" />

468 

469O array `rows` é a parte que você alteraria, e `cellsOf` a transforma na string empacotada. O hook desenha apenas em um painel cujo `id` é `heat`, então abra um com `$.ui.open({ id: 'heat' })` de um comando, como o exemplo [`hello-tabs`](#build-a-pane-with-tabs) abre seu painel.

470 

471Cada caractere tem que ser uma célula de largura. Para animar um `Raster` que já está na tela, chame `$.ui.blit` com o `id` do painel como `requestId`, a `key` do `Raster`, o mesmo tamanho e novas células. Para este exemplo, é `$.ui.blit({ requestId: 'heat', key: 'grid', columns: 3, rows: 2, cells: cellsOf(newRows) })`. Ele repinta apenas esse elemento sem executar seu hook `ui.render` novamente.

472 

473<h2 id="respond-to-presses-and-typing">

474 Responder a pressionamentos e digitação

475</h2>

476 

477Quando o usuário pressiona um botão, digita em um campo ou escolhe de uma lista que seu mod desenhou, o Claude Code chama a função que você deu a esse controle, e ela é executada em seu módulo. Cada controle leva seus próprios callbacks:

478 

479* **`Button`**: leva `onPress(e)`, onde `e.surface` é o app de onde veio o pressionamento

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

481* **`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' }]`

482 

483Um 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`](/docs/pt/plugins/mods/reference#interface) com a `key` em `e.element`, e outro mod pode fazer hook nesses 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.

484 

485<h3 id="know-which-keys-your-mod-can-receive">

486 Foco do teclado e atalhos de teclado

487</h3>

488 

489Seu mod nunca lê o teclado por si só. O usuário pressiona uma tecla, o Claude Code decide qual de seus controles é para, e o callback desse controle é executado. Além de um [atalho de teclado de dígito na faixa](/docs/pt/plugins/mods/reference#elements), isso acontece apenas enquanto seu painel ou faixa tem foco do teclado. O resto do tempo, as teclas vão para o prompt.

490 

491<h4 id="how-a-pane-gets-keyboard-focus">

492 Como um painel obtém foco do teclado

493</h4>

494 

495Um painel obtém foco do teclado de uma de três maneiras:

496 

497* Seu mod o abre com `focus: true` de um comando ou um pressionamento

498* O usuário pressiona Ctrl+X depois Tab

499* O usuário clica nele

500 

501O Claude Code concede `focus: true` apenas enquanto o prompt está vazio e nada mais tem foco do teclado. Um painel que abre enquanto o usuário está digitando não toma seus pressionamentos de tecla.

502 

503<h4 id="what-each-key-does">

504 O que cada tecla faz

505</h4>

506 

507Esta tabela lista o que uma tecla faz enquanto seu painel ou faixa tem foco do teclado:

508 

509| Tecla | O que faz |

510| :- | :- |

511| Tab | Move para o próximo controle |

512| Para cima e Para baixo | Movem entre controles enquanto seu desenho cabe. Quando o painel ou faixa tem mais linhas do que pode mostrar, eles o rolam. |

513| Enter | Pressiona o `Button` focado, envia o `Input` focado ou escolhe em um `Select` |

514| Atalho de teclado de um botão | Pressiona esse botão. Enquanto um `Input` tem o foco, cada tecla imprimível vai para o campo. |

515| Esc | Retorna o foco do teclado para o prompt. Com `closeOnEscape: true`, também fecha o painel. |

516 

517Um mod não pode vincular Tab ou as setas para nada mais, então um jogo direciona com `w`, `a`, `s` e `d`.

518 

519<h4 id="set-a-hotkey-and-the-first-focus">

520 Definir um atalho de teclado e o primeiro foco

521</h4>

522 

523Duas propriedades em um controle decidem como o teclado o alcança:

524 

525* **`hotkey`**: para deixar o usuário pressionar um `Button` com uma tecla, dê a ele um `hotkey` de um dígito ou uma letra minúscula, como em `hotkey: 'a'`

526* **`autoFocus`**: para escolher qual controle tem o foco quando o painel abre, adicione `autoFocus: true` a ele. Deixe a propriedade de fora dos outros, porque o Claude Code recusa `autoFocus: false`.

527 

528Como um atalho de teclado mostra depende do botão e do app:

529 

530| Botão | No terminal | No app Desktop |

531| :- | :- | :- |

532| Com colchetes, o padrão | `[ Add one ]`, sem atalho de teclado mostrado | O rótulo com uma pequena tecla ao lado |

533| Com `plain: true` | `1: One` | O rótulo com uma pequena tecla ao lado |

534 

535No terminal, nomeie a tecla no rótulo de um botão entre colchetes, ou use `plain: true`, para que o usuário possa ver o que pressionar. A [referência de elementos](/docs/pt/plugins/mods/reference#elements) tem as outras regras de `Button`: `action`, atalhos de teclado de dígito na faixa e dois botões em um atalho de teclado.

536 

537<h3 id="take-typed-input-and-draw-a-row-for-each-item">

538 Tomar entrada digitada e desenhar uma linha para cada item

539</h3>

540 

541Muitos painéis são um campo de texto com uma lista sob ele. O exemplo nesta seção é um painel de notas: você digita uma nota e pressiona Enter para adicioná-la, e cada nota tem um botão `x` que a deleta. Com duas notas adicionadas, o terminal desenha o painel desta forma:

542 

543```text theme={null}

544╭──────────────────────────────────────────────────────────╮

545│ Note: Type a note and press Enter ⏎ add ✕ │

546│ x buy milk │

547│ x call bob │

548╰──────────────────────────────────────────────────────────╯

549```

550 

551O exemplo usa duas técnicas:

552 

553* **Tomar entrada digitada**: um `Input` chama `onSubmit(value)` com o texto do campo quando o usuário pressiona Enter, e `onInput(value)` em cada mudança

554* **Desenhar uma lista**: mapeie seus dados para uma linha cada, e dê a cada botão de linha sua própria `key`

555 

556Este hook desenha o conteúdo do painel:

557 

558```javascript theme={null}

559// The list the pane draws

560let notes = []

561 

562on('ui.render', { component: 'Pane' }, async ($, e, next) => {

563 // Draw only in the pane opened with the id 'notes'

564 if (e.requestId !== 'notes') return next(e)

565 const { Box, Text, Button, Input } = $.ui.resolve(e)

566 const redraw = () => $.ui.invalidate('ui.render')

567 

568 return Box({

569 flexDirection: 'column',

570 children: [

571 Input({

572 key: 'new-note',

573 label: 'Note',

574 placeholder: 'Type a note and press Enter',

575 // Draw the field empty each time, which clears it after a submit

576 value: '',

577 submitLabel: 'add',

578 autoFocus: true,

579 // Runs when you press Enter in the field

580 onSubmit: async (value) => {

581 // Ignore an empty line

582 if (!value.trim()) return

583 notes = [...notes, value.trim()]

584 redraw()

585 await $.store.set('notes', notes)

586 },

587 }),

588 // One row for each note: a delete button, then the note's text

589 ...notes.map((note, i) =>

590 Box({

591 flexDirection: 'row',

592 columnGap: 1,

593 children: [

594 Button({

595 // A key of its own, so each row's button can be told apart

596 key: 'delete-' + i,

597 label: 'x',

598 plain: true,

599 onPress: async () => {

600 notes = notes.filter((_, j) => j !== i)

601 redraw()

602 await $.store.set('notes', notes)

603 },

604 }),

605 Text({ children: [note] }),

606 ],

607 }),

608 ),

609 ],

610 })

611})

612```

613 

614Para tentar o painel:

615 

616* **Adicionar uma nota**: digite uma linha e pressione Enter. A linha aparece como uma nova linha e o campo esvazia.

617* **Deletar uma nota**: pressione Tab até o botão `x` da nota ter o foco, depois pressione Enter. O `x` é o rótulo do botão e não um atalho de teclado, então digitar a letra não o pressiona.

618 

619Cada mudança segue o mesmo ciclo de renderização que `hello-tabs`: o callback altera `notes`, chama `redraw` e salva a lista em `$.store`.

620 

621O campo esvazia após cada envio por causa de sua propriedade `value`. `value` é o texto que o campo contém quando é desenhado, e a digitação do usuário o substitui até seu hook desenhar o campo novamente. O exemplo sempre desenha o campo com `''`.

622 

623O exemplo salva as notas e não as carrega. Para trazê-las de volta na próxima sessão, leia-as em um hook `session.start`, da forma que `hello-tabs` lê `count`.

624 

625Três propriedades compõem a linha do campo, `Note: Type a note and press Enter ⏎ add`:

626 

627| Propriedade | No exemplo | O que é |

628| :- | :- | :- |

629| `label` | `Note` | O texto antes do campo. O terminal desenha `: ` após ele. |

630| `placeholder` | `Type a note and press Enter` | Texto fraco que mostra enquanto o campo está vazio |

631| `submitLabel` | `add` | A palavra após `⏎` que diz o que Enter faz |

632 

633Enviar um `Input` não inicia uma volta a menos que seu callback chame [`$.prompt.submit`](/docs/pt/plugins/mods/api#start-a-turn-from-a-background-job).

634 

635<h2 id="redraw-when-something-changes">

636 Redesenhar um site

637</h2>

638 

639Um desenho é um instantâneo: mostra o que seu hook `ui.render` retornou a última vez que o hook foi executado. Para mostrar algo novo, o hook tem que ser executado novamente. O Claude Code o executa novamente para algumas mudanças, e seu mod pede o resto.

640 

641<h3 id="when-claude-code-redraws-without-being-asked">

642 Quando o Claude Code redesenha sem ser solicitado

643</h3>

644 

645O Claude Code executa seu hook `ui.render` novamente quando as propriedades do site mudam ou a largura do terminal muda. Ele não executa o hook em um timer, e não pode dizer quando uma variável em seu módulo muda.

646 

647<h3 id="redraw-when-your-data-changes">

648 Redesenhar quando seus dados mudam

649</h3>

650 

651Para ter seus sites desenhados novamente após suas próprias mudanças de dados, chame `$.ui.invalidate('ui.render')`. Este painel conta pressionamentos. O callback do botão altera `count`, depois pede um redesenho:

652 

653```javascript theme={null}

654let count = 0

655 

656on('ui.render', { component: 'Pane' }, async ($, e, next) => {

657 if (e.requestId !== 'counter') return next(e)

658 const { Box, Text, Button } = $.ui.resolve(e)

659 return Box({

660 flexDirection: 'row',

661 columnGap: 2,

662 children: [

663 Button({

664 key: 'more',

665 label: 'Add one',

666 onPress: () => {

667 count += 1

668 // The data changed, so ask Claude Code to draw the pane again

669 $.ui.invalidate('ui.render')

670 },

671 }),

672 Text({ children: ['Count: ' + count] }),

673 ],

674 })

675})

676```

677 

678Cada pressionamento levanta o número no painel. O exemplo [`hello-tabs`](#build-a-pane-with-tabs) envolve a mesma chamada em sua função `redraw`.

679 

680Um valor que você mantém em [`$.state`](#keep-a-value-in-\$-state) não precisa da chamada, porque escrever o valor redesenha os sites que o leem.

681 

682<h3 id="redraw-on-a-timer">

683 Redesenhar em um timer

684</h3>

685 

686Para manter um relógio, uma contagem regressiva ou um valor de fora da sessão atual, redesenhe em um cronograma. Inicie um timer no hook `session.start` do módulo. Se o módulo já tiver um, como `hello-tabs` tem, adicione a linha [`$.clock.every`](/docs/pt/plugins/mods/api#run-work-in-the-background) a ele:

687 

688```javascript theme={null}

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

690 // Every 1000 milliseconds, ask Claude Code to draw your sites again

691 $.clock.every(1000, () => $.ui.invalidate('ui.render'))

692 return next(e)

693})

694```

695 

696O Claude Code agora executa seu hook `ui.render` uma vez por segundo. O timer para quando o módulo recarrega, e a nova cópia do módulo inicia o seu próprio.

697 

698<h3 id="how-often-a-site-can-redraw">

699 Com que frequência um site pode redesenhar

700</h3>

701 

702O Claude Code limita com que frequência redesenha um site, então seu mod pode chamar `$.ui.invalidate` com a frequência que seus dados mudam. O painel visível e a faixa têm um limite mais alto do que outros sites, e a [tabela de limites](/docs/pt/plugins/mods/reference#limits) tem os números.

703 

704Chamadas que vêm mais rápido que o limite são combinadas em um redesenho. Esse redesenho executa seu hook uma vez, e o hook lê seus dados como estão naquele momento, então o valor mais recente mostra e os valores no meio não. Uma animação não pode ser executada mais rápido que o limite.

705 

706<h2 id="keep-state">

707 Manter estado

708</h2>

709 

710Um mod tem três lugares para manter um valor, e diferem em quanto tempo o valor dura: até o módulo recarregar, até a sessão terminar ou de uma sessão para a próxima. Escolha por quanto tempo o valor tem que durar:

711 

712| Mantê-lo em | Dura até | Use para |

713| :- | :- | :- |

714| Uma variável no nível do módulo | O módulo recarrega, o que acontece toda vez que você salva um arquivo durante o desenvolvimento | Valores que você pode perder, como `tab` é em `hello-tabs` |

715| `$.state` | A sessão termina, ou o usuário executa `/clear`, `/resume` ou `/branch` | Valores que um desenho depende que devem sobreviver a um recarregamento |

716| `$.store` | Seu mod o deleta, ou nenhuma sessão lê ou escreve o armazenamento por [`cleanupPeriodDays`](/docs/pt/settings-reference#cleanupperioddays). O armazenamento é um armazenamento de chave-valor, salvo como um arquivo JSON do seu próprio plugin sob `~/.claude/plugins/store/`. | Configurações, histórico, qualquer coisa que o usuário espera encontrar na próxima vez |

717 

718`$.store.get(key)` resolve para o valor ou `undefined`, e `$.store.set(key, value)` leva qualquer valor JSON.

719 

720<h3 id="keep-a-value-in-state">

721 Manter um valor em `$.state`

722</h3>

723 

724`$.state` mantém valores pela duração de uma sessão, e redesenha para você. É estado reativo: um hook `ui.render` que lê um valor se inscreve nele, então o Claude Code redesenha esse site cada vez que você escreve o valor, e você não chama `$.ui.invalidate`. Um valor em `$.state` também sobrevive a um recarregamento do módulo, o que uma variável não faz.

725 

726Para configurá-lo, declare seus valores, aponte seu manifesto para a declaração, depois defina e use cada valor. Os exemplos movem o `count` de `hello-tabs` para `$.state`.

727 

728<h4 id="declare-the-values">

729 Declarar os valores

730</h4>

731 

732Declare os valores em um arquivo de tipos. A chave externa é o nome do seu plugin, e cada entrada sob ela é um valor e seu tipo. Salve isto como `hello-tabs/types/index.d.ts`:

733 

734```typescript hello-tabs/types/index.d.ts theme={null}

735declare module 'claude-code' {

736 interface PluginState {

737 'hello-tabs': {

738 tab: 'one' | 'two'

739 count: number

740 }

741 }

742}

743```

744 

745<h4 id="point-the-manifest-at-the-declaration">

746 Apontar o manifesto para a declaração

747</h4>

748 

749Para deixar `claude plugin validate` verificar seu código contra esse arquivo, adicione um campo `types` ao manifesto com seu caminho:

750 

751```json hello-tabs/.claude-plugin/plugin.json theme={null}

752{

753 "name": "hello-tabs",

754 "version": "0.1.0",

755 "description": "Opens a pane with two tabs and a counter",

756 "author": { "name": "Your Name" },

757 "types": "./types/index.d.ts"

758}

759```

760 

761<h4 id="define-read-and-write-a-value">

762 Definir, ler e escrever um valor

763</h4>

764 

765Em seu módulo, defina cada valor com um padrão, leia-o enquanto desenha e escreva-o de um callback. `atom` nomeia um valor e seu padrão, `read` o retorna e `update` o escreve. Os três ajudantes chamam `$.state.get` e `$.state.set` para você:

766 

767```javascript theme={null}

768import { atom, read, update } from 'claude-code'

769 

770// At the top of the module: name the value and give its default

771const count = atom({ plugin: 'hello-tabs', key: 'count' }, 0)

772 

773// In the ui.render hook: read the value to draw it

774const n = await read($, count)

775 

776// In a Button: write a new value from the old one

777onPress: () => update($, count, (value) => value + 1)

778```

779 

780Porque o hook `ui.render` leu `count`, o Claude Code executa o hook novamente cada vez que o botão o escreve.

781 

782Três regras se aplicam ao código:

783 

784* **Escreva `plugin` e `key` como strings literais**: `claude plugin validate` as lê de sua fonte

785* **Declare cada valor no arquivo de tipos**: caso contrário a validação falha com `hello-tabs.count is not declared`

786* **Escreva de um callback ou hook de outro evento**: um hook `ui.render` pode ler estado e não pode escrevê-lo, então escreva de `onPress`, `onSubmit` ou um hook para outro evento

787 

788<h4 id="change-hello-tabs-to-use-state">

789 Alterar `hello-tabs` para usar `$.state`

790</h4>

791 

792Para mover `count` em `hello-tabs` para `$.state`, altere cada linha que o usa:

793 

794* **No topo do módulo**: adicione a linha `import` e substitua `let count = 0` pela linha `atom`

795* **No hook `ui.render`**: adicione a linha `read` antes de `tabButton` e desenhe `'Count: ' + n` no `Text`

796* **No botão Add one**: substitua `onPress` pelo da [Salvar de mais de uma sessão](#save-from-more-than-one-session), que salva a contagem bem como escreve-a

797* **No hook `session.start`**: substitua as duas linhas que leem `saved` pela chamada `loadCount` de [Carregar um valor salvo novamente após `/clear`](#load-a-saved-value-again-after-clear)

798 

799Mantenha `redraw` para os botões de aba, porque `tab` ainda é uma variável.

800 

801<h3 id="load-a-saved-value-again-after-clear">

802 Carregar um valor salvo novamente após `/clear`

803</h3>

804 

805Se seu mod copia um valor salvo de `$.store` para `$.state` em `session.start`, tem que copiá-lo novamente após `/clear`, `/resume` ou `/branch`. Esses comandos colocam cada valor `$.state` de volta ao seu padrão, e `session.start` não dispara novamente. [`classic.SessionStart`](/docs/pt/plugins/mods/events#hook-the-settings-hook-events) dispara após cada um deles, com `e.source` definido como `clear`, `resume` ou `fork`, então copie o valor novamente em um hook nele. Caso contrário seu desenho mostra o padrão, e um callback que salva o valor `$.state` escreve o padrão sobre o que você armazenou.

806 

807Este código carrega `count` de ambos os hooks. Ele se baseia na versão `$.state` de `hello-tabs`, onde `count` é um atom e `update` é importado. Coloque `loadCount` acima de `register` e adicione a chamada `loadCount` ao hook `session.start` que você já tem. `classic.SessionStart` também dispara na inicialização e após compactação, que não redefine `$.state`, então o filtro em `source` mantém o hook aos três resets:

808 

809```javascript theme={null}

810// Copy the saved count from $.store into $.state, or 0 if nothing is saved

811async function loadCount($) {

812 const saved = Number((await $.store.get('count')) ?? 0)

813 await update($, count, () => saved)

814}

815 

816// Runs before your first prompt, and again after a reload

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

818 await loadCount($)

819 return next(e)

820})

821 

822// Runs again after /clear, /resume, and /branch, which reports fork

823on('classic.SessionStart', { source: ['clear', 'resume', 'fork'] }, async ($, e, next) => {

824 await loadCount($)

825 return next(e)

826})

827```

828 

829Com ambos os hooks em vigor, o painel mostra a contagem salva após `/clear` e não `0`, e o próximo pressionamento de **Add one** adiciona à contagem salva.

830 

831`loadCount` escreve o valor armazenado sobre o em `$.state`, e `session.start` dispara novamente cada vez que o módulo recarrega. Para manter o armazenamento de ficar para trás, salve em cada mudança, como o botão **Add one** faz.

832 

833Para verificar o recarregamento sem uma sessão, [teste o desenho após `/clear`](/docs/pt/plugins/mods/test#test-a-drawing-after-clear).

834 

835<h3 id="save-from-more-than-one-session">

836 Salvar de mais de uma sessão

837</h3>

838 

839Cada sessão em sua máquina que executa seu mod compartilha um `$.store`. Um `get` seguido por um `set` não é atômico. Quando duas sessões cada uma lê um valor, o altera e o escreve de volta, elas correm, e a segunda escrita substitui a primeira.

840 

841Duas escolhas tornam isso menos provável:

842 

843* **Dê a cada item sua própria chave**: um `set` altera apenas sua própria chave, então sessões que escrevem chaves diferentes não sobrescrevem uma à outra

844* **Leia novamente logo antes de escrever**: para um valor que várias sessões alteram, `get` a chave no callback e construa o novo valor a partir disso, não de uma cópia que você carregou em `session.start`. Outra escrita de sessão ainda é perdida se cair entre seu `get` e seu `set`.

845 

846Este botão adiciona um ao que o armazenamento contém agora, depois atualiza o desenho:

847 

848```javascript theme={null}

849onPress: async () => {

850 // Read what the store holds now, which another session may have changed

851 const saved = Number((await $.store.get('count')) ?? 0)

852 // Save the new count, then show it

853 await $.store.set('count', saved + 1)

854 await update($, count, () => saved + 1)

855}

856```

857 

858Se uma segunda sessão pressionou seu próprio botão três vezes desde que esta sessão começou, este pressionamento mostra e salva uma contagem que inclui esses três.

859 

860<h2 id="next-steps">

861 Próximos passos

862</h2>

863 

864* [Reagir a eventos](/docs/pt/plugins/mods/events): alimente seu desenho de chamadas de ferramenta e voltas

865* [Use a API de mods](/docs/pt/plugins/mods/api): alimente seu desenho de timers e chamadas de modelo

866* [Teste um desenho](/docs/pt/plugins/mods/test#test-a-drawing): pressione seus botões de um teste, em mais de uma superfície

867* [Sites de renderização](/docs/pt/plugins/mods/reference#render-sites) e [elementos](/docs/pt/plugins/mods/reference#elements): propriedades de cada site e propriedades de cada elemento

plugins/mods/overview.md +269 −0 created

Details

1> ## Documentation Index

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

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

4 

5# Visão geral de mods

6 

7> Adicione painéis, comandos e regras de chamada de ferramentas ao Claude Code com um mod. Veja o que um mod pode fazer, como criar ou instalar um, e onde os mods são executados.

8 

9Um mod é um [plugin](/docs/pt/plugins/overview) que muda como o Claude Code se parece e se comporta. É feito de manipuladores de eventos em JavaScript ou TypeScript: Claude Code chama um quando um evento acontece, como uma chamada de ferramenta, um prompt enviado, ou uma parte da interface sendo desenhada, e o manipulador pode observar o evento, alterá-lo ou assumir o controle dele. Use um mod para adicionar um recurso próprio ao Claude Code, como um painel que mostra graficamente o quão cheio seu contexto está após cada solicitação. Para os arquivos em um mod e um exemplo completo, veja [Como um mod funciona](#how-a-mod-works).

10 

11<Note>

12 Os [hooks](/docs/pt/hooks) existentes do Claude Code também são executados em eventos, como um comando shell, uma solicitação HTTP ou um prompt que você configura em um arquivo de configurações. Os manipuladores de um mod são funções que são executadas dentro do Claude Code em vez disso. Claude Code chama ambos os tipos de hooks: nessas páginas, "hook" significa um manipulador de um mod, e o tipo de arquivo de configurações é um "settings hook".

13</Note>

14 

15<h2 id="what-a-mod-can-do">

16 O que um mod pode fazer

17</h2>

18 

19Settings hooks, skills, linhas de status e servidores MCP funcionam de fora do Claude Code: cada um executa um script ou fornece ao Claude texto ou ferramentas. Um mod é executado dentro do Claude Code, então pode fazer coisas que eles não conseguem:

20 

21* **Desenhar uma interface que você pode usar**: um painel ao lado da transcrição ou uma faixa acima do prompt, com abas, botões e campos de texto. Veja [Desenhar na interface](/docs/pt/plugins/mods/interface).

22* **Redesenhar a própria interface do Claude Code**: substituir ou reformatar partes que o Claude Code desenha, como a linha de uma chamada de ferramenta, o spinner ou o diálogo que o Claude faz perguntas. Veja [Alterar o que o Claude Code já desenha](/docs/pt/plugins/mods/interface#change-what-claude-code-already-draws).

23* **Intervir em uma chamada de ferramenta ou uma solicitação**: por exemplo, manter uma chamada de ferramenta enquanto você faz uma pergunta ao usuário, responder sem executar a ferramenta ou enviar uma solicitação para um modelo diferente. Veja [Guardar ou alterar uma chamada de ferramenta](/docs/pt/plugins/mods/events#guard-or-change-a-tool-call) e [Seguir um turno](/docs/pt/plugins/mods/events#follow-a-turn).

24* **Executar seu próprio código em um comando**: um `/command` que executa sua função imediatamente, sem nenhum turno do Claude, mesmo enquanto o Claude está trabalhando. Veja [Adicionar um comando ou uma ferramenta](/docs/pt/plugins/mods/api#add-a-command-or-a-tool).

25* **Compartilhar dados entre hooks**: os hooks de um mod compartilham as variáveis em seu arquivo, então o que um hook registra, outro pode mostrar. Por exemplo, um hook pode contar chamadas de ferramenta enquanto outro mostra a contagem ao lado do spinner, ou um pode ler o uso de tokens de cada solicitação enquanto outro o mostra em gráfico em um painel. Veja [Reagir a eventos](/docs/pt/plugins/mods/events).

26 

27Os mods funcionam no CLI do Claude Code e na aba Code do aplicativo Claude Desktop. Veja [Onde os mods são executados](#where-mods-run) para entender como eles se comportam em outros lugares, como na extensão VS Code, `claude -p` e sessões na nuvem. Se um settings hook, uma skill ou um servidor MCP já faz o que você precisa, [compare-os](#compare-mods-settings-hooks-skills-and-mcp-servers) antes de escrever um mod. Para gerenciar mods para uma organização, veja [Gerenciar mods para sua organização](/docs/pt/plugins/mods/admin).

28 

29<h2 id="get-a-mod">

30 Obter um mod

31</h2>

32 

33Você pode começar com um mod de três maneiras:

34 

35* **Use um que você já tem**: alguns dos próprios recursos do Claude Code são mods, como `/diff`. Veja [Mods integrados ao Claude Code](#mods-built-into-claude-code).

36* **Crie um**: descreva o que você quer em uma sessão do Claude Code, e o Claude escreve o mod. Veja [Peça ao Claude por um mod](/docs/pt/plugins/mods/create#ask-claude-for-a-mod). Para aprender como o código de um mod funciona, [escreva um você mesmo](/docs/pt/plugins/mods/create#write-a-mod-yourself).

37* **Instale um**: veja [Instalar ou atualizar um mod](#install-or-update-a-mod)

38 

39<h3 id="install-or-update-a-mod">

40 Instalar ou atualizar um mod

41</h3>

42 

43<Warning>

44 Um mod é código que é executado com suas permissões. Pode ler e escrever seus arquivos, iniciar processos e fazer solicitações de rede. Instale mods apenas de autores e marketplaces em que você confia. Veja [Decidir se confia em um mod](#decide-whether-to-trust-a-mod).

45</Warning>

46 

47Um mod é instalado como um plugin, a partir de um marketplace. Forneça o nome do plugin, um `@` e o nome do marketplace. Estes exemplos instalam um plugin chamado `token-chart` de um marketplace chamado `your-org`:

48 

49* Em uma sessão do Claude Code, execute `/plugin install token-chart@your-org`.

50* No seu shell, execute `claude plugin install token-chart@your-org`.

51 

52[Instalar plugins](/docs/pt/plugins/install) cobre marketplaces, escopos, a extensão VS Code e o aplicativo Desktop, e [manter plugins atualizados](/docs/pt/plugins/install#keep-plugins-updated), tudo isso se aplica a um plugin que contém um mod sem alterações.

53 

54Se você instalar ou atualizar um mod do seu shell enquanto uma sessão está aberta, execute `/reload-plugins` nessa sessão para carregá-lo. Caso contrário, ele carrega na próxima vez que você iniciar o Claude Code.

55 

56<h2 id="decide-whether-to-trust-a-mod">

57 Decidir se confia em um mod

58</h2>

59 

60Um mod é código que é executado com suas permissões, dentro do Claude Code. Instale mods apenas de autores e [marketplaces em que você confia](/docs/pt/plugins/security).

61 

62<h3 id="what-a-mod-can-reach">

63 O que um mod pode alcançar

64</h3>

65 

66Um mod é executado com suas permissões, então antes de instalar um, saiba o que ele tem acesso. Uma vez carregado, um mod pode:

67 

68* **Agir em sua máquina como você**: ler e escrever arquivos em qualquer lugar que sua conta de usuário possa, iniciar programas e fazer solicitações de rede

69* **Ler seus segredos**: variáveis de ambiente e arquivos de configurações, incluindo uma chave de API que você mantém em qualquer um deles

70* **Ver sua sessão**: cada prompt que você envia e cada chamada de ferramenta que o Claude faz

71* **Alterar sua sessão**: reescrever um prompt ou uma chamada de ferramenta, enviar um prompt como se você o tivesse digitado, ou enviar uma mensagem para outra de suas sessões

72* **Agir sem pedir a você**: aprovar uma chamada de ferramenta antes de você ser perguntado

73* **Gastar seu uso**: chamar um modelo em seu plano ou chave de API

74 

75Um mod que aprova chamadas de ferramenta pode aprovar uma que uma regra `ask` solicitaria, ou que um de seus próprios hooks `PreToolUse` bloqueou. [Estender permissões com hooks](/docs/pt/permissions#extend-permissions-with-hooks) lista o que tal mod pode aprovar, incluindo quando pode aprovar uma chamada que uma regra `deny` recusa.

76 

77Um mod pode reformatar grande parte da interface do Claude Code, mas não o prompt de permissão. Não pode alterar o que um prompt mostra a você.

78 

79<h3 id="list-what-a-mod-does-before-you-install-one">

80 Listar o que um mod faz antes de instalá-lo

81</h3>

82 

83Antes de instalar um mod, você pode listar quais eventos ele conecta e o que pede ao Claude Code para fazer, como ler um arquivo ou fazer uma solicitação de rede, sem executá-lo. Obtenha os arquivos do plugin primeiro, por exemplo clonando seu repositório. Depois, no seu shell, execute `claude plugin validate` no diretório do plugin:

84 

85```bash theme={null}

86claude plugin validate ./some-mod

87```

88 

89As linhas `hooks:` e `calls:` na saída listam os eventos que o mod manipula e o que pede ao Claude Code para fazer. [Revisar o que um mod pode fazer](/docs/pt/plugins/mods/admin#review-what-a-mod-can-do) mostra a saída e quais chamadas procurar.

90 

91<h2 id="turn-mods-on-or-off">

92 Ativar ou desativar mods

93</h2>

94 

95Os mods requerem Claude Code v2.1.287 ou posterior, e estão ativados por padrão. No seu shell, execute `claude --version` para verificar e atualize o Claude Code se o seu for mais antigo.

96 

97Para desativar mods, escolha quantos parar e por quanto tempo. Para ativá-los novamente, desfaça a mesma alteração:

98 

99* **Um mod**: desabilite ou desinstale seu plugin da [**aba Installed em `/plugin`**](/docs/pt/plugins/install#manage-installed-plugins)

100* **Cada mod instalado, para uma sessão**: inicie o Claude Code com [`--safe-mode`](/docs/pt/cli-reference#cli-flags), que também deixa de fora suas outras personalizações

101* **Cada mod que você instalou, em cada sessão**: defina [`"disableAllHooks": true`](/docs/pt/settings-reference#disableallhooks) em `~/.claude/settings.json`. Seus settings hooks e linha de status personalizada também param. O que sua organização gerencia continua funcionando.

102 

103Se você usar o Claude Code através de uma organização, um administrador também pode limitar quais mods carregam. Os administradores começam em [Impedir que mods instalados pelo usuário sejam carregados](/docs/pt/plugins/mods/admin#stop-user-installed-mods-from-loading).

104 

105Para descobrir se mods podem carregar para você, veja [Verificar se mods podem carregar](/docs/pt/plugins/mods/troubleshoot#check-whether-mods-can-load).

106 

107<Note>

108 Se você definiu `CLAUDE_CODE_ENABLE_FUNCTION_HOOKS` durante acesso antecipado, remova-o. Claude Code v2.1.287 e posterior o ignora, então defini-lo como `0` não mantém mods desativados.

109</Note>

110 

111<h3 id="see-which-mods-a-session-loaded">

112 Ver quais mods uma sessão carregou

113</h3>

114 

115Para ver quais mods uma sessão de terminal carregou, execute `/plugin` no prompt do Claude Code. Uma linha atenuada sob as abas fornece a contagem e os nomes, como `1 mod active · first-mod`. Se um mod que você instalou não estiver nomeado lá, veja [Descobrir por que um mod não faz nada](/docs/pt/plugins/mods/troubleshoot#find-out-why-a-mod-does-nothing).

116 

117<h2 id="how-a-mod-works">

118 Como um mod funciona

119</h2>

120 

121Um mod é um [plugin](/docs/pt/plugins/overview) cujo código registra manipuladores de eventos, chamados hooks. O Claude Code executa um hook quando seu evento acontece, como quando o Claude chama uma ferramenta ou quando o spinner é desenhado. Um mod pequeno tem três arquivos:

122 

123```text theme={null}

124first-mod/

125├── .claude-plugin/

126│ └── plugin.json

127└── hooks/

128 ├── hooks.json

129 └── register.js

130```

131 

132* **`plugin.json`**: o [manifesto](/docs/pt/plugins/manifest-reference) do plugin

133* **`hooks.json`**: [aponta para seu arquivo de código](/docs/pt/plugins/mods/reference#files)

134* **`register.js`**: [seu código](/docs/pt/plugins/mods/create#write-a-mod-yourself), chamado de módulo hooks. Ele diz ao Claude Code em quais eventos executar suas funções.

135 

136Este é um `register.js` completo. Ele conta as chamadas de ferramenta que o Claude faz e mostra a contagem ao lado do spinner enquanto o Claude trabalha, como em `Thinking · tool calls: 3…`.

137 

138```javascript hooks/register.js theme={null}

139// A contagem, compartilhada pelos dois hooks abaixo

140let calls = 0

141 

142// Claude Code chama isso uma vez quando o mod carrega

143export function register(on) {

144 // Executado cada vez que Claude está prestes a usar uma ferramenta

145 on('tool.call', async ($, e, next) => {

146 calls += 1

147 // Peça ao Claude Code para desenhar a interface novamente, para que a nova contagem apareça

148 $.ui.invalidate('ui.render')

149 // Deixe a ferramenta ser executada normalmente

150 return next(e)

151 })

152 

153 // Executado cada vez que Claude Code desenha o spinner

154 on('ui.render', { component: 'Spinner' }, async ($, e, next) => {

155 // Mantenha o spinner do Claude Code, com a contagem adicionada após sua palavra

156 return next({ ...e, props: { ...e.props, suffix: ' · tool calls: ' + calls + '…' } })

157 })

158}

159```

160 

161O arquivo registra dois hooks, e ambos usam a variável `calls` no topo:

162 

163* **O hook [`tool.call`](/docs/pt/plugins/mods/reference#tools)** é executado cada vez que o Claude está prestes a usar uma ferramenta. Adiciona um a `calls`, pede ao Claude Code para desenhar a interface novamente e deixa a ferramenta ser executada normalmente.

164* **O hook [`ui.render`](/docs/pt/plugins/mods/reference#interface)** é executado cada vez que o Claude Code desenha o spinner. Mantém o próprio spinner do Claude Code e adiciona a contagem após a palavra.

165 

166Esta gravação mostra o mod em ação. Observe a linha do spinner acima da caixa de prompt: enquanto o Claude lista um diretório e lê dois arquivos, ele lê `Thinking · tool calls: 1…`, depois `2…`, depois `3…`.

167 

168<Frame>

169 <video autoPlay muted loop playsInline controls className="w-full dark:hidden" src="https://mintcdn.com/claude-code/dgiVO_Od1X1faduV/images/mods-overview-light.mp4?fit=max&auto=format&n=dgiVO_Od1X1faduV&q=85&s=00a18aa0743b59a700f0275ce226e6d1" aria-label="Em uma sessão do Claude Code, o prompt 'list the files here and read the README' é digitado e enviado. Enquanto o Claude trabalha, o spinner lê 'Thinking · tool calls: 1', depois 2, depois 3, conforme o Claude lista os arquivos e lê dois deles." data-path="images/mods-overview-light.mp4" />

170 

171 <video autoPlay muted loop playsInline controls className="w-full hidden dark:block" src="https://mintcdn.com/claude-code/dgiVO_Od1X1faduV/images/mods-overview-dark.mp4?fit=max&auto=format&n=dgiVO_Od1X1faduV&q=85&s=d5223da2fef16ceaaa214a36d72c0536" aria-label="Em uma sessão do Claude Code, o prompt 'list the files here and read the README' é digitado e enviado. Enquanto o Claude trabalha, o spinner lê 'Thinking · tool calls: 1', depois 2, depois 3, conforme o Claude lista os arquivos e lê dois deles." data-path="images/mods-overview-dark.mp4" />

172</Frame>

173 

174<h3 id="what-a-hook-can-do-with-an-event">

175 O que um hook pode fazer com um evento

176</h3>

177 

178O Claude Code executa seu hook antes de agir no evento, então o hook decide o que acontece a seguir. Ele tem três opções:

179 

180* **Observar**: notar o que está acontecendo e deixar continuar inalterado, como o hook `tool.call` no exemplo faz

181* **Reescrever**: alterar o evento antes de continuar, como o hook `ui.render` faz quando adiciona a contagem ao spinner

182* **Responder**: manipular o evento em si, para que o comportamento usual não seja executado, como recusar um comando

183 

184Para fazer qualquer coisa fora de seu próprio código, como desenhar, adicionar um comando, chamar um modelo, ler um arquivo, iniciar um processo ou fazer uma solicitação de rede, um hook chama a API de mods. Um hook não tem outra maneira de fazer essas coisas, é por isso que o Claude Code pode [listar o que um mod faz](#list-what-a-mod-does-before-you-install-one) antes de você instalá-lo.

185 

186Para o código por trás de cada opção, veja [Reagir a eventos](/docs/pt/plugins/mods/events#how-a-hook-handles-an-event). Para o que um hook pode chamar, veja [Usar a API de mods](/docs/pt/plugins/mods/api).

187 

188<h3 id="where-mods-run">

189 Onde os mods são executados

190</h3>

191 

192Os hooks de um mod são executados em todos os tipos de sessão que carregam o plugin. O desenho é mais restrito: apenas o terminal e o aplicativo Desktop mostram painéis, faixas e linhas substituídas de um mod. Esta tabela lista cada lugar onde você pode executar o Claude Code:

193 

194| Onde você executa o Claude Code | Hooks são executados | O que o mod desenha aparece |

195| :- | :- | :- |

196| `claude` em um terminal, incluindo o terminal integrado de um editor e o plugin JetBrains | Sim | Sim |

197| A aba Code do aplicativo Desktop, exceto em uma sessão WSL | Sim | Sim, exceto elementos que a [tabela de elementos](/docs/pt/plugins/mods/reference#elements) marca como apenas terminal |

198| Uma [sessão WSL](/docs/pt/desktop-wsl) no aplicativo Desktop | Não, porque plugins não estão disponíveis em sessões WSL | Não |

199| O painel de chat da extensão VS Code | Sim | Não |

200| `claude -p` e o [Agent SDK](/docs/pt/agent-sdk/overview) | Sim | Não |

201| [Remote Control](/docs/pt/remote-control) de claude.ai ou do aplicativo móvel | Sim, na sessão em sua máquina | No terminal em sua máquina |

202| Uma [sessão na nuvem](/docs/pt/claude-code-on-the-web) | Sim, para um plugin que [alcança a sessão na nuvem](/docs/pt/cloud-environments#what-carries-over-from-your-setup) | Não |

203 

204Um mod que desenha pode verificar em qual aplicativo está sendo executado e voltar para uma linha na transcrição ou uma resposta de texto de comando onde nada desenha.

205 

206<h2 id="control-mods-for-your-organization">

207 Controlar mods para sua organização

208</h2>

209 

210Os administradores decidem se mods são executados e quais, através de [configurações gerenciadas](/docs/pt/managed-settings). [Gerenciar mods para sua organização](/docs/pt/plugins/mods/admin) cobre o que acontece por padrão, como revisar um mod e como aplicar uma política com um mod próprio.

211 

212<h2 id="compare-mods-settings-hooks-skills-and-mcp-servers">

213 Comparar mods, settings hooks, skills e servidores MCP

214</h2>

215 

216Mods, settings hooks, skills e servidores MCP se sobrepõem. Esta tabela mostra o que cada um é e quando escolhê-lo.

217 

218| | Mod | Settings hook | Skill | Servidor MCP |

219| :- | :- | :- | :- | :- |

220| O que é | Funções em um plugin que o Claude Code chama em seu próprio processo | Um comando shell, solicitação HTTP ou prompt que o Claude Code executa em um evento de ciclo de vida | Um arquivo `SKILL.md` de instruções que o Claude lê | Um processo ou serviço externo que fornece ferramentas ao Claude |

221| O que pode alterar | Chamadas de ferramenta, prompts, comandos, turnos e o que a interface desenha | Se uma chamada de ferramenta ou prompt prossegue, argumentos de uma chamada de ferramenta e resultado, e contexto adicionado para o Claude | O que o Claude sabe e faz | Quais ferramentas o Claude tem |

222| Pode desenhar na interface | Sim | Não | Não | Não |

223| O que você escreve | JavaScript ou TypeScript | Um script e uma entrada `settings.json` | Markdown | Um servidor em qualquer linguagem |

224| Escolha quando | Você quer um painel, uma faixa acima do prompt, um comando personalizado ou reescrever um evento | Você quer bloquear, permitir ou registrar um evento com um script que você já tem | Você fica colando as mesmas instruções no chat | O Claude precisa alcançar um sistema externo |

225 

226Cada um dos outros tem sua própria página: [Hooks](/docs/pt/hooks), [Skills](/docs/pt/skills) e [MCP](/docs/pt/mcp). Um plugin pode conter todos os quatro, então um mod pode ser enviado no mesmo plugin que uma skill e um servidor MCP.

227 

228<h2 id="mods-built-into-claude-code">

229 Mods integrados ao Claude Code

230</h2>

231 

232Alguns dos próprios recursos do Claude Code são mods. Para ver os que sua sessão tem, execute `/plugin` no prompt do Claude Code e vá para a aba **Installed**, que os lista em **Built-in**. Você não pode atualizar ou desinstalar um mod integrado, e a última coluna da tabela diz como desativar cada um. A linha [`mods active`](#see-which-mods-a-session-loaded) deixa mods integrados de fora.

233 

234Esta tabela lista cada entrada pelo nome que `/plugin` mostra:

235 

236| Nome em `/plugin` | O que faz | Onde está ativado | Como desativar |

237| :- | :- | :- | :- |

238| `cc-plugin-agents-md` | Carrega `AGENTS.md` como instruções do projeto | Cada sessão, exceto [as que não conseguem ler `AGENTS.md`](/docs/pt/memory#when-agents-md-support-is-unavailable) | Desabilite em `/plugin` ou [escolha quais arquivos de instruções carregam](/docs/pt/memory#choose-which-instruction-files-load) |

239| `cc-plugin-diff` | Assume o controle de [`/diff`](/docs/pt/interactive-mode#review-changes-with-%2Fdiff) e desenha seu painel | Sessões de terminal interativas | Desabilite em `/plugin`. `/diff` permanece, e a versão integrada do Claude Code do comando responde. |

240| `cc-plugin-plugin-authoring` | Dá ao Claude a [skill `plugin-authoring`](/docs/pt/plugins/mods/create#ask-claude-for-a-mod) para escrever mods. Contém uma skill e nenhum código de mod. | A menos que a Anthropic tenha desativado mods instalados remotamente | Desabilite em `/plugin` |

241| `cc-plugin-sec-default` | Guarda o que sua organização gerencia dos mods que um usuário instala | [Onde o guarda carrega](/docs/pt/plugins/mods/admin#know-what-happens-by-default) | Você não consegue. Um administrador [define a ordem](/docs/pt/plugins/mods/admin#install-your-organizations-mods) em configurações gerenciadas |

242| `cc-plugin-telemetry` | Envia os registros de análise que o Claude Code e seus mods integrados registram | Onde a análise própria do Claude Code está ativada | Desabilite em `/plugin` ou desative a análise, por exemplo com [`DISABLE_TELEMETRY`](/docs/pt/env-vars) |

243| `cc-plugin-you-should-know` | Executa um agente lateral que vigia você enquanto Claude trabalha em tarefas mais longas. Quando encontra algo que vale a pena saber que você pode perder, mostra uma nota acima do prompt. | Desativado por padrão. Listado em `/plugin` -> **Installed** -> **Show disabled** se disponível para sua organização. Ative com [`/plugin enable cc-plugin-you-should-know@builtin`](/docs/pt/plugins/cli-reference#plugin-in-a-session). | Desabilite em `/plugin` |

244 

245As configurações e sinalizadores que param mods instalados, como `disableAllHooks`, `--bare` e `--safe-mode`, não param mods integrados.

246 

247<h3 id="read-the-source-of-built-in-mods">

248 Ler a fonte de mods integrados

249</h3>

250 

251A fonte de quatro desses mods é pública no [diretório `mods` do repositório Claude Code](https://github.com/anthropics/claude-code/tree/main/mods). Cada um é um plugin completo com seu módulo hooks e testes:

252 

253* [`diff`](https://github.com/anthropics/claude-code/tree/main/mods/diff): o painel `/diff`, com botões vinculados a ações de teclado e rolagem que o mod manipula

254* [`agents-md`](https://github.com/anthropics/claude-code/tree/main/mods/agents-md): carrega `AGENTS.md` como instruções do projeto, com uma opção [`userConfig`](/docs/pt/plugins/components#user-configuration)

255* [`sec-default`](https://github.com/anthropics/claude-code/tree/main/mods/sec-default): o guarda descrito em [Saber o que acontece por padrão](/docs/pt/plugins/mods/admin#know-what-happens-by-default), um modelo para um mod que aplica política

256* [`telemetry`](https://github.com/anthropics/claude-code/tree/main/mods/telemetry): adiciona métodos que outros mods podem chamar e envia seus tipos

257 

258<h2 id="next-steps">

259 Próximos passos

260</h2>

261 

262* [Criar um mod](/docs/pt/plugins/mods/create): construa um que conte chamadas de ferramenta, mostre a contagem ao lado do spinner e adicione um comando, e aprenda o loop de edição e recarga

263* [Desenhar na interface](/docs/pt/plugins/mods/interface): painéis, a faixa acima do prompt, botões, campos de texto e estado

264* [Reagir a eventos](/docs/pt/plugins/mods/events): chamadas de ferramenta, prompts, turnos e a ordem em que mods são executados

265* [Usar a API de mods](/docs/pt/plugins/mods/api): comandos, ferramentas, chamadas de modelo, temporizadores e arquivos

266* [Testar um mod](/docs/pt/plugins/mods/test): testes automatizados que são executados sem uma sessão

267* [Solucionar problemas de um mod](/docs/pt/plugins/mods/troubleshoot): as razões pelas quais um mod não faz nada e o log de depuração

268* [Gerenciar mods para sua organização](/docs/pt/plugins/mods/admin): padrões, configurações gerenciadas, revisão de um mod e mods de política

269* [Referência de mods](/docs/pt/plugins/mods/reference): cada evento, método, elemento e limite

plugins/mods/test.md +422 −0 created

Details

1> ## Documentation Index

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

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

4 

5# Testar um mod

6 

7> Escreva testes automatizados para um mod Claude Code que levantam eventos, simulam respostas do Claude Code e pressionam botões, sem sessão, login ou rede.

8 

9Você pode escrever testes automatizados para um mod e executá-los a partir do seu shell com [`claude plugin test`](/docs/pt/plugins/mods/reference#commands). Um teste levanta os eventos que seus hooks tratam e verifica o que os hooks fizeram, para que você detecte um problema antes que ele chegue a uma sessão. O primeiro exemplo testa o mod de [Create a mod](/docs/pt/plugins/mods/create).

10 

11<h2 id="write-a-test">

12 Escrever um teste

13</h2>

14 

15Um teste carrega seu mod, envia eventos através de seus hooks da forma como Claude Code faria, e verifica o que os hooks fizeram, sem uma sessão, um login ou uma rede. Você executa testes a partir do seu shell com `claude plugin test`, e cada arquivo de teste importa o test kit, uma biblioteca de teste no módulo `claude-code/testing`.

16 

17Dê a cada arquivo de teste um nome que termine em `.test.ts`, como `first-mod.test.ts`, e salve-o em qualquer lugar no diretório do plugin. Cada arquivo de teste precisa de pelo menos um `test()`, ou a execução falha com `declares no test(): nothing ran`. Um arquivo de teste pode importar seus próprios arquivos do mod e helpers `.ts` irmãos, para que você possa fazer testes unitários de funções simples, como as regras de um jogo, sem o kit.

18 

19Este teste levanta duas chamadas de ferramenta, executa o comando `/tally` de [Create a mod](/docs/pt/plugins/mods/create), e verifica se a resposta conta ambas. Sua primeira linha é um [stub](#stub-what-claude-code-would-answer), que responde as chamadas de ferramenta no lugar do Claude Code. Salve-o como `first-mod/tests/first-mod.test.ts`:

20 

21```typescript first-mod/tests/first-mod.test.ts theme={null}

22import { expect, test } from 'claude-code/testing'

23 

24test('/tally reports the tool calls the mod has seen', async ($, on) => {

25 // Answer each tool call in Claude Code's place, so no tool runs

26 on('tool.call', () => ({ result: 'ok' }))

27 

28 // Raise two tool calls, which the mod's tool.call hook counts

29 await $.tool.call({ tool: 'Bash', command: 'ls' })

30 await $.tool.call({ tool: 'Read', file_path: 'README.md' })

31 

32 // Run /tally and check the text its hook returns

33 const answer = await $.command.run({ command: 'tally', args: '' })

34 expect(answer.text).toBe('Claude has made 2 tool calls since this mod loaded')

35})

36```

37 

38No seu shell, execute os testes a partir do diretório `first-mod`:

39 

40```bash theme={null}

41claude plugin test

42```

43 

44A saída nomeia cada teste e se passou, com tempos que variam de execução para execução:

45 

46```text theme={null}

47tests/first-mod.test.ts:

48(pass) /tally reports the tool calls the mod has seen [22.87ms]

49 

50 1 pass

51 0 fail

52Ran 1 test across 1 file. [0.19s]

53```

54 

55Cada `$.tool.call` passou pelo hook [`tool.call`](/docs/pt/plugins/mods/reference#tools) do mod, que adicionou um à sua contagem e passou a chamada para o stub. Nenhum `ls` foi executado e nenhum arquivo foi lido. `$.command.run` então foi para o hook [`command.run`](/docs/pt/plugins/mods/reference#commands-and-configuration) do mod, e `answer` é o objeto que esse hook retornou.

56 

57O comando sai com status 1 quando um teste falha, então funciona em CI. Se seus próprios mods não conseguirem carregar no shell que o executa, ele imprime uma linha começando com `claude plugin test: hooks modules are turned off` com o motivo, e sai com status 1.

58 

59<h3 id="stub-what-claude-code-would-answer">

60 Simular o que Claude Code responderia

61</h3>

62 

63Nenhum modelo, armazenamento ou ferramenta é executado em um teste, então onde quer que seu mod espere que Claude Code responda, o teste fornece a resposta com um stub. Uma função de teste recebe dois argumentos para isso:

64 

65* **`$`**: o próprio `$` do teste, que fica no lugar do Claude Code. Não é a [mods API](/docs/pt/plugins/mods/reference#mods-api-methods) que um hook recebe. Cada um de seus métodos levanta o evento de mesmo nome, o envia através dos hooks do seu mod, e resolve para o resultado: `$.tool.call({ tool: 'Bash', command: 'ls' })` levanta `tool.call`. `$.command.run`, `$.prompt.submit`, `$.session.start`, e `$.turn.complete` funcionam da mesma forma, e `$.classic.Stop` e os outros métodos `$.classic` levantam um [evento de hook de configurações](/docs/pt/plugins/mods/events#hook-the-settings-hook-events). Um teste não pode levantar uma chamada de mods API como `ui.close` diretamente. Dispare-a através do seu mod, por exemplo pressionando o botão que fecha o painel.

66* **`on`**: chame-o para registrar stubs, que são hooks que respondem no lugar do Claude Code. Nomeie um stub para uma chamada de mods API sem o `$.`, então um stub registrado como `store.get` responde seu `$.store.get` do mod. Quando seu mod chama [`$.model.complete`](/docs/pt/plugins/mods/api#call-a-model) ou [`$.store.get`](/docs/pt/plugins/mods/interface#keep-state), um stub fornece a resposta.

67 

68Este exemplo simula uma chamada de modelo. O hook pertence a um mod chamado `grader`, e trata um comando `/grade` que envia uma frase para um modelo e relata se a resposta começa com `PASS`. O arquivo contém apenas o hook sob teste, então o mod também precisa de um `plugin.json` e um `hooks.json`, como em [Create a mod](/docs/pt/plugins/mods/create#write-a-mod-yourself). Para digitar `/grade` em uma sessão, o mod também tem que [registrar o comando](/docs/pt/plugins/mods/api#add-a-command):

69 

70```javascript grader/hooks/register.js theme={null}

71export function register(on) {

72 on('command.run', { command: 'grade' }, async ($, e) => {

73 // e.args is the text typed after /grade

74 const reply = await $.model.complete({

75 model: 'haiku',

76 system: 'Grade the sentence. Start your reply with PASS or FAIL.',

77 prompt: e.args,

78 })

79 const passed = reply.isAnswered && reply.text.startsWith('PASS')

80 return { text: passed ? 'Passed' : 'Try again' }

81 })

82}

83```

84 

85Este teste simula a chamada do modelo para verificar o que o hook faz com uma resposta aprovada:

86 

87```typescript grader/tests/grader.test.ts theme={null}

88import { expect, test } from 'claude-code/testing'

89 

90test('a passing grade is reported', async ($, on) => {

91 // Answer the mod's $.model.complete call with a fixed reply, so no model runs

92 on('model.complete', () => ({

93 value: {

94 isAnswered: true,

95 text: 'PASS\nNice sentence.',

96 usage: { input_tokens: 10, output_tokens: 5, cache_read_input_tokens: 0, cache_creation_input_tokens: 0 },

97 },

98 }))

99 

100 // Run /grade, which makes the mod call the model

101 const answer = await $.command.run({ command: 'grade', args: 'The cat sat on the mat.' })

102 expect(answer.text).toBe('Passed')

103})

104```

105 

106O teste passa porque o `reply` do hook é o objeto sob `value`, cujo `text` começa com `PASS`. Para verificar o outro ramo, adicione um segundo teste cujo stub retorna um `text` que começa com `FAIL`, e espere `Try again`.

107 

108Um stub para uma chamada de mods API retorna um objeto com um campo `value`, que contém o que a chamada resolve em seu mod: `{ value: 7 }` faz `$.store.get` resolver para `7`. Um stub para um dos eventos do Claude Code, como [`turn.step`](/docs/pt/plugins/mods/reference#turns) ou `tool.call`, retorna o resultado próprio desse evento, como `{ result: 'ok' }`. `$.session.send` e `$.prompt.fill` também levam o resultado do evento, como a tabela mostra. [Look up what a stub returns](#look-up-what-a-stub-returns) mostra qual forma cada nome comum assume. Dois erros significam que um stub está errado ou faltando. A saída de um teste falhado inclui um bloco intitulado `the engine reported:`, e cada erro aparece lá:

109 

110* `returned neither { value } nor { deny }`: um stub para uma chamada de mods API retornou um valor simples

111* `no implementation for` seguido por um nome: seu mod fez essa chamada e nenhum stub a responde

112 

113O kit também exporta mocks em memória que respondem um namespace inteiro para você. `mock.clock(on)` responde [`$.clock`](/docs/pt/plugins/mods/api#run-work-in-the-background), `mock.store(on, { count: 7 })` responde `$.store` de um armazenamento que começa com essas entradas, e `mock.env(on, { CI: 'true' })` responde `$.env.get` dessas variáveis. `mock.clock` retorna um relógio simulado que seu teste avança, então um teste de um temporizador não espera. `mock.store` não retorna nada, então para verificar o que seu mod salvou, escreva os dois stubs `store` você mesmo como o [drawing test](#test-a-drawing) faz.

114 

115<h3 id="follow-the-test-kit’s-rules">

116 Seguir as regras do test kit

117</h3>

118 

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

120 

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

122 

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

124 

125 ```typescript theme={null}

126 // Answer the event after your hook passes it on with next(e)

127 on('session.start', () => ({ cwd: '/work' }))

128 // Answer the $.command.register call your hook makes

129 on('command.register', () => ({ value: undefined }))

130 // Raise the event, which runs your session.start hook

131 await $.session.start({ surface: 'terminal', isInteractive: true, cwd: '/work' })

132 ```

133 

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

135 

136* **Um hook que retorna `next(e)` precisa de um stub para responder.** Quando seu hook [`ui.render`](/docs/pt/plugins/mods/reference#interface) retorna `next(e)`, por exemplo para não desenhar nada enquanto Claude está ocioso, [montá-lo](#test-a-drawing) falha com `no implementation for ui.render`. Registre um stub que retorna um elemento como dados simples:

137 

138 ```typescript theme={null}

139 // Stands for what Claude Code would draw at the site

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

141 ```

142 

143 Com o stub registrado, a montagem é bem-sucedida, e `ui.find({ type: 'Text' })` retorna esse elemento sempre que seu hook retornou `next(e)`.

144 

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

146 

147 ```typescript theme={null}

148 on('turn.step', async function* ($, e) {

149 // Each yield is one piece of the model's streamed reply

150 yield { kind: 'text', index: 0, text: 'ok' }

151 // The return value is the result of the whole request

152 return { turnId: e.turnId, index: e.index, answer: 'ok', toolUses: [], stopReason: 'end_turn', usage: null }

153 })

154 

155 // Raise one request to the model, which runs your turn.step hook

156 const stream = $.turn.step({ turnId: 't', index: 0, model: 'claude-test', messageCount: 1 })

157 // Read every piece until the stream says it's done

158 let step = await stream.next()

159 while (step.done !== true) step = await stream.next()

160 const result = step.value

161 ```

162 

163 Quando o loop termina, `result` é o objeto que o stub retornou, depois que seu hook `turn.step` teve a chance de alterá-lo. Aqui `result.answer` é `'ok'`.

164 

165* **Levante uma chamada de ferramenta com o nome da ferramenta e argumentos como campos**, como `await $.tool.call({ tool: 'Bash', command: 'ls' })`, e registre um stub `tool.call` que retorna `{ result }`.

166 

167<h3 id="look-up-what-a-stub-returns">

168 Procurar o que um stub retorna

169</h3>

170 

171Cada chamada de mods API que seu mod faz em um teste precisa de um stub que responda no lugar do Claude Code, exceto as poucas que o kit responde por si: chamadas [`$.ui.invalidate`](/docs/pt/plugins/mods/interface#redraw-when-something-changes) e [`$.state`](/docs/pt/plugins/mods/interface#keep-state). Para chamadas `$.clock`, use `mock.clock(on)`, ou seu `$.clock.now()` do mod falha com `no implementation for clock.now`.

172 

173Esta tabela lista as que mods usam mais. A primeira coluna é a chamada que seu mod faz ou o evento que passa com `next(e)`. A segunda é a função para passar para `on` sob esse nome, então a linha `$.store.get` se torna `on('store.get', ($, e) => ({ value: saved.get(e.key) }))`. Um `'...'` em um stub marca texto para você preencher:

174 

175| Seu mod chama ou passa | Stub |

176| :- | :- |

177| `$.command.register`, `$.tool.register`, `$.ui.toast`, `$.ui.log`, `$.ui.status`, `$.ui.close`, `$.store.set` | `() => ({ value: undefined })`. Para `ui.toast` e `ui.log`, o texto é `e.text`. |

178| `$.store.get` | `($, e) => ({ value: saved.get(e.key) })` |

179| `$.fs.read` | `($, e) => ({ value: e.path.endsWith('notes.md') ? '# Notes' : '' })`. `e.path` chega como um caminho absoluto, então compare com `endsWith`. |

180| `$.ui.open` | `() => ({ value: { isPlaced: true } })` |

181| `$.ui.ask` | Um stub `tool.call`, porque a pergunta a alcança como uma chamada para a ferramenta `AskUserQuestion`: `($, e) => ({ result: { answers: { [e.questions[0].question]: 'Run it' } } })`. Verifique `e.tool` primeiro se seu mod passa outras chamadas de ferramenta. |

182| `$.model.complete` | `() => ({ value: { isAnswered: true, text: '...', usage } })` |

183| `$.process.run` | `($, e) => ({ value: { exitCode: 0, stdout: '...', stderr: '' } })`. `e.argv` é a lista de argumentos e `e.init` contém `cwd` e `timeoutMs`. |

184| Qualquer chamada de mods API que deve falhar | `() => ({ deny: 'the reason' })`, que faz a chamada rejeitar em seu mod. Um stub que lança é pulado. |

185| `session.start` | `() => ({ cwd: '/work' })` |

186| `turn.start` | `($, e) => ({ turnId: e.turnId })` |

187| `tool.call` | `() => ({ result: '...' })` |

188| `turn.complete` | `() => ({ text: '' })`. Levante-o com `$.turn.complete({ turnId, answer, durationMs, isAborted: false, usage: null })`. |

189| `prompt.submit` | `($, e) => ({ text: e.text })` |

190| `prompt.fill` | `() => ({ isFilled: true })` |

191| `$.prompt.read` | `() => ({ value: { text: '...', cursor: 0 } })` |

192| `$.ui.copy` | `() => ({ value: { isCopied: true } })` |

193| `$.session.messages` | `() => ({ value: [{ role: 'assistant', text: '...', toolUses: [] }] })` |

194| `$.session.id`, `$.agent.list` | `() => ({ value: 'abc123' })`, `() => ({ value: [] })` |

195| `session.send` | `() => ({ isDelivered: true })`. `e.to` chega como uma string mesmo quando seu mod passou `{ sessionId }`. |

196| `session.receive` | `($, e) => ({ text: e.text })`. Levante-o com `$.session.receive({ origin: { kind: 'peer-send-message' }, text })`. |

197| `ui.render` | `() => ({ type: 'Text', props: {}, children: ['...'] })` |

198 

199`expect` tem as asserções `toBe`, `toEqual`, `toMatch`, `toMatchObject`, `toContain`, `toBeDefined`, `toBeUndefined`, e `toThrow`, e `.not` antes de qualquer uma delas.

200 

201<h2 id="test-a-timer">

202 Testar um temporizador

203</h2>

204 

205Um mod que executa trabalho em um temporizador precisa de um relógio que o teste controla, para que o teste possa avançar o tempo em vez de esperar. `const clock = mock.clock(on)` retorna um relógio simulado que começa em `0` e se move apenas quando seu teste o move. Para começar em outro tempo, passe-o em milissegundos, como em `mock.clock(on, { now: 5000 })`. O relógio tem estes métodos:

206 

207| Método | O que faz |

208| :- | :- |

209| `await clock.advance(1000)` | Avança o tempo por esse número de milissegundos e executa cada temporizador que vence |

210| `await clock.set(5000)` | Avança o tempo para esse valor, como `advance` faria |

211| `clock.now()` | Retorna o tempo, que é o que seu `$.clock.now()` do mod resolve para |

212| `await clock.settle()` | Executa temporizadores que já vencem, como uma cadeia de chamadas `$.clock.after` de zero atraso, sem mover o tempo |

213| `await clock.sleep(2000)` | Dentro de um stub, faz esse stub responder apenas uma vez que o teste avançou tão longe, que é como você simula um modelo ou processo lento |

214 

215Este hook pertence a um mod chamado `countdown`, e trata um comando `/countdown` que leva um número de segundos, inicia um temporizador `$.clock.every` de um segundo, e mostra um toast em zero. Como com `grader`, o arquivo contém apenas o hook sob teste e não registra o comando:

216 

217```javascript countdown/hooks/register.js theme={null}

218export function register(on) {

219 on('command.run', { command: 'countdown' }, async ($, e) => {

220 // e.args is the text typed after /countdown

221 let left = Number(e.args)

222 const timer = $.clock.every(1000, () => {

223 left -= 1

224 if (left === 0) {

225 timer.cancel()

226 $.ui.toast('Time is up')

227 }

228 })

229 // Print nothing in the transcript

230 return {}

231 })

232}

233```

234 

235Este teste executa `/countdown 3` e move o relógio simulado, então verifica três segundos de comportamento sem esperar três segundos:

236 

237```typescript countdown/tests/countdown.test.ts theme={null}

238import { expect, mock, test } from 'claude-code/testing'

239 

240test('the countdown ends with a toast', async ($, on) => {

241 // Answer every $.clock call from a clock the test controls

242 const clock = mock.clock(on)

243 // Collect the text of each toast the mod shows

244 const toasts: string[] = []

245 on('ui.toast', ($, e) => {

246 toasts.push(e.text)

247 return { value: undefined }

248 })

249 

250 await $.command.run({ command: 'countdown', args: '3' })

251 // After two seconds the timer has fired twice, and no toast is due

252 await clock.advance(2000)

253 expect(toasts).toEqual([])

254 // The third second brings the count to zero

255 await clock.advance(1000)

256 expect(toasts).toEqual(['Time is up'])

257})

258```

259 

260O primeiro `expect` mostra que o toast não vem cedo, e o segundo mostra que vem uma vez. Cada `advance` resolve depois que os temporizadores que vencem foram executados, então a verificação na próxima linha vê seu efeito.

261 

262<h2 id="test-a-drawing">

263 Testar um desenho

264</h2>

265 

266Um teste pode desenhar um dos [render sites](/docs/pt/plugins/mods/reference#render-sites) do seu mod, então pressionar, digitar em e encontrar os elementos que desenhou. `$.ui.mount` desenha o site através do hook `ui.render` do seu mod e retorna um identificador com um método para cada um desses. Para cobrir vários aplicativos em um teste, defina `surface` para o aplicativo a desenhar. Este teste abre o painel de [Build a pane with tabs](/docs/pt/plugins/mods/interface#build-a-pane-with-tabs), muda abas, pressiona o botão, e verifica a contagem no terminal e no aplicativo Desktop:

267 

268```typescript hello-tabs/tests/hello-tabs.test.ts theme={null}

269import { expect, test } from 'claude-code/testing'

270 

271// What Claude Code passes to a ui.render hook for this pane, apart from the app

272const PANE = {

273 plugin: 'hello-tabs',

274 component: 'Pane',

275 requestId: 'hello-tabs',

276 viewport: { columns: 100, rows: 30 },

277 props: {

278 title: 'Hello tabs',

279 isFocused: true,

280 bodyColumns: 60,

281 placement: 'inline',

282 scroll: { offset: 0, bodyRows: 10 },

283 view: {},

284 },

285} as const

286 

287test('the second tab counts presses and saves the count', async ($, on) => {

288 // Stub $.store with a Map, so the test can read what the mod saved

289 const saved = new Map<string, unknown>()

290 on('store.get', ($, e) => ({ value: saved.get(e.key) }))

291 on('store.set', ($, e) => {

292 saved.set(e.key, e.value)

293 return { value: undefined }

294 })

295 

296 // Draw the pane once for each app

297 for (const surface of ['terminal', 'desktop'] as const) {

298 const ui = await $.ui.mount({ ...PANE, surface })

299 // Press the buttons by the key the mod gave them

300 await ui.press({ key: 'tab-two' })

301 await ui.press({ key: 'more' })

302 // The second tab's count line is in the drawing

303 expect(await ui.find({ type: 'Text', text: /^Count: \d+$/ })).toBeDefined()

304 await ui.unmount()

305 }

306 

307 // One press in each app makes two

308 expect(saved.get('count')).toBe(2)

309})

310```

311 

312No seu shell, execute `claude plugin test` a partir do diretório `hello-tabs`. O teste passa quando ambos os aplicativos desenham a linha de contagem e o mod salvou `2`. A contagem é transferida do primeiro aplicativo para o segundo porque ambas as montagens usam o mesmo módulo carregado.

313 

314O identificador que `$.ui.mount` retorna tem estes métodos, que endereçam elementos pela `key` que você deu a eles:

315 

316| Método | O que faz |

317| :- | :- |

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

319| `input({ key: 'new-note', text: 'buy milk' })` | Digita o texto no `Input` com essa chave e pressiona Enter. Adicione `kind: 'change'` para digitar sem enviar. |

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

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

322| `unmount()` | Remove o desenho |

323 

324Cada método resolve depois que seu manipulador terminou, então você pode verificar o resultado na próxima linha. Defina `props` para o que Claude Code passaria para esse site. A [tabela de render sites](/docs/pt/plugins/mods/reference#render-sites) lista os props de cada site, e [os tipos para sua compilação](/docs/pt/plugins/mods/create#get-the-types-for-your-build) têm seus tipos.

325 

326Um teste de desenho verifica a árvore que seu hook retorna e se é válida para esse aplicativo. Não verifica como o aplicativo a pinta, então veja um novo layout em uma sessão real também.

327 

328<h3 id="test-a-drawing-after-clear">

329 Testar um desenho após `/clear`

330</h3>

331 

332Cada teste começa com cada valor `$.state` em seu padrão, que é como `/clear` os deixa. Para testar o que seu mod faz a seguir, pule `session.start`, levante `classic.SessionStart` com `source: 'clear'`, e verifique o que seu mod desenha.

333 

334Este teste verifica o módulo de [Load a saved value again after `/clear`](/docs/pt/plugins/mods/interface#load-a-saved-value-again-after-clear). Adicione-o ao arquivo de [Test a drawing](#test-a-drawing), onde `PANE` é definido. O primeiro teste desse arquivo espera que o botão salve a contagem, como o botão em [Save from more than one session](/docs/pt/plugins/mods/interface#save-from-more-than-one-session) faz:

335 

336```typescript hello-tabs/tests/hello-tabs.test.ts theme={null}

337test('the saved count comes back after /clear', async ($, on) => {

338 // The store already holds a count of 7

339 on('store.get', () => ({ value: 7 }))

340 // Answer the event after your hook passes it on with next(e)

341 on('classic.SessionStart', () => ({}))

342 

343 // Raise the event that fires after /clear, which runs your hook

344 await $.classic.SessionStart({ source: 'clear' })

345 

346 const ui = await $.ui.mount({ ...PANE, surface: 'terminal' })

347 await ui.press({ key: 'tab-two' })

348 // The pane shows the stored count, not the default of 0

349 expect(await ui.find({ type: 'Text', text: 'Count: 7' })).toBeDefined()

350})

351```

352 

353O teste passa quando seu hook `classic.SessionStart` copiou o `7` armazenado em `$.state` antes do painel desenhar. Sem esse hook em seu módulo, o painel desenha `Count: 0`, `find` retorna `undefined`, e o teste falha em `toBeDefined`.

354 

355<h2 id="test-a-mod-that-judges-other-mods">

356 Testar um mod que julga outros mods

357</h2>

358 

359Um mod que sua organização lista em [`prependPlugins`](/docs/pt/plugins/mods/admin) pode recusar outro mod antes que ele carregue. Para testar um, defina o nível do seu mod e dê ao teste um segundo mod para o seu admitir ou recusar:

360 

361* **`tier`**: chame-o uma vez no topo do arquivo de teste, como em `tier('prepend')`, para carregar seu mod como `prepend`, `append`, ou `builtin`, seu lugar na [ordem que mods são executados](/docs/pt/plugins/mods/events#the-order-mods-run-in). Sem ele, seu mod carrega como `user`.

362* **`plugins`**: passe `test` um objeto de opções antes do corpo do teste. Seu array `plugins` contém mods que você escreve inline, cada um com um `name` e uma função `register`. Para carregar um em algum lugar diferente de `user`, adicione `tier` a ele.

363 

364Este arquivo de teste carrega o [policy mod da página admin](/docs/pt/plugins/mods/admin#enforce-a-policy-with-a-mod-of-your-own) primeiro. Verifica que o policy mod recusa um mod que inicia um processo e admite um que não:

365 

366```typescript acme-guard/tests/guard.test.ts theme={null}

367import { expect, test, tier } from 'claude-code/testing'

368 

369// Load the mod under test ahead of every other mod

370tier('prepend')

371 

372// A second mod whose code calls $.process.run, which the policy blocks

373const runner = {

374 name: 'runner',

375 register(on) {

376 on('tool.call', async ($, e, next) => {

377 await $.process.run(['ls'])

378 return { result: 'runner answered' }

379 })

380 },

381}

382 

383// A second mod that calls nothing the policy blocks

384const reader = {

385 name: 'reader',

386 register(on) {

387 on('tool.call', async ($, e, next) => {

388 return { result: 'reader answered' }

389 })

390 },

391}

392 

393test('refuses a mod that starts a process', { plugins: [runner] }, async ($, on) => {

394 on('tool.call', () => ({ result: 'claude code answered' }))

395 let message = ''

396 try {

397 // The first call on $ loads the mods, so the refusal is thrown here

398 await $.tool.call({ tool: 'Bash', command: 'ls' })

399 } catch (error) {

400 message = error.message

401 }

402 expect(message).toBe('runner: refused by acme-guard: Acme policy: mods may not call process.run')

403})

404 

405test('admits a mod that starts no process', { plugins: [reader] }, async ($, on) => {

406 on('tool.call', () => ({ result: 'claude code answered' }))

407 const out = await $.tool.call({ tool: 'Bash', command: 'ls' })

408 // The answer comes from reader, which shows that it loaded

409 expect(out).toEqual({ result: 'reader answered' })

410})

411```

412 

413No seu shell, execute `claude plugin test` a partir do diretório `acme-guard`. Ambos os testes passam com o policy mod como a página admin mostra.

414 

415O kit carrega cada mod na primeira chamada do teste em `$`. Quando seu mod recusa um, essa chamada lança, e a mensagem nomeia o mod recusado, o mod que o recusou, e seu motivo. No segundo teste nada é recusado, então `reader` responde a chamada de ferramenta antes que chegue ao stub.

416 

417<h2 id="next-steps">

418 Próximos passos

419</h2>

420 

421* [Troubleshoot a mod](/docs/pt/plugins/mods/troubleshoot): descubra por que um mod não faz nada em uma sessão

422* [Mods reference](/docs/pt/plugins/mods/reference): cada evento de entrada e resultado, para escrever stubs

plugins/mods/troubleshoot.md +284 −0 created

Details

1> ## Documentation Index

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

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

4 

5# Solucionar problemas de um mod

6 

7> Descubra por que um mod Claude Code não faz nada: corresponda o sintoma ou mensagem à sua causa, procure mensagens de recusa e leia o log de depuração.

8 

9Quando um módulo de um mod ou um de seus hooks falha, Claude Code o ignora e a sessão continua, então um mod quebrado pode parecer um que não faz nada. Comece verificando o que Claude Code leu do seu mod e onde ele relata um problema, depois encontre o sintoma ou mensagem que você tem.

10 

11<h2 id="find-out-why-a-mod-does-nothing">

12 Descubra por que um mod não faz nada

13</h2>

14 

15Quando um mod não faz nada, duas verificações encontram o motivo: o que Claude Code lê dos arquivos do mod e a linha que ele escreve quando ignora algo. Para a primeira, em seu shell execute [`claude plugin validate`](/docs/pt/plugins/mods/create#check-what-claude-code-reads-from-your-mod) com o diretório do mod, como em `claude plugin validate ./first-mod`. Isso detecta um evento digitado incorretamente, um manifesto ruim e um módulo que Claude Code não consegue ler, sem iniciar uma sessão.

16 

17Quando um módulo não carrega, um hook é ignorado ou outro mod recusa o seu, Claude Code escreve uma linha que nomeia seu mod. Onde você lê essa linha depende da sessão:

18 

19* **Uma sessão que recarrega dinamicamente um diretório de plugin**: uma linha fraca na transcrição. Essa é uma sessão interativa que você iniciou com `--plugin-dir`, ou uma onde você [habilitou o recarregamento dinâmico](/docs/pt/plugins/mods/create#ask-claude-for-a-mod) para mods que Claude escreveu.

20* **Qualquer outra sessão interativa, como uma que executa um mod que você instalou de um marketplace**: o [log de depuração](#read-the-debug-log) apenas. Para obter um, inicie a sessão com `claude --debug`.

21* **Uma execução `claude -p` com `--plugin-dir`**: stderr, no formato de saída de texto padrão. Uma recusa por outro mod vai apenas para o log de depuração.

22 

23<h2 id="check-whether-mods-can-load">

24 Verifique se os mods podem carregar

25</h2>

26 

27Para verificar se sua configuração permite que os mods carreguem, sem instalar um, execute `claude plugin test` em seu shell, a partir de um diretório que não contenha um mod. Você não precisa de uma sessão. A mensagem que ele imprime informa o estado:

28 

29| A mensagem inclui | O que significa |

30| :- | :- |

31| `no hooks module to load` | Os mods podem carregar. O comando não encontrou nenhum mod para testar neste diretório. |

32| `hooks modules are turned off here` | Uma configuração está mantendo seus mods fora: `disableAllHooks` em suas próprias configurações, ou a política de sua organização |

33| `hooks modules are turned off in this process` | A Anthropic desativou os mods instalados remotamente. Nenhuma configuração em sua máquina os ativa novamente. |

34 

35Uma organização também pode definir `allowManagedModsOnly` para permitir apenas seus próprios mods, o que este comando não relata. Nesse caso, um mod que você instala não carrega, e [uma mensagem diz por quê](/docs/pt/plugins/mods/troubleshoot#messages-from-the-built-in-guard).

36 

37<h2 id="the-mod-doesn’t-load">

38 O mod não carrega

39</h2>

40 

41Nada que o mod adiciona aparece: nenhum comando, nenhum desenho e nenhuma mudança de comportamento.

42 

43<h3 id="your-version-is-older-than-2-1-287">

44 Sua versão é mais antiga que 2.1.287

45</h3>

46 

47`claude --version` imprime uma versão mais antiga que 2.1.287. Sua versão é anterior aos mods estarem ativados por padrão.

48 

49[Atualize Claude Code](/docs/pt/setup#update-claude-code).

50 

51<h3 id="the-mods-active-line-doesn’t-name-the-mod">

52 A linha `mods active` não nomeia o mod

53</h3>

54 

55Nada que o mod adiciona aparece, e a [linha `mods active`](/docs/pt/plugins/mods/overview#see-which-mods-a-session-loaded) em `/plugin` não o nomeia. O módulo hooks não carregou. Quando Claude Code o recusou, o log de depuração tem uma linha que começa com `hooks module`, o nome do mod e `not loaded:`, como em `hooks module first-mod@inline not loaded: disableAllHooks in managed settings` para um mod carregado com `--plugin-dir`.

56 

57Leia o motivo após os dois pontos. A seção [mensagens de recusa](#refusal-messages) lista cada uma. Se o log não tiver tal linha, trabalhe através das outras entradas neste grupo.

58 

59<h3 id="a-claude-p-run-prints-hooks-module-not-loaded">

60 Uma execução `claude -p` imprime `hooks module not loaded`

61</h3>

62 

63A linha começa com o nome do mod e vai para stderr. O módulo hooks foi recusado. Uma execução não interativa não tem transcrição, então a mensagem vai para stderr.

64 

65Leia o motivo após os dois pontos. A seção [mensagens de recusa](#refusal-messages) lista cada uma.

66 

67<h3 id="refusal-messages">

68 Mensagens de recusa

69</h3>

70 

71Cada uma delas segue `hooks module`, o nome do mod e `not loaded:` no log de depuração.

72 

73| A mensagem começa com | O que significa |

74| :- | :- |

75| `hooks modules are turned off for installed plugins in this process` | A Anthropic desativou os mods instalados remotamente. Nenhuma configuração em sua máquina os ativa novamente. |

76| `disableAllHooks in managed settings` | Sua organização desativou hooks de plugins instalados |

77| `only managed plugins and built-in plugins run` | `allowManagedHooksOnly` está definido, ou `disableAllHooks` está definido em um arquivo de configurações diferente de configurações gerenciadas |

78| `installed plugins that are not managed load no hooks module in this mode (--bare)` | Você iniciou Claude Code com `--bare` |

79| `another plugin of that name loads first` | Dois plugins compartilham um nome. O gerenciado, ou o carregado primeiro, é usado. |

80 

81<h3 id="messages-from-the-built-in-guard">

82 Mensagens do guarda integrado

83</h3>

84 

85Em uma máquina com configurações gerenciadas, ou para um usuário conectado com um plano Team ou Enterprise, o [guarda integrado](/docs/pt/plugins/mods/admin#know-what-happens-by-default) pode recusar um mod ou uma de suas respostas. Cada mensagem nomeia a opção que o administrador de sua organização define para alterar a regra.

86 

87| A mensagem contém | O que significa | Onde aparece |

88| :- | :- | :- |

89| `mods are limited to your organization's by policy (allowManagedModsOnly)` | Sua organização permite apenas [seus próprios mods](/docs/pt/plugins/mods/admin#install-your-organizations-mods), então o seu não foi carregado | O log de depuração e a transcrição em uma [sessão que recarrega dinamicamente um diretório de plugin](#find-out-why-a-mod-does-nothing) |

90| `tried to lift a deny rule in your settings` | O hook [`tool.check`](/docs/pt/plugins/mods/reference#tools) do seu mod aprovou uma chamada que uma regra `deny` recusa. A chamada permanece recusada. | A transcrição e o log de depuração, uma vez para cada mod em uma sessão. Em uma execução `claude -p`, apenas o log de depuração. |

91| `the deny rules in your settings could not be checked for this call, so it is refused` | O guarda falhou ao verificar uma chamada que um mod aprovou, então recusou a chamada | O motivo que Claude lê para a chamada recusada |

92 

93<h3 id="validate-passes-and-lists-no-hooks-line">

94 `validate` passa e não lista nenhuma linha `hooks`

95</h3>

96 

97`hooks/hooks.json` não tem uma chave `modules`, ou a chave está digitada incorretamente.

98 

99Adicione `"modules": ["./register.js"]`.

100 

101<h3 id="hooks-module-did-not-load">

102 `hooks module did not load`

103</h3>

104 

105A linha começa com o nome do mod, depois `hooks module did not load:` e um motivo, que fornece o arquivo e a linha quando o problema está em seu código. Claude Code não conseguiu carregar o módulo, por exemplo porque seu código de nível superior lançou.

106 

107Corrija o erro que o motivo nomeia.

108 

109<h3 id="options-do-not-fit-plugin-json-userconfig">

110 `options do not fit plugin.json userConfig`

111</h3>

112 

113A linha começa com o nome do mod, depois `hooks module did not load: options do not fit plugin.json userConfig:` e um motivo. Uma opção não se encaixa em seu campo [`userConfig`](/docs/pt/plugins/components#user-configuration), como um número acima do `max` do campo, ou um campo obrigatório não tem valor.

114 

115Defina ou altere o valor. O final da linha nomeia sua entrada `pluginConfigs` em `settings.json`.

116 

117<h3 id="no-mod-loads-in-a-directory-you-opened-for-the-first-time">

118 Nenhum mod carrega em um diretório que você abriu pela primeira vez

119</h3>

120 

121Você não respondeu ao prompt de confiança para o diretório.

122 

123Inicie uma sessão interativa nesse diretório com `claude` e aceite o prompt de confiança que ele abre.

124 

125<h3 id="no-installed-plugin-loads-at-all">

126 Nenhum plugin instalado carrega

127</h3>

128 

129Você iniciou Claude Code com `--safe-mode`.

130 

131Inicie sem a flag.

132 

133<h2 id="a-hook-is-skipped-or-a-mod-is-unloaded">

134 Um hook é ignorado ou um mod é descarregado

135</h2>

136 

137O mod carregou e então Claude Code ignorou um de seus hooks ou o descarregou.

138 

139<h3 id="hook-skipped">

140 `hook skipped`

141</h3>

142 

143A linha nomeia o mod e o evento, depois diz `hook skipped:` e um motivo, como em `first-mod: tool.call hook skipped: threw Error: boom`. Um hook lançou, executou além de seu [limite de tempo de 10 segundos](/docs/pt/plugins/mods/reference#limits), ou retornou um resultado de forma incorreta. A linha aparece uma vez para cada evento e tipo de falha até o mod recarregar.

144 

145Corrija o erro. O log de depuração tem uma linha para cada ocorrência.

146 

147<h3 id="it-crashed-the-hooks-worker">

148 `it crashed the hooks worker`

149</h3>

150 

151A linha começa com o nome do mod, como em `first-mod was unloaded: it crashed the hooks worker`. Os mods instalados compartilham um thread de worker. O worker parou de responder ou travou, e Claude Code rastreou isso para este mod e o descarregou. Um hook que bloqueia a thread, como um loop que nunca aguarda, é uma causa.

152 

153Corrija o hook.

154 

155<h3 id="mods-that-run-in-the-hooks-worker-are-off-for-this-session">

156 `mods that run in the hooks worker are off for this session`

157</h3>

158 

159A linha lê `hooks: mods that run in the hooks worker are off for this session: it crashed 3 times`. O worker parou três vezes e Claude Code não conseguiu rastrear as paradas para um mod, então descarregou cada mod que não é integrado, incluindo mods que sua organização instala. Esta linha chega à transcrição em cada sessão interativa.

160 

161Execute `/reload-plugins` para carregá-los novamente.

162 

163<h2 id="a-tool-call-is-denied">

164 Uma chamada de ferramenta é recusada

165</h2>

166 

167O mod carregou e seus hooks executam, e uma chamada de ferramenta que ele tocou é recusada.

168 

169<h3 id="a-hook-changed-this-call’s-input-after-the-model-wrote-it">

170 `a hook changed this call's input after the model wrote it`

171</h3>

172 

173Em modo automático, uma chamada de ferramenta recusada fornece este motivo. Um hook alterou a entrada da chamada de ferramenta após o [classificador do lado do servidor](/docs/pt/permission-modes#server-side-classifier-review) revisá-la, então essa revisão não cobre o que seria executado. O hook pode ser um [`tool.call`](/docs/pt/plugins/mods/reference#tools) ou [`turn.step`](/docs/pt/plugins/mods/reference#turns) hook do mod, ou um hook de configurações [`PreToolUse`](/docs/pt/hooks#pretooluse). A mensagem não diz qual.

174 

175A mensagem diz a Claude para emitir a chamada novamente conforme registrado. Se isso também for recusado, o hook altera a entrada toda vez, então desative o mod ou hook, ou saia do modo automático e aprove a chamada você mesmo.

176 

177<h3 id="a-message-about-the-deny-rules-in-your-settings">

178 Uma mensagem sobre as regras de negação em suas configurações

179</h3>

180 

181`tried to lift a deny rule in your settings` e `the deny rules in your settings could not be checked for this call, so it is refused` ambas vêm do guarda integrado.

182 

183Procure-as em [Mensagens do guarda integrado](#messages-from-the-built-in-guard).

184 

185<h2 id="a-drawing-doesn’t-appear-or-respond">

186 Um desenho não aparece ou responde

187</h2>

188 

189O mod carregou e seu painel, banda ou controles não se comportam como você espera.

190 

191<h3 id="a-pane-or-band-is-empty-or-shows-claude-code’s-usual-content">

192 Um painel ou banda está vazio ou mostra o conteúdo usual de Claude Code

193</h3>

194 

195A [árvore](/docs/pt/plugins/mods/interface#build-a-tree-from-elements) que seu hook retornou não validou. Com `--plugin-dir`, a transcrição diz `ui.render (Pane) refused:` com o motivo, como em `first-mod: ui.render (Pane) refused: Box prop "flexDirection" must be one of row, column, row-reverse, column-reverse; the engine drew its own`. O log de depuração tem `a hook returned a tree that does not validate` com o mesmo motivo.

196 

197Leia 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.

198 

199<h3 id="ui-open-runs-and-no-pane-appears">

200 `$.ui.open` executa e nenhum painel aparece

201</h3>

202 

203A chamada não veio de algo que o usuário fez, e o terminal é mais estreito que 144 colunas.

204 

205Abra o painel a partir de um comando ou botão, ou verifique o resultado `isPlaced` da chamada. Veja [Abrir um painel no momento certo](/docs/pt/plugins/mods/interface#open-a-pane-at-the-right-time).

206 

207<h3 id="hotkeys-do-nothing">

208 Hotkeys não fazem nada

209</h3>

210 

211Seu painel não tem foco de teclado.

212 

213Pressione Ctrl+X depois Tab, ou clique no painel. Abra-o com `focus: true` a partir de um comando.

214 

215<h3 id="a-drawing-works-in-the-terminal-and-not-in-the-desktop-app">

216 Um desenho funciona no terminal e não no aplicativo Desktop

217</h3>

218 

219O site ou elemento não está disponível lá.

220 

221Verifique as [render sites](/docs/pt/plugins/mods/reference#render-sites) e tabelas de [elementos](/docs/pt/plugins/mods/reference#elements).

222 

223<h2 id="an-edit-or-a-value-is-lost">

224 Uma edição ou um valor é perdido

225</h2>

226 

227O mod executa e uma mudança que você fez ou um valor que ele manteve não está lá.

228 

229<h3 id="your-edits-don’t-take-effect">

230 Suas edições não entram em vigor

231</h3>

232 

233Você está editando um plugin que instalou. Claude Code executa a cópia em cache para a versão instalada.

234 

235Desenvolva com `--plugin-dir` apontado para sua cópia de trabalho, como em `claude --plugin-dir ./first-mod`, que recarrega quando você salva.

236 

237<h3 id="a-value-resets-when-the-module-reloads">

238 Um valor é redefinido quando o módulo recarrega

239</h3>

240 

241Variáveis de nível de módulo são reinicializadas em cada recarregamento.

242 

243[Mantenha o valor em `$.state` ou `$.store`](/docs/pt/plugins/mods/interface#keep-state).

244 

245<h3 id="a-value-resets-after-/clear-/resume-or-/branch">

246 Um valor é redefinido após `/clear`, `/resume` ou `/branch`

247</h3>

248 

249Um valor é redefinido, ou um valor salvo é substituído por seu padrão. Cada um desses comandos redefine `$.state` para seus padrões, e `session.start` não dispara novamente.

250 

251[Carregue o valor salvo novamente](/docs/pt/plugins/mods/interface#load-a-saved-value-again-after-clear) em um hook `classic.SessionStart`.

252 

253<h2 id="read-the-debug-log">

254 Leia o log de depuração

255</h2>

256 

257O 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:

258 

259```bash theme={null}

260claude --debug-file ./mod-debug.log --plugin-dir ./first-mod

261```

262 

263Em outro terminal, siga o arquivo e filtre pelo nome do seu mod:

264 

265```bash theme={null}

266tail -f ./mod-debug.log | grep first-mod

267```

268 

269Um mod que carregou tem uma linha que o nomeia e lista os eventos que ele conecta. Um mod carregado com `--plugin-dir` aparece sob seu nome seguido por `@inline`:

270 

271```text theme={null}

272hooks module first-mod@inline loaded (worker, environment 2, tier user); events: session.start,tool.call,command.run,ui.render

273```

274 

275Um desenho que não validou conta como um resultado recusado e também recebe uma linha. Para escrever suas próprias linhas no log, chame [`$.ui.log`](/docs/pt/plugins/mods/api#show-something-without-starting-a-turn) com um segundo argumento, como em `$.ui.log('message', { to: 'debug' })`. Sem o segundo argumento, `$.ui.log` adiciona uma linha fraca à transcrição.

276 

277Enquanto você edita um mod carregado com `--plugin-dir`, a transcrição mostra uma linha para cada recarregamento que nomeia o mod e lista seus hooks. Se um salvamento quebrar o módulo, a linha diz `reload failed, the previous version stays loaded:` com o motivo, e a última versão de trabalho continua executando.

278 

279<h2 id="next-steps">

280 Próximas etapas

281</h2>

282 

283* [Teste um mod](/docs/pt/plugins/mods/test): detecte problemas antes que eles cheguem a uma sessão

284* [Solucionar problemas de plugins](/docs/pt/plugins/troubleshooting): problemas com instalação e carregamento de um plugin que não são específicos de mods

plugins/org.md +4 −1

Details

212| `pluginTrustMessage` | Anexa seu texto ao aviso de confiança que `/plugin` mostra antes de um plugin instalar | Não muda o próprio texto do aviso |212| `pluginTrustMessage` | Anexa seu texto ao aviso de confiança que `/plugin` mostra antes de um plugin instalar | Não muda o próprio texto do aviso |

213| `allowedChannelPlugins` | Substitui a lista padrão de plugins permitidos para enviar mensagens de canal. Requer `channelsEnabled: true` | Veja [Restrict which channel plugins can run](/docs/pt/channels#restrict-which-channel-plugins-can-run) |213| `allowedChannelPlugins` | Substitui a lista padrão de plugins permitidos para enviar mensagens de canal. Requer `channelsEnabled: true` | Veja [Restrict which channel plugins can run](/docs/pt/channels#restrict-which-channel-plugins-can-run) |

214| [`CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL=1`](/docs/pt/env-vars) | Para sessões de terminal interativas de auto-registrar o marketplace oficial | Não remove um marketplace já registrado. A allowlist e blocklist controlam o mesmo auto-registro sem ele. Uma máquina que começou uma vez com ele definido não retoma auto-registro depois que você o desdefine |214| [`CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL=1`](/docs/pt/env-vars) | Para sessões de terminal interativas de auto-registrar o marketplace oficial | Não remove um marketplace já registrado. A allowlist e blocklist controlam o mesmo auto-registro sem ele. Uma máquina que começou uma vez com ele definido não retoma auto-registro depois que você o desdefine |

215| [`allowManagedModsOnly`](/docs/pt/plugins/mods/admin#stop-user-installed-mods-from-loading) | Para cada [mod](/docs/pt/plugins/mods/overview) instalado que não [conta como da sua organização](/docs/pt/plugins/mods/admin#install-your-organizations-mods) de carregar | Não para um plugin que contém um mod de instalar. Para isso, use as chaves de marketplace nesta tabela |

215 216 

216Cada chave na tabela é uma configuração gerenciada, exceto `enabledPlugins`, `syncClaudeAiPlugins` e `CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL`:217Cada chave na tabela é uma configuração gerenciada, exceto `enabledPlugins`, `syncClaudeAiPlugins`, `CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL` e `allowManagedModsOnly`:

217 218 

218* **`enabledPlugins`**: você pode defini-lo em qualquer escopo, e as configurações gerenciadas o bloqueiam.219* **`enabledPlugins`**: você pode defini-lo em qualquer escopo, e as configurações gerenciadas o bloqueiam.

219* **`syncClaudeAiPlugins`**: cada usuário também pode defini-lo em suas próprias configurações de usuário ou local. Veja seu [escopo na referência de configurações](/docs/pt/settings-reference#syncclaudeaiplugins).220* **`syncClaudeAiPlugins`**: cada usuário também pode defini-lo em suas próprias configurações de usuário ou local. Veja seu [escopo na referência de configurações](/docs/pt/settings-reference#syncclaudeaiplugins).

220* **`CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL`**: esta é uma variável de ambiente que você entrega através do bloco `env` gerenciado mostrado sob [Turn updates off for the whole fleet](#turn-updates-off-for-the-whole-fleet).221* **`CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL`**: esta é uma variável de ambiente que você entrega através do bloco `env` gerenciado mostrado sob [Turn updates off for the whole fleet](#turn-updates-off-for-the-whole-fleet).

222* **`allowManagedModsOnly`**: esta é uma opção em um plugin built-in, que você define sob `pluginConfigs` em configurações gerenciadas. Veja [Stop user-installed mods from loading](/docs/pt/plugins/mods/admin#stop-user-installed-mods-from-loading).

221 223 

222Cada chave de configurações aqui tem uma entrada na [referência de configurações](/docs/pt/settings-reference).224Cada chave de configurações aqui tem uma entrada na [referência de configurações](/docs/pt/settings-reference).

223 225 


457* [Marketplace reference](/docs/pt/plugins/marketplace-reference#marketplace-sources): os valores `source` que `extraKnownMarketplaces`, `strictKnownMarketplaces` e `blockedMarketplaces` aceitam459* [Marketplace reference](/docs/pt/plugins/marketplace-reference#marketplace-sources): os valores `source` que `extraKnownMarketplaces`, `strictKnownMarketplaces` e `blockedMarketplaces` aceitam

458* [Host and maintain a marketplace](/docs/pt/plugins/host-marketplace): execute o marketplace que sua política aponta460* [Host and maintain a marketplace](/docs/pt/plugins/host-marketplace): execute o marketplace que sua política aponta

459* [Plugin security and trust](/docs/pt/plugins/security): o que um plugin pode fazer em uma máquina e como revisar um antes de instalar461* [Plugin security and trust](/docs/pt/plugins/security): o que um plugin pode fazer em uma máquina e como revisar um antes de instalar

462* [Manage mods for your organization](/docs/pt/plugins/mods/admin): desative ou limite mods, os plugins que executam JavaScript dentro do Claude Code

460* [Server-managed settings](/docs/pt/server-managed-settings): entregue essas chaves do console de administração do claude.ai463* [Server-managed settings](/docs/pt/server-managed-settings): entregue essas chaves do console de administração do claude.ai

461* [Troubleshoot plugins](/docs/pt/plugins/troubleshooting#blocked-by-your-organization): as mensagens que os usuários veem quando a política os bloqueia464* [Troubleshoot plugins](/docs/pt/plugins/troubleshooting#blocked-by-your-organization): as mensagens que os usuários veem quando a política os bloqueia

Details

30* [**Skills**](/docs/pt/plugins/components#skills): instruções `SKILL.md` que Claude carrega quando relevante, e que você também pode executar como um comando30* [**Skills**](/docs/pt/plugins/components#skills): instruções `SKILL.md` que Claude carrega quando relevante, e que você também pode executar como um comando

31* [**Agents**](/docs/pt/plugins/components#agents): definições de subagentes que Claude pode delegar31* [**Agents**](/docs/pt/plugins/components#agents): definições de subagentes que Claude pode delegar

32* [**Hooks**](/docs/pt/plugins/components#hooks): comandos que Claude Code executa em pontos do seu ciclo de vida, como após cada edição32* [**Hooks**](/docs/pt/plugins/components#hooks): comandos que Claude Code executa em pontos do seu ciclo de vida, como após cada edição

33* [**Um módulo de hooks**](/docs/pt/plugins/mods/overview): hooks escritos como funções JavaScript, que também podem desenhar painéis e adicionar comandos. Um plugin que tem um é chamado de mod

33* [**MCP servers**](/docs/pt/plugins/components#mcp-servers): servidores de ferramentas aos quais Claude Code se conecta enquanto o plugin está ativado34* [**MCP servers**](/docs/pt/plugins/components#mcp-servers): servidores de ferramentas aos quais Claude Code se conecta enquanto o plugin está ativado

34 35 

35Este diagrama mostra um plugin chamado `my-plugin` que contém um de cada um desses componentes, e o que você obtém de cada arquivo uma vez que o plugin é carregado.36Este diagrama mostra um plugin chamado `my-plugin` que contém uma skill, um agente, hooks e um servidor MCP, e o que você obtém de cada arquivo uma vez que o plugin é carregado.

36 37 

37<img src="https://mintcdn.com/claude-code/2Q_GtOEovg5qaBem/images/plugin-directory.svg?fit=max&auto=format&n=2Q_GtOEovg5qaBem&q=85&s=f623b64e82713b830e48174f0a922888" className="dark:hidden" alt="Diagrama em duas colunas unidas por cinco setas retas. À esquerda, o diretório de um plugin chamado my-plugin, contendo um manifesto em .claude-plugin/plugin.json, skills/review/SKILL.md, agents/reviewer.md, hooks/hooks.json, .mcp.json e outros componentes. À direita, o que cada arquivo oferece em sua sessão: o manifesto define o nome do plugin, my-plugin; a skill é executada como /my-plugin:review; o arquivo do agente é um subagente que Claude pode delegar; o arquivo de hooks contém hooks que são executados em eventos do ciclo de vida; e .mcp.json adiciona um servidor MCP que oferece ferramentas a Claude." width="760" height="336" data-path="images/plugin-directory.svg" />38<img src="https://mintcdn.com/claude-code/2Q_GtOEovg5qaBem/images/plugin-directory.svg?fit=max&auto=format&n=2Q_GtOEovg5qaBem&q=85&s=f623b64e82713b830e48174f0a922888" className="dark:hidden" alt="Diagrama em duas colunas unidas por cinco setas retas. À esquerda, o diretório de um plugin chamado my-plugin, contendo um manifesto em .claude-plugin/plugin.json, skills/review/SKILL.md, agents/reviewer.md, hooks/hooks.json, .mcp.json e outros componentes. À direita, o que cada arquivo oferece em sua sessão: o manifesto define o nome do plugin, my-plugin; a skill é executada como /my-plugin:review; o arquivo do agente é um subagente que Claude pode delegar; o arquivo de hooks contém hooks que são executados em eventos do ciclo de vida; e .mcp.json adiciona um servidor MCP que oferece ferramentas a Claude." width="760" height="336" data-path="images/plugin-directory.svg" />

38 39 

Details

29Um plugin pode conter conteúdo que executa código em sua máquina com seus privilégios de usuário e conteúdo que entra no contexto do Claude como instruções, portanto [revise um plugin antes de instalá-lo](#review-a-plugin-before-you-install). Aqui está o que um plugin instalado pode fazer:29Um plugin pode conter conteúdo que executa código em sua máquina com seus privilégios de usuário e conteúdo que entra no contexto do Claude como instruções, portanto [revise um plugin antes de instalá-lo](#review-a-plugin-before-you-install). Aqui está o que um plugin instalado pode fazer:

30 30 

31* **Hooks**: os [hooks](/docs/pt/hooks) de um plugin são executados como comandos shell em pontos do ciclo de vida do Claude Code, como antes ou depois de uma chamada de ferramenta.31* **Hooks**: os [hooks](/docs/pt/hooks) de um plugin são executados como comandos shell em pontos do ciclo de vida do Claude Code, como antes ou depois de uma chamada de ferramenta.

32* **Mods**: um [mod](/docs/pt/plugins/mods/overview) de um plugin executa JavaScript dentro do Claude Code com suas permissões. Para listar o que um mod faz antes de instalá-lo, veja [Decida se confia em um mod](/docs/pt/plugins/mods/overview#decide-whether-to-trust-a-mod).

32* **Servidores MCP e LSP**: Claude Code se conecta aos [servidores MCP](/docs/pt/mcp) que um plugin habilitado declara e fornece ao Claude suas ferramentas. Um servidor MCP stdio é executado como um processo que Claude Code inicia em sua máquina. Claude Code também inicia os servidores de linguagem que o plugin declara.33* **Servidores MCP e LSP**: Claude Code se conecta aos [servidores MCP](/docs/pt/mcp) que um plugin habilitado declara e fornece ao Claude suas ferramentas. Um servidor MCP stdio é executado como um processo que Claude Code inicia em sua máquina. Claude Code também inicia os servidores de linguagem que o plugin declara.

33* **Diretório `bin/`**: Claude Code adiciona o diretório `bin/` de cada plugin habilitado ao `PATH` do shell da ferramenta Bash, para que os comandos Bash do Claude possam executar qualquer executável lá.34* **Diretório `bin/`**: Claude Code adiciona o diretório `bin/` de cada plugin habilitado ao `PATH` do shell da ferramenta Bash, para que os comandos Bash do Claude possam executar qualquer executável lá.

34* **Skills, comandos e agentes**: estes entram no contexto do Claude como instruções, portanto influenciam o que Claude faz com as ferramentas que já possui.35* **Skills, comandos e agentes**: estes entram no contexto do Claude como instruções, portanto influenciam o que Claude faz com as ferramentas que já possui.


37As [regras de permissão](/docs/pt/permissions) e [sandbox](/docs/pt/sandboxing) do Claude Code cobrem as chamadas de ferramenta que Claude faz, não o código que um plugin executa por si só:38As [regras de permissão](/docs/pt/permissions) e [sandbox](/docs/pt/sandboxing) do Claude Code cobrem as chamadas de ferramenta que Claude faz, não o código que um plugin executa por si só:

38 39 

39* **Hooks e processos de servidor**: command hooks executam comandos shell com suas permissões completas de usuário. Claude Code executa hooks e servidores MCP fora da sandbox.40* **Hooks e processos de servidor**: command hooks executam comandos shell com suas permissões completas de usuário. Claude Code executa hooks e servidores MCP fora da sandbox.

40* **Chamadas de ferramenta do Claude**: uma chamada para uma das ferramentas MCP do plugin e um comando Bash que executa um executável do `bin/` do plugin são chamadas de ferramenta, portanto suas regras de permissão se aplicam a elas.41* **Chamadas de ferramenta do Claude**: uma chamada para uma das ferramentas MCP do plugin e um comando Bash que executa um executável do `bin/` do plugin são chamadas de ferramenta, portanto suas regras de permissão se aplicam a elas. Para o que um mod pode fazer em uma chamada de ferramenta, veja [Decida se confia em um mod](/docs/pt/plugins/mods/overview#decide-whether-to-trust-a-mod).

41 42 

42Instalar um plugin também o habilita, a menos que seu manifesto ou entrada de marketplace defina [`defaultEnabled: false`](/docs/pt/plugins/install#choose-an-install-scope) e você não o tenha habilitado você mesmo.43Instalar um plugin também o habilita, a menos que seu manifesto ou entrada de marketplace defina [`defaultEnabled: false`](/docs/pt/plugins/install#choose-an-install-scope) e você não o tenha habilitado você mesmo.

43 44 

Details

201 201 

202Uma adição bem-sucedida imprime `Successfully added marketplace: <name>`.202Uma adição bem-sucedida imprime `Successfully added marketplace: <name>`.

203 203 

204<h3 id="invalid-git-url">

205 `Invalid git URL`

206</h3>

207 

208Você adicionou um marketplace, instalou um plugin ou executou uma atualização a partir de um endereço git, e o comando falhou com `Invalid git URL` em sua mensagem.

209 

210Claude Code verifica cada endereço git antes de executar git. Ele recusa um endereço cujo protocolo não suporta. Ele também recusa um endereço que git poderia ler como nomeando um servidor ou pasta diferente do que o endereço mostra.

211 

212O texto após o endereço nomeia o que mudar. Reescreva o endereço como a mensagem diz e execute o comando novamente.

213 

214Uma recusa que em vez disso diz `is blocked by enterprise policy` vem das configurações da sua organização. Veja [Marketplace source is blocked by enterprise policy](#marketplace-source-is-blocked-by-enterprise-policy).

215 

204<h3 id="path-does-not-exist">216<h3 id="path-does-not-exist">

205 `Path does not exist: <path>`217 `Path does not exist: <path>`

206</h3>218</h3>


410 422 

411`claude plugin install` no seu shell imprime uma mensagem diferente. Para um plugin já instalado no escopo de destino, imprime `Plugin "<name>@<marketplace>" is already installed (scope: user)` e sai com 0. Se seu diretório de cache está faltando, o mesmo comando o re-baixa.423`claude plugin install` no seu shell imprime uma mensagem diferente. Para um plugin já instalado no escopo de destino, imprime `Plugin "<name>@<marketplace>" is already installed (scope: user)` e sai com 0. Se seu diretório de cache está faltando, o mesmo comando o re-baixa.

412 424 

425<h3 id="plugin-would-share-its-folder">

426 `"<plugin>" was not installed: it would share its folder with "<other>"`

427</h3>

428 

429Você instalou um plugin através de `claude plugin install`, `/plugin`, ou uma sugestão de instalação em uma sessão, e Claude Code o recusou com esta linha, ou com `would share its saved data with`.

430 

431O id do plugin recusado e o id de um plugin instalado mapeiam para a mesma pasta no disco: eles são os mesmos uma vez que `.` e `@` são escritos como `-`. No macOS e Windows, ids que diferem apenas em maiúsculas mapeiam para a mesma pasta também. Instalar ambos colocaria os arquivos de um plugin na pasta do outro, então Claude Code recusa e o plugin instalado mantém seus arquivos.

432 

433A mensagem nomeia a saída:

434 

435* **O outro plugin está instalado**: a mensagem diz `Only one of the two can be installed.` e nomeia o comando `claude plugin uninstall`, ou o passo de desinstalação em `/plugin`, que remove o outro plugin. Execute-o, depois instale novamente. Para o que a desinstalação remove, veja [What an uninstall deletes and keeps](/docs/pt/plugins/cli-reference#what-an-uninstall-deletes-and-keeps).

436* **Ambos os ids chegam em uma instalação**, como um plugin e uma dependência que ele precisa: nenhuma ordem de instalação ajuda. Apenas um mantenedor do marketplace que lista os dois plugins pode corrigi-lo, renomeando um deles. Quando os dois vêm de marketplaces diferentes, um mantenedor de qualquer um deles pode.

437 

413<h3 id="this-plugin-uses-a-source-type-your-claude-code-version-does-not-suppo">438<h3 id="this-plugin-uses-a-source-type-your-claude-code-version-does-not-suppo">

414 `This plugin uses a source type your Claude Code version does not support`439 `This plugin uses a source type your Claude Code version does not support`

415</h3>440</h3>


790* **`URL is unset or invalid`**: uma opção `${user_config.*}` que a URL usa não está definida. Execute `/plugin configure <plugin>` para defini-la815* **`URL is unset or invalid`**: uma opção `${user_config.*}` que a URL usa não está definida. Execute `/plugin configure <plugin>` para defini-la

791* **`has an invalid MCP url`** ou **`headersHelper for MCP server '<server>' references ${user_config.*}`**: a configuração do próprio plugin está em falta. Corrija a `url` ou `headersHelper` em sua configuração MCP do plugin, ou relate ao autor do plugin se o plugin não é seu. O caso `headersHelper` tem sua própria entrada em [plugin command references user\_config](/docs/pt/errors#plugin-command-references-user-config)816* **`has an invalid MCP url`** ou **`headersHelper for MCP server '<server>' references ${user_config.*}`**: a configuração do próprio plugin está em falta. Corrija a `url` ou `headersHelper` em sua configuração MCP do plugin, ou relate ao autor do plugin se o plugin não é seu. O caso `headersHelper` tem sua própria entrada em [plugin command references user\_config](/docs/pt/errors#plugin-command-references-user-config)

792 817 

818<h4 id="bundled-mcp-server-name-was-not-started-it-needs-configuration">

819 `Bundled MCP server "<name>" was not started: it needs configuration`

820</h4>

821 

822O plugin inclui o servidor como um [bundle MCPB](/docs/pt/plugins/components#include-a-packaged-mcpb-server) que declara `user_config`, e uma configuração obrigatória não tem valor salvo ainda ou um valor salvo falha na validação do próprio bundle, então Claude Code pula o início do servidor. O resto do plugin funciona.

823 

824Selecione o plugin na aba **Installed** do `/plugin` e escolha **Configure** para fornecer os valores. Depois que você salvar, `/plugin` mostra `Configuration saved.` e fecha, e Claude Code recarrega plugins conforme descrito em [Gerenciar plugins instalados](/docs/pt/plugins/install#manage-installed-plugins). O servidor inicia uma vez que esse reload se aplica. Antes da v2.1.285, Claude Code pulava o servidor sem mostrar esta linha.

825 

793<h4 id="server-is-configured-but-never-connects">826<h4 id="server-is-configured-but-never-connects">

794 Server is configured but never connects827 Server is configured but never connects

795</h4>828</h4>


934 967 

935Seu plugin declara opções `userConfig`, mas nenhum diálogo de configuração aparece quando você o instala.968Seu plugin declara opções `userConfig`, mas nenhum diálogo de configuração aparece quando você o instala.

936 969 

937A instalação interativa mostra o diálogo, e o comando de shell leva os valores como sinalizadores em vez disso:970Se a instalação solicita os valores depende de onde você a executa:

938 971 

939* **`/plugin install` em uma sessão, ou a aba Discover em `/plugin`**: o diálogo é parte desta instalação interativa972* **`/plugin install` em uma sessão, ou a aba Discover em `/plugin`**: o diálogo é parte desta instalação interativa

973* **O diálogo Manage plugins da extensão VS Code**: solicita opções não definidas como um formulário após a instalação. Antes da v2.1.285, instalar lá não mostrava formulário de opções, então defina os valores a partir de uma sessão de terminal com `/plugin configure <plugin>@<marketplace>`

940* **`claude plugin install` no seu shell**: nunca pede valores `userConfig`. Salva qualquer valor `--config KEY=VALUE` que você passa, e quando opções permanecem não definidas imprime `N userConfig options not yet set — run /plugin configure <plugin>@<marketplace> in Claude Code, or pass --config KEY=VALUE.` Quando qualquer uma das opções não definidas é obrigatória, `(M required)` segue `not yet set`.974* **`claude plugin install` no seu shell**: nunca pede valores `userConfig`. Salva qualquer valor `--config KEY=VALUE` que você passa, e quando opções permanecem não definidas imprime `N userConfig options not yet set — run /plugin configure <plugin>@<marketplace> in Claude Code, or pass --config KEY=VALUE.` Quando qualquer uma das opções não definidas é obrigatória, `(M required)` segue `not yet set`.

941 975 

942Se você instalou a partir do shell, passe os valores com `--config`, um sinalizador por opção:976Se você instalou a partir do shell, passe os valores com `--config`, um sinalizador por opção:


945claude plugin install my-plugin@my-marketplace --config api_url=https://example.com979claude plugin install my-plugin@my-marketplace --config api_url=https://example.com

946```980```

947 981 

948Quando cada opção está definida, a saída de instalação não carrega nenhuma linha `not yet set`. Para abrir o diálogo depois em vez disso, execute `/plugin configure my-plugin@my-marketplace` em uma sessão.982Quando cada opção está definida, a saída de instalação não carrega nenhuma linha `not yet set`.

983 

984Para abrir o diálogo depois em vez disso, execute `/plugin configure my-plugin@my-marketplace` em uma sessão. A partir do shell, [`claude plugin configure`](/docs/pt/plugins/cli-reference#plugin-configure) mostra quais opções ainda estão não definidas e salva valores canalizados em stdin. Requer Claude Code v2.1.285 ou posterior.

949 985 

950Se você passar uma chave `--config` que o manifesto não declara, o plugin ainda instala, e o comando imprime `⚠ Installed, but --config not applied: --config key "<key>" isn't declared in this plugin's userConfig.` seguido pelas chaves que o plugin declara.986Se você passar uma chave `--config` que o manifesto não declara, o plugin ainda instala, e o comando imprime `⚠ Installed, but --config not applied: --config key "<key>" isn't declared in this plugin's userConfig.` seguido pelas chaves que o plugin declara.

951 987 

988Para um plugin que envia um [arquivo de pacote MCPB](/docs/pt/plugins/components#include-a-packaged-mcpb-server) declarando `user_config` próprio, a mensagem lê `isn't declared in this plugin's userConfig or by its bundled MCP servers.` em vez disso, e as chaves conhecidas incluem as chaves desse servidor, escritas `<server>.<key>`. Um pacote que o manifesto referencia por URL não é lido no tempo de instalação, então suas chaves não estão listadas e a mensagem diz para configurá-lo em `/plugin`. Definir chaves `<server>.<key>` requer Claude Code v2.1.285 ou posterior.

989 

952<h3 id="claude-plugin-validate-reports-errors">990<h3 id="claude-plugin-validate-reports-errors">

953 `claude plugin validate` reports errors991 `claude plugin validate` reports errors

954</h3>992</h3>


968| `Path contains ".." which could be a path traversal attempt: <path>` | Um caminho de componente escapa do diretório do plugin. | Use caminhos dentro da raiz do plugin. |1006| `Path contains ".." which could be a path traversal attempt: <path>` | Um caminho de componente escapa do diretório do plugin. | Use caminhos dentro da raiz do plugin. |

969| `Path is a file; skills entries must be directories containing SKILL.md` | Uma entrada `skills` aponta para `SKILL.md` em vez de seu diretório. | Aponte para o diretório pai, ou `.` para um `SKILL.md` no nível raiz. |1007| `Path is a file; skills entries must be directories containing SKILL.md` | Uma entrada `skills` aponta para `SKILL.md` em vez de seu diretório. | Aponte para o diretório pai, ou `.` para um `SKILL.md` no nível raiz. |

970| `No frontmatter block found` ou `YAML frontmatter failed to parse: <error>` | Um arquivo de skill, agent ou comando tem frontmatter YAML faltando ou inválido. | Adicione ou corrija o frontmatter entre delimitadores `---`. Relatado ao validar um diretório de plugin. |1008| `No frontmatter block found` ou `YAML frontmatter failed to parse: <error>` | Um arquivo de skill, agent ou comando tem frontmatter YAML faltando ou inválido. | Adicione ou corrija o frontmatter entre delimitadores `---`. Relatado ao validar um diretório de plugin. |

1009| `Plugin name "<name>" is reserved: it passes as one of Anthropic's own` | O nome `name` do plugin é um dos [nomes reservados](/docs/pt/plugins/manifest-reference#name). | Renomeie o plugin para o que ele faz. |

971| `Unknown field '<key>'` | O manifesto tem um campo que o schema não define. | Remova-o, ou use o nome que a mensagem sugere. Claude Code ignora campos desconhecidos no tempo de carregamento. |1010| `Unknown field '<key>'` | O manifesto tem um campo que o schema não define. | Remova-o, ou use o nome que a mensagem sugere. Claude Code ignora campos desconhecidos no tempo de carregamento. |

972 1011 

973Execute o comando novamente após cada correção até que imprima sem erros.1012Execute o comando novamente após cada correção até que imprima sem erros.

Details

84<span id="loop-provider-differences" />84<span id="loop-provider-differences" />

85 85 

86<Note>86<Note>

87 Intervalos escolhidos dinamicamente e o [prompt de manutenção integrado](#run-the-built-in-maintenance-prompt) funcionam em todos os provedores, e com [busca de sinalizador de recurso](/docs/pt/env-vars#features-that-need-feature-flag-fetching) desativada. No Amazon Bedrock, Claude Platform no AWS, Google Cloud's Agent Platform e Microsoft Foundry, ou com busca desativada, ambos exigem Claude Code v2.1.248 ou posterior. Nesses casos, em versões anteriores, um prompt sem intervalo é executado em um cronograma fixo de 10 minutos, e um `/loop` sem prompt imprime a mensagem de uso.87 Intervalos escolhidos dinamicamente e o [prompt de manutenção integrado](#run-the-built-in-maintenance-prompt) funcionam em todos os provedores, e com [busca de sinalizador de recurso](/docs/pt/env-vars#features-that-need-feature-flag-fetching) desativada. No Amazon Bedrock, Claude Platform no AWS, Google Cloud's Agent Platform e Microsoft Foundry, ou com busca desativada, ambos exigem Claude Code v2.1.248 ou posterior.

88</Note>88</Note>

89 89 

90<h3 id="run-the-built-in-maintenance-prompt">90<h3 id="run-the-built-in-maintenance-prompt">

Details

87Um runner serve um proprietário por vez. A primeira sessão que um runner pega bloqueia o runner para o proprietário dessa sessão, e o runner então executa sessões apenas para esse proprietário, até uma capacidade configurada. Quem é o proprietário depende de como a sessão foi iniciada:87Um runner serve um proprietário por vez. A primeira sessão que um runner pega bloqueia o runner para o proprietário dessa sessão, e o runner então executa sessões apenas para esse proprietário, até uma capacidade configurada. Quem é o proprietário depende de como a sessão foi iniciada:

88 88 

89* **Sessões que um usuário inicia**: o proprietário é a conta desse usuário.89* **Sessões que um usuário inicia**: o proprietário é a conta desse usuário.

90* **Sessões de canal Claude Tag**: Claude as executa sem nenhuma conta de usuário anexada, portanto o proprietário é o [agente Claude Tag](https://claude.com/docs/claude-tag/concepts/glossary#agent-identity) que iniciou a sessão. Cada sessão de canal que esse agente inicia tem o mesmo proprietário, quem quer que tenha enviado a mensagem do Slack, portanto um runner bloqueado para ela serve sessões que diferentes pessoas iniciaram quando você a executa em um `--capacity` acima de um ou com um `--drain-grace-sec` positivo. Um runner bloqueado para um usuário nunca pega estes, e um runner bloqueado para um agente Claude Tag nunca pega as sessões de um usuário.90* **Sessões de canal Claude Tag**: Claude as executa sem nenhuma conta de usuário anexada, portanto o proprietário é o [agente Claude Tag](https://claude.com/docs/claude-tag/concepts/glossary#agent-identity) que iniciou a sessão. Cada sessão de canal que esse agente inicia tem o mesmo proprietário, quem quer que tenha enviado a mensagem do Slack, portanto um runner bloqueado para ela serve sessões que diferentes pessoas iniciaram quando você a executa em um `--capacity` acima de um ou com um `--drain-grace-sec` positivo.

91 91 

92O tamanho mínimo da frota é, portanto, o número de proprietários que você espera estar ativos de uma vez, contando usuários e agentes Claude Tag.92O tamanho mínimo da frota é, portanto, o número de proprietários que você espera estar ativos de uma vez, contando usuários e agentes Claude Tag.

93 93 

Details

163 Exceções por chave entre fontes gerenciadas163 Exceções por chave entre fontes gerenciadas

164</h3>164</h3>

165 165 

166Três tipos de chaves são exceções à regra de não mesclagem:166Essas chaves são exceções à regra de não mesclagem:

167 167 

168* **Chaves de bloqueio entre fontes**: um pequeno conjunto de chaves, como os bloqueios da lista de permissão de sandbox, [listadas na página de configurações gerenciadas](/docs/pt/managed-settings#precedence-within-the-managed-tier). O Claude Code as honra quando qualquer fonte gerenciada controlada por administrador as define; o nível de registro HKCU gravável pelo usuário é excluído.168* **Chaves de bloqueio entre fontes**: um pequeno conjunto de chaves, como os bloqueios da lista de permissão de sandbox, [listadas na página de configurações gerenciadas](/docs/pt/managed-settings#precedence-within-the-managed-tier). O Claude Code as honra quando qualquer fonte gerenciada controlada por administrador as define; o nível de registro HKCU gravável pelo usuário é excluído.

169 169 


171* **O bloco `env`**: além da unidade de telemetria e variáveis de roteamento emparelhadas com uma chave de credencial, ambas cobertas abaixo, ele se mescla por chave entre as fontes controladas por administrador. Para cada variável de ambiente, a fonte de prioridade mais alta que a define vence, e as fontes de administrador inferiores preenchem variáveis que as fontes superiores deixam não definidas. Uma entrada `env` gerenciada pelo endpoint, portanto, se aplica sempre que a configuração gerenciada pelo servidor deixa essa variável não definida, ou enquanto um valor de servidor em cache para ela é [retido pendente de confirmação do servidor](#fetch-and-caching-behavior). Requer Claude Code v2.1.223 ou posterior. Antes da v2.1.223, o Claude Code aplica apenas o bloco `env` da fonte selecionada.171* **O bloco `env`**: além da unidade de telemetria e variáveis de roteamento emparelhadas com uma chave de credencial, ambas cobertas abaixo, ele se mescla por chave entre as fontes controladas por administrador. Para cada variável de ambiente, a fonte de prioridade mais alta que a define vence, e as fontes de administrador inferiores preenchem variáveis que as fontes superiores deixam não definidas. Uma entrada `env` gerenciada pelo endpoint, portanto, se aplica sempre que a configuração gerenciada pelo servidor deixa essa variável não definida, ou enquanto um valor de servidor em cache para ela é [retido pendente de confirmação do servidor](#fetch-and-caching-behavior). Requer Claude Code v2.1.223 ou posterior. Antes da v2.1.223, o Claude Code aplica apenas o bloco `env` da fonte selecionada.

172 * **Unidade de telemetria**: as chaves do exportador `OTEL_EXPORTER_OTLP_*`, os toggles de captura de conteúdo `OTEL_LOG_*`, `OTEL_LOGS_EXPORTER` e as variáveis de rastreamento beta `ENABLE_BETA_TRACING_DETAILED` e `BETA_TRACING_ENDPOINT` seguem a fonte mais alta que define qualquer uma delas como uma unidade. Uma fonte que entrega a chave de credencial `otelHeadersHelper` também reclama a unidade, mas coloca essas variáveis apenas quando é a fonte selecionada: uma fonte que não é selecionada mas entrega a chave não contribui com nenhuma delas e ainda bloqueia fontes inferiores de preenchê-las. De qualquer forma, um endpoint do exportador de uma fonte nunca pode ser emparelhado com credenciais de outra.172 * **Unidade de telemetria**: as chaves do exportador `OTEL_EXPORTER_OTLP_*`, os toggles de captura de conteúdo `OTEL_LOG_*`, `OTEL_LOGS_EXPORTER` e as variáveis de rastreamento beta `ENABLE_BETA_TRACING_DETAILED` e `BETA_TRACING_ENDPOINT` seguem a fonte mais alta que define qualquer uma delas como uma unidade. Uma fonte que entrega a chave de credencial `otelHeadersHelper` também reclama a unidade, mas coloca essas variáveis apenas quando é a fonte selecionada: uma fonte que não é selecionada mas entrega a chave não contribui com nenhuma delas e ainda bloqueia fontes inferiores de preenchê-las. De qualquer forma, um endpoint do exportador de uma fonte nunca pode ser emparelhado com credenciais de outra.

173 * **Roteamento emparelhado com credencial**: uma fonte que emparelha variáveis de roteamento com uma chave de credencial somente de fonte selecionada, como `apiKeyHelper` ou `otelHeadersHelper`, contribui com essas variáveis de roteamento apenas quando vence o slot.173 * **Roteamento emparelhado com credencial**: uma fonte que emparelha variáveis de roteamento com uma chave de credencial somente de fonte selecionada, como `apiKeyHelper` ou `otelHeadersHelper`, contribui com essas variáveis de roteamento apenas quando vence o slot.

174* **`allowedProviders`**: uma lista definida na máquina e uma lista gerenciada pelo servidor se combinam conforme [a nota de Escopo dessa entrada](/docs/pt/settings-reference#allowedproviders) afirma. Requer Claude Code v2.1.285 ou posterior

174* **Chaves de login do gateway**: o Claude Code nunca lê [`forceLoginGatewayUrl`](/docs/pt/settings-reference#forcelogingatewayurl), [`gatewayInternalNetworks`](/docs/pt/settings-reference#gatewayinternalnetworks) ou o valor `"gateway"` de [`forceLoginMethod`](/docs/pt/settings-reference#forceloginmethod) das configurações gerenciadas pelo servidor, portanto um valor lá não se aplica nem oculta um definido em uma política MDM ou arquivo de configurações gerenciadas. A entrada [`managedSourcesBehavior`](/docs/pt/settings-reference#managedsourcesbehavior) diz qual fonte de administrador na máquina as fornece.175* **Chaves de login do gateway**: o Claude Code nunca lê [`forceLoginGatewayUrl`](/docs/pt/settings-reference#forcelogingatewayurl), [`gatewayInternalNetworks`](/docs/pt/settings-reference#gatewayinternalnetworks) ou o valor `"gateway"` de [`forceLoginMethod`](/docs/pt/settings-reference#forceloginmethod) das configurações gerenciadas pelo servidor, portanto um valor lá não se aplica nem oculta um definido em uma política MDM ou arquivo de configurações gerenciadas. A entrada [`managedSourcesBehavior`](/docs/pt/settings-reference#managedsourcesbehavior) diz qual fonte de administrador na máquina as fornece.

175 176 

176<h3 id="fetch-and-caching-behavior">177<h3 id="fetch-and-caching-behavior">

sessions.md +20 −2

Details

29 29 

30`claude --continue` abre uma [sessão em background](/docs/pt/agent-view) que foi concluída, mas não uma que ainda está em execução; abrir sessões em background concluídas requer Claude Code v2.1.257 ou posterior. Se sua conversa mais recente for uma que você [moveu para o background](/docs/pt/agent-view#send-the-session-to-the-background) e ainda estiver em execução lá, Claude Code sai com `Your most recent conversation is running in the background` e o ID dessa sessão. Anexe à sessão a partir de [`claude agents`](/docs/pt/agent-view#attach-to-a-session), ou execute `claude --resume` para escolher outra.30`claude --continue` abre uma [sessão em background](/docs/pt/agent-view) que foi concluída, mas não uma que ainda está em execução; abrir sessões em background concluídas requer Claude Code v2.1.257 ou posterior. Se sua conversa mais recente for uma que você [moveu para o background](/docs/pt/agent-view#send-the-session-to-the-background) e ainda estiver em execução lá, Claude Code sai com `Your most recent conversation is running in the background` e o ID dessa sessão. Anexe à sessão a partir de [`claude agents`](/docs/pt/agent-view#attach-to-a-session), ou execute `claude --resume` para escolher outra.

31 31 

32<span id="resume-a-running-background-session" />

33 

34Quando a conversa que você retoma com `claude --resume` ou `/resume` pertence a uma [sessão em background](/docs/pt/agent-view) que ainda está em execução, Claude Code abre a sessão em execução em si. Com `--bg` na linha de comando, a retomada é um [dispatch em background](/docs/pt/agent-view#from-your-shell) em vez disso. Antes da v2.1.285, Claude Code recusava e dizia para você abrir a sessão com `claude attach <id>`, ou para parar com `claude stop <id>` primeiro.

35 

36* **Do seu shell**: `claude --resume <session>` executa [`claude attach`](/docs/pt/agent-view#attach-to-a-session) nessa sessão no mesmo terminal em vez de carregar a transcrição em si. Um prompt que você passa na linha de comando, como em `claude --resume <session> "check the tests too"`, vai para a sessão como seu próximo turno primeiro, e Claude Code imprime `Sent your prompt to the background session (<id>); opening it…` antes de anexar. `claude -p --resume <session> "prompt"` digitado em um terminal faz o mesmo, portanto `-p` não mantém essa execução não interativa.

37 

38 Claude Code não abre a sessão quando a linha de comando tem qualquer um destes:

39 

40 * Entrada ou saída canalizada ou redirecionada

41 * Flags que configuram a sessão, como `--permission-mode`, `--model` ou `--settings`

42 * Flags que leem a saída, como `--output-format json` ou `--json-schema`

43 * Flags que limitam ou rebobinham a execução, como `--max-turns` ou `--max-budget-usd`

44 

45 Com qualquer um destes, ou quando [agent view está desativado](/docs/pt/agent-view#turn-off-agent-view), Claude Code não envia nada e sai com status 1, imprimindo que a sessão está em execução no background junto com o comando `claude attach <id>` que a abre, ou dizendo para você encontrá-la em `claude agents` quando não conseguir determinar o ID. Adicione `--fork-session` para retomar uma cópia da conversa em vez disso. Para continuar a conversa em si em uma sessão sua, com suas flags aplicadas, execute `claude stop <id>` e depois repita o comando.

46 

47 Um prompt que começa com `/` ou `!` não é enviado, e nem é qualquer prompt enquanto a sessão aguarda sua resposta a uma pergunta. Em ambos os casos Claude Code não abre a sessão, e a mensagem inclui `Your prompt was not sent to it` com o motivo.

48* **De dentro de uma sessão**: `/resume` move sua conversa atual para o background e anexa este terminal à sessão em execução, imprimindo `Opening "<title>", running in the background (<id>)`. Pressione `←` em um prompt vazio para retornar à agent view, que também lista a conversa que você deixou. Quando a conversa atual não consegue se mover para o background, por exemplo porque você já está anexado a uma sessão em background ou a persistência de sessão está desativada, `/resume` imprime o comando `claude attach` para executar em vez disso.

49 

32Você pode executar `claude --resume <session-id>` de qualquer diretório: Claude Code procura o ID no diretório do projeto atual e seus git worktrees primeiro, depois em todos os outros projetos nesta máquina, para que encontre uma sessão que começou em outro lugar ou se moveu com [`/cd`](/docs/pt/commands). A busca entre projetos resolve o ID apenas quando exatamente um outro projeto contém uma transcrição com mensagens para ele, portanto uma duplicata copiada manualmente faz Claude Code relatar não encontrado em vez de retomar uma cópia arbitrária. Se nenhuma sessão armazenada corresponder ao ID, Claude Code relata `No conversation found with session ID: <session-id>`. Antes da v2.1.223, a busca parava no diretório do projeto atual e seus git worktrees, portanto você tinha que retomar do diretório em que a sessão trabalhou por último.50Você pode executar `claude --resume <session-id>` de qualquer diretório: Claude Code procura o ID no diretório do projeto atual e seus git worktrees primeiro, depois em todos os outros projetos nesta máquina, para que encontre uma sessão que começou em outro lugar ou se moveu com [`/cd`](/docs/pt/commands). A busca entre projetos resolve o ID apenas quando exatamente um outro projeto contém uma transcrição com mensagens para ele, portanto uma duplicata copiada manualmente faz Claude Code relatar não encontrado em vez de retomar uma cópia arbitrária. Se nenhuma sessão armazenada corresponder ao ID, Claude Code relata `No conversation found with session ID: <session-id>`. Antes da v2.1.223, a busca parava no diretório do projeto atual e seus git worktrees, portanto você tinha que retomar do diretório em que a sessão trabalhou por último.

33 51 

34<h3 id="what-a-resumed-session-restores">52<h3 id="what-a-resumed-session-restores">

35 O que uma sessão retomada restaura53 O que uma sessão retomada restaura

36</h3>54</h3>

37 55 

38Uma sessão retomada restaura a conversa junto com o estado salvo nela:56Quando Claude Code carrega uma conversa de sua transcrição, a sessão retomada restaura a conversa junto com o estado salvo nela:

39 57 

40* Histórico de conversa: o histórico completo, incluindo chamadas de ferramentas e resultados. Uma ferramenta que ainda estava em execução quando o processo anterior terminou, por exemplo em uma falha, não termina ou executa novamente quando você retoma. Claude vê a chamada marcada como interrompida antes de seu resultado ser registrado e é instruído a verificar se ela teve efeito antes de executá-la novamente, a menos que [`CLAUDE_CODE_RESUME_INTERRUPTED_TURN`](/docs/pt/env-vars#variables) esteja definido. Antes da v2.1.281, Claude Code descartava a chamada interrompida da conversa ou a mostrava a Claude como uma que você interrompeu.58* Histórico de conversa: o histórico completo, incluindo chamadas de ferramentas e resultados. Uma ferramenta que ainda estava em execução quando o processo anterior terminou, por exemplo em uma falha, não termina ou executa novamente quando você retoma. Claude vê a chamada marcada como interrompida antes de seu resultado ser registrado e é instruído a verificar se ela teve efeito antes de executá-la novamente, a menos que [`CLAUDE_CODE_RESUME_INTERRUPTED_TURN`](/docs/pt/env-vars#variables) esteja definido. Antes da v2.1.281, Claude Code descartava a chamada interrompida da conversa ou a mostrava a Claude como uma que você interrompeu.

41* Modelo: a sessão continua no modelo que estava usando. O modelo não é restaurado quando foi descontinuado ou não é permitido por `availableModels`, quando uma flag `--model` ou uma variável de ambiente da família `ANTHROPIC_MODEL` escolhe um no lançamento, ou em provedores que usam IDs de implantação específicos do provedor, como [Amazon Bedrock, Google Cloud's Agent Platform e Microsoft Foundry](/docs/pt/third-party-integrations); veja [configuração de modelo](/docs/pt/model-config#setting-your-model) para a ordem de resolução.59* Modelo: a sessão continua no modelo que estava usando. O modelo não é restaurado quando foi descontinuado ou não é permitido por `availableModels`, quando uma flag `--model` ou uma variável de ambiente da família `ANTHROPIC_MODEL` escolhe um no lançamento, ou em provedores que usam IDs de implantação específicos do provedor, como [Amazon Bedrock, Google Cloud's Agent Platform e Microsoft Foundry](/docs/pt/third-party-integrations); veja [configuração de modelo](/docs/pt/model-config#setting-your-model) para a ordem de resolução.


51 Modo de permissão ao retomar69 Modo de permissão ao retomar

52</h4>70</h4>

53 71 

54Qual modo de permissão Claude Code inicia uma sessão retomada depende de como você retoma:72Qual modo de permissão Claude Code inicia uma sessão retomada depende de como você retoma. Os casos abaixo se aplicam quando Claude Code carrega a conversa de sua transcrição; quando você [abre uma sessão em background que ainda está em execução](#resume-a-running-background-session) em vez disso, essa sessão mantém o modo de permissão em que está.

55 73 

56* Terminal: `claude --continue`, `claude --resume <session-id>` ou `claude --resume <name>` quando o nome corresponde a uma sessão, sem `-p`. Claude Code restaura o modo de permissão em que a sessão estava, exceto nos casos da tabela. Passe `--permission-mode` ou `--dangerously-skip-permissions` para substituir o modo restaurado.74* Terminal: `claude --continue`, `claude --resume <session-id>` ou `claude --resume <name>` quando o nome corresponde a uma sessão, sem `-p`. Claude Code restaura o modo de permissão em que a sessão estava, exceto nos casos da tabela. Passe `--permission-mode` ou `--dangerously-skip-permissions` para substituir o modo restaurado.

57* Não interativo: `claude -p --resume` ou `claude -p --continue`. Claude Code inicia a execução no modo de permissão em que uma nova execução `claude -p` iniciaria, exceto que uma sessão que terminou em modo de plano retoma em modo de plano sob as [condições abaixo](#resume-in-plan-mode-with-p).75* Não interativo: `claude -p --resume` ou `claude -p --continue`. Claude Code inicia a execução no modo de permissão em que uma nova execução `claude -p` iniciaria, exceto que uma sessão que terminou em modo de plano retoma em modo de plano sob as [condições abaixo](#resume-in-plan-mode-with-p).

Details

599| [`allowedChannelPlugins`](#allowedchannelplugins) | Substitua a lista de permissões padrão de [plugins de canal](/docs/pt/channels#restrict-which-channel-plugins-can-run) que podem enviar mensagens | Plugins e skills | Managed |599| [`allowedChannelPlugins`](#allowedchannelplugins) | Substitua a lista de permissões padrão de [plugins de canal](/docs/pt/channels#restrict-which-channel-plugins-can-run) que podem enviar mensagens | Plugins e skills | Managed |

600| [`allowedHttpHookUrls`](#allowedhttphookurls) | Limite quais URLs os [hooks HTTP](/docs/pt/hooks) podem atingir | Hooks e automação | Any file |600| [`allowedHttpHookUrls`](#allowedhttphookurls) | Limite quais URLs os [hooks HTTP](/docs/pt/hooks) podem atingir | Hooks e automação | Any file |

601| [`allowedMcpServers`](#allowedmcpservers) | Lista de permissões de quais [servidores MCP](/docs/pt/mcp) os usuários podem adicionar | MCP | Any file |601| [`allowedMcpServers`](#allowedmcpservers) | Lista de permissões de quais [servidores MCP](/docs/pt/mcp) os usuários podem adicionar | MCP | Any file |

602| [`allowedProviders`](#allowedproviders) | Limite quais [provedores de API](/docs/pt/third-party-integrations) uma máquina pode usar | Autenticação e provedores | Managed |

602| [`allowManagedHooksOnly`](#allowmanagedhooksonly) | Execute apenas os [hooks](/docs/pt/hooks) que sua organização implanta | Hooks e automação | Managed |603| [`allowManagedHooksOnly`](#allowmanagedhooksonly) | Execute apenas os [hooks](/docs/pt/hooks) que sua organização implanta | Hooks e automação | Managed |

603| [`allowManagedMcpServersOnly`](#allowmanagedmcpserversonly) | Faça a lista de permissões de [MCP](/docs/pt/mcp) gerenciada ser a única que se aplica | MCP | Managed |604| [`allowManagedMcpServersOnly`](#allowmanagedmcpserversonly) | Faça a lista de permissões de [MCP](/docs/pt/mcp) gerenciada ser a única que se aplica | MCP | Managed |

604| [`allowManagedPermissionRulesOnly`](#allowmanagedpermissionrulesonly) | Faça as [configurações gerenciadas](/docs/pt/managed-settings) serem a única fonte de [regras de permissão](/docs/pt/permissions#managed-settings) | Configurações de permissão | Managed |605| [`allowManagedPermissionRulesOnly`](#allowmanagedpermissionrulesonly) | Faça as [configurações gerenciadas](/docs/pt/managed-settings) serem a única fonte de [regras de permissão](/docs/pt/permissions#managed-settings) | Configurações de permissão | Managed |

605| [`alwaysThinkingEnabled`](#alwaysthinkingenabled) | Desative o [pensamento estendido](/docs/pt/model-config#extended-thinking) para cada sessão | Modelo e respostas | Any file |606| [`alwaysThinkingEnabled`](#alwaysthinkingenabled) | Desative o [pensamento estendido](/docs/pt/model-config#extended-thinking) para cada sessão | Modelo e respostas | Any file |

606| [`apiKeyHelper`](#apikeyhelper) | Gere a [credencial de API](/docs/pt/authentication#credential-management) com seu próprio comando | Autenticação e provedores | Any file |607| [`apiKeyHelper`](#apikeyhelper) | Gere a [credencial de API](/docs/pt/authentication#credential-management) com seu próprio comando | Autenticação e provedores | Any file |

607| [`askUserQuestionTimeout`](#askuserquestiontimeout) | Permita que uma pergunta sem resposta [continue automaticamente](/docs/pt/tools-reference#question-auto-continue-timeout) após tempo ocioso | Interface e terminal | User or managed |608| [`askUserQuestionTimeout`](#askuserquestiontimeout) | Permita que uma pergunta sem resposta [continue automaticamente](/docs/pt/tools-reference#question-auto-continue-timeout) após tempo ocioso | Interface e terminal | User or managed |

609| [`appendPlugins`](#appendplugins) | Execute os [mods](/docs/pt/plugins/mods/admin) de sua organização após cada mod que um usuário instala | Plugins e skills | User or managed |

608| [`attribution`](#attribution) | Personalize a atribuição que Claude Code adiciona a commits e pull requests | Git e atribuição | Any file |610| [`attribution`](#attribution) | Personalize a atribuição que Claude Code adiciona a commits e pull requests | Git e atribuição | Any file |

609| [`attribution.commit`](#attribution-commit) | Altere ou oculte o trailer que Claude Code adiciona aos commits | Git e atribuição | Any file |611| [`attribution.commit`](#attribution-commit) | Altere ou oculte o trailer que Claude Code adiciona aos commits | Git e atribuição | Any file |

610| [`attribution.pr`](#attribution-pr) | Altere ou oculte a linha de atribuição nas descrições de pull request | Git e atribuição | Any file |612| [`attribution.pr`](#attribution-pr) | Altere ou oculte a linha de atribuição nas descrições de pull request | Git e atribuição | Any file |


729| [`policyHelper.timeoutMs`](#policyhelper-timeoutms) | Defina quanto tempo Claude Code aguarda o [auxiliar](/docs/pt/managed-settings#compute-the-policy-with-a-helper-program) | Configurações empresariais e gerenciadas | Managed |731| [`policyHelper.timeoutMs`](#policyhelper-timeoutms) | Defina quanto tempo Claude Code aguarda o [auxiliar](/docs/pt/managed-settings#compute-the-policy-with-a-helper-program) | Configurações empresariais e gerenciadas | Managed |

730| [`preferredNotifChannel`](#preferrednotifchannel) | Escolha um [sino de terminal ou notificação de desktop](/docs/pt/terminal-config#get-a-terminal-bell-or-notification) para conclusão de tarefa | Remoto, desktop e notificações | Any file |732| [`preferredNotifChannel`](#preferrednotifchannel) | Escolha um [sino de terminal ou notificação de desktop](/docs/pt/terminal-config#get-a-terminal-bell-or-notification) para conclusão de tarefa | Remoto, desktop e notificações | Any file |

731| [`prefersReducedMotion`](#prefersreducedmotion) | [Reduza ou desative](/docs/pt/accessibility#accessibility-settings) animações de spinner, shimmer e flash | Interface e terminal | Any file |733| [`prefersReducedMotion`](#prefersreducedmotion) | [Reduza ou desative](/docs/pt/accessibility#accessibility-settings) animações de spinner, shimmer e flash | Interface e terminal | Any file |

734| [`prependPlugins`](#prependplugins) | Execute os [mods](/docs/pt/plugins/mods/admin) de sua organização antes de cada mod que um usuário instala | Plugins e skills | User or managed |

732| [`processWrapper`](#processwrapper) | Execute os processos em segundo plano de Claude Code através de um [inicializador corporativo](/docs/pt/corporate-launcher) no macOS e Linux | Agentes, sessões e worktrees | User or managed |735| [`processWrapper`](#processwrapper) | Execute os processos em segundo plano de Claude Code através de um [inicializador corporativo](/docs/pt/corporate-launcher) no macOS e Linux | Agentes, sessões e worktrees | User or managed |

733| [`promptCacheTtl`](#promptcachettl) | Escolha o [tempo de vida do cache de prompt](/docs/pt/prompt-caching#cache-lifetime) para a conversa principal | Modelo e respostas | Any file |736| [`promptCacheTtl`](#promptcachettl) | Escolha o [tempo de vida do cache de prompt](/docs/pt/prompt-caching#cache-lifetime) para a conversa principal | Modelo e respostas | Any file |

734| [`promptSuggestionEnabled`](#promptsuggestionenabled) | Oculte as [sugestões de prompt](/docs/pt/interactive-mode#prompt-suggestions) acinzentadas na caixa de entrada | Interface e terminal | Any file |737| [`promptSuggestionEnabled`](#promptsuggestionenabled) | Oculte as [sugestões de prompt](/docs/pt/interactive-mode#prompt-suggestions) acinzentadas na caixa de entrada | Interface e terminal | Any file |


3675 `spinnerTipsOverride`3678 `spinnerTipsOverride`

3676</h3>3679</h3>

3677 3680 

3678Adicione suas próprias dicas às [dicas do spinner](#spinnertipsenabled) que Claude Code mostra enquanto Claude trabalha, ou substitua as dicas integradas pelas suas. Claude Code coloca suas dicas na mesma rotação que as integradas: ele escolhe a dica que não foi mostrada há mais tempo, pula dicas ainda em seu cooldown, e quebra empates por prioridade.3681Adicione suas próprias dicas às [dicas do spinner](#spinnertipsenabled) que Claude Code mostra enquanto Claude trabalha, ou substitua as dicas integradas pelas suas. Claude Code coloca suas dicas na mesma rotação que as integradas.

3679 3682 

3680Se você definir [`spinnerTipsEnabled`](#spinnertipsenabled) como `false`, Claude Code oculta todas as dicas, incluindo as suas.3683Se você definir [`spinnerTipsEnabled`](#spinnertipsenabled) como `false`, Claude Code oculta todas as dicas, incluindo as suas.

3681 3684 


3683* **Type**: objeto com campos `tips`, `tipsFile`, `label` e `excludeDefault`, cada um opcional3686* **Type**: objeto com campos `tips`, `tipsFile`, `label` e `excludeDefault`, cada um opcional

3684* **Default**: unset, portanto Claude Code mostra apenas as dicas integradas3687* **Default**: unset, portanto Claude Code mostra apenas as dicas integradas

3685 3688 

3686Objetos de dica, `tipsFile`, `label` e a regra da linha Scope que configurações de projeto e local contribuem apenas com strings simples requerem Claude Code v2.1.247 ou posterior. Em versões anteriores, `excludeDefault` de um arquivo de projeto ou local também se aplica.3689Objetos de dica, `tipsFile`, `label` e a regra da linha Scope que configurações de projeto e local contribuem apenas com strings simples requerem Claude Code v2.1.247 ou posterior.

3687 3690 

3688Cada entrada `tips` é uma string simples ou um objeto com estes campos:3691Cada entrada `tips` é uma string simples ou um objeto com estes campos:

3689 3692 


4305Quando você o define como `true`, Claude Code altera quais hooks e comandos semelhantes a hooks são carregados:4308Quando você o define como `true`, Claude Code altera quais hooks e comandos semelhantes a hooks são carregados:

4306 4309 

4307* **Hooks gerenciados e SDK são executados**: hooks de configurações gerenciadas e hooks que o [Agent SDK](/docs/pt/agent-sdk/overview) registra em processo4310* **Hooks gerenciados e SDK são executados**: hooks de configurações gerenciadas e hooks que o [Agent SDK](/docs/pt/agent-sdk/overview) registra em processo

4308* **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 mais4311* **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](/docs/pt/plugins/mods/overview) em tal plugin é carregado apenas quando [conta como da sua organização](/docs/pt/plugins/mods/admin#install-your-organizations-mods)

4309* **Tudo o mais é bloqueado**: hooks de usuário, projeto e local, hooks de outros plugins e hooks declarados no frontmatter do agente4312* **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](/docs/pt/plugins/mods/overview#mods-built-into-claude-code) continuam sendo executados. Para bloquear apenas os mods dos usuários, defina [`allowManagedModsOnly`](/docs/pt/plugins/mods/admin#set-options-on-the-built-in-guard) em vez disso.

4310* **Plugins com origem em comando são desativados**: Claude Code também desativa plugins com uma [`command` source](/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`4313* **Plugins com origem em comando são desativados**: Claude Code também desativa plugins com uma [`command` source](/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`

4311* **Comandos `headersHelper` do marketplace são bloqueados**: Claude Code também bloqueia comandos [`headersHelper`](/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 posterior4314* **Comandos `headersHelper` do marketplace são bloqueados**: Claude Code também bloqueia comandos [`headersHelper`](/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

4312* **Linha de status e sugestão de arquivo restringem-se a configurações gerenciadas**: Claude Code lê [`statusLine`](/docs/pt/statusline), [`fileSuggestion`](#filesuggestion) e [`subagentStatusLine`](/docs/pt/statusline#subagent-status-lines) apenas de configurações gerenciadas, seguindo os [gates de linha de status e sugestão de arquivo](#status-line-and-file-suggestion-gates)4315* **Linha de status e sugestão de arquivo restringem-se a configurações gerenciadas**: Claude Code lê [`statusLine`](/docs/pt/statusline), [`fileSuggestion`](#filesuggestion) e [`subagentStatusLine`](/docs/pt/statusline#subagent-status-lines) apenas de configurações gerenciadas, seguindo os [gates de linha de status e sugestão de arquivo](#status-line-and-file-suggestion-gates)


5046* **`git`**: qualquer URL git, com `url`5049* **`git`**: qualquer URL git, com `url`

5047* **`url`**: uma URL direta para um arquivo `marketplace.json`, com `url` e `headers` opcional e `headersHelper` para acesso autenticado. `headersHelper` nomeia um comando que imprime cabeçalhos cujos valores são muito efêmeros para listar em `headers`, e requer Claude Code v2.1.238 ou posterior5050* **`url`**: uma URL direta para um arquivo `marketplace.json`, com `url` e `headers` opcional e `headersHelper` para acesso autenticado. `headersHelper` nomeia um comando que imprime cabeçalhos cujos valores são muito efêmeros para listar em `headers`, e requer Claude Code v2.1.238 ou posterior

5048* **`file`**: um caminho local para um arquivo `marketplace.json`, com `path`5051* **`file`**: um caminho local para um arquivo `marketplace.json`, com `path`

5049* **`directory`**: um caminho do sistema de arquivos local, com `path`, apenas para desenvolvimento5052* **`directory`**: um caminho do sistema de arquivos local, com `path`. Use-o para desenvolvimento, ou para um marketplace que sua organização [implanta em cada máquina](/docs/pt/plugins/mods/admin#install-your-organizations-mods).

5050* **`settings`**: um marketplace inline declarado diretamente no arquivo de configurações sem um repositório hospedado, com `name` e `plugins`5053* **`settings`**: um marketplace inline declarado diretamente no arquivo de configurações sem um repositório hospedado, com `name` e `plugins`

5051 5054 

5052O tipo de fonte `git` funciona com qualquer serviço de hospedagem git, incluindo GitLab auto-hospedado e Bitbucket. Claude Code clona o repositório com a mesma autenticação que `git clone` usaria nessa máquina: helpers de credencial configurados ou chaves SSH. Um token de provedor como `GITHUB_TOKEN` entra em vigor através de um helper de credencial que o lê. Consulte [Repositórios privados](/docs/pt/plugins/host-marketplace#grant-access-to-a-private-marketplace) para detalhes de configuração.5055O tipo de fonte `git` funciona com qualquer serviço de hospedagem git, incluindo GitLab auto-hospedado e Bitbucket. Claude Code clona o repositório com a mesma autenticação que `git clone` usaria nessa máquina: helpers de credencial configurados ou chaves SSH. Um token de provedor como `GITHUB_TOKEN` entra em vigor através de um helper de credencial que o lê. Consulte [Repositórios privados](/docs/pt/plugins/host-marketplace#grant-access-to-a-private-marketplace) para detalhes de configuração.


5133 5136 

5134Claude Code ignora entradas de projeto e local porque substitui esses valores em configurações de plugin hook, MCP e LSP, e um repositório clonado não deve ser capaz de fornecê-los. Antes de v2.1.207, configurações de projeto e local também eram lidas.5137Claude Code ignora entradas de projeto e local porque substitui esses valores em configurações de plugin hook, MCP e LSP, e um repositório clonado não deve ser capaz de fornecê-los. Antes de v2.1.207, configurações de projeto e local também eram lidas.

5135 5138 

5139<h3 id="prependplugins">

5140 `prependPlugins`

5141</h3>

5142 

5143Liste os plugins gerenciados cujos [mods](/docs/pt/plugins/mods/overview) são executados antes de cada mod que um usuário instala, na ordem listada. Quando você define esta chave em configurações gerenciadas, nomeie `sec-default@builtin` na lista para manter a guarda integrada. Em configurações gerenciadas, Claude Code pula um id cujo plugin não conta como de sua organização. Consulte [Instale os mods de sua organização e defina a ordem](/docs/pt/plugins/mods/admin#install-your-organizations-mods) para essas condições e para como as duas chaves de ordenação funcionam juntas.

5144 

5145* **Scope**: [`User or managed`](#scopes). Claude Code lê a chave de configurações gerenciadas. Lê a chave de configurações de usuário apenas em uma máquina sem configurações gerenciadas, para um usuário que não está conectado com um plano Team ou Enterprise. Ignora a chave em configurações de projeto e local e em um arquivo `--settings`.

5146* **Type**: array de strings `plugin-name@marketplace-name`

5147* **Default**: não definido

5148 

5149```json managed-settings.json theme={null}

5150{

5151 "extraKnownMarketplaces": {

5152 "acme-tools": {

5153 "source": { "source": "directory", "path": "/opt/acme/claude-plugins" }

5154 }

5155 },

5156 "enabledPlugins": { "acme-guard@acme-tools": true },

5157 "prependPlugins": ["acme-guard@acme-tools", "sec-default@builtin"]

5158}

5159```

5160 

5161<h3 id="appendplugins">

5162 `appendPlugins`

5163</h3>

5164 

5165Liste os plugins gerenciados cujos [mods](/docs/pt/plugins/mods/overview) são executados após cada mod que um usuário instala, na ordem listada. Um id listado em ambos `prependPlugins` e `appendPlugins` é antecedido. Em configurações gerenciadas, Claude Code pula um id cujo plugin não [conta como de sua organização](/docs/pt/plugins/mods/admin#install-your-organizations-mods).

5166 

5167* **Scope**: [`User or managed`](#scopes). Claude Code lê a chave de configurações gerenciadas. Lê a chave de configurações de usuário apenas em uma máquina sem configurações gerenciadas, para um usuário que não está conectado com um plano Team ou Enterprise. Ignora a chave em configurações de projeto e local e em um arquivo `--settings`.

5168* **Type**: array de strings `plugin-name@marketplace-name`

5169* **Default**: não definido

5170 

5171```json managed-settings.json theme={null}

5172{

5173 "extraKnownMarketplaces": {

5174 "acme-tools": {

5175 "source": { "source": "directory", "path": "/opt/acme/claude-plugins" }

5176 }

5177 },

5178 "enabledPlugins": { "acme-audit@acme-tools": true },

5179 "appendPlugins": ["acme-audit@acme-tools"]

5180}

5181```

5182 

5136<h2 id="mcp">5183<h2 id="mcp">

5137 MCP5184 MCP

5138</h2>5185</h2>


5653 5700 

5654* **Escopo**: [`Qualquer arquivo`](#scopes)5701* **Escopo**: [`Qualquer arquivo`](#scopes)

5655* **Tipo**: Boolean5702* **Tipo**: Boolean

5656 * `true`: Claude Code desativa a ferramenta Artifact para cada sessão à qual o arquivo se aplica, e nenhum outro arquivo a ativa novamente. Antes da v2.1.242, um arquivo com precedência mais alta poderia substituir um `true` de um arquivo com precedência mais baixa em vez da chave agir como um bloqueio5703 * `true`: Claude Code desativa a ferramenta Artifact para cada sessão à qual o arquivo se aplica, e nenhum outro arquivo a ativa novamente

5657 * `false`: ignorado; para deixar a ferramenta ativada, remova a chave5704 * `false`: ignorado; para deixar a ferramenta ativada, remova a chave

5658* **Padrão**: não definido, então a ferramenta segue a [disponibilidade](/docs/pt/artifacts#availability) de sua conta5705* **Padrão**: não definido, então a ferramenta segue a [disponibilidade](/docs/pt/artifacts#availability) de sua conta

5659* **Substituições por sessão**: [`CLAUDE_CODE_DISABLE_ARTIFACT`](/docs/pt/env-vars) definido como `1` desativa a ferramenta para uma sessão5706* **Substituições por sessão**: [`CLAUDE_CODE_DISABLE_ARTIFACT`](/docs/pt/env-vars) definido como `1` desativa a ferramenta para uma sessão


5740}5787}

5741```5788```

5742 5789 

5743Enquanto uma fonte diferente de suas próprias configurações de usuário mantém a ferramenta desativada, o Claude Code oculta a linha **Artifacts** em `/config`, porque ativá-la lá não mudaria nada. [Desativar artifacts](/docs/pt/artifacts#disable-artifacts) lista todas as maneiras de desativar a ferramenta. Antes da v2.1.242, o Claude Code ignorava essa chave em configurações de projeto e locais, e um arquivo mais alto na [pilha de precedência](/docs/pt/settings#settings-precedence) poderia ativar a ferramenta novamente sobre um `false` de um arquivo mais baixo.5790Enquanto uma fonte diferente de suas próprias configurações de usuário mantém a ferramenta desativada, o Claude Code oculta a linha **Artifacts** em `/config`, porque ativá-la lá não mudaria nada. [Desativar artifacts](/docs/pt/artifacts#disable-artifacts) lista todas as maneiras de desativar a ferramenta.

5744 5791 

5745<h3 id="inputneedednotifenabled">5792<h3 id="inputneedednotifenabled">

5746 `inputNeededNotifEnabled`5793 `inputNeededNotifEnabled`


5879 5926 

5880Forneça credenciais através de scripts auxiliares e, para organizações, force um método de login ou organização. Veja [Autenticação](/docs/pt/authentication).5927Forneça credenciais através de scripts auxiliares e, para organizações, force um método de login ou organização. Veja [Autenticação](/docs/pt/authentication).

5881 5928 

5929<h3 id="allowedproviders">

5930 `allowedProviders`

5931</h3>

5932 

5933Liste os serviços através dos quais uma máquina pode acessar Claude, como a API Anthropic, Amazon Bedrock ou um gateway LLM. Uma sessão em um provedor que não está listado é recusada na inicialização, no login e quando ele próximo contata a API, portanto mudar para um provedor não listado no meio da sessão também é recusado. A [mensagem de recusa](/docs/pt/errors#managed-settings-dont-allow-this-api-provider) nomeia o que selecionou o provedor e os passos para continuar. Requer Claude Code v2.1.285 ou posterior.

5934 

5935* **Escopo**: [`Gerenciado`](#scopes). Uma lista que as fontes de admin próprias da máquina definem, políticas MDM e arquivos de configurações gerenciadas, continua se aplicando quando configurações gerenciadas por servidor também entregam uma: uma sessão pode então usar apenas os provedores em ambas as listas, portanto uma lista gerenciada por servidor pode estreitar o que a máquina permite mas nunca ampliá-lo. Qual `allowedProviders` da fonte da máquina conta segue [como Claude Code combina fontes gerenciadas](/docs/pt/managed-settings#how-claude-code-combines-managed-sources). Uma lista entregue apenas através de configurações gerenciadas por servidor alcança apenas as sessões que [buscam configurações gerenciadas por servidor](/docs/pt/server-managed-settings#platform-availability).

5936* **Tipo**: array de strings, cada uma de:

5937 * `"anthropic"`: a API Anthropic no host próprio da Anthropic, através de um login claude.ai ou Console ou uma chave API. Emparelhe-a com [`forceLoginMethod`](#forceloginmethod) ou [`forceLoginOrgUUID`](#forceloginorguuid) para também restringir o login

5938 * `"bedrock"`: [Amazon Bedrock](/docs/pt/amazon-bedrock)

5939 * `"vertex"`: [Plataforma de Agente do Google Cloud](/docs/pt/google-vertex-ai), anteriormente Vertex AI

5940 * `"foundry"`: [Microsoft Foundry](/docs/pt/microsoft-foundry)

5941 * `"anthropicAws"`: [Claude Platform on AWS](/docs/pt/claude-platform-on-aws)

5942 * `"mantle"`: o endpoint [Mantle](/docs/pt/amazon-bedrock#use-the-mantle-endpoint) do Amazon Bedrock. Uma sessão que [executa Mantle junto com a API Invoke](/docs/pt/amazon-bedrock#run-mantle-alongside-the-invoke-api) usa ambos os provedores, portanto liste `"bedrock"` e `"mantle"` juntos para ela

5943 * `"customEndpoint"`: a API Anthropic ou a API de um provedor de nuvem enviada para outro host, como um [gateway LLM](/docs/pt/llm-gateway) nomeado por `ANTHROPIC_BASE_URL`, uma variável `ANTHROPIC_*_BASE_URL` do provedor, ou um valor `ANTHROPIC_FOUNDRY_RESOURCE` que não é um nome de recurso simples. Claude Code o admite apenas para o valor exato que um bloco [`env`](#env) gerenciado fixa

5944 * `"gateway"`: um login de [gateway na nuvem](/docs/pt/claude-apps-gateway)

5945* **Padrão**: não definido, portanto qualquer provedor pode ser usado

5946 

5947```json managed-settings.json theme={null}

5948{

5949 "allowedProviders": ["anthropic", "bedrock"]

5950}

5951```

5952 

5953A entrada de cada provedor de nuvem significa o próprio serviço desse provedor, incluindo seus endpoints regionais, FIPS e privados.

5954 

5955Uma entrada que Claude Code não reconhece como um nome de provedor é descartada e relatada, e o resto da lista permanece aplicado. Com uma lista vazia, ou uma cujas entradas são todas não reconhecidas, Claude Code recusa cada provedor e não inicia na máquina.

5956 

5957<h4 id="endpoints-that-need-a-pin-in-managed-env">

5958 Endpoints que precisam de um pin no `env` gerenciado

5959</h4>

5960 

5961Um pin é um valor de variável de endpoint definido em um bloco [`env`](#env) gerenciado. Quando uma sessão envia o tráfego de um provedor para algum lugar diferente do serviço próprio desse provedor, Claude Code o admite apenas se o valor da sessão for o mesmo que o pin. Estes endpoints precisam de um:

5962 

5963* **Sessões `"customEndpoint"`**: a variável que nomeia o host, como `ANTHROPIC_BASE_URL`

5964* **Amazon Bedrock**: as variáveis `AWS_ENDPOINT_URL`, `AWS_ENDPOINT_URL_BEDROCK` e `AWS_ENDPOINT_URL_BEDROCK_RUNTIME` do SDK AWS quando apontam para fora do próprio serviço Bedrock. A sessão permanece sob `"bedrock"` em vez de `"customEndpoint"`

5965* **URL de login de um gateway**: a sessão permanece sob `"gateway"`, e [`forceLoginGatewayUrl`](#forcelogingatewayurl) também conta como o pin

5966 

5967Quais blocos `env` contam como pins depende de onde a lista é definida:

5968 

5969* **Uma fonte de administrador na máquina define uma lista**: apenas os blocos `env` das fontes de administrador próprias da máquina contam

5970* **Apenas configurações gerenciadas por servidor definem uma lista**: um valor `env` nessas configurações gerenciadas por servidor também conta

5971 

5972A lista não julga as variáveis de credencial e tenancy de um provedor de nuvem ou o caminho de rede, como `HTTPS_PROXY` e configurações de certificado. Defina-as para a frota no bloco `env` gerenciado.

5973 

5882<h3 id="apikeyhelper">5974<h3 id="apikeyhelper">

5883 `apiKeyHelper`5975 `apiKeyHelper`

5884</h3>5976</h3>


6401| :- | :- | :- |6493| :- | :- | :- |

6402| Listas | Combina entradas de todas as fontes | [`permissions.allow`](#permissions-allow), [`sandbox.network.allowedDomains`](#sandbox-network-alloweddomains) e outras chaves de lista |6494| Listas | Combina entradas de todas as fontes | [`permissions.allow`](#permissions-allow), [`sandbox.network.allowedDomains`](#sandbox-network-alloweddomains) e outras chaves de lista |

6403| Bloqueios | Aplica o valor mais rigoroso que qualquer fonte define. Quando nenhuma fonte define um valor rigoroso, aplica um valor mais flexível apenas da fonte mais alta | [`allowManagedPermissionRulesOnly`](#allowmanagedpermissionrulesonly), [`permissions.disableBypassPermissionsMode`](#permissions-disablebypasspermissionsmode) e outros bloqueios booleanos ou enum |6495| Bloqueios | Aplica o valor mais rigoroso que qualquer fonte define. Quando nenhuma fonte define um valor rigoroso, aplica um valor mais flexível apenas da fonte mais alta | [`allowManagedPermissionRulesOnly`](#allowmanagedpermissionrulesonly), [`permissions.disableBypassPermissionsMode`](#permissions-disablebypasspermissionsmode) e outros bloqueios booleanos ou enum |

6404| Listas de restrição | Pega a lista inteira da fonte mais alta que a define, sem adicionar entradas de fontes inferiores. Quando a fonte mais alta não define uma, pega inteira da próxima fonte abaixo | [`availableModels`](#availablemodels), [`allowedMcpServers`](#allowedmcpservers), [`strictKnownMarketplaces`](#strictknownmarketplaces), [`allowedChannelPlugins`](#allowedchannelplugins) e a cadeia [`fallbackModel`](#fallbackmodel) |6496| Listas de restrição | Pega a lista inteira da fonte mais alta que a define, sem adicionar entradas de fontes inferiores. Quando a fonte mais alta não define uma, pega inteira da próxima fonte abaixo | [`availableModels`](#availablemodels), [`allowedMcpServers`](#allowedmcpservers), [`allowedProviders`](#allowedproviders), [`strictKnownMarketplaces`](#strictknownmarketplaces), [`allowedChannelPlugins`](#allowedchannelplugins) e a cadeia [`fallbackModel`](#fallbackmodel) |

6405| Valores tomados inteiros | Pega o valor inteiro da fonte mais alta que o define, sem combinar entradas ou campos de fontes inferiores. Quando a fonte mais alta não o define, pega inteiro da próxima fonte abaixo | [`sandbox.credentials.awsPairs`](#sandbox-credentials-awspairs), [`sandbox.ripgrep`](#sandbox-ripgrep) |6497| Valores tomados inteiros | Pega o valor inteiro da fonte mais alta que o define, sem combinar entradas ou campos de fontes inferiores. Quando a fonte mais alta não o define, pega inteiro da próxima fonte abaixo | [`sandbox.credentials.awsPairs`](#sandbox-credentials-awspairs), [`sandbox.ripgrep`](#sandbox-ripgrep) |

6406| Servidores MCP fornecidos | Combina os nomes de servidor de todas as fontes. Quando duas fontes definem o mesmo nome, aplica a entrada inteira da fonte mais alta | [`managedMcpServers`](#managedmcpservers) |6498| Servidores MCP fornecidos | Combina os nomes de servidor de todas as fontes. Quando duas fontes definem o mesmo nome, aplica a entrada inteira da fonte mais alta | [`managedMcpServers`](#managedmcpservers) |

6407| Lê apenas da fonte de prioridade mais alta | Lê a chave apenas da fonte de prioridade mais alta que carrega uma chave de política, então o valor de uma fonte inferior é ignorado mesmo quando a fonte mais alta não define nenhum | [`apiKeyHelper`](#apikeyhelper), [`awsAuthRefresh`](#awsauthrefresh), [`awsCredentialExport`](#awscredentialexport), [`gcpAuthRefresh`](#gcpauthrefresh), [`otelHeadersHelper`](#otelheadershelper), `proxyAuthHelper`, [`forceLoginOrgUUID`](#forceloginorguuid), os valores `"claudeai"` e `"console"` de [`forceLoginMethod`](#forceloginmethod), [`parentSettingsBehavior`](#parentsettingsbehavior), [`modelPicker`](#modelpicker), [`policyHelper`](#policyhelper), [`permissions.defaultMode`](#permissions-defaultmode) |6499| Lê apenas da fonte de prioridade mais alta | Lê a chave apenas da fonte de prioridade mais alta que carrega uma chave de política, então o valor de uma fonte inferior é ignorado mesmo quando a fonte mais alta não define nenhum | [`apiKeyHelper`](#apikeyhelper), [`awsAuthRefresh`](#awsauthrefresh), [`awsCredentialExport`](#awscredentialexport), [`gcpAuthRefresh`](#gcpauthrefresh), [`otelHeadersHelper`](#otelheadershelper), `proxyAuthHelper`, [`forceLoginOrgUUID`](#forceloginorguuid), os valores `"claudeai"` e `"console"` de [`forceLoginMethod`](#forceloginmethod), [`parentSettingsBehavior`](#parentsettingsbehavior), [`modelPicker`](#modelpicker), [`policyHelper`](#policyhelper), [`permissions.defaultMode`](#permissions-defaultmode) |


6415* **[`policyHelper`](#policyhelper)**: Claude Code a honra apenas quando a fonte mais alta que carrega uma chave de política é uma política MDM ou um arquivo de configurações gerenciadas, então sob configurações gerenciadas pelo servidor ela não se aplica.6507* **[`policyHelper`](#policyhelper)**: Claude Code a honra apenas quando a fonte mais alta que carrega uma chave de política é uma política MDM ou um arquivo de configurações gerenciadas, então sob configurações gerenciadas pelo servidor ela não se aplica.

6416* **[`modelOverrides`](#modeloverrides)**: emparelha com `availableModels`. Claude Code pega `modelOverrides` da fonte mais alta que a define, a menos que uma fonte mais alta defina `availableModels` sem `modelOverrides`. Nesse caso, ele ignora `modelOverrides` de todas as fontes.6508* **[`modelOverrides`](#modeloverrides)**: emparelha com `availableModels`. Claude Code pega `modelOverrides` da fonte mais alta que a define, a menos que uma fonte mais alta defina `availableModels` sem `modelOverrides`. Nesse caso, ele ignora `modelOverrides` de todas as fontes.

6417* **[`forceLoginGatewayUrl`](#forcelogingatewayurl), [`gatewayInternalNetworks`](#gatewayinternalnetworks) e o valor `"gateway"` de [`forceLoginMethod`](#forceloginmethod)**: Claude Code nunca lê nenhum deles de configurações gerenciadas pelo servidor, então um valor lá não se aplica nem oculta um definido em uma política MDM ou arquivo de configurações gerenciadas. Entre as fontes de administrador na máquina, apenas a fonte classificada mais alta que carrega uma chave de política as fornece, independentemente de configurações gerenciadas pelo servidor também estarem presentes.6509* **[`forceLoginGatewayUrl`](#forcelogingatewayurl), [`gatewayInternalNetworks`](#gatewayinternalnetworks) e o valor `"gateway"` de [`forceLoginMethod`](#forceloginmethod)**: Claude Code nunca lê nenhum deles de configurações gerenciadas pelo servidor, então um valor lá não se aplica nem oculta um definido em uma política MDM ou arquivo de configurações gerenciadas. Entre as fontes de administrador na máquina, apenas a fonte classificada mais alta que carrega uma chave de política as fornece, independentemente de configurações gerenciadas pelo servidor também estarem presentes.

6510* **[`allowedProviders`](#allowedproviders)**: após a regra da tabela, a lista da própria máquina ainda limita o resultado, conforme a nota de Escopo da entrada afirma.

6418 6511 

6419Para confirmar quais fontes se combinaram em uma máquina, execute `/status` e [leia a linha `Setting sources`](/docs/pt/managed-settings#read-the-source-in-/status).6512Para confirmar quais fontes se combinaram em uma máquina, execute `/status` e [leia a linha `Setting sources`](/docs/pt/managed-settings#read-the-source-in-/status).

6420 6513 

skills.md +1 −1

Details

740 740 

741* **Diretório de trabalho**: Claude Code executa cada comando no diretório de trabalho atual do shell da sessão. Esse diretório se move quando Claude executa `cd`. Use [`${CLAUDE_SKILL_DIR}` ou `${CLAUDE_PROJECT_DIR}`](#available-string-substitutions) em caminhos que devem ser resolvidos da mesma forma sempre.741* **Diretório de trabalho**: Claude Code executa cada comando no diretório de trabalho atual do shell da sessão. Esse diretório se move quando Claude executa `cd`. Use [`${CLAUDE_SKILL_DIR}` ou `${CLAUDE_PROJECT_DIR}`](#available-string-substitutions) em caminhos que devem ser resolvidos da mesma forma sempre.

742* **stderr**: com o shell `bash` padrão, Claude Code mescla stderr em stdout. Qualquer coisa que o comando escreva em stderr aparece no texto injetado.742* **stderr**: com o shell `bash` padrão, Claude Code mescla stderr em stdout. Qualquer coisa que o comando escreva em stderr aparece no texto injetado.

743* **Timeout**: cada comando é executado sob o [timeout](/docs/pt/tools-reference#timeout-and-output-limits) padrão de 2 minutos da ferramenta Bash. Quando a ferramenta Bash [move um comando com timeout para o background](/docs/pt/tools-reference#background-commands), a skill ainda é renderizada. O texto injetado relata a mudança e nomeia a tarefa em background e o arquivo coletando a saída do comando. Quando o comando é um que a ferramenta Bash nunca coloca automaticamente em background, Claude Code o mata no timeout. Essa falha [aborta a invocação](#when-an-injected-command-fails).743* **Timeout**: cada comando é executado sob o [timeout](/docs/pt/tools-reference#timeout-and-output-limits) padrão de 2 minutos da ferramenta Bash. Quando a ferramenta Bash [move um comando com timeout para o background](/docs/pt/tools-reference#foreground-commands-that-move-to-the-background), a skill ainda é renderizada. O texto injetado relata a mudança e nomeia a tarefa em background e o arquivo coletando a saída do comando. Quando o comando é um que a ferramenta Bash nunca coloca automaticamente em background, Claude Code o mata no timeout. Essa falha [aborta a invocação](#when-an-injected-command-fails).

744* **Tamanho da saída**: saída além do limite inline da ferramenta Bash chega como um caminho de arquivo mais uma visualização curta, não texto truncado. [Output limits](/docs/pt/tools-reference#output-limits) cobre o limite e como ajustar cada limite.744* **Tamanho da saída**: saída além do limite inline da ferramenta Bash chega como um caminho de arquivo mais uma visualização curta, não texto truncado. [Output limits](/docs/pt/tools-reference#output-limits) cobre o limite e como ajustar cada limite.

745 745 

746A ferramenta PowerShell aplica o mesmo comportamento de timeout, backgrounding e output-ceiling aos comandos que executa. Veja a seção [ferramenta PowerShell](/docs/pt/tools-reference#powershell-tool) para seus detalhes.746A ferramenta PowerShell aplica o mesmo comportamento de timeout, backgrounding e output-ceiling aos comandos que executa. Veja a seção [ferramenta PowerShell](/docs/pt/tools-reference#powershell-tool) para seus detalhes.

statusline.md +7 −7

Details

20Aqui está um exemplo de uma [linha de status de múltiplas linhas](#display-multiple-lines) que exibe informações do git na primeira linha e uma barra de contexto codificada por cores na segunda.20Aqui está um exemplo de uma [linha de status de múltiplas linhas](#display-multiple-lines) que exibe informações do git na primeira linha e uma barra de contexto codificada por cores na segunda.

21 21 

22<Frame>22<Frame>

23 <img src="https://mintcdn.com/claude-code/nibzesLaJVh4ydOq/images/statusline-multiline.png?fit=max&auto=format&n=nibzesLaJVh4ydOq&q=85&s=60f11387658acc9ff75158ae85f2ac87" alt="Uma linha de status de múltiplas linhas mostrando nome do modelo, diretório, ramificação git na primeira linha, e uma barra de progresso de uso de contexto com custo e duração na segunda linha" width="776" height="212" data-path="images/statusline-multiline.png" />23 <img src="https://mintcdn.com/claude-code/HDAmBwgbrZVk0pOt/images/statusline-multiline.png?fit=max&auto=format&n=HDAmBwgbrZVk0pOt&q=85&s=a9d0a2fe8e446d80b1abc46da3f93270" alt="Uma linha de status de múltiplas linhas mostrando nome do modelo, diretório, ramificação git na primeira linha, e uma barra de progresso de uso de contexto com custo e duração na segunda linha" width="1224" height="262" data-path="images/statusline-multiline.png" />

24</Frame>24</Frame>

25 25 

26Esta página orienta você sobre [configurar uma linha de status básica](#set-up-a-status-line), explica [como os dados fluem](#how-status-lines-work) do Claude Code para seu script, lista [todos os campos que você pode exibir](#available-data) e fornece [exemplos prontos para usar](#examples) para padrões comuns como status do git, rastreamento de custos e barras de progresso.26Esta página orienta você sobre [configurar uma linha de status básica](#set-up-a-status-line), explica [como os dados fluem](#how-status-lines-work) do Claude Code para seu script, lista [todos os campos que você pode exibir](#available-data) e fornece [exemplos prontos para usar](#examples) para padrões comuns como status do git, rastreamento de custos e barras de progresso.


93Estes exemplos usam scripts Bash, que funcionam no macOS e Linux. No Windows, consulte [Configuração do Windows](#windows-configuration) para exemplos de PowerShell e Git Bash.93Estes exemplos usam scripts Bash, que funcionam no macOS e Linux. No Windows, consulte [Configuração do Windows](#windows-configuration) para exemplos de PowerShell e Git Bash.

94 94 

95<Frame>95<Frame>

96 <img src="https://mintcdn.com/claude-code/nibzesLaJVh4ydOq/images/statusline-quickstart.png?fit=max&auto=format&n=nibzesLaJVh4ydOq&q=85&s=696445e59ca0059213250651ad23db6b" alt="Uma linha de status mostrando nome do modelo, diretório e porcentagem de contexto" width="726" height="164" data-path="images/statusline-quickstart.png" />96 <img src="https://mintcdn.com/claude-code/HDAmBwgbrZVk0pOt/images/statusline-quickstart.png?fit=max&auto=format&n=HDAmBwgbrZVk0pOt&q=85&s=88a7eab9c1038dd098ee8e284d96b7e6" alt="Uma linha de status mostrando nome do modelo, diretório e porcentagem de contexto" width="1224" height="224" data-path="images/statusline-quickstart.png" />

97</Frame>97</Frame>

98 98 

99<Steps>99<Steps>


444Exiba o modelo atual e o uso da janela de contexto com uma barra de progresso visual. Cada script lê JSON de stdin, extrai o campo `used_percentage` e constrói uma barra de 10 caracteres onde blocos preenchidos (▓) representam o uso:444Exiba o modelo atual e o uso da janela de contexto com uma barra de progresso visual. Cada script lê JSON de stdin, extrai o campo `used_percentage` e constrói uma barra de 10 caracteres onde blocos preenchidos (▓) representam o uso:

445 445 

446<Frame>446<Frame>

447 <img src="https://mintcdn.com/claude-code/nibzesLaJVh4ydOq/images/statusline-context-window-usage.png?fit=max&auto=format&n=nibzesLaJVh4ydOq&q=85&s=15b58ab3602f036939145dde3165c6f7" alt="Uma linha de status mostrando nome do modelo e uma barra de progresso com porcentagem" width="448" height="152" data-path="images/statusline-context-window-usage.png" />447 <img src="https://mintcdn.com/claude-code/HDAmBwgbrZVk0pOt/images/statusline-context-window-usage.png?fit=max&auto=format&n=HDAmBwgbrZVk0pOt&q=85&s=f3918a549912dc47e90f2b69e68bc847" alt="Uma linha de status mostrando nome do modelo e uma barra de progresso com porcentagem" width="1224" height="224" data-path="images/statusline-context-window-usage.png" />

448</Frame>448</Frame>

449 449 

450<CodeGroup>450<CodeGroup>


513Mostre a ramificação git com indicadores codificados por cores para arquivos preparados e modificados. Este script usa [códigos de escape ANSI](https://en.wikipedia.org/wiki/ANSI_escape_code#Colors) para cores de terminal: `\033[32m` é verde, `\033[33m` é amarelo e `\033[0m` redefine para padrão.513Mostre a ramificação git com indicadores codificados por cores para arquivos preparados e modificados. Este script usa [códigos de escape ANSI](https://en.wikipedia.org/wiki/ANSI_escape_code#Colors) para cores de terminal: `\033[32m` é verde, `\033[33m` é amarelo e `\033[0m` redefine para padrão.

514 514 

515<Frame>515<Frame>

516 <img src="https://mintcdn.com/claude-code/nibzesLaJVh4ydOq/images/statusline-git-context.png?fit=max&auto=format&n=nibzesLaJVh4ydOq&q=85&s=e656f34f90d1d9a1d0e220988914345f" alt="Uma linha de status mostrando modelo, diretório, ramificação git e indicadores coloridos para arquivos preparados e modificados" width="742" height="178" data-path="images/statusline-git-context.png" />516 <img src="https://mintcdn.com/claude-code/HDAmBwgbrZVk0pOt/images/statusline-git-context.png?fit=max&auto=format&n=HDAmBwgbrZVk0pOt&q=85&s=f13c190724d9ec7188c17cd2f98b7bf4" alt="Uma linha de status mostrando modelo, diretório, ramificação git e indicadores coloridos para arquivos preparados e modificados" width="1224" height="224" data-path="images/statusline-git-context.png" />

517</Frame>517</Frame>

518 518 

519Cada script verifica se o diretório atual é um repositório git, conta arquivos preparados e modificados e exibe indicadores codificados por cores:519Cada script verifica se o diretório atual é um repositório git, conta arquivos preparados e modificados e exibe indicadores codificados por cores:


611Cada script formata o custo como moeda e converte milissegundos em minutos e segundos:611Cada script formata o custo como moeda e converte milissegundos em minutos e segundos:

612 612 

613<Frame>613<Frame>

614 <img src="https://mintcdn.com/claude-code/nibzesLaJVh4ydOq/images/statusline-cost-tracking.png?fit=max&auto=format&n=nibzesLaJVh4ydOq&q=85&s=e3444a51fe6f3440c134bd5f1f08ad29" alt="Uma linha de status mostrando nome do modelo, custo da sessão e duração" width="588" height="180" data-path="images/statusline-cost-tracking.png" />614 <img src="https://mintcdn.com/claude-code/HDAmBwgbrZVk0pOt/images/statusline-cost-tracking.png?fit=max&auto=format&n=HDAmBwgbrZVk0pOt&q=85&s=925f7024c3b38be0f0eca63564bfb52f" alt="Uma linha de status mostrando nome do modelo, custo da sessão e duração" width="1224" height="224" data-path="images/statusline-cost-tracking.png" />

615</Frame>615</Frame>

616 616 

617<CodeGroup>617<CodeGroup>


672Seu script pode exibir múltiplas linhas para criar uma exibição mais rica.672Seu script pode exibir múltiplas linhas para criar uma exibição mais rica.

673 673 

674<Frame>674<Frame>

675 <img src="https://mintcdn.com/claude-code/nibzesLaJVh4ydOq/images/statusline-multiline.png?fit=max&auto=format&n=nibzesLaJVh4ydOq&q=85&s=60f11387658acc9ff75158ae85f2ac87" alt="Uma linha de status de múltiplas linhas mostrando nome do modelo, diretório, ramificação git na primeira linha, e uma barra de progresso de uso de contexto com custo e duração na segunda linha" width="776" height="212" data-path="images/statusline-multiline.png" />675 <img src="https://mintcdn.com/claude-code/HDAmBwgbrZVk0pOt/images/statusline-multiline.png?fit=max&auto=format&n=HDAmBwgbrZVk0pOt&q=85&s=a9d0a2fe8e446d80b1abc46da3f93270" alt="Uma linha de status de múltiplas linhas mostrando nome do modelo, diretório, ramificação git na primeira linha, e uma barra de progresso de uso de contexto com custo e duração na segunda linha" width="1224" height="262" data-path="images/statusline-multiline.png" />

676</Frame>676</Frame>

677 677 

678Este exemplo combina várias técnicas: cores baseadas em limite (verde abaixo de 70%, amarelo 70-89%, vermelho 90%+), uma barra de progresso e informações de ramificação git. Cada instrução `print` ou `echo` cria uma linha separada:678Este exemplo combina várias técnicas: cores baseadas em limite (verde abaixo de 70%, amarelo 70-89%, vermelho 90%+), uma barra de progresso e informações de ramificação git. Cada instrução `print` ou `echo` cria uma linha separada:


781Este exemplo cria um link clicável para seu repositório GitHub. Mantenha Cmd (macOS) ou Ctrl (Windows/Linux) pressionado e clique para abrir o link em seu navegador.781Este exemplo cria um link clicável para seu repositório GitHub. Mantenha Cmd (macOS) ou Ctrl (Windows/Linux) pressionado e clique para abrir o link em seu navegador.

782 782 

783<Frame>783<Frame>

784 <img src="https://mintcdn.com/claude-code/nibzesLaJVh4ydOq/images/statusline-links.png?fit=max&auto=format&n=nibzesLaJVh4ydOq&q=85&s=4bcc6e7deb7cf52f41ab85a219b52661" alt="Uma linha de status mostrando um link clicável para um repositório GitHub" width="726" height="198" data-path="images/statusline-links.png" />784 <img src="https://mintcdn.com/claude-code/HDAmBwgbrZVk0pOt/images/statusline-links.png?fit=max&auto=format&n=HDAmBwgbrZVk0pOt&q=85&s=4778a144a28cb498c99d5fa018bb374a" alt="Uma linha de status mostrando um link clicável para um repositório GitHub" width="1224" height="224" data-path="images/statusline-links.png" />

785</Frame>785</Frame>

786 786 

787Cada script obtém a URL remota do git, converte o formato SSH para HTTPS e envolve o nome do repositório em códigos de escape OSC 8. A versão Bash usa `printf '%b'` que interpreta escapes de barra invertida de forma mais confiável que `echo -e` em diferentes shells:787Cada script obtém a URL remota do git, converte o formato SSH para HTTPS e envolve o nome do repositório em códigos de escape OSC 8. A versão Bash usa `printf '%b'` que interpreta escapes de barra invertida de forma mais confiável que `echo -e` em diferentes shells:

Details

253 253 

254As equipes de segurança podem configurar permissões gerenciadas para o que Claude Code é e não é permitido fazer, o que não pode ser substituído pela configuração local. [Saiba mais](/docs/pt/security).254As equipes de segurança podem configurar permissões gerenciadas para o que Claude Code é e não é permitido fazer, o que não pode ser substituído pela configuração local. [Saiba mais](/docs/pt/security).

255 255 

256Para limitar quais dessas opções de implantação uma máquina gerenciada pode usar, defina [`allowedProviders`](/docs/pt/settings-reference#allowedproviders) nas configurações gerenciadas. Por exemplo, `["bedrock"]` permite Amazon Bedrock e nada mais; uma frota Bedrock que também ativa o endpoint Mantle lista `"mantle"` também. A entrada diz quais variáveis de endpoint também precisam de um pin `env` gerenciado. Requer Claude Code v2.1.285 ou posterior.

257 

256<h3 id="leverage-mcp-for-integrations">258<h3 id="leverage-mcp-for-integrations">

257 Usar MCP para integrações259 Usar MCP para integrações

258</h3>260</h3>

tools-reference.md +31 −16

Details

159 * Se `cd` sair desses diretórios, Claude Code redefine para o diretório do projeto e anexa `Shell cwd was reset to <dir>` ao resultado da ferramenta.159 * Se `cd` sair desses diretórios, Claude Code redefine para o diretório do projeto e anexa `Shell cwd was reset to <dir>` ao resultado da ferramenta.

160 * Para desabilitar esse carregamento de forma que cada comando Bash comece no diretório do projeto, defina `CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1`.160 * Para desabilitar esse carregamento de forma que cada comando Bash comece no diretório do projeto, defina `CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1`.

161* Variáveis de ambiente não persistem. Um `export` em um comando não estará disponível no próximo.161* Variáveis de ambiente não persistem. Um `export` em um comando não estará disponível no próximo.

162* Aliases e funções de shell definidas no arquivo de inicialização do seu shell estão disponíveis. No início da sessão, Claude Code carrega `~/.zshrc`, `~/.bashrc`, ou `~/.profile` dependendo do seu shell, captura os aliases, funções e opções de shell resultantes e os aplica a cada comando Bash.162* Aliases e funções de shell definidas no seu arquivo de inicialização de shell estão disponíveis. No início da sessão, Claude Code carrega `~/.zshrc`, `~/.bashrc`, ou `~/.profile` dependendo do seu shell, captura os aliases, funções e opções de shell resultantes e os aplica a cada comando Bash.

163 163 

164Ative seu virtualenv ou ambiente conda antes de iniciar Claude Code. Para fazer variáveis de ambiente persistirem entre comandos Bash, defina [`CLAUDE_ENV_FILE`](/docs/pt/env-vars) para um script de shell antes de iniciar Claude Code, ou use um [hook SessionStart](/docs/pt/hooks#persist-environment-variables) para preenchê-lo dinamicamente.164Ative seu virtualenv ou ambiente conda antes de iniciar Claude Code. Para fazer variáveis de ambiente persistirem entre comandos Bash, defina [`CLAUDE_ENV_FILE`](/docs/pt/env-vars) para um script de shell antes de iniciar Claude Code, ou use um [hook SessionStart](/docs/pt/hooks#persist-environment-variables) para preenchê-lo dinamicamente.

165 165 


167 Limites de timeout e saída167 Limites de timeout e saída

168</h3>168</h3>

169 169 

170Cada comando é executado sob um timeout, e Claude o gerencia: quando quer mais tempo do que o padrão para um comando, ele passa o parâmetro `timeout` com essa chamada. Você nunca define um timeout por comando.170Cada comando é executado sob um timeout, e Claude o gerencia: quando precisa de mais tempo do que o padrão para um comando, ele passa o parâmetro `timeout` com essa chamada. Você nunca define um timeout por comando.

171 171 

172Duas [variáveis de ambiente](/docs/pt/env-vars) controlam o que Claude obtém para um comando que é executado em primeiro plano:172Duas [variáveis de ambiente](/docs/pt/env-vars) controlam o que Claude obtém para um comando que é executado em primeiro plano:

173 173 

174* `BASH_DEFAULT_TIMEOUT_MS` — o padrão quando Claude não passa timeout; dois minutos por padrão174* `BASH_DEFAULT_TIMEOUT_MS` — o padrão quando Claude não passa timeout; dois minutos por padrão

175* `BASH_MAX_TIMEOUT_MS` — com o padrão, define o limite máximo que limita o que Claude solicita: o limite efetivo é o maior dos dois, dez minutos por padrão175* `BASH_MAX_TIMEOUT_MS` — com o padrão, define o limite máximo que limita o que Claude solicita: o limite efetivo é o maior dos dois, dez minutos por padrão

176 176 

177Para um comando que Claude inicia em segundo plano, `timeout` define por quanto tempo o comando pode ser executado lá, com o padrão e máximo separados descritos em [Comandos em segundo plano](#background-commands). A [ferramenta PowerShell](#powershell-tool) segue as mesmas regras de timeout e lê as mesmas duas variáveis.177Para um comando que Claude inicia em segundo plano, `timeout` define por quanto tempo o comando pode ser executado lá, com o padrão e máximo separados descritos em [Limite de tempo para comandos em segundo plano](#time-limit-for-background-commands). A [ferramenta PowerShell](#powershell-tool) segue as mesmas regras de timeout e lê as mesmas duas variáveis.

178 178 

179<h4 id="output-limits">179<h4 id="output-limits">

180 Limites de saída180 Limites de saída


185| Resultado | O que Claude obtém |185| Resultado | O que Claude obtém |

186| :- | :- |186| :- | :- |

187| Válido | Inline até aproximadamente 30.000 caracteres por padrão; além disso, o caminho de um arquivo salvo no diretório da sessão e truncado após 64 MiB, mais uma visualização de até os primeiros 2.000 caracteres, e Claude lê ou pesquisa o arquivo quando precisa do resto |187| Válido | Inline até aproximadamente 30.000 caracteres por padrão; além disso, o caminho de um arquivo salvo no diretório da sessão e truncado após 64 MiB, mais uma visualização de até os primeiros 2.000 caracteres, e Claude lê ou pesquisa o arquivo quando precisa do resto |

188| Falha | Inline até aproximadamente 10.000 caracteres; além disso, um trecho de cabeça e cauda desse tamanho cortado da janela de releitura, sem caminho de arquivo |188| Falha | Inline até aproximadamente 10.000 caracteres; além disso, um trecho de cabeçalho e cauda desse tamanho cortado da janela de releitura, sem caminho de arquivo |

189 189 

190Um comando que sai com código 1 conta como um resultado válido para a ferramenta Bash apenas quando Claude Code reconhece o código de saída 1 como um resultado benigno para esse comando: `grep`, `rg`, `egrep`, `fgrep`, `find`, `diff`, `test`, e `[`, mais `git diff` e `git grep`. Todo outro comando que sai com código 1 conta como uma falha, mesmo quando o código de saída 1 é um resultado informacional benigno: sem correspondências para `pgrep` e `jq -e`, arquivos que diferem para `cmp`.190Um comando que sai com código 1 conta como um resultado válido para a ferramenta Bash apenas quando Claude Code reconhece o código de saída 1 como um resultado benigno para esse comando: `grep`, `rg`, `egrep`, `fgrep`, `find`, `diff`, `test`, e `[`, mais `git diff` e `git grep`. Todo outro comando que sai com código 1 conta como uma falha, mesmo quando o código de saída 1 é um resultado informacional benigno: sem correspondências para `pgrep` e `jq -e`, arquivos que diferem para `cmp`.

191 191 

192[`BASH_MAX_OUTPUT_LENGTH`](/docs/pt/env-vars) define quantos caracteres de saída Claude Code relê do arquivo de trabalho para o resultado de um comando: 30.000 por padrão, até um limite máximo de 150.000. Aumente quando seus comandos rotineiramente ultrapassam essa janela, como um build verboso ou um log de suite de testes completo. Aumentá-lo amplia a janela de releitura, que também é a janela de onde um trecho de comando com falha é cortado. Não aumenta os limites inline: um resultado válido acima do limite inline chega como um caminho de arquivo mais visualização independentemente dessa variável.192[`BASH_MAX_OUTPUT_LENGTH`](/docs/pt/env-vars) define quantos caracteres de saída Claude Code relê do arquivo de trabalho para o resultado de um comando: 30.000 por padrão, até um limite máximo de 150.000. Aumente quando seus comandos rotineiramente ultrapassarem essa janela, como um build verboso ou um log de suite de testes completo. Aumentá-lo amplia a janela de releitura, que também é a janela de onde um trecho de comando com falha é cortado. Não aumenta os limites inline: um resultado válido acima do limite inline chega como um caminho de arquivo mais visualização independentemente dessa variável.

193 193 

194Para alterar quanto de um resultado válido Claude recebe inline, defina a configuração [`bashOutputMaxChars`](/docs/pt/settings-reference#bashoutputmaxchars) em vez disso, até 128.000 caracteres. Ela dimensiona o limite inline e a janela de releitura juntos, e Claude Code então ignora `BASH_MAX_OUTPUT_LENGTH`. Requer Claude Code v2.1.261 ou posterior.194Para alterar quanto de um resultado válido Claude recebe inline, defina a configuração [`bashOutputMaxChars`](/docs/pt/settings-reference#bashoutputmaxchars) em vez disso, até 128.000 caracteres. Ele dimensiona o limite inline e a janela de releitura juntos, e Claude Code então ignora `BASH_MAX_OUTPUT_LENGTH`. Requer Claude Code v2.1.261 ou posterior.

195 195 

196<h3 id="background-commands">196<h3 id="background-commands">

197 Comandos em segundo plano197 Comandos em segundo plano

198</h3>198</h3>

199 199 

200Para processos de longa duração, como servidores de desenvolvimento ou builds de observação, Claude pode definir `run_in_background: true` para iniciar o comando como uma tarefa em segundo plano e continuar trabalhando enquanto é executado. Liste e interrompa tarefas em segundo plano com `/tasks`. Depois que você interromper uma lá, ou de um cliente conectado como o aplicativo de desktop, Claude continua em vez de esperar. Se um subagentos iniciou o comando, é esse subagentos que continua.200Para processos de longa duração, como servidores de desenvolvimento ou builds de observação, Claude pode definir `run_in_background: true` para iniciar o comando como uma tarefa em segundo plano e continuar trabalhando enquanto é executado. Liste e interrompa tarefas em segundo plano com `/tasks`. Depois de interromper uma lá, ou de um cliente conectado como o aplicativo de desktop, Claude continua em vez de esperar. Se um subagentos iniciou o comando, é esse subagentos que continua.

201 201 

202Um comando que um [subagentos em primeiro plano](/docs/pt/sub-agents#run-subagents-in-foreground-or-background) iniciou para quando a execução desse subagentos termina, independentemente de ter terminado, falhado ou sido interrompido. Um comando que a conversa principal ou um subagentos em segundo plano iniciou continua sendo executado após uma resposta final, até sair, ser interrompido ou atingir seu limite de tempo. No modo não interativo com a flag `-p`, [comandos em segundo plano terminam logo após o resultado final da execução](/docs/pt/headless#background-tasks-at-exit).202<h4 id="when-a-background-command-stops">

203 Quando um comando em segundo plano para

204</h4>

205 

206Um comando que um [subagentos em primeiro plano](/docs/pt/sub-agents#run-subagents-in-foreground-or-background) iniciou para quando a execução desse subagentos termina, quer tenha terminado, falhado ou sido interrompido. Um comando que a conversa principal ou um subagentos em segundo plano iniciou continua sendo executado após uma resposta final, até sair, ser interrompido ou atingir seu [limite de tempo](#time-limit-for-background-commands). No modo não interativo com a flag `-p`, [comandos em segundo plano terminam logo após o resultado final da execução](/docs/pt/headless#background-tasks-at-exit).

207 

208<h4 id="time-limit-for-background-commands">

209 Limite de tempo para comandos em segundo plano

210</h4>

203 211 

204Comandos Bash e PowerShell em segundo plano têm um limite de tempo, contado a partir do momento em que o comando entra em segundo plano:212Comandos Bash e PowerShell em segundo plano têm um limite de tempo, contado a partir do momento em que o comando entra em segundo plano:

205 213 

206* Um comando que Claude inicia em segundo plano obtém 30 minutos, ou o `timeout` que Claude passa com `run_in_background`, até um máximo de 2 horas214* Um comando que Claude inicia em segundo plano obtém 30 minutos, ou o `timeout` que Claude passa com `run_in_background`, até um máximo de 2 horas

207* Um comando que começa em primeiro plano e depois se move para segundo plano, por exemplo com `Ctrl+B` ou em seu timeout, obtém 30 minutos a partir da mudança215* Um comando que começa em primeiro plano e depois se move para segundo plano, por exemplo com `Ctrl+B` ou em seu timeout, obtém 30 minutos a partir da mudança

208 216 

217Quando um comando em segundo plano atinge seu limite de tempo, Claude Code o interrompe e diz a Claude por quê, e Claude pode iniciar o comando novamente com um `timeout` mais longo se o trabalho ainda precisar. O aviso de parada lê `Background command "<description>" was stopped after reaching its background time limit`.

218 

219<h4 id="raise-the-time-limit-for-background-commands">

220 Aumente o limite de tempo para comandos em segundo plano

221</h4>

222 

209Duas [variáveis de ambiente](/docs/pt/env-vars) aumentam esses limites, para comandos Bash e PowerShell igualmente. Ambas usam milissegundos, e nenhuma pode encurtar um limite: um valor mais baixo deixa o padrão de 30 minutos e o máximo de 2 horas em vigor.223Duas [variáveis de ambiente](/docs/pt/env-vars) aumentam esses limites, para comandos Bash e PowerShell igualmente. Ambas usam milissegundos, e nenhuma pode encurtar um limite: um valor mais baixo deixa o padrão de 30 minutos e o máximo de 2 horas em vigor.

210 224 

211* Defina `BASH_DEFAULT_TIMEOUT_MS` acima de `1800000` para substituir o padrão de 30 minutos por esse valor, tanto para comandos que Claude inicia sem um `timeout` quanto para comandos movidos225* Defina `BASH_DEFAULT_TIMEOUT_MS` acima de `1800000` para substituir o padrão de 30 minutos por esse valor, tanto para comandos que Claude inicia sem um `timeout` quanto para comandos movidos

212* Defina `BASH_MAX_TIMEOUT_MS` acima de `7200000` para aumentar o máximo de 2 horas para esse valor. Definir `BASH_DEFAULT_TIMEOUT_MS` acima de `7200000` aumenta o máximo da mesma forma226* Defina `BASH_MAX_TIMEOUT_MS` acima de `7200000` para aumentar o máximo de 2 horas para esse valor. Definir `BASH_DEFAULT_TIMEOUT_MS` acima de `7200000` aumenta o máximo da mesma forma

213 227 

214Quando um comando em segundo plano atinge seu limite de tempo, Claude Code o interrompe e diz a Claude por quê, e Claude pode iniciar o comando novamente com um `timeout` mais longo se o trabalho ainda precisar. O aviso de parada lê `Background command "<description>" was stopped after reaching its background time limit`.228<h4 id="foreground-commands-that-move-to-the-background">

229 Comandos em primeiro plano que se movem para segundo plano

230</h4>

215 231 

216Quando um comando em primeiro plano atinge seu timeout sem terminar, Claude Code o move para segundo plano em vez de interrompê-lo, a menos que o comando comece com `sleep`. O limite de tempo de um comando movido é contado a partir da mudança, e um comando movido de um subagentos em primeiro plano ainda para quando a execução desse subagentos termina.232Quando um comando em primeiro plano atinge seu timeout sem terminar, Claude Code o move para segundo plano em vez de interrompê-lo, a menos que o comando comece com `sleep`. O [limite de tempo](#time-limit-for-background-commands) de um comando movido é contado a partir da mudança, e um comando movido de um subagentos em primeiro plano ainda para quando a execução desse subagentos termina.

217 233 

218Definir [`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1`](/docs/pt/env-vars#variables) desabilita o auto-backgrounding junto com o resto da funcionalidade de tarefas em segundo plano.234Definir [`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1`](/docs/pt/env-vars#variables) desabilita o auto-backgrounding junto com o resto da funcionalidade de tarefas em segundo plano.

219 235 

220O resultado de um comando movido para segundo plano indica o que aconteceu:236O resultado de um comando movido para segundo plano declara o que aconteceu:

221 237 

222* Quando o timeout dispara a mudança, o resultado relata explicitamente: `Command did not complete within its 120s timeout and was moved to the background`, com os segundos correspondendo ao timeout que se aplicava, seguido pela ID da tarefa e o caminho do arquivo para o qual a saída está sendo escrita.238* Quando o timeout dispara a mudança, o resultado relata explicitamente: `Command did not complete within its 120s timeout and was moved to the background`, com os segundos correspondendo ao timeout que se aplicava, seguido pela ID da tarefa e o caminho do arquivo para o qual a saída está sendo escrita.

223* Um `cd`, `pushd`, `popd`, ou `chdir` dentro de um comando que é movido para segundo plano nunca é mantido: o resultado afirma `Session cwd remains <dir>; directory changes made by the backgrounded command do not apply to subsequent commands.`, então Claude não age em uma mudança de diretório que não aconteceu.239* Um `cd`, `pushd`, `popd`, ou `chdir` dentro de um comando que é movido para segundo plano nunca é mantido: o resultado declara `Session cwd remains <dir>; directory changes made by the backgrounded command do not apply to subsequent commands.`, então Claude não age em uma mudança de diretório que não aconteceu.

224 240 

225<h3 id="memory-limit-on-linux-and-wsl">241<h3 id="memory-limit-on-linux-and-wsl">

226 Limite de memória em Linux e WSL242 Limite de memória no Linux e WSL

227</h3>243</h3>

228 244 

229Em Linux e WSL, defina [`CLAUDE_CODE_TOOL_MEMORY_LIMIT`](/docs/pt/env-vars#variables) para um tamanho como `4G` para limitar a memória que comandos Bash, PowerShell e [Monitor](#monitor-tool) podem usar, para que um build descontrolado não consuma a memória que o resto da sessão precisa. Requer Claude Code v2.1.233 ou posterior. Antes de v2.1.246, comandos da ferramenta Monitor eram executados fora do limite.245No Linux e WSL, defina [`CLAUDE_CODE_TOOL_MEMORY_LIMIT`](/docs/pt/env-vars#variables) para um tamanho como `4G` para limitar a memória que comandos Bash, PowerShell e [Monitor](#monitor-tool) podem usar, para que um build descontrolado não consuma a memória que o resto da sessão precisa. Requer Claude Code v2.1.233 ou posterior. Antes de v2.1.246, comandos da ferramenta Monitor eram executados fora do limite.

230 246 

231* Escreva o tamanho como um número de bytes ou com um sufixo `K`, `M`, `G`, ou `T`. Defina `0`, `off`, `false`, `no`, ou `none` para desativar o limite. Claude Code ignora qualquer outro valor que não consiga ler como um tamanho, como `4e9`.247* Escreva o tamanho como um número de bytes ou com um sufixo `K`, `M`, `G`, ou `T`. Defina `0`, `off`, `false`, `no`, ou `none` para desativar o limite. Claude Code ignora qualquer outro valor que não consiga ler como um tamanho, como `4e9`.

232* Claude Code conta todos os comandos Bash, PowerShell e Monitor de uma sessão contra o único limite, não cada comando por si só.248* Claude Code conta todos os comandos Bash, PowerShell e Monitor de uma sessão contra o único limite, não cada comando por si só.


246Seja qual for sua lista, estas regras se aplicam:262Seja qual for sua lista, estas regras se aplicam:

247 263 

248* **Nomes desconhecidos**: Claude Code ignora nomes que não reconhece264* **Nomes desconhecidos**: Claude Code ignora nomes que não reconhece

249* **Bash, PowerShell e Monitor**: Claude Code mantém comandos Bash, PowerShell e Monitor tool sob o limite seja qual for sua lista265* **Variável não definida**: Claude Code pega o conjunto de outros tipos limitados da configuração que Anthropic entrega do servidor, e esse conjunto pode mudar ao longo do tempo, então defina a variável quando precisar de um conjunto que não mude

250* **Variável não definida**: Claude Code pega o conjunto de outros tipos limitados da configuração que Anthropic entrega do servidor, e esse conjunto pode mudar ao longo do tempo, então defina a variável quando você precisa de um conjunto que não muda

251* **Hooks com permissão**: mesmo com cada tipo limitado, Claude Code exclui do limite um hook que pode bloquear ou alterar o resultado de uma ação, e qualquer servidor MCP que tal hook chama, então o kernel matando um hook com permissão não pode permitir a ação que estava bloqueando266* **Hooks com permissão**: mesmo com cada tipo limitado, Claude Code exclui do limite um hook que pode bloquear ou alterar o resultado de uma ação, e qualquer servidor MCP que tal hook chama, então o kernel matando um hook com permissão não pode permitir a ação que estava bloqueando

252 267 

253<h2 id="edit-tool-behavior">268<h2 id="edit-tool-behavior">

ultrareview.md +1 −1

Details

66 66 

67No modo PR, o sandbox remoto clona a pull request diretamente do host em vez de agrupar sua árvore de trabalho local. O modo PR funciona com repositórios em `github.com` e em instâncias do [GitHub Enterprise Server](/docs/pt/github-enterprise-server) que um proprietário conectou ao Claude Code.67No modo PR, o sandbox remoto clona a pull request diretamente do host em vez de agrupar sua árvore de trabalho local. O modo PR funciona com repositórios em `github.com` e em instâncias do [GitHub Enterprise Server](/docs/pt/github-enterprise-server) que um proprietário conectou ao Claude Code.

68 68 

69Para repositórios em `github.com`, o sandbox clona com a conta do GitHub conectada à sua conta Claude, portanto a conta deve ser capaz de ler o repositório da PR. Claude Code verifica isso antes de criar a sessão na nuvem, a menos que você tenha definido [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](/docs/pt/env-vars#variables), e recusa o lançamento quando [nenhuma conta está conectada](/docs/pt/errors#no-github-account-is-connected-to-your-claude-account) ou [a conta não consegue ver o repositório](/docs/pt/errors#your-connected-github-account-cant-see-the-repository); a recusa nomeia a correção. Antes da v2.1.248, Claude Code não verificava isso antes do lançamento.69Para repositórios em `github.com`, o sandbox clona com a conta do GitHub conectada à sua conta Claude, portanto a conta deve ser capaz de ler o repositório da PR.

70 70 

71Execute [`/web-setup`](/docs/pt/web-quickstart#connect-from-your-terminal) para conectar seu login do GitHub CLI à sua conta Claude.71Execute [`/web-setup`](/docs/pt/web-quickstart#connect-from-your-terminal) para conectar seu login do GitHub CLI à sua conta Claude.

72 72 

vs-code.md +25 −5

Details

58 58 

59 * **Activity Bar**: clique no ícone Spark na barra lateral esquerda para abrir a lista de sessões. Clique em qualquer sessão para abri-la no seu [local preferido](#extension-settings), ou inicie uma nova. Este ícone está sempre visível na Activity Bar.59 * **Activity Bar**: clique no ícone Spark na barra lateral esquerda para abrir a lista de sessões. Clique em qualquer sessão para abri-la no seu [local preferido](#extension-settings), ou inicie uma nova. Este ícone está sempre visível na Activity Bar.

60 * **Command Palette**: `Cmd+Shift+P` (Mac) ou `Ctrl+Shift+P` (Windows/Linux), digite "Claude Code" e selecione uma opção como "Open in New Tab"60 * **Command Palette**: `Cmd+Shift+P` (Mac) ou `Ctrl+Shift+P` (Windows/Linux), digite "Claude Code" e selecione uma opção como "Open in New Tab"

61 * **Status Bar**: se você definiu [`preferredLocation`](#extension-settings) como `sidebar`, ou abriu Claude com **Claude Code: Open in Side Bar**, clique em **✻ Claude Code** no canto inferior direito da janela. Isso funciona mesmo quando nenhum arquivo está aberto.61 * **Status Bar**: clique em **✻ Claude Code** no canto inferior direito da janela. Isso funciona mesmo quando nenhum arquivo está aberto.

62 62 

63 Você pode arrastar o painel Claude para reposicioná-lo em qualquer lugar no VS Code. Veja [Personalize seu fluxo de trabalho](#customize-your-workflow) para detalhes.63 Você pode arrastar o painel Claude para reposicioná-lo em qualquer lugar no VS Code. Veja [Personalize seu fluxo de trabalho](#customize-your-workflow) para detalhes.

64 </Step>64 </Step>


362 362 

363Na aba Plugins:363Na aba Plugins:

364 364 

365* **Plugins instalados** aparecem no topo com interruptores de alternância para ativá-los ou desativá-los365* **Plugins instalados** aparecem no topo com interruptores de alternância para ativá-los ou desativá-los.

366 * Se você desativar um plugin que o arquivo `.claude/settings.json` compartilhado do seu projeto ativa, a extensão pergunta primeiro: **Desativar para mim** o desativa apenas para você, enquanto **Desativar para todos** altera o arquivo compartilhado.

366* **Plugins disponíveis** de seus marketplaces configurados aparecem abaixo367* **Plugins disponíveis** de seus marketplaces configurados aparecem abaixo

367* Pesquise para filtrar plugins por nome ou descrição368* Pesquise para filtrar plugins por nome ou descrição

368* Clique em **Instalar** em qualquer plugin disponível369* Clique em **Instalar** em qualquer plugin disponível


373* **Instalar para este projeto**: compartilhado com colaboradores do projeto (escopo de projeto)374* **Instalar para este projeto**: compartilhado com colaboradores do projeto (escopo de projeto)

374* **Instalar localmente**: apenas para você, apenas neste repositório (escopo local)375* **Instalar localmente**: apenas para você, apenas neste repositório (escopo local)

375 376 

377Após a conclusão da instalação, um formulário solicita qualquer uma das [opções de configuração](/docs/pt/plugins/components#user-configuration) do plugin que ainda não estão definidas. Para revisar ou alterar as opções posteriormente, clique no ícone de engrenagem na linha do plugin.

378 

379Os campos de texto sensíveis são mascarados, e um segredo que você salvou anteriormente mostra **(inalterado)**. Deixe o campo em branco para manter o valor salvo.

380 

381Depois de salvar as alterações, as sessões abertas recarregam seus plugins e o diálogo mostra **Reinicie Claude para aplicar alterações de plugin**.

382 

383<h3 id="uninstall-plugins">

384 Desinstalar plugins

385</h3>

386 

387Cada linha instalada nomeia o [escopo](/docs/pt/plugins/install#choose-an-install-scope) em que está instalada. Para desinstalar essa instalação, clique no ícone de lixeira da linha. Um ícone de lixeira esmaecido marca uma linha que você não pode desinstalar deste workspace, como um plugin que sua organização gerencia ou um instalado para outro projeto.

388 

389A extensão pergunta primeiro em dois casos:

390 

391* **Um plugin que o arquivo `.claude/settings.json` compartilhado do seu projeto ativa**: escolha **Desativar para mim**, que mantém o plugin instalado para seus colaboradores, ou **Desinstalar para todos**, que remove a instalação do projeto com [`--keep-data`](/docs/pt/plugins/cli-reference#what-an-uninstall-deletes-and-keeps), para que o diretório de dados salvos do plugin permaneça. Se você já desativou o plugin para si mesmo, o ícone de lixeira remove sua própria instalação sem a pergunta.

392* **Caso contrário, a última instalação de um plugin com dados salvos**: escolha se deseja manter ou excluir os dados; **Manter** é o padrão

393 

376<h3 id="share-a-plugin-install-link">394<h3 id="share-a-plugin-install-link">

377 Compartilhar um link de instalação de plugin395 Compartilhar um link de instalação de plugin

378</h3>396</h3>


407 425 

408* Digite um repositório GitHub, URL ou caminho local para adicionar um novo marketplace426* Digite um repositório GitHub, URL ou caminho local para adicionar um novo marketplace

409* Clique no ícone de atualização para atualizar a lista de plugins de um marketplace427* Clique no ícone de atualização para atualizar a lista de plugins de um marketplace

410* Clique no ícone de lixeira para remover um marketplace428* Clique no ícone de lixeira para remover um marketplace. Removê-lo [desinstala todos os plugins que você instalou dele](/docs/pt/plugins/install#manage-marketplaces), portanto uma confirmação nomeia esses plugins primeiro

429 

430As alterações de plugin que você faz no diálogo se aplicam imediatamente às sessões Claude Code abertas naquela janela VS Code.

411 431 

412As alterações de plugin que você faz no diálogo se aplicam imediatamente às sessões Claude Code abertas naquela janela VS Code. Se a sessão a partir da qual você abriu o diálogo não conseguir recarregar seus plugins, o diálogo oferece tentar novamente ou reiniciar Claude naquela sessão.432Se a sessão a partir da qual você abriu o diálogo não conseguir recarregar seus plugins, o diálogo oferece tentar novamente ou reiniciar Claude naquela sessão.

413 433 

414<Note>434<Note>

415 O gerenciamento de plugins no VS Code usa os mesmos comandos CLI sob o capô. Plugins e marketplaces que você configura na extensão também estão disponíveis na CLI, e vice-versa.435 O gerenciamento de plugins no VS Code usa os mesmos comandos CLI sob o capô. Plugins e marketplaces que você configura na extensão também estão disponíveis na CLI, e vice-versa.


7904. **Desabilite extensões conflitantes**: Desabilite temporariamente outras extensões de IA (Cline, Continue, etc.)8104. **Desabilite extensões conflitantes**: Desabilite temporariamente outras extensões de IA (Cline, Continue, etc.)

7915. **Verifique a confiança do workspace**: A extensão não funciona em Modo Restrito8115. **Verifique a confiança do workspace**: A extensão não funciona em Modo Restrito

792 812 

793Alternativamente, se você definiu [`preferredLocation`](#extension-settings) como `sidebar`, ou abriu Claude com **Claude Code: Open in Side Bar**, clique em "✻ Claude Code" na **Status Bar** (canto inferior direito). Isso funciona mesmo sem um arquivo aberto. Você também pode usar a **Paleta de Comandos** (`Cmd+Shift+P` / `Ctrl+Shift+P`) e digitar "Claude Code".813Alternativamente, clique em **✻ Claude Code** na **Status Bar** no canto inferior direito da janela. Isso funciona mesmo sem um arquivo aberto. Você também pode usar a **Paleta de Comandos** (`Cmd+Shift+P` / `Ctrl+Shift+P`) e digitar "Claude Code".

794 814 

795<h3 id="cmd-esc-does-nothing-on-macos">815<h3 id="cmd-esc-does-nothing-on-macos">

796 Cmd+Esc não faz nada no macOS816 Cmd+Esc não faz nada no macOS

worktrees.md +1 −1

Details

145* A worktree pertence a uma sessão `--worktree` que você não colocou em segundo plano, qualquer que seja sua idade.145* A worktree pertence a uma sessão `--worktree` que você não colocou em segundo plano, qualquer que seja sua idade.

146* Você criou a worktree você mesmo com `git worktree add`, mesmo que depois tenha executado uma sessão `--worktree <name>` nela e colocado essa sessão em segundo plano.146* Você criou a worktree você mesmo com `git worktree add`, mesmo que depois tenha executado uma sessão `--worktree <name>` nela e colocado essa sessão em segundo plano.

147 147 

148Claude Code escreve um marcador nos metadados git de cada worktree que cria com git, e a varredura mantém qualquer worktree sem um, incluindo uma worktree que um hook [`WorktreeCreate`](#non-git-version-control) criou. Antes da v2.1.246, a varredura não verificava o marcador, e poderia remover uma worktree que você criou você mesmo quando um registro antigo de sessão em segundo plano apontava para ela.148Claude Code escreve um marcador nos metadados git de cada worktree que cria com git, e a varredura mantém qualquer worktree sem um, incluindo uma worktree que um hook [`WorktreeCreate`](#non-git-version-control) criou.

149 149 

150Enquanto um agente está em execução, Claude Code mantém um `git worktree lock` em sua worktree para que limpeza simultânea não possa removê-la, e libera o bloqueio quando o agente termina. Claude Code mantém o mesmo bloqueio na worktree que criou para uma sessão em segundo plano enquanto a sessão executa, para que a varredura deixe a worktree no lugar e `git worktree remove` recuse removê-la.150Enquanto um agente está em execução, Claude Code mantém um `git worktree lock` em sua worktree para que limpeza simultânea não possa removê-la, e libera o bloqueio quando o agente termina. Claude Code mantém o mesmo bloqueio na worktree que criou para uma sessão em segundo plano enquanto a sessão executa, para que a varredura deixe a worktree no lugar e `git worktree remove` recuse removê-la.

151 151