Documentation 2026-07-20 23:01 UTC to 2026-07-21 23:00 UTC

6 6 

7> Registre o gateway com seu IdP, crie o contêiner, implante no Kubernetes ou Cloud Run e o opere: verificações de integridade, rotação de segredos, atualizações e segurança.7> Registre o gateway com seu IdP, crie o contêiner, implante no Kubernetes ou Cloud Run e o opere: verificações de integridade, rotação de segredos, atualizações e segurança.

8 8 

9Esta página cobre o lado operacional da execução do [gateway de aplicativos Claude](/pt/claude-apps-gateway): registrar um cliente OAuth em seu provedor de identidade (IdP), implantar o gateway como um contêiner e executá-lo no dia a dia. Para cada opção no arquivo `gateway.yaml` que o gateway lê na inicialização, consulte a [Referência de configuração](/pt/claude-apps-gateway-config).9Esta página cobre o lado operacional da execução do [gateway de aplicativos Claude](/docs/pt/claude-apps-gateway): registrar um cliente OAuth em seu provedor de identidade (IdP), implantar o gateway como um contêiner e executá-lo no dia a dia. Para cada opção no arquivo `gateway.yaml` que o gateway lê na inicialização, consulte a [Referência de configuração](/docs/pt/claude-apps-gateway-config).

10 10 

11Uma implantação em produção segue quatro etapas em ordem, e as seções abaixo as correspondem. As duas primeiras são onde você faz escolhas; as duas últimas são material de referência para consultar quando estiver em execução.11Uma implantação em produção segue quatro etapas em ordem, e as seções abaixo as correspondem. As duas primeiras são onde você faz escolhas; as duas últimas são material de referência para consultar quando estiver em execução.

12 12 

31 31 

32Qualquer IdP compatível com OIDC funciona: Okta, Microsoft Entra ID, Google Workspace, Keycloak, Dex, PingFederate e outros. O IdP deve atender a três requisitos:32Qualquer IdP compatível com OIDC funciona: Okta, Microsoft Entra ID, Google Workspace, Keycloak, Dex, PingFederate e outros. O IdP deve atender a três requisitos:

33 33 

34* Serve `/.well-known/openid-configuration`, sobre HTTPS em produção; o gateway aceita um [emissor `http://`](/pt/claude-apps-gateway-config#oidc), e um emissor de loopback adicionalmente requer `CLAUDE_GATEWAY_ALLOW_LOOPBACK=1`34* Serve `/.well-known/openid-configuration`, sobre HTTPS em produção; o gateway aceita um [emissor `http://`](/docs/pt/claude-apps-gateway-config#oidc), e um emissor de loopback adicionalmente requer `CLAUDE_GATEWAY_ALLOW_LOOPBACK=1`

35* Suporta o fluxo de código de autorização. PKCE (Proof Key for Code Exchange) está ativado por padrão; desative-o com `oidc.use_pkce: false` para IdPs que não o suportam35* Suporta o fluxo de código de autorização. PKCE (Proof Key for Code Exchange) está ativado por padrão; desative-o com `oidc.use_pkce: false` para IdPs que não o suportam

36* Retorna `email` e opcionalmente `groups` no id\_token, ou os serve do endpoint userinfo com `oidc.userinfo_fallback: true`36* Retorna `email` e opcionalmente `groups` no id\_token, ou os serve do endpoint userinfo com `oidc.userinfo_fallback: true`

37 37 

41 41 

42* **Okta**: o servidor de autorização da organização em `https://example.okta.com` retorna um id\_token fino que omite `email` e `groups`, então defina `oidc.userinfo_fallback: true` sempre que o usar como `issuer`. Um servidor de autorização personalizado como `https://example.okta.com/oauth2/default` que inclui `email` e opcionalmente `groups` no id\_token os emite diretamente e não precisa de fallback. Okta emite `groups` apenas quando o escopo `groups` é solicitado em `oidc.scopes` e o filtro de reivindicação de grupos do aplicativo o permite; `userinfo_fallback` não pode preencher uma reivindicação que o IdP não foi solicitado.42* **Okta**: o servidor de autorização da organização em `https://example.okta.com` retorna um id\_token fino que omite `email` e `groups`, então defina `oidc.userinfo_fallback: true` sempre que o usar como `issuer`. Um servidor de autorização personalizado como `https://example.okta.com/oauth2/default` que inclui `email` e opcionalmente `groups` no id\_token os emite diretamente e não precisa de fallback. Okta emite `groups` apenas quando o escopo `groups` é solicitado em `oidc.scopes` e o filtro de reivindicação de grupos do aplicativo o permite; `userinfo_fallback` não pode preencher uma reivindicação que o IdP não foi solicitado.

43* **Microsoft Entra ID**: `issuer` = `https://login.microsoftonline.com/<tenant-id>/v2.0`. Entra emite Object IDs de grupo em vez de nomes, então use os GUIDs em `managed.policies.match.groups`, ou use App Roles para nomes legíveis por humanos. Se seu locatário emite funções sob `roles` em vez de `groups`, defina `oidc.groups_claim: roles`.43* **Microsoft Entra ID**: `issuer` = `https://login.microsoftonline.com/<tenant-id>/v2.0`. Entra emite Object IDs de grupo em vez de nomes, então use os GUIDs em `managed.policies.match.groups`, ou use App Roles para nomes legíveis por humanos. Se seu locatário emite funções sob `roles` em vez de `groups`, defina `oidc.groups_claim: roles`.

44* **Google Workspace**: `issuer` = `https://accounts.google.com`. O id\_token do Google não carrega grupos. Para usar `allowed_groups` baseado em grupo ou `managed.policies` com Google como IdP, configure [`oidc.google_groups`](/pt/claude-apps-gateway-config#oidc), que procura os grupos de cada usuário através da API do Directory do Admin SDK usando uma conta de serviço com delegação em todo o domínio. Sem isso, use `oidc.allowed_email_domains` para gating de associação e `managed.policies.match.email_domain` para atribuição de política. Google também ignora o escopo padrão `offline_access`. Para tokens de atualização, defina `oidc.scopes: [openid, profile, email]` e `oidc.extra_auth_params: { access_type: offline, prompt: consent }`.44* **Google Workspace**: `issuer` = `https://accounts.google.com`. O id\_token do Google não carrega grupos. Para usar `allowed_groups` baseado em grupo ou `managed.policies` com Google como IdP, configure [`oidc.google_groups`](/docs/pt/claude-apps-gateway-config#oidc), que procura os grupos de cada usuário através da API do Directory do Admin SDK usando uma conta de serviço com delegação em todo o domínio. Sem isso, use `oidc.allowed_email_domains` para gating de associação e `managed.policies.match.email_domain` para atribuição de política. Google também ignora o escopo padrão `offline_access`. Para tokens de atualização, defina `oidc.scopes: [openid, profile, email]` e `oidc.extra_auth_params: { access_type: offline, prompt: consent }`.

45 45 

46Para suporte com um provedor de identidade não abordado acima, consulte [Troubleshooting](#troubleshooting).46Para suporte com um provedor de identidade não abordado acima, consulte [Troubleshooting](#troubleshooting).

47 47 

48<Warning>48<Warning>

49 Tokens de atualização permitem que o gateway renove a sessão de um desenvolvedor silenciosamente, sem enviar o desenvolvedor de volta ao navegador. Eles também impulsionam o desprovisionamento, porque quando o IdP desativa um usuário, a próxima atualização falha e a sessão termina dentro de `ttl_hours`. O gateway solicita `offline_access` por padrão para obter um token de atualização. Se seu IdP exigir consentimento explícito para acesso offline, configure o cliente OAuth para permitir.49 Tokens de atualização permitem que o gateway renove a sessão de um desenvolvedor silenciosamente, sem enviar o desenvolvedor de volta ao navegador. Eles também impulsionam o desprovisionamento, porque quando o IdP desativa um usuário, a próxima atualização falha e a sessão termina dentro de `ttl_hours`. O gateway solicita `offline_access` por padrão para obter um token de atualização. Se seu IdP exigir consentimento explícito para acesso offline, configure o cliente OAuth para permitir.

50 50 

51 Se seu IdP não conseguir emitir tokens de atualização, o gateway ainda funciona, mas não há renovação silenciosa, então os desenvolvedores executam novamente o login do navegador quando sua sessão expira. Para evitar que isso aconteça a cada hora, aumente [`session.ttl_hours`](/pt/claude-apps-gateway-config#session) para `8` ou `12`. A compensação é a latência de desprovisionamento, porque sem tokens de atualização um usuário desativado mantém acesso até que o TTL mais longo decorra.51 Se seu IdP não conseguir emitir tokens de atualização, o gateway ainda funciona, mas não há renovação silenciosa, então os desenvolvedores executam novamente o login do navegador quando sua sessão expira. Para evitar que isso aconteça a cada hora, aumente [`session.ttl_hours`](/docs/pt/claude-apps-gateway-config#session) para `8` ou `12`. A compensação é a latência de desprovisionamento, porque sem tokens de atualização um usuário desativado mantém acesso até que o TTL mais longo decorra.

52</Warning>52</Warning>

53 53 

54<h2 id="deployment">54<h2 id="deployment">

62Algumas decisões moldam a implantação além de onde ela é executada:62Algumas decisões moldam a implantação além de onde ela é executada:

63 63 

64* **Custo**: não há licença separada ou taxa por assento para o gateway; é parte do binário `claude`. Você paga pela inferência através de seu compromisso de nuvem ou Anthropic existente, mais a computação para o contêiner e seu coletor de telemetria.64* **Custo**: não há licença separada ou taxa por assento para o gateway; é parte do binário `claude`. Você paga pela inferência através de seu compromisso de nuvem ou Anthropic existente, mais a computação para o contêiner e seu coletor de telemetria.

65* **Bypass**: o gateway não impõe que a única rota para um modelo passe por ele. Um desenvolvedor com sua própria credencial ainda pode chamar o provedor diretamente, então fechar esse caminho é uma decisão de política de rede, por exemplo, bloqueando a saída para `api.anthropic.com` exceto do gateway. Bloquear essa saída também quebra a [verificação de segurança de domínio WebFetch](/pt/data-usage#webfetch-domain-safety-check), que chama `api.anthropic.com` de cada máquina do desenvolvedor; defina `skipWebFetchPreflight: true` na política gerenciada para desativá-lo.65* **Bypass**: o gateway não impõe que a única rota para um modelo passe por ele. Um desenvolvedor com sua própria credencial ainda pode chamar o provedor diretamente, então fechar esse caminho é uma decisão de política de rede, por exemplo, bloqueando a saída para `api.anthropic.com` exceto do gateway. Bloquear essa saída também quebra a [verificação de segurança de domínio WebFetch](/docs/pt/data-usage#webfetch-domain-safety-check), que chama `api.anthropic.com` de cada máquina do desenvolvedor; defina `skipWebFetchPreflight: true` na política gerenciada para desativá-lo.

66* **Múltiplos gateways**: cada gateway é uma implantação separada com sua própria configuração. O CLI armazena sua impressão digital de confiança e credenciais por nome de host do gateway, então diferentes equipes podem se conectar a diferentes gateways sem conflito. Para servir múltiplos emissores OIDC, execute instâncias separadas.66* **Múltiplos gateways**: cada gateway é uma implantação separada com sua própria configuração. O CLI armazena sua impressão digital de confiança e credenciais por nome de host do gateway, então diferentes equipes podem se conectar a diferentes gateways sem conflito. Para servir múltiplos emissores OIDC, execute instâncias separadas.

67* **Serverless**: Cloud Run funciona; defina `min-instances: 1` para evitar descoberta OIDC fria. Lambda e Cloud Functions não funcionam, porque o gateway é um servidor HTTP de longa duração.67* **Serverless**: Cloud Run funciona; defina `min-instances: 1` para evitar descoberta OIDC fria. Lambda e Cloud Functions não funcionam, porque o gateway é um servidor HTTP de longa duração.

68 68 

69Cada topologia de produção aqui coloca um proxy L7, como um Ingress, o front-end do Cloud Run ou um ALB, na frente de réplicas HTTP simples. Defina [`listen.trusted_proxies`](/pt/claude-apps-gateway-config#listen) para os intervalos de origem do proxy para que o gateway leia IPs de cliente de `X-Forwarded-For`. O gateway honra o cabeçalho apenas quando o par TCP é confiável; o [exemplo trabalhado do Google Cloud](/pt/claude-apps-gateway-on-gcp) tem valores concretos por topologia. Sem proxies confiáveis, cada solicitação parece vir do IP do proxy, o que colapsa limites de taxa por IP em um balde compartilhado e registra o IP do proxy em eventos de auditoria.69Cada topologia de produção aqui coloca um proxy L7, como um Ingress, o front-end do Cloud Run ou um ALB, na frente de réplicas HTTP simples. Defina [`listen.trusted_proxies`](/docs/pt/claude-apps-gateway-config#listen) para os intervalos de origem do proxy para que o gateway leia IPs de cliente de `X-Forwarded-For`. O gateway honra o cabeçalho apenas quando o par TCP é confiável; o [exemplo trabalhado do Google Cloud](/docs/pt/claude-apps-gateway-on-gcp) tem valores concretos por topologia. Sem proxies confiáveis, cada solicitação parece vir do IP do proxy, o que colapsa limites de taxa por IP em um balde compartilhado e registra o IP do proxy em eventos de auditoria.

70 70 

71<h3 id="container-image">71<h3 id="container-image">

72 Imagem de contêiner72 Imagem de contêiner

74 74 

75Construa sua própria imagem em torno do binário nativo `claude` da versão padrão do Claude Code:75Construa sua própria imagem em torno do binário nativo `claude` da versão padrão do Claude Code:

76 76 

771. Baixe a compilação Linux para a arquitetura de sua imagem de uma versão fixada; consulte [Instalar uma versão específica](/pt/setup#install-a-specific-version) para a URL de download.771. Baixe a compilação Linux para a arquitetura de sua imagem de uma versão fixada; consulte [Instalar uma versão específica](/docs/pt/setup#install-a-specific-version) para a URL de download.

782. Verifique-a contra o `manifest.json` assinado por GPG da versão conforme descrito em [Integridade binária e assinatura de código](/pt/setup#binary-integrity-and-code-signing).782. Verifique-a contra o `manifest.json` assinado por GPG da versão conforme descrito em [Integridade binária e assinatura de código](/docs/pt/setup#binary-integrity-and-code-signing).

793. Copie-a para o contexto de compilação.793. Copie-a para o contexto de compilação.

80 80 

81Espelhe a versão em seu registro interno se suas compilações não conseguirem alcançar o host de versão, e fixe a versão que sua frota executa.81Espelhe a versão em seu registro interno se suas compilações não conseguirem alcançar o host de versão, e fixe a versão que sua frota executa.

82 82 

83Além do binário, a imagem precisa:83Além do binário, a imagem precisa:

84 84 

85* **Uma imagem baseada em glibc**: a compilação glibc tem apenas dependências dinâmicas de bibliotecas glibc. Imagens baseadas em Musl precisam da compilação `linux-x64-musl` ou `linux-arm64-musl` mais pacotes adicionais; consulte [Configuração do Alpine Linux](/pt/setup#alpine-linux-and-musl-based-distributions).85* **Uma imagem baseada em glibc**: a compilação glibc tem apenas dependências dinâmicas de bibliotecas glibc. Imagens baseadas em Musl precisam da compilação `linux-x64-musl` ou `linux-arm64-musl` mais pacotes adicionais; consulte [Configuração do Alpine Linux](/docs/pt/setup#alpine-linux-and-musl-based-distributions).

86* **Um diretório de estado gravável**: o gateway é executado como qualquer usuário, mas imagens mínimas não têm home gravável. Defina `CLAUDE_CONFIG_DIR` para um caminho gravável como `/tmp/.claude`.86* **Um diretório de estado gravável**: o gateway é executado como qualquer usuário, mas imagens mínimas não têm home gravável. Defina `CLAUDE_CONFIG_DIR` para um caminho gravável como `/tmp/.claude`.

87* **O comando do contêiner**: `claude gateway --config /etc/claude/gateway.yaml`, com o arquivo de configuração montado como somente leitura e segredos fornecidos como variáveis de ambiente; o gateway escuta em `listen.port`, padrão `8080`.87* **O comando do contêiner**: `claude gateway --config /etc/claude/gateway.yaml`, com o arquivo de configuração montado como somente leitura e segredos fornecidos como variáveis de ambiente; o gateway escuta em `listen.port`, padrão `8080`.

88 88 

99<Note>99<Note>

100 **Identidade de carga de trabalho**100 **Identidade de carga de trabalho**

101 101 

102 Prefira a identidade de carga de trabalho da plataforma em relação a chaves estáticas: IRSA no EKS para Bedrock e para Claude Platform na AWS, Workload Identity no GKE para Agent Platform e identidade de carga de trabalho no AKS para Foundry. Defina `auth: {}` no bloco upstream, ou `use_azure_ad: true` para Foundry, e o gateway pega a identidade do pod através da cadeia de credencial padrão desse provedor. Para um emparelhamento entre nuvens, como um upstream Bedrock no GKE, defina credenciais explícitas no bloco `auth` do upstream. A [referência `upstreams`](/pt/claude-apps-gateway-config#upstreams) tem detalhes de configuração por plataforma.102 Prefira a identidade de carga de trabalho da plataforma em relação a chaves estáticas: IRSA no EKS para Bedrock e para Claude Platform na AWS, Workload Identity no GKE para Agent Platform e identidade de carga de trabalho no AKS para Foundry. Defina `auth: {}` no bloco upstream, ou `use_azure_ad: true` para Foundry, e o gateway pega a identidade do pod através da cadeia de credencial padrão desse provedor. Para um emparelhamento entre nuvens, como um upstream Bedrock no GKE, defina credenciais explícitas no bloco `auth` do upstream. A [referência `upstreams`](/docs/pt/claude-apps-gateway-config#upstreams) tem detalhes de configuração por plataforma.

103</Note>103</Note>

104 104 

105<h3 id="cloud-run">105<h3 id="cloud-run">

109Configure o serviço da seguinte forma:109Configure o serviço da seguinte forma:

110 110 

111* Deixe `listen.port` em seu padrão de `8080`, que corresponde ao `PORT` padrão do Cloud Run, ou defina `port: ${PORT}`111* Deixe `listen.port` em seu padrão de `8080`, que corresponde ao `PORT` padrão do Cloud Run, ou defina `port: ${PORT}`

112* Defina `public_url` para a origem externamente alcançável. Para produção, isso normalmente é o nome de host de um balanceador de carga interno, porque `/login` [rejeita endereços públicos](/pt/claude-apps-gateway#prerequisites) e a URL `*.run.app` se resolve para um, então a URL do Cloud Run sozinha funciona apenas para um teste de fumaça `curl` ou navegador. A exceção é uma rede onde `*.run.app` se resolve privadamente através do Private Service Connect e uma zona privada do Cloud DNS; nessa topologia a URL do Cloud Run é um `public_url` válido. O [exemplo trabalhado do Google Cloud](/pt/claude-apps-gateway-on-gcp#deploy-the-gateway) cobre ambos.112* Defina `public_url` para a origem externamente alcançável. Para produção, isso normalmente é o nome de host de um balanceador de carga interno, porque `/login` [rejeita endereços públicos](/docs/pt/claude-apps-gateway#prerequisites) e a URL `*.run.app` se resolve para um, então a URL do Cloud Run sozinha funciona apenas para um teste de fumaça `curl` ou navegador. A exceção é uma rede onde `*.run.app` se resolve privadamente através do Private Service Connect e uma zona privada do Cloud DNS; nessa topologia a URL do Cloud Run é um `public_url` válido. O [exemplo trabalhado do Google Cloud](/docs/pt/claude-apps-gateway-on-gcp#deploy-the-gateway) cobre ambos.

113* Monte a configuração como um volume secreto113* Monte a configuração como um volume secreto

114* Defina `min-instances: 1` para evitar descoberta OIDC fria na primeira solicitação114* Defina `min-instances: 1` para evitar descoberta OIDC fria na primeira solicitação

115 115 

116<Note>116<Note>

117 Para um exemplo trabalhado completo no Google Cloud, cobrindo Cloud Run ou GKE, Cloud SQL e Secret Manager, consulte [Implantar no Google Cloud](/pt/claude-apps-gateway-on-gcp).117 Para um exemplo trabalhado completo no Google Cloud, cobrindo Cloud Run ou GKE, Cloud SQL e Secret Manager, consulte [Implantar no Google Cloud](/docs/pt/claude-apps-gateway-on-gcp).

118</Note>118</Note>

119 119 

120<h3 id="push-the-gateway-url-to-developer-machines">120<h3 id="push-the-gateway-url-to-developer-machines">

121 Envie a URL do gateway para máquinas de desenvolvedores121 Envie a URL do gateway para máquinas de desenvolvedores

122</h3>122</h3>

123 123 

124Assim que o gateway estiver servindo, envie `forceLoginMethod` e `forceLoginGatewayUrl` para a máquina de cada desenvolvedor através de configurações gerenciadas, via MDM ou escrevendo o `managed-settings.json` por SO diretamente. Sem isso, `/login` mostra o seletor de conta padrão sem opção de gateway. Consulte [Configurações gerenciadas do lado do cliente](/pt/claude-apps-gateway-config#client-side-managed-settings) para os caminhos de arquivo.124Assim que o gateway estiver servindo, envie `forceLoginMethod` e `forceLoginGatewayUrl` para a máquina de cada desenvolvedor através de configurações gerenciadas, via MDM ou escrevendo o `managed-settings.json` por SO diretamente. Sem isso, `/login` mostra o seletor de conta padrão sem opção de gateway. Consulte [Configurações gerenciadas do lado do cliente](/docs/pt/claude-apps-gateway-config#client-side-managed-settings) para os caminhos de arquivo.

125 125 

126<h2 id="operations">126<h2 id="operations">

127 Operações127 Operações

160 160 

161* **Sessões existentes**: tokens portadores validam localmente com o segredo JWT, atualizações de sessão não tocam o armazenamento e o processo do gateway ainda pode servir inferência161* **Sessões existentes**: tokens portadores validam localmente com o segredo JWT, atualizações de sessão não tocam o armazenamento e o processo do gateway ainda pode servir inferência

162* **Novas entradas**: falham até que o Postgres se recupere, porque o fluxo de dispositivo e seus contadores de limite de taxa vivem no Postgres162* **Novas entradas**: falham até que o Postgres se recupere, porque o fluxo de dispositivo e seus contadores de limite de taxa vivem no Postgres

163* **[Aplicação de limite de gastos](/pt/claude-apps-gateway-spend-limits#postgres-availability)**: falha aberta por padrão durante a interrupção, então a inferência ainda flui; inverta para falha fechada se preferir bloquear do que executar sem medição163* **[Aplicação de limite de gastos](/docs/pt/claude-apps-gateway-spend-limits#postgres-availability)**: falha aberta por padrão durante a interrupção, então a inferência ainda flui; inverta para falha fechada se preferir bloquear do que executar sem medição

164* **Prontidão**: `/readyz` relata não-pronto durante a interrupção, então orquestradores que controlam tráfego na prontidão removem cada réplica da rotação de uma vez. Nessa topologia todo tráfego, incluindo inferência que o gateway ainda poderia servir, falha no balanceador de carga até que o Postgres se recupere. A sonda de vivacidade em `/healthz` continua passando, então as réplicas não são reiniciadas. Aponte a sonda de prontidão para `/healthz` em vez disso se preferir que desenvolvedores conectados continuem funcionando através de uma interrupção de armazenamento; o custo é que novas entradas falham contra uma réplica que ainda relata pronto.164* **Prontidão**: `/readyz` relata não-pronto durante a interrupção, então orquestradores que controlam tráfego na prontidão removem cada réplica da rotação de uma vez. Nessa topologia todo tráfego, incluindo inferência que o gateway ainda poderia servir, falha no balanceador de carga até que o Postgres se recupere. A sonda de vivacidade em `/healthz` continua passando, então as réplicas não são reiniciadas. Aponte a sonda de prontidão para `/healthz` em vez disso se preferir que desenvolvedores conectados continuem funcionando através de uma interrupção de armazenamento; o custo é que novas entradas falham contra uma réplica que ainda relata pronto.

165 165 

166Se seu IdP cair, as sessões existentes funcionam até `ttl_hours`, e novas entradas e atualizações falham. Defina um `ttl_hours` mais longo se seu IdP tiver janelas de manutenção frequentes.166Se seu IdP cair, as sessões existentes funcionam até `ttl_hours`, e novas entradas e atualizações falham. Defina um `ttl_hours` mais longo se seu IdP tiver janelas de manutenção frequentes.

191| `admin_audit` | Trilha de mutação de API de administrador | `admin.audit_retention_days`, padrão 365 |191| `admin_audit` | Trilha de mutação de API de administrador | `admin.audit_retention_days`, padrão 365 |

192| `principal_emails` | Email, nome de exibição e grupos de IdP de cada principal vistos pela última vez. Contém PII. | `admin.identity_retention_days` desde última atividade, padrão 90 |192| `principal_emails` | Email, nome de exibição e grupos de IdP de cada principal vistos pela última vez. Contém PII. | `admin.identity_retention_days` desde última atividade, padrão 90 |

193 193 

194Um loop de 30 segundos expira linhas `kv` após seu TTL, e uma varredura horária impõe as janelas de retenção nas tabelas de gastos, então nada cresce sem limite. Sem [limites de gastos](/pt/claude-apps-gateway-spend-limits) configurados, apenas `kv` é escrito. Se sua política de segurança proíbe DDL da função de aplicativo, pré-crie essas tabelas e `_migrations` com uma função de administrador e conceda à função de aplicativo `SELECT, INSERT, UPDATE, DELETE` em cada uma.194Um loop de 30 segundos expira linhas `kv` após seu TTL, e uma varredura horária impõe as janelas de retenção nas tabelas de gastos, então nada cresce sem limite. Sem [limites de gastos](/docs/pt/claude-apps-gateway-spend-limits) configurados, apenas `kv` é escrito. Se sua política de segurança proíbe DDL da função de aplicativo, pré-crie essas tabelas e `_migrations` com uma função de administrador e conceda à função de aplicativo `SELECT, INSERT, UPDATE, DELETE` em cada uma.

195 195 

196Com limites de gastos em uso, um banco de dados perdido significa rastreamento de gastos e limites perdidos, não apenas re-entradas de desenvolvedores, então execute backups regulares. Para apagar um desenvolvedor que partiu imediatamente em vez de esperar pela retenção, execute `DELETE FROM principal_emails WHERE principal = '<sub>'` diretamente; isso remove a única tabela que mantém seu email, nome e grupos. Linhas `spend` e `admin_audit` referenciam apenas o `sub` OIDC pseudônimo.196Com limites de gastos em uso, um banco de dados perdido significa rastreamento de gastos e limites perdidos, não apenas re-entradas de desenvolvedores, então execute backups regulares. Para apagar um desenvolvedor que partiu imediatamente em vez de esperar pela retenção, execute `DELETE FROM principal_emails WHERE principal = '<sub>'` diretamente; isso remove a única tabela que mantém seu email, nome e grupos. Linhas `spend` e `admin_audit` referenciam apenas o `sub` OIDC pseudônimo.

197 197 

218| Dados | Caminho | Enviado para Anthropic pelo gateway |218| Dados | Caminho | Enviado para Anthropic pelo gateway |

219| ----------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | ----------------------------------------------------- |219| ----------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | ----------------------------------------------------- |

220| Inferência (prompts, conclusões) | CLI → gateway → seu upstream | Apenas se a API Anthropic for um upstream configurado |220| Inferência (prompts, conclusões) | CLI → gateway → seu upstream | Apenas se a API Anthropic for um upstream configurado |

221| Telemetria (métricas OTLP, mais [logs e rastreamentos opcionais](/pt/claude-apps-gateway-config#telemetry)) | CLI → gateway → seu coletor | Nunca |221| Telemetria (métricas OTLP, mais [logs e rastreamentos opcionais](/docs/pt/claude-apps-gateway-config#telemetry)) | CLI → gateway → seu coletor | Nunca |

222| Identidade (email, grupos, sub) | IdP → gateway → JWT → CLI; o CLI o carimba em exportações OTLP | Nunca |222| Identidade (email, grupos, sub) | IdP → gateway → JWT → CLI; o CLI o carimba em exportações OTLP | Nunca |

223| Configurações gerenciadas | Seu YAML de gateway → CLI | Nunca |223| Configurações gerenciadas | Seu YAML de gateway → CLI | Nunca |

224| Log de auditoria | Gateway stderr → seu agregador | Nunca |224| Log de auditoria | Gateway stderr → seu agregador | Nunca |

237 237 

238Duas ameaças estão fora do escopo porque são sua infraestrutura para proteger:238Duas ameaças estão fora do escopo porque são sua infraestrutura para proteger:

239 239 

240* **Um host de gateway comprometido**: o host mantém a credencial upstream e distribui [configurações gerenciadas](/pt/claude-apps-gateway-config#managed) para cada desenvolvedor conectado, então o controle sobre a configuração do gateway é comparável ao controle sobre seu MDM. O diálogo de aprovação única do CLI para configurações capazes de shell limita mudanças silenciosas, mas não substitui a segurança do host.240* **Um host de gateway comprometido**: o host mantém a credencial upstream e distribui [configurações gerenciadas](/docs/pt/claude-apps-gateway-config#managed) para cada desenvolvedor conectado, então o controle sobre a configuração do gateway é comparável ao controle sobre seu MDM. O diálogo de aprovação única do CLI para configurações capazes de shell limita mudanças silenciosas, mas não substitui a segurança do host.

241* **Um provedor OIDC malicioso**: o provedor assina os id\_tokens que o gateway confia, então pode afirmar qualquer identidade. Verificar e proteger seu IdP é sua responsabilidade.241* **Um provedor OIDC malicioso**: o provedor assina os id\_tokens que o gateway confia, então pode afirmar qualquer identidade. Verificar e proteger seu IdP é sua responsabilidade.

242 242 

243<h3 id="user-code-brute-force-resistance">243<h3 id="user-code-brute-force-resistance">

246 246 

247O `user_code` que um desenvolvedor digita na página de verificação `/device` tem 8 caracteres extraídos de um alfabeto de 20 caracteres, o que produz 20⁸ ou cerca de 2,56×10¹⁰ combinações, e expira após 10 minutos.247O `user_code` que um desenvolvedor digita na página de verificação `/device` tem 8 caracteres extraídos de um alfabeto de 20 caracteres, o que produz 20⁸ ou cerca de 2,56×10¹⁰ combinações, e expira após 10 minutos.

248 248 

249O gateway aplica limites de taxa por IP nos endpoints de concessão de dispositivo, configuráveis via [`rate_limits`](/pt/claude-apps-gateway-config#http-tuning). Aumente os limites se muitos desenvolvedores entrarem de um único endereço NAT corporativo compartilhado. Os limites se aplicam apenas ao fluxo de entrada, não à inferência.249O gateway aplica limites de taxa por IP nos endpoints de concessão de dispositivo, configuráveis via [`rate_limits`](/docs/pt/claude-apps-gateway-config#http-tuning). Aumente os limites se muitos desenvolvedores entrarem de um único endereço NAT corporativo compartilhado. Os limites se aplicam apenas ao fluxo de entrada, não à inferência.

250 250 

251<h3 id="compliance-posture">251<h3 id="compliance-posture">

252 Postura de conformidade252 Postura de conformidade

255* **Residência de dados**: o plano de dados do próprio gateway não envia nada para Anthropic a menos que a API Anthropic seja um upstream configurado; quando é, seu acordo de tratamento de dados existente se aplica ao caminho de inferência. Telemetria, auditoria, identidade e configurações vão apenas para os destinos que você configura.255* **Residência de dados**: o plano de dados do próprio gateway não envia nada para Anthropic a menos que a API Anthropic seja um upstream configurado; quando é, seu acordo de tratamento de dados existente se aplica ao caminho de inferência. Telemetria, auditoria, identidade e configurações vão apenas para os destinos que você configura.

256* **Tráfego de processo de host**: o processo de host é o CLI do Claude Code, que pode enviar análises de inicialização e verificações de atualização para Anthropic. Para implantações de saída estrita, defina `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1` no ambiente do contêiner do gateway.256* **Tráfego de processo de host**: o processo de host é o CLI do Claude Code, que pode enviar análises de inicialização e verificações de atualização para Anthropic. Para implantações de saída estrita, defina `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1` no ambiente do contêiner do gateway.

257* **Análises do cliente**: o CLI desativa sua própria análise de uso enquanto conectado a um gateway, e o relatório de erros está desativado por padrão em superfícies de API de terceiros.257* **Análises do cliente**: o CLI desativa sua própria análise de uso enquanto conectado a um gateway, e o relatório de erros está desativado por padrão em superfícies de API de terceiros.

258* **Máquinas do cliente**: CLIs de desenvolvedores ainda enviam verificações de nome de host WebFetch e verificações de versão para Anthropic a menos que `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1` e `skipWebFetchPreflight: true` sejam definidos. Consulte [uso de dados](/pt/data-usage).258* **Máquinas do cliente**: CLIs de desenvolvedores ainda enviam verificações de nome de host WebFetch e verificações de versão para Anthropic a menos que `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1` e `skipWebFetchPreflight: true` sejam definidos. Consulte [uso de dados](/docs/pt/data-usage).

259* **Classificações de pesquisa**: a credencial do gateway desativa o coletor vinculado a Anthropic, então as classificações não são enviadas para Anthropic.259* **Classificações de pesquisa**: a credencial do gateway desativa o coletor vinculado a Anthropic, então as classificações não são enviadas para Anthropic.

260* **Compartilhamento de transcrição**: escolher Sim em um prompt de compartilhamento de transcrição de pesquisa escreve um arquivo local em `~/.claude/feedback-bundles/` em vez de fazer upload para Anthropic.260* **Compartilhamento de transcrição**: escolher Sim em um prompt de compartilhamento de transcrição de pesquisa escreve um arquivo local em `~/.claude/feedback-bundles/` em vez de fazer upload para Anthropic.

261* **Atualizações do cliente**: verificações de atualização são separadas do tráfego do gateway. Fixe versões através de sua própria distribuição e defina `DISABLE_UPDATES` se laptops não devem buscar versões. `DISABLE_AUTOUPDATER` para apenas atualizações de fundo enquanto `claude update` ainda funciona.261* **Atualizações do cliente**: verificações de atualização são separadas do tráfego do gateway. Fixe versões através de sua própria distribuição e defina `DISABLE_UPDATES` se laptops não devem buscar versões. `DISABLE_AUTOUPDATER` para apenas atualizações de fundo enquanto `claude update` ainda funciona.

262* **TLS**: sirva `public_url` sobre HTTPS em produção, seja do próprio listener do gateway via `listen.tls` ou de um ingress que termina TLS na frente de réplicas HTTP simples com `listen.public_url` definido. O gateway não recusa HTTP simples. O IdP deve servir HTTPS em produção, e o Postgres suporta `?sslmode=require`. Defina `Strict-Transport-Security` em seu ingress.262* **TLS**: sirva `public_url` sobre HTTPS em produção, seja do próprio listener do gateway via `listen.tls` ou de um ingress que termina TLS na frente de réplicas HTTP simples com `listen.public_url` definido. O gateway não recusa HTTP simples. O IdP deve servir HTTPS em produção, e o Postgres suporta `?sslmode=require`. Defina `Strict-Transport-Security` em seu ingress.

263* **Divulgação de vulnerabilidade**: siga [Relatando problemas de segurança](/pt/security#reporting-security-issues)263* **Divulgação de vulnerabilidade**: siga [Relatando problemas de segurança](/docs/pt/security#reporting-security-issues)

264 264 

265<h2 id="troubleshooting">265<h2 id="troubleshooting">

266 Troubleshooting266 Troubleshooting

272* **Problema de entrada**: o desenvolvedor executa `claude --debug-file ./claude-debug.txt`, reproduz e envia esse arquivo mais o log de auditoria do gateway para a mesma janela272* **Problema de entrada**: o desenvolvedor executa `claude --debug-file ./claude-debug.txt`, reproduz e envia esse arquivo mais o log de auditoria do gateway para a mesma janela

273* **Problema de inferência**: o modelo solicitado, os upstreams configurados e o log de auditoria do gateway para a solicitação, que registra qual upstream o serviu e o status da resposta273* **Problema de inferência**: o modelo solicitado, os upstreams configurados e o log de auditoria do gateway para a solicitação, que registra qual upstream o serviu e o status da resposta

274 274 

275O stderr do gateway inclui o fluxo de eventos de auditoria, o log de auditoria registra identidades de desenvolvedores, e o arquivo de debug registra saída de hook e servidor MCP da máquina do desenvolvedor. Revise e remova essas informações antes de postar em uma issue pública.

276 

275| Sintoma | Causa | Correção |277| Sintoma | Causa | Correção |

276| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |278| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

277| A `/login` de um desenvolvedor mostra o seletor de conta padrão em vez da tela **Cloud gateway** | `forceLoginMethod` ou `forceLoginGatewayUrl` não está definido em configurações gerenciadas nessa máquina | Implante o [arquivo de configurações gerenciadas](/pt/claude-apps-gateway#set-the-gateway-url) no dispositivo; `/login` lê a URL do gateway de lá |279| A `/login` de um desenvolvedor mostra o seletor de conta padrão em vez da tela **Cloud gateway** | `forceLoginMethod` ou `forceLoginGatewayUrl` não está definido em configurações gerenciadas nessa máquina | Implante o [arquivo de configurações gerenciadas](/docs/pt/claude-apps-gateway#set-the-gateway-url) no dispositivo; `/login` lê a URL do gateway de lá |

278| A inicialização mostra `Gateway login is configured in managed settings, but this Claude Code build does not include Cloud gateway support.` | A compilação do Claude Code instalada é anterior ao suporte do gateway | Peça ao desenvolvedor para atualizar o Claude Code para uma versão que inclua suporte do Cloud gateway |280| A inicialização mostra `Gateway login is configured in managed settings, but this Claude Code build does not include Cloud gateway support.` | A compilação do Claude Code instalada é anterior ao suporte do gateway | Peça ao desenvolvedor para atualizar o Claude Code para uma versão que inclua suporte do Cloud gateway |

279| CLI `/login`: `Gateway hosts must be on your organization's private network; <host> resolves to the public (or unrecognized) address <ip>` | O nome de host do gateway se resolve para pelo menos um endereço IP público. Claude Code verifica cada endereço resolvido e requer que cada um seja privado. Uma causa comum é um nome de pilha dupla onde uma família se resolve para um endereço público, incluindo balanceadores de carga de pilha dupla internos da AWS, que retornam endereços AAAA de intervalo público. {/* min-version: 2.1.206 */}Os endpoints de gateway público operados pela Anthropic estão isentos da verificação, e `/login` os aceita sobre `https://`. Antes da v2.1.206, `/login` os rejeitava como qualquer outro endereço público | Faça o nome do gateway se resolver apenas para endereços privados em máquinas de desenvolvedores. Para um nome de pilha dupla, solte o registro de intervalo público ou sirva um nome DNS apenas interno separado. Consulte o [pré-requisito de rede privada](/pt/claude-apps-gateway#prerequisites). |281| CLI `/login`: `Gateway hosts must be on your organization's private network; <host> resolves to the public (or unrecognized) address <ip>` | O nome de host do gateway se resolve para pelo menos um endereço IP público. Claude Code verifica cada endereço resolvido e requer que cada um seja privado. Uma causa comum é um nome de pilha dupla onde uma família se resolve para um endereço público, incluindo balanceadores de carga de pilha dupla internos da AWS, que retornam endereços AAAA de intervalo público. {/* min-version: 2.1.206 */}Os endpoints de gateway público operados pela Anthropic estão isentos da verificação, e `/login` os aceita sobre `https://`. Antes da v2.1.206, `/login` os rejeitava como qualquer outro endereço público | Faça o nome do gateway se resolver apenas para endereços privados em máquinas de desenvolvedores. Para um nome de pilha dupla, solte o registro de intervalo público ou sirva um nome DNS apenas interno separado. Consulte o [pré-requisito de rede privada](/docs/pt/claude-apps-gateway#prerequisites). |

280| CLI `/login`: `Gateway login requires a direct connection and does not support connecting through an HTTP proxy` | Um `HTTPS_PROXY` ou `HTTP_PROXY` se aplica ao host do gateway e o nome de host do proxy se resolve para um endereço público. Um proxy cujo host se resolve apenas para endereços privados é permitido e não dispara esse erro | Adicione o host do gateway a `NO_PROXY` na máquina do desenvolvedor para que a conexão seja direta, ou use um proxy cujo nome de host se resolve para endereços privados |282| CLI `/login`: `Gateway login requires a direct connection and does not support connecting through an HTTP proxy` | Um `HTTPS_PROXY` ou `HTTP_PROXY` se aplica ao host do gateway e o nome de host do proxy se resolve para um endereço público. Um proxy cujo host se resolve apenas para endereços privados é permitido e não dispara esse erro | Adicione o host do gateway a `NO_PROXY` na máquina do desenvolvedor para que a conexão seja direta, ou use um proxy cujo nome de host se resolve para endereços privados |

281| CLI `/login`: `Could not resolve gateway host <host>` | A máquina não consegue resolver o nome DNS interno do gateway, normalmente porque não está na rede corporativa | Peça ao desenvolvedor para se conectar à sua rede ou VPN e tente `/login` novamente |283| CLI `/login`: `Could not resolve gateway host <host>` | A máquina não consegue resolver o nome DNS interno do gateway, normalmente porque não está na rede corporativa | Peça ao desenvolvedor para se conectar à sua rede ou VPN e tente `/login` novamente |

282| A inicialização sai com um erro de validação de configuração nomeando `store.postgres_url` | Nenhum Postgres configurado; o gateway requer Postgres | Defina `store.postgres_url`. Para desenvolvimento local, use um contêiner descartável: `docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres`. |284| A inicialização sai com um erro de validação de configuração nomeando `store.postgres_url` | Nenhum Postgres configurado; o gateway requer Postgres | Defina `store.postgres_url`. Para desenvolvimento local, use um contêiner descartável: `docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres`. |

283| A inicialização sai: `requires the native binary` | Executando sob Node em vez do binário nativo | Instale o Claude Code com um dos [métodos de instalação autônoma](/pt/setup) |285| A inicialização sai: `requires the native binary` | Executando sob Node em vez do binário nativo | Instale o Claude Code com um dos [métodos de instalação autônoma](/docs/pt/setup) |

284| A inicialização sai com um erro de descoberta OIDC após `config.load` | `oidc.issuer` inacessível, ou cadeia TLS não confiável | Verifique se o emissor é alcançável do pod e serve `/.well-known/openid-configuration`. Defina `ca_cert_pem` para PKI privada. |286| A inicialização sai com um erro de descoberta OIDC após `config.load` | `oidc.issuer` inacessível, ou cadeia TLS não confiável | Verifique se o emissor é alcançável do pod e serve `/.well-known/openid-configuration`. Defina `ca_cert_pem` para PKI privada. |

285| A inicialização sai com um erro de permissão do Postgres | A função de aplicativo carece de `CREATE TABLE` | Pré-crie o esquema com uma função de administrador e conceda DML à função de aplicativo, ou conceda DDL temporariamente para inicializações que aplicam novas migrações |287| A inicialização sai com um erro de permissão do Postgres | A função de aplicativo carece de `CREATE TABLE` | Pré-crie o esquema com uma função de administrador e conceda DML à função de aplicativo, ou conceda DDL temporariamente para inicializações que aplicam novas migrações |

286| `/oauth/callback` mostra "Sign-in could not be completed" | Domínio de email rejeitado, validação de id\_token falhou, ou `email_verified` é explicitamente `false`, que o gateway sempre rejeita sem substituição | Verifique `allowed_email_domains` e que o IdP retorna uma reivindicação `email` verificada. Para `email_verified: false`, corrija a verificação do lado do IdP. Se seu IdP emite email sob um nome de reivindicação diferente, defina `oidc.email_claim`. |288| `/oauth/callback` mostra "Sign-in could not be completed" | Domínio de email rejeitado, validação de id\_token falhou, ou `email_verified` é explicitamente `false`, que o gateway sempre rejeita sem substituição | Verifique `allowed_email_domains` e que o IdP retorna uma reivindicação `email` verificada. Para `email_verified: false`, corrija a verificação do lado do IdP. Se seu IdP emite email sob um nome de reivindicação diferente, defina `oidc.email_claim`. |

293| A entrada é concluída no IdP, mas o callback falha, com um erro de CSP no Chrome ou "this sign-in link has expired" no Safari | O IdP retornou o código via `response_mode=form_post`, que o auto-envia entre origens via POST para `/oauth/callback`. Chrome bloqueia isso sob um CSP estrito; Safari permite o envio, mas o callback lê apenas a string de consulta. | Certifique-se de que seu IdP honra `response_mode=query`, que o gateway solicita explicitamente para que o callback seja um redirecionamento simples |295| A entrada é concluída no IdP, mas o callback falha, com um erro de CSP no Chrome ou "this sign-in link has expired" no Safari | O IdP retornou o código via `response_mode=form_post`, que o auto-envia entre origens via POST para `/oauth/callback`. Chrome bloqueia isso sob um CSP estrito; Safari permite o envio, mas o callback lê apenas a string de consulta. | Certifique-se de que seu IdP honra `response_mode=query`, que o gateway solicita explicitamente para que o callback seja um redirecionamento simples |

294| O login funciona localmente, mas falha atrás de um ALB | `public_url` não definido, então o IdP obtém a origem interna `http://` como `redirect_uri` | Defina `listen.public_url` para a origem externa `https://` |296| O login funciona localmente, mas falha atrás de um ALB | `public_url` não definido, então o IdP obtém a origem interna `http://` como `redirect_uri` | Defina `listen.public_url` para a origem externa `https://` |

295| O desenvolvedor vê o prompt de confiança repetidamente | O certificado TLS está girando por réplica ou por solicitação | Use um certificado estável no ingress, ou termine TLS uma vez e execute réplicas sobre HTTP simples internamente |297| O desenvolvedor vê o prompt de confiança repetidamente | O certificado TLS está girando por réplica ou por solicitação | Use um certificado estável no ingress, ou termine TLS uma vez e execute réplicas sobre HTTP simples internamente |

296| CLI `/login`: "Could not verify the gateway's TLS certificate" ou `SELF_SIGNED_CERT_IN_CHAIN` | A cadeia TLS do gateway é assinada por uma CA privada não no armazenamento de confiança do host CLI | Claude Code lê o armazenamento de confiança do SO por padrão no binário nativo e no Node 22.15 ou posterior; [`CLAUDE_CODE_CERT_STORE`](/pt/network-config#ca-certificate-store) controla esse comportamento. Se a CA está instalada no armazenamento de confiança do SO, certifique-se de que os desenvolvedores estão em um tempo de execução atual. Caso contrário, defina `NODE_EXTRA_CA_CERTS` para o PEM do certificado CA antes de iniciar. O prompt de impressão digital de primeira conexão ainda se aplica. |298| CLI `/login`: "Could not verify the gateway's TLS certificate" ou `SELF_SIGNED_CERT_IN_CHAIN` | A cadeia TLS do gateway é assinada por uma CA privada não no armazenamento de confiança do host CLI | Claude Code lê o armazenamento de confiança do SO por padrão no binário nativo e no Node 22.15 ou posterior; [`CLAUDE_CODE_CERT_STORE`](/docs/pt/network-config#ca-certificate-store) controla esse comportamento. Se a CA está instalada no armazenamento de confiança do SO, certifique-se de que os desenvolvedores estão em um tempo de execução atual. Caso contrário, defina `NODE_EXTRA_CA_CERTS` para o PEM do certificado CA antes de iniciar. O prompt de impressão digital de primeira conexão ainda se aplica. |

297 299 

298<h2 id="related">300<h2 id="related">

299 Relacionado301 Relacionado

300</h2>302</h2>

301 303 

302* [Visão geral do gateway de aplicativos Claude](/pt/claude-apps-gateway): início rápido e conexão de desenvolvedor304* [Visão geral do gateway de aplicativos Claude](/docs/pt/claude-apps-gateway): início rápido e conexão de desenvolvedor

303* [Referência de configuração](/pt/claude-apps-gateway-config): cada opção `gateway.yaml`305* [Referência de configuração](/docs/pt/claude-apps-gateway-config): cada opção `gateway.yaml`

87 87 

88Quando o mesmo comportamento tem tanto uma variável de ambiente quanto um campo de configurações, a variável de ambiente tem precedência. Por exemplo, `ANTHROPIC_MODEL` substitui a configuração `model`, e `CLAUDE_CODE_AUTO_CONNECT_IDE` substitui `autoConnectIde`. O campo de configurações se aplica quando a variável de ambiente não está definida.88Quando o mesmo comportamento tem tanto uma variável de ambiente quanto um campo de configurações, a variável de ambiente tem precedência. Por exemplo, `ANTHROPIC_MODEL` substitui a configuração `model`, e `CLAUDE_CODE_AUTO_CONNECT_IDE` substitui `autoConnectIde`. O campo de configurações se aplica quando a variável de ambiente não está definida.

89 89 

90Quando a mesma variável é definida tanto no seu shell quanto em um arquivo de configurações no bloco `env`, o valor do arquivo de configurações se aplica. Claude Code escreve cada entrada `env` no ambiente do processo na inicialização, substituindo o valor herdado do shell. Algumas variáveis são tratadas como casos especiais; a [configuração `env`](/pt/settings#available-settings) lista as exceções.

91 

92Entre arquivos de configurações, os valores `env` seguem a [precedência de configurações](/pt/settings#settings-precedence), então uma entrada de configurações gerenciada substitui a mesma variável nas configurações de usuário ou projeto.

93 

90Como uma variável de ambiente interage com flags CLI e comandos em sessão varia por recurso: `--model` e `/model` substituem `ANTHROPIC_MODEL`, enquanto `CLAUDE_CODE_EFFORT_LEVEL` substitui `/effort`. Quando uma variável interage com outra fonte de configuração, sua linha na lista [Variáveis](#variables) declara a precedência ou vincula à página que a documenta.94Como uma variável de ambiente interage com flags CLI e comandos em sessão varia por recurso: `--model` e `/model` substituem `ANTHROPIC_MODEL`, enquanto `CLAUDE_CODE_EFFORT_LEVEL` substitui `/effort`. Quando uma variável interage com outra fonte de configuração, sua linha na lista [Variáveis](#variables) declara a precedência ou vincula à página que a documenta.

91 95 

92Claude Code lê variáveis de ambiente na inicialização, então as mudanças entram em efeito na próxima vez que você inicia `claude`.96Claude Code lê variáveis de ambiente na inicialização, então as mudanças entram em efeito na próxima vez que você inicia `claude`.

96</h2>100</h2>

97 101 

98| Variável | Propósito |102| Variável | Propósito |

99| :------------------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |103| :------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

100| `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 em vez disso, execute `unset ANTHROPIC_API_KEY` |104| `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 em vez disso, execute `unset ANTHROPIC_API_KEY` |

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

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

134| `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](/pt/microsoft-foundry)) |138| `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](/pt/microsoft-foundry)) |

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

136| `ANTHROPIC_SMALL_FAST_MODEL` | \[DEPRECATED] Nome do [modelo da classe Haiku para tarefas em segundo plano](/pt/costs) |140| `ANTHROPIC_SMALL_FAST_MODEL` | \[DEPRECATED] Nome do [modelo da classe Haiku para tarefas em segundo plano](/pt/costs) |

137| `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. Em Amazon Bedrock, isso só tem efeito quando `ANTHROPIC_DEFAULT_HAIKU_MODEL` ou o descontinuado `ANTHROPIC_SMALL_FAST_MODEL` também está definido, já que Amazon Bedrock de outra forma usa o modelo primário para tarefas em segundo plano |141| `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. Em Amazon Bedrock, isso só tem efeito quando `ANTHROPIC_DEFAULT_HAIKU_MODEL` ou o descontinuado `ANTHROPIC_SMALL_FAST_MODEL` também está definido, já que Amazon Bedrock de outra forma executa tarefas em segundo plano no [modelo Sonnet padrão ou modelo primário](/pt/amazon-bedrock#4-pin-model-versions) na região da sessão |

138| `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](/pt/llm-gateway). Veja [Google Cloud's Agent Platform](/pt/google-vertex-ai) |142| `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](/pt/llm-gateway). Veja [Google Cloud's Agent Platform](/pt/google-vertex-ai) |

139| `ANTHROPIC_VERTEX_PROJECT_ID` | ID do projeto GCP para solicitações Google Cloud's Agent Platform. Substituído por `GCLOUD_PROJECT`, `GOOGLE_CLOUD_PROJECT` ou o projeto no seu arquivo de credenciais `GOOGLE_APPLICATION_CREDENTIALS`. Veja [Google Cloud's Agent Platform](/pt/google-vertex-ai) |143| `ANTHROPIC_VERTEX_PROJECT_ID` | ID do projeto GCP para solicitações Google Cloud's Agent Platform. Substituído por `GCLOUD_PROJECT`, `GOOGLE_CLOUD_PROJECT` ou o projeto no seu arquivo de credenciais `GOOGLE_APPLICATION_CREDENTIALS`. Veja [Google Cloud's Agent Platform](/pt/google-vertex-ai) |

140| `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 |144| `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 |

165| `CLAUDE_CODE_ATTRIBUTION_HEADER` | Defina como `0` para omitir o bloco de atribuição (versão do cliente e impressão digital do prompt) do início do prompt do sistema. Desabilitá-lo melhora as taxas de acerto do cache de prompt ao rotear através de um [gateway LLM](/pt/llm-gateway). O cache da API Anthropic não é afetado |169| `CLAUDE_CODE_ATTRIBUTION_HEADER` | Defina como `0` para omitir o bloco de atribuição (versão do cliente e impressão digital do prompt) do início do prompt do sistema. Desabilitá-lo melhora as taxas de acerto do cache de prompt ao rotear através de um [gateway LLM](/pt/llm-gateway). O cache da API Anthropic não é afetado |

166| `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | Defina a capacidade de contexto em tokens usada para cálculos de auto-compactação. Padrão é a janela de contexto do modelo: 200K para modelos padrão ou 1M para modelos de [contexto estendido](/pt/model-config#extended-context), exceto em Sonnet 5, que tem seu próprio [limite padrão](/pt/model-config#sonnet-5-context-window). Use um valor mais baixo como `500000` em um modelo de 1M para tratar a janela como 500K para fins de compactação. O valor é limitado à janela de contexto real do modelo. `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` é aplicado como uma porcentagem deste valor. Definir esta variável desacopla o limite de compactação do `used_percentage` da linha de status, que sempre usa a janela de contexto completa do modelo |170| `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | Defina a capacidade de contexto em tokens usada para cálculos de auto-compactação. Padrão é a janela de contexto do modelo: 200K para modelos padrão ou 1M para modelos de [contexto estendido](/pt/model-config#extended-context), exceto em Sonnet 5, que tem seu próprio [limite padrão](/pt/model-config#sonnet-5-context-window). Use um valor mais baixo como `500000` em um modelo de 1M para tratar a janela como 500K para fins de compactação. O valor é limitado à janela de contexto real do modelo. `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` é aplicado como uma porcentagem deste valor. Definir esta variável desacopla o limite de compactação do `used_percentage` da linha de status, que sempre usa a janela de contexto completa do modelo |

167| `CLAUDE_CODE_AUTO_CONNECT_IDE` | Substitua a [conexão IDE](/pt/vs-code) automática. Por padrão, Claude Code se conecta automaticamente quando iniciado dentro do terminal integrado de uma IDE suportada. 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`](/pt/settings#global-config-settings) |171| `CLAUDE_CODE_AUTO_CONNECT_IDE` | Substitua a [conexão IDE](/pt/vs-code) automática. Por padrão, Claude Code se conecta automaticamente quando iniciado dentro do terminal integrado de uma IDE suportada. 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`](/pt/settings#global-config-settings) |

172| `CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS` | {/* min-version: 2.1.207 */}Tempo em milissegundos que Claude Code aguarda para que a cadeia de provedor de credencial padrão AWS produza credenciais antes da solicitação falhar com [`AWS default-chain credential resolve timed out`](/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 SSO baseado em navegador com MFA através de um wrapper como `aws-vault`. Aplica-se onde Claude Code assina com a cadeia padrão: [Amazon Bedrock](/pt/amazon-bedrock#credential-caching-and-resolution-timeout), [Claude Platform on AWS](/pt/claude-platform-on-aws) e o [endpoint Mantle](/pt/amazon-bedrock#use-the-mantle-endpoint). Requer Claude Code v2.1.207 ou posterior |

168| `CLAUDE_CODE_BRIDGE_SESSION_ID` | {/* min-version: 2.1.199 */}Definido automaticamente em subprocessos de ferramenta Bash e [comando hook](/pt/hooks) enquanto a sessão tem uma conexão [Remote Control](/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](/pt/claude-code-on-the-web), leia `CLAUDE_CODE_REMOTE_SESSION_ID` em vez disso |173| `CLAUDE_CODE_BRIDGE_SESSION_ID` | {/* min-version: 2.1.199 */}Definido automaticamente em subprocessos de ferramenta Bash e [comando hook](/pt/hooks) enquanto a sessão tem uma conexão [Remote Control](/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](/pt/claude-code-on-the-web), leia `CLAUDE_CODE_REMOTE_SESSION_ID` em vez disso |

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

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

176| `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 |181| `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 |

177| `CLAUDE_CODE_DISABLE_1M_CONTEXT` | Defina como `1` para desabilitar suporte a [janela de contexto de 1M](/pt/model-config#extended-context). Quando definido, variantes de modelo de 1M não estão disponíveis no seletor de modelo, e sessões [Sonnet 5](/pt/model-config#sonnet-5-context-window) são tratadas como tendo uma janela de 200K. Útil para ambientes corporativos com requisitos de conformidade |182| `CLAUDE_CODE_DISABLE_1M_CONTEXT` | Defina como `1` para desabilitar suporte a [janela de contexto de 1M](/pt/model-config#extended-context). Quando definido, variantes de modelo de 1M não estão disponíveis no seletor de modelo, e sessões [Sonnet 5](/pt/model-config#sonnet-5-context-window) são tratadas como tendo uma janela de 200K. Útil para ambientes corporativos com requisitos de conformidade |

178| `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` | Defina como `1` para desabilitar [raciocínio adaptativo](/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`. {/* min-version: 2.1.111 */}A partir de v2.1.111, não tem efeito em Fable 5, Sonnet 5 ou Opus 4.7 e posterior, que sempre usam raciocínio adaptativo |183| `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` | Defina como `1` para desabilitar [raciocínio adaptativo](/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`. {/* min-version: 2.1.111 */}A partir de v2.1.111, não tem efeito em Fable 5, Sonnet 5 ou Opus 4.7 e posterior, que sempre usam raciocínio adaptativo |

179| `CLAUDE_CODE_DISABLE_ADVISOR_TOOL` | {/* min-version: 2.1.98 */}Defina como `1` para desabilitar a [ferramenta advisor](/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. Requer Claude Code v2.1.98 ou posterior |184| `CLAUDE_CODE_DISABLE_ADVISOR_TOOL` | Defina como `1` para desabilitar a [ferramenta advisor](/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 |

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

181| `CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN` | Defina como `1` para desabilitar [renderização em tela cheia](/pt/fullscreen) e usar o renderizador de tela principal clássico. A conversa permanece 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`](/pt/settings#available-settings). Você também pode alternar com `/tui default`. Não se aplica a sessões em segundo plano abertas de [visualização de agentes](/pt/agent-view), que sempre usam renderização em tela cheia |186| `CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN` | Defina como `1` para desabilitar [renderização em tela cheia](/pt/fullscreen) e usar o renderizador de tela principal clássico. A conversa permanece 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`](/pt/settings#available-settings). Você também pode alternar com `/tui default`. Não se aplica a sessões em segundo plano abertas de [visualização de agentes](/pt/agent-view), que sempre usam renderização em tela cheia |

182| `CLAUDE_CODE_DISABLE_ARTIFACT` | Defina como `1` para desabilitar a ferramenta [Artifact](/pt/artifacts), que publica saída de sessão como uma página web privada em claude.ai. Equivalente à configuração [`disableArtifact`](/pt/settings#available-settings) |187| `CLAUDE_CODE_DISABLE_ARTIFACT` | Defina como `1` para desabilitar a ferramenta [Artifact](/pt/artifacts), que publica saída de sessão como uma página web privada em claude.ai. Equivalente à configuração [`disableArtifact`](/pt/settings#available-settings) |

183| `CLAUDE_CODE_DISABLE_ATTACHMENTS` | Defina como `1` para desabilitar o 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 |188| `CLAUDE_CODE_DISABLE_ATTACHMENTS` | Defina como `1` para desabilitar o 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 |

184| `CLAUDE_CODE_DISABLE_AUTO_MEMORY` | Defina como `1` para desabilitar [memória automática](/pt/memory#auto-memory). Defina como `0` para forçar a memória automática mesmo quando `--bare` mode ou [`autoMemoryEnabled: false`](/pt/settings#available-settings) desabilitaria de outra forma. Quando desabilitada, Claude não cria ou carrega arquivos de memória automática |189| `CLAUDE_CODE_DISABLE_AUTO_MEMORY` | Defina como `1` para desabilitar [memória automática](/pt/memory#auto-memory). Defina como `0` para forçar a memória automática mesmo quando `--bare` mode ou [`autoMemoryEnabled: false`](/pt/settings#available-settings) desabilitaria de outra forma. Quando desabilitada, Claude não cria ou carrega arquivos de memória automática |

185| `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` | Defina como `1` para desabilitar toda a funcionalidade de tarefas em segundo plano, incluindo o parâmetro `run_in_background` em ferramentas Bash e subagent, auto-backgrounding e o atalho Ctrl+B |190| `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` | Defina como `1` para desabilitar toda a funcionalidade de tarefas em segundo plano, incluindo o parâmetro `run_in_background` em ferramentas Bash e subagent, auto-backgrounding e o atalho Ctrl+B |

191| `CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD` | {/* min-version: 2.1.208 */}Defina como `1` para pular a verificação de que uma resposta de streaming [Amazon Bedrock](/pt/amazon-bedrock) carrega o tipo de conteúdo `application/vnd.amazon.eventstream`. Sem essa variável, uma resposta com um tipo de conteúdo diferente falha com um erro nomeando esse tipo de conteúdo, o que significa que um [gateway ou proxy está transformando a resposta](/pt/amazon-bedrock#streaming-errors-behind-a-gateway-or-proxy). Defina apenas quando o gateway reescreve o cabeçalho `Content-Type` mas passa o corpo do event-stream binário inalterado; se o corpo em si foi transformado, as solicitações falham com `Truncated event message received` em vez disso. Requer Claude Code v2.1.208 ou posterior |

186| `CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF` | {/* min-version: 2.1.196 */}Defina como `1` para parar os comandos de shell em segundo plano em execução de uma [sessão em segundo plano](/pt/agent-view), fluxos de trabalho dinâmicos e, {/* min-version: 2.1.198 */}a partir de v2.1.198, subagentes em segundo plano quando o [supervisor](/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: colocar uma sessão em segundo plano com `←` ou [`/background`](/pt/agent-view#from-inside-a-session) ainda carrega o trabalho em andamento, e `CLAUDE_DISABLE_ADOPT` desativa ambos. Requer Claude Code v2.1.196 ou posterior |192| `CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF` | {/* min-version: 2.1.196 */}Defina como `1` para parar os comandos de shell em segundo plano em execução de uma [sessão em segundo plano](/pt/agent-view), fluxos de trabalho dinâmicos e, {/* min-version: 2.1.198 */}a partir de v2.1.198, subagentes em segundo plano quando o [supervisor](/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: colocar uma sessão em segundo plano com `←` ou [`/background`](/pt/agent-view#from-inside-a-session) ainda carrega o trabalho em andamento, e `CLAUDE_DISABLE_ADOPT` desativa ambos. Requer Claude Code v2.1.196 ou posterior |

187| `CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP` | {/* min-version: 2.1.193 */}Defina como `1` para parar Claude Code de encerrar [comandos de shell em segundo plano](/pt/interactive-mode#background-bash-commands) quando o sistema operacional relata pressão de memória. Por padrão, em macOS e Linux, Claude Code encerra um shell em segundo plano iniciado na sessão principal em um sinal de pressão de memória uma vez que a sessão ficou ociosa por 30 minutos e nenhuma volta ou subagente está 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 |193| `CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP` | {/* min-version: 2.1.193 */}Defina como `1` para parar Claude Code de encerrar [comandos de shell em segundo plano](/pt/interactive-mode#background-bash-commands) quando o sistema operacional relata pressão de memória. Por padrão, em macOS e Linux, Claude Code encerra um shell em segundo plano iniciado na sessão principal em um sinal de pressão de memória uma vez que a sessão ficou ociosa por 30 minutos e nenhuma volta ou subagente está 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 |

188| `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS` | Defina como `1` para desabilitar as [skills](/pt/skills) e workflows que vêm com Claude Code: skills agrupadas e workflows integrados são removidos inteiramente, enquanto comandos slash integrados como `/init` permanecem digitáveis mas são ocultados do modelo. Skills de plugins, `.claude/skills/` e `.claude/commands/` não são afetadas. Equivalente à configuração [`disableBundledSkills`](/pt/settings#available-settings); `0` não a substitui |194| `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS` | Defina como `1` para desabilitar as [skills](/pt/skills) e workflows que vêm com Claude Code: skills agrupadas e workflows integrados são removidos inteiramente, enquanto comandos slash 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` em vez disso. Skills de plugins, `.claude/skills/` e `.claude/commands/` não são afetadas. Equivalente à configuração [`disableBundledSkills`](/pt/settings#available-settings); `0` não a substitui |

189| `CLAUDE_CODE_DISABLE_CLAUDE_MDS` | Defina como `1` para evitar carregar qualquer arquivo de memória CLAUDE.md no contexto, incluindo arquivos de usuário, projeto e memória automática |195| `CLAUDE_CODE_DISABLE_CLAUDE_MDS` | Defina como `1` para evitar carregar qualquer arquivo de memória CLAUDE.md no contexto, incluindo arquivos de usuário, projeto e memória automática |

190| `CLAUDE_CODE_DISABLE_CRON` | Defina como `1` para desabilitar [tarefas agendadas](/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 |196| `CLAUDE_CODE_DISABLE_CRON` | Defina como `1` para desabilitar [tarefas agendadas](/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 |

191| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | Defina como `1` para remover cabeçalhos de solicitação `anthropic-beta` específicos do 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 |197| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | Defina como `1` para remover cabeçalhos de solicitação `anthropic-beta` específicos do 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](/pt/mcp#scale-with-mcp-tool-search) é desabilitada e todas as ferramentas MCP carregam antecipadamente, mesmo quando `ENABLE_TOOL_SEARCH` está definido |

192| `CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS` | {/* min-version: 2.1.198 */}Defina como `1` para desabilitar os [subagentes Explore e Plan](/pt/sub-agents#built-in-subagents) integrados. Claude explora com suas ferramentas de busca ou o subagente de propósito geral em vez disso, e [modo plan](/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 todos os tipos de subagentes integrados no Agent SDK ou modo não interativo, use `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS` em vez disso. Requer Claude Code v2.1.198 ou posterior |198| `CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS` | {/* min-version: 2.1.198 */}Defina como `1` para desabilitar os [subagentes Explore e Plan](/pt/sub-agents#built-in-subagents) integrados. Claude explora com suas ferramentas de busca ou o subagente de propósito geral em vez disso, e [modo plan](/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 todos os tipos de subagentes integrados no Agent SDK ou modo não interativo, use `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS` em vez disso. Requer Claude Code v2.1.198 ou posterior |

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

194| `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` | Defina como `1` para desabilitar as pesquisas de qualidade de sessão "Como Claude está se saindo?". 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 participar novamente. Para definir uma taxa de amostra em vez de desabilitar completamente, use a configuração [`feedbackSurveyRate`](/pt/settings#available-settings). Veja [Pesquisas de qualidade de sessão](/pt/data-usage#session-quality-surveys) |200| `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` | Defina como `1` para desabilitar as pesquisas de qualidade de sessão "Como Claude está se saindo?". 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 participar novamente. Para definir uma taxa de amostra em vez de desabilitar completamente, use a configuração [`feedbackSurveyRate`](/pt/settings#available-settings). Veja [Pesquisas de qualidade de sessão](/pt/data-usage#session-quality-surveys) |

208| `CLAUDE_CODE_DISABLE_WORKFLOWS` | Defina como `1` para desabilitar [workflows](/pt/workflows#turn-workflows-off). Equivalente à configuração [`disableWorkflows`](/pt/settings#available-settings) |214| `CLAUDE_CODE_DISABLE_WORKFLOWS` | Defina como `1` para desabilitar [workflows](/pt/workflows#turn-workflows-off). Equivalente à configuração [`disableWorkflows`](/pt/settings#available-settings) |

209| `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` e a configuração `effortLevel`. Veja [Ajustar nível de esforço](/pt/model-config#adjust-effort-level) |215| `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` e a configuração `effortLevel`. Veja [Ajustar nível de esforço](/pt/model-config#adjust-effort-level) |

210| `CLAUDE_CODE_ENABLE_APPEND_SUBAGENT_PROMPT` | {/* min-version: 2.1.205 */}Defina como `1` para habilitar a adição de texto extra ao final do prompt do sistema de cada [subagente](/pt/sub-agents). A flag [`--append-subagent-system-prompt`](/pt/cli-reference#cli-flags) fornece o texto adicionado e define esta variável automaticamente, então você não precisa defini-la você mesmo. Requer Claude Code v2.1.205 ou posterior |216| `CLAUDE_CODE_ENABLE_APPEND_SUBAGENT_PROMPT` | {/* min-version: 2.1.205 */}Defina como `1` para habilitar a adição de texto extra ao final do prompt do sistema de cada [subagente](/pt/sub-agents). A flag [`--append-subagent-system-prompt`](/pt/cli-reference#cli-flags) fornece o texto adicionado e define esta variável automaticamente, então você não precisa defini-la você mesmo. Requer Claude Code v2.1.205 ou posterior |

211| `CLAUDE_CODE_ENABLE_AUTO_MODE` | {/* min-version: 2.1.158 */}Defina como `1` para disponibilizar [modo automático](/pt/permission-modes#eliminate-prompts-with-auto-mode) em Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry e sessões [gateway de aplicativos Claude](/pt/claude-apps-gateway) conectadas. Requer Claude Code v2.1.158 ou posterior. Não tem efeito na API Anthropic, onde o modo automático está disponível por padrão. Veja [Habilitar modo automático em Amazon Bedrock, Google Cloud's Agent Platform ou Microsoft Foundry](/pt/permission-modes#enable-auto-mode-on-bedrock-agent-platform-or-foundry) |217| `CLAUDE_CODE_ENABLE_AUTO_MODE` | {/* min-version: 2.1.207 */}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 [gateway de aplicativos Claude](/pt/claude-apps-gateway) conectadas. Em v2.1.158 através v2.1.206, definir isso como `1` era necessário para disponibilizar [modo automático](/pt/permission-modes#eliminate-prompts-with-auto-mode) nesses provedores |

212| `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` | Substitua a disponibilidade de [recapitulação de sessão](/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`](/pt/settings#available-settings) é `false`. Tem precedência sobre a configuração e toggle `/config` |218| `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` | Substitua a disponibilidade de [recapitulação de sessão](/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`](/pt/settings#available-settings) é `false`. Tem precedência sobre a configuração e toggle `/config` |

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

214| `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` | Defina como `1` para rotear a pesquisa de qualidade de sessão "Como Claude está se saindo?" para seu próprio [coletor OpenTelemetry](/pt/monitoring-usage) quando o tráfego não essencial vinculado ao Anthropic está bloqueado. As classificações de pesquisa são emitidas apenas como eventos OTEL para seu coletor configurado. Nenhum dado de pesquisa é enviado ao 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 do produto da organização têm precedência |220| `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` | Defina como `1` para rotear a pesquisa de qualidade de sessão "Como Claude está se saindo?" para seu próprio [coletor OpenTelemetry](/pt/monitoring-usage) quando o tráfego não essencial vinculado ao Anthropic está bloqueado. As classificações de pesquisa são emitidas apenas como eventos OTEL para seu coletor configurado. Nenhum dado de pesquisa é enviado ao 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 do produto da organização têm precedência |

220| `CLAUDE_CODE_ENABLE_TELEMETRY` | Defina como `1` para habilitar coleta de dados OpenTelemetry para métricas e logging. Obrigatório antes de configurar exportadores OTel. Veja [Monitoramento](/pt/monitoring-usage) |226| `CLAUDE_CODE_ENABLE_TELEMETRY` | Defina como `1` para habilitar coleta de dados OpenTelemetry para métricas e logging. Obrigatório antes de configurar exportadores OTel. Veja [Monitoramento](/pt/monitoring-usage) |

221| `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 fluxos de trabalho automatizados e scripts usando modo SDK |227| `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 fluxos de trabalho automatizados e scripts usando modo SDK |

222| `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` | Defina como `1` para habilitar [equipes de agentes](/pt/agent-teams). As equipes de agentes são experimentais e desabilitadas por padrão |228| `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` | Defina como `1` para habilitar [equipes de agentes](/pt/agent-teams). As equipes de agentes são experimentais e desabilitadas por padrão |

223| `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 |229| `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. {/* min-version: 2.1.206 */}Um valor exportado em seu shell também se aplica às [sessões em segundo plano](/pt/agent-view) que você despacha com `claude agents` ou `--bg`. Antes de 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 herdou |

224| `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 na íntegra |230| `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 na íntegra |

225| `CLAUDE_CODE_FORCE_SESSION_PERSISTENCE` | {/* min-version: 2.1.172 */}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 pela primeira vez pela ferramenta Bash do Claude Code, causa uma sessão genuína de nível superior a ser classificada incorretamente como aninhada. {/* min-version: 2.1.178 */}A partir de v2.1.178, Claude Code detecta o caso tmux automaticamente e ignora o marcador herdado, então tmux não precisa mais dessa variável. Também honrado em v2.1.169 e anterior; não tem efeito em v2.1.170 e v2.1.171, onde a detecção de sessão aninhada que ele substitui foi removida |231| `CLAUDE_CODE_FORCE_SESSION_PERSISTENCE` | {/* min-version: 2.1.172 */}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 pela primeira vez pela ferramenta Bash do Claude Code, causa uma sessão genuína de nível superior a ser classificada incorretamente como aninhada. {/* min-version: 2.1.178 */}A partir de v2.1.178, Claude Code detecta o caso tmux automaticamente e ignora o marcador herdado, então tmux não precisa mais dessa variável. Também honrado em v2.1.169 e anterior; não tem efeito em v2.1.170 e v2.1.171, onde a detecção de sessão aninhada que ele substitui foi removida |

226| `CLAUDE_CODE_FORCE_STRIKETHROUGH` | {/* min-version: 2.1.186 */}Defina como `1` para forçar renderização de tachado para `~~text~~` nas respostas do Claude quando seu terminal suporta mas não é detectado automaticamente, 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 |232| `CLAUDE_CODE_FORCE_STRIKETHROUGH` | {/* min-version: 2.1.186 */}Defina como `1` para forçar renderização de tachado para `~~text~~` nas respostas do Claude quando seu terminal suporta mas não é detectado automaticamente, 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 |

227| `CLAUDE_CODE_FORCE_SYNC_OUTPUT` | Defina como `1` para forçar a habilitação do modo privado DEC 2026 [saída sincronizada](https://gist.github.com/christianparpart/d8a62cc1ab659194337d73e399004036) quando seu terminal suporta mas não é detectado automaticamente. Útil para emuladores como `eat` do Emacs que implementam BSU/ESU mas não respondem à sonda de capacidade. Não tem efeito sob tmux |233| `CLAUDE_CODE_FORCE_SYNC_OUTPUT` | Defina como `1` para forçar a habilitação do modo privado DEC 2026 [saída sincronizada](https://gist.github.com/christianparpart/d8a62cc1ab659194337d73e399004036) quando seu terminal suporta mas não é detectado automaticamente. Ú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](/pt/fullscreen), isso não altera o renderizador |

228| `CLAUDE_CODE_FORK_SUBAGENT` | Defina como `1` para permitir [subagentes bifurcados](/pt/sub-agents#fork-the-current-conversation), ou `0` para desabilitá-los, substituindo qualquer rollout do lado do servidor. Quando habilitado, Claude pode solicitar o tipo de subagente `fork` para gerar uma bifurcação, um subagente que herda o contexto de conversa completo em vez de começar do zero. Spawns sem um tipo de subagente ainda usam o subagente de propósito geral, e todos os spawns de subagente são executados em segundo plano. O comando [`/fork`](/pt/commands) explícito funciona sem essa variável. Funciona em modo interativo e via SDK ou `claude -p` |234| `CLAUDE_CODE_FORK_SUBAGENT` | Defina como `1` para permitir [subagentes bifurcados](/pt/sub-agents#fork-the-current-conversation), ou `0` para desabilitá-los, substituindo qualquer rollout do lado do servidor. Quando habilitado, Claude pode solicitar o tipo de subagente `fork` para gerar uma bifurcação, um subagente que herda o contexto de conversa completo em vez de começar do zero. Spawns sem um tipo de subagente ainda usam o subagente de propósito geral, e todos os spawns de subagente são executados em segundo plano. O comando [`/fork`](/pt/commands) explícito funciona sem essa variável. Funciona em modo interativo e via SDK ou `claude -p` |

229| `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 está no seu PATH. Veja [Configuração do Windows](/pt/setup#set-up-on-windows) |235| `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 está no seu PATH. Veja [Configuração do Windows](/pt/setup#set-up-on-windows) |

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

261| `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 contêiner. 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 contêineres](/pt/plugin-marketplaces#pre-populate-plugins-for-containers) |267| `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 contêiner. 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 contêineres](/pt/plugin-marketplaces#pre-populate-plugins-for-containers) |

262| `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 linha de status, e respeitar a política de execução efetiva da máquina em vez disso. Por padrão, Claude Code contorna a política de execução no escopo do processo para que scripts `.ps1` e importações de módulo funcionem em instalações Windows padrão com Restricted. O bypass no escopo do processo nunca substitui a Política de Grupo `MachinePolicy` ou `UserPolicy` independentemente dessa configuração |268| `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 linha de status, e respeitar a política de execução efetiva da máquina em vez disso. Por padrão, Claude Code contorna a política de execução no escopo do processo para que scripts `.ps1` e importações de módulo funcionem em instalações Windows padrão com Restricted. O bypass no escopo do processo nunca substitui a Política de Grupo `MachinePolicy` ou `UserPolicy` independentemente dessa configuração |

263| `CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS` | {/* min-version: 2.1.182 */}Tempo máximo em milissegundos que [modo não interativo](/pt/headless#background-tasks-at-exit) com a flag `-p` aguarda após a volta final para subagentes em segundo plano e workflows cujo resultado faz parte da saída. Padrão: `600000`, ou 10 minutos. Quando o limite é excedido, tarefas em segundo plano restantes são encerradas e o processo sai. Defina como `0` para aguardar indefinidamente. Este limite é separado do período de carência de cinco segundos que se aplica a shells em segundo plano simples |269| `CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS` | {/* min-version: 2.1.182 */}Tempo máximo em milissegundos que [modo não interativo](/pt/headless#background-tasks-at-exit) com a flag `-p` aguarda após a volta final para subagentes em segundo plano e workflows cujo resultado faz parte da saída. Padrão: `600000`, ou 10 minutos. Quando o limite é excedido, tarefas em segundo plano restantes são encerradas e o processo sai. Defina como `0` para aguardar indefinidamente. Este limite é separado do período de carência de cinco segundos que se aplica a shells em segundo plano simples |

270| `CLAUDE_CODE_PROCESS_WRAPPER` | {/* min-version: 2.1.208 */}Inicie os processos que Claude Code começa a partir de seu próprio binário através de um executável wrapper, dado como um prefixo argv como `/opt/corp/launcher`. Cobre o serviço em segundo plano que hospeda sessões [visualização de agentes](/pt/agent-view), cada sessão que ele gera e o relançamento que Claude Code realiza de si mesmo para terminar de instalar uma atualização. O primeiro token deve ser o caminho absoluto de um executável que termina executando `exec "$@"`, e a maioria dos lançadores é apenas esse caminho único. O valor é uma lista de argumentos, não um comando de shell: espaço em branco separa tokens, aspas duplas agrupam um caminho que contém espaços, e um valor que começa com `[` é lido como uma matriz de string JSON. Defina em bloco `env` de configurações de usuário ou [gerenciadas](/pt/permissions#managed-settings), não como exportação de shell, para que o serviço em segundo plano desanexado o herde; configurações de projeto e local não podem defini-lo. A extensão VS Code configura seu próprio lançador separadamente através de sua configuração `claudeProcessWrapper`. Ignorado no Windows. `CLAUDE_CODE_SHELL_PREFIX` é um controle separado: envolve os comandos de shell que Claude Code executa como uma string única entre aspas, enquanto essa variável envolve os próprios processos do Claude Code como um prefixo argv. Veja [Executar Claude Code atrás de um lançador corporativo](/pt/corporate-launcher) |

264| `CLAUDE_CODE_PROPAGATE_TRACEPARENT` | {/* min-version: 2.1.152 */}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 é habilitada apenas quando conectado diretamente à API Anthropic. Adicionado em v2.1.152. Veja [Rastreamentos (beta)](/pt/monitoring-usage#traces-beta) |271| `CLAUDE_CODE_PROPAGATE_TRACEPARENT` | {/* min-version: 2.1.152 */}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 é habilitada apenas quando conectado diretamente à API Anthropic. Adicionado em v2.1.152. Veja [Rastreamentos (beta)](/pt/monitoring-usage#traces-beta) |

265| `CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST` | Definido por plataformas host que incorporam Claude Code e gerenciam roteamento de provedor de modelo em seu nome. Quando definido, seleção de provedor, endpoint e variáveis de autenticação como `CLAUDE_CODE_USE_BEDROCK`, `ANTHROPIC_BASE_URL` e `ANTHROPIC_API_KEY` em arquivos de configuração são ignorados para que configurações de usuário não possam substituir o roteamento do host. O opt-out automático de telemetria para Amazon Bedrock, Google Cloud's Agent Platform e Microsoft Foundry também é ignorado, então a telemetria segue o opt-out padrão `DISABLE_TELEMETRY`. Veja [Comportamentos padrão por provedor de API](/pt/data-usage#default-behaviors-by-api-provider) |272| `CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST` | Definido por plataformas host que incorporam Claude Code e gerenciam roteamento de provedor de modelo em seu nome. Quando definido, seleção de provedor, endpoint e variáveis de autenticação como `CLAUDE_CODE_USE_BEDROCK`, `ANTHROPIC_BASE_URL` e `ANTHROPIC_API_KEY` em arquivos de configuração são ignorados para que configurações de usuário não possam substituir o roteamento do host. O opt-out automático de telemetria para Amazon Bedrock, Google Cloud's Agent Platform e Microsoft Foundry também é ignorado, então a telemetria segue o opt-out padrão `DISABLE_TELEMETRY`. Veja [Comportamentos padrão por provedor de API](/pt/data-usage#default-behaviors-by-api-provider) |

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

279| `CLAUDE_CODE_SIMPLE` | Defina como `1` para executar com um prompt do sistema mínimo e apenas as 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, plugins, servidores MCP, memória automática e CLAUDE.md. Tokens OAuth e credenciais de keychain não são lidos, então a autenticação Anthropic deve vir de `ANTHROPIC_API_KEY` ou um `apiKeyHelper` em `--settings`. Equivalente a passar [`--bare`](/pt/headless#start-faster-with-bare-mode) |286| `CLAUDE_CODE_SIMPLE` | Defina como `1` para executar com um prompt do sistema mínimo e apenas as 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, plugins, servidores MCP, memória automática e CLAUDE.md. Tokens OAuth e credenciais de keychain não são lidos, então a autenticação Anthropic deve vir de `ANTHROPIC_API_KEY` ou um `apiKeyHelper` em `--settings`. Equivalente a passar [`--bare`](/pt/headless#start-faster-with-bare-mode) |

280| `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 optar por não participar mesmo em modelos onde o experimento ou configuração do servidor habilitaria de outra forma. O conjunto de ferramentas completo, hooks, servidores MCP e descoberta de CLAUDE.md permanecem habilitados |287| `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 optar por não participar mesmo em modelos onde o experimento ou configuração do servidor habilitaria de outra forma. O conjunto de ferramentas completo, hooks, servidores MCP e descoberta de CLAUDE.md permanecem habilitados |

281| `CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH` | Pule autenticação do lado do cliente para [Claude Platform on AWS](/pt/claude-platform-on-aws), para gateways que assinam solicitações por conta própria |288| `CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH` | Pule autenticação do lado do cliente para [Claude Platform on AWS](/pt/claude-platform-on-aws), para gateways que assinam solicitações por conta própria |

289| `CLAUDE_CODE_SKIP_AWS_CRED_CACHE` | {/* min-version: 2.1.207 */}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 tempo limite de resolução](/pt/amazon-bedrock#credential-caching-and-resolution-timeout). Requer Claude Code v2.1.207 ou posterior |

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

283| `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 do 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. {/* min-version: 2.1.203 */}Antes de 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 |291| `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 do 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. {/* min-version: 2.1.203 */}Antes de 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 |

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

295| `CLAUDE_CODE_SYNTAX_HIGHLIGHT` | Defina como `false` para desabilitar destaque de sintaxe na 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`](/pt/settings) |303| `CLAUDE_CODE_SYNTAX_HIGHLIGHT` | Defina como `false` para desabilitar destaque de sintaxe na 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`](/pt/settings) |

296| `CLAUDE_CODE_TASK_LIST_ID` | Compartilhe uma lista de tarefas entre sessões. Defina o mesmo ID em múltiplas instâncias do Claude Code para coordenar em uma lista de tarefas compartilhada. Veja [Lista de tarefas](/pt/interactive-mode#task-list) |304| `CLAUDE_CODE_TASK_LIST_ID` | Compartilhe uma lista de tarefas entre sessões. Defina o mesmo ID em múltiplas instâncias do Claude Code para coordenar em uma lista de tarefas compartilhada. Veja [Lista de tarefas](/pt/interactive-mode#task-list) |

297| `CLAUDE_CODE_TEAM_NAME` | Nome da equipe de agentes à qual este companheiro pertence. Definido automaticamente em membros de [equipe de agentes](/pt/agent-teams) |305| `CLAUDE_CODE_TEAM_NAME` | Nome da equipe de agentes à qual este companheiro pertence. Definido automaticamente em membros de [equipe de agentes](/pt/agent-teams) |

306| `CLAUDE_CODE_TEAM_TEARDOWN_PARK_TIMEOUT_MS` | {/* min-version: 2.1.206 */}Substitua, em milissegundos, quanto tempo uma sessão não interativa aguarda na saída para que sua [equipe de agentes](/pt/agent-teams) termine 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 |

298| `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 este caminho. Padrão: `/tmp` em macOS, `os.tmpdir()` em Linux e Windows. {/* min-version: 2.1.161 */}A partir de v2.1.161, em macOS e Linux, subprocessos Bash [sandboxed](/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 inalterado. Os próprios arquivos temporários do Claude Code sempre usam sua substituição |307| `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 este caminho. Padrão: `/tmp` em macOS, `os.tmpdir()` em Linux e Windows. {/* min-version: 2.1.161 */}A partir de v2.1.161, em macOS e Linux, subprocessos Bash [sandboxed](/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 inalterado. Os próprios arquivos temporários do Claude Code sempre usam sua substituição |

299| `CLAUDE_CODE_TMUX_TRUECOLOR` | Defina como `1` para permitir saída truecolor de 24 bits dentro de tmux. 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 esteja configurado para isso. Defina isso após adicionar `set -ga terminal-overrides ',*:Tc'` ao seu `~/.tmux.conf`. Veja [Configuração de terminal](/pt/terminal-config) para outras configurações de tmux |308| `CLAUDE_CODE_TMUX_TRUECOLOR` | Defina como `1` para permitir saída truecolor de 24 bits dentro de tmux. 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 esteja configurado para isso. Defina isso após adicionar `set -ga terminal-overrides ',*:Tc'` ao seu `~/.tmux.conf`. Veja [Configuração de terminal](/pt/terminal-config) para outras configurações de tmux |

300| `CLAUDE_CODE_USE_ANTHROPIC_AWS` | Use [Claude Platform on AWS](/pt/claude-platform-on-aws) |309| `CLAUDE_CODE_USE_ANTHROPIC_AWS` | Use [Claude Platform on AWS](/pt/claude-platform-on-aws) |

318| `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ê deseja controle explícito sobre quando a compactação ocorre |327| `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ê deseja controle explícito sobre quando a compactação ocorre |

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

320| `DISABLE_COST_WARNINGS` | Defina como `1` para desabilitar mensagens de aviso de custo |329| `DISABLE_COST_WARNINGS` | Defina como `1` para desabilitar mensagens de aviso de custo |

321| `DISABLE_DOCTOR_COMMAND` | Defina como `1` para ocultar o comando `/doctor` 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`. {/* min-version: 2.1.205 */}Antes de v2.1.205, essa variável ocultava a tela de diagnósticos `/doctor` |330| `DISABLE_DOCTOR_COMMAND` | Defina como `1` para ocultar a skill de verificação de configuração [`/doctor`](/pt/commands#all-commands) 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`. {/* min-version: 2.1.205 */}Antes de v2.1.205, essa variável ocultava a tela de diagnósticos `/doctor` |

322| `DISABLE_ERROR_REPORTING` | Defina como `1` para optar por não participar do relatório de erros do Sentry |331| `DISABLE_ERROR_REPORTING` | Defina como `1` para optar por não participar do relatório de erros |

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

324| `DISABLE_FEEDBACK_COMMAND` | Defina como `1` para desabilitar o comando `/feedback`. O nome mais antigo `DISABLE_BUG_COMMAND` também é aceito |333| `DISABLE_FEEDBACK_COMMAND` | Defina como `1` para desabilitar o comando `/feedback`. O nome mais antigo `DISABLE_BUG_COMMAND` também é aceito |

325| `DISABLE_GROWTHBOOK` | Defina como `1` para desabilitar busca de flag de recurso GrowthBook e usar padrões de código para cada flag. Logging de eventos de telemetria permanece ativado a menos que `DISABLE_TELEMETRY` também esteja definido |334| `DISABLE_GROWTHBOOK` | Defina como `1` para desabilitar busca de flag de recurso GrowthBook e usar padrões de código para cada flag. Logging de eventos de telemetria permanece ativado a menos que `DISABLE_TELEMETRY` também esteja definido |

340| `ENABLE_CLAUDEAI_MCP_SERVERS` | Defina como `false` para desabilitar [servidores MCP claude.ai](/pt/mcp#use-mcp-servers-from-claude-ai) no Claude Code. Habilitado por padrão para usuários conectados. Para desabilitar por projeto ou por organização, defina [`disableClaudeAiConnectors`](/pt/settings#available-settings) em configurações em vez disso |349| `ENABLE_CLAUDEAI_MCP_SERVERS` | Defina como `false` para desabilitar [servidores MCP claude.ai](/pt/mcp#use-mcp-servers-from-claude-ai) no Claude Code. Habilitado por padrão para usuários conectados. Para desabilitar por projeto ou por organização, defina [`disableClaudeAiConnectors`](/pt/settings#available-settings) em configurações em vez disso |

341| `ENABLE_PROMPT_CACHING_1H` | Defina como `1` para solicitar um TTL de cache de prompt de 1 hora em vez do padrão de 5 minutos. Destinado para usuários de chave de API, [Amazon Bedrock](/pt/amazon-bedrock), [Google Cloud's Agent Platform](/pt/google-vertex-ai), [Microsoft Foundry](/pt/microsoft-foundry) e [Claude Platform on AWS](/pt/claude-platform-on-aws). Usuários de assinatura recebem TTL de 1 hora automaticamente. Escritas de cache de 1 hora são cobradas a uma taxa mais alta |350| `ENABLE_PROMPT_CACHING_1H` | Defina como `1` para solicitar um TTL de cache de prompt de 1 hora em vez do padrão de 5 minutos. Destinado para usuários de chave de API, [Amazon Bedrock](/pt/amazon-bedrock), [Google Cloud's Agent Platform](/pt/google-vertex-ai), [Microsoft Foundry](/pt/microsoft-foundry) e [Claude Platform on AWS](/pt/claude-platform-on-aws). Usuários de assinatura recebem TTL de 1 hora automaticamente. Escritas de cache de 1 hora são cobradas a uma taxa mais alta |

342| `ENABLE_PROMPT_CACHING_1H_BEDROCK` | Descontinuado. Use `ENABLE_PROMPT_CACHING_1H` em vez disso |351| `ENABLE_PROMPT_CACHING_1H_BEDROCK` | Descontinuado. Use `ENABLE_PROMPT_CACHING_1H` em vez disso |

343| `ENABLE_TOOL_SEARCH` | Controla [busca de ferramentas MCP](/pt/mcp#scale-with-mcp-tool-search). Não definido: todas as ferramentas MCP adiadas por padrão, mas carregadas antecipadamente em Google Cloud's Agent Platform ou quando `ANTHROPIC_BASE_URL` aponta para um host que não é de primeira parte. Valores: `true` (sempre adia e envia o cabeçalho beta, solicitações falham em modelos Google Cloud's Agent Platform anteriores a Sonnet 4.5 ou Opus 4.5, ou em proxies que não suportam `tool_reference`), `auto` (modo de limite: carrega antecipadamente se as ferramentas se encaixarem em 10% do contexto), `auto:N` (limite personalizado, por exemplo, `auto:5` para 5%), `false` (carrega tudo antecipadamente) |352| `ENABLE_TOOL_SEARCH` | Controla [busca de ferramentas MCP](/pt/mcp#scale-with-mcp-tool-search). Não definido: todas as ferramentas MCP adiadas por padrão, mas carregadas antecipadamente em Google Cloud's Agent Platform ou quando `ANTHROPIC_BASE_URL` aponta para um host que não é de primeira parte. Valores: `true` (sempre adia e envia o cabeçalho beta, solicitações falham em modelos Google Cloud's Agent Platform anteriores a Sonnet 4.5 ou Opus 4.5, ou em proxies que não suportam `tool_reference`), `auto` (modo de limite: carrega antecipadamente se as ferramentas se encaixarem em 10% do contexto), `auto:N` (limite personalizado, por exemplo, `auto:5` para 5%), `false` (carrega tudo antecipadamente). Ignorado quando `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` está definido, que força todas as ferramentas a carregar antecipadamente |

344| `FALLBACK_FOR_ALL_PRIMARY_MODELS` | Defina como qualquer valor não vazio para fazer todos os modelos, não apenas Opus, parar de tentar novamente com um erro de sobrecarga repetido quando nenhum modelo fallback está configurado. {/* min-version: 2.1.160 */}A partir de v2.1.160, uma [cadeia de modelo fallback](/pt/model-config#fallback-model-chains) configurada aciona em erros de sobrecarga repetidos para qualquer modelo primário, então esta variável não afeta a alternância para um modelo fallback |353| `FALLBACK_FOR_ALL_PRIMARY_MODELS` | Defina como qualquer valor não vazio para fazer todos os modelos, não apenas Opus, parar de tentar novamente com um erro de sobrecarga repetido quando nenhum modelo fallback está configurado. {/* min-version: 2.1.160 */}A partir de v2.1.160, uma [cadeia de modelo fallback](/pt/model-config#fallback-model-chains) configurada aciona em erros de sobrecarga repetidos para qualquer modelo primário, então esta variável não afeta a alternância para um modelo fallback |

345| `FORCE_AUTOUPDATE_PLUGINS` | Defina como `1` para forçar auto-atualizações de plugins mesmo quando o auto-atualizador principal está desabilitado via `DISABLE_AUTOUPDATER` |354| `FORCE_AUTOUPDATE_PLUGINS` | Defina como `1` para forçar auto-atualizações de plugins mesmo quando o auto-atualizador principal está desabilitado via `DISABLE_AUTOUPDATER` |

355| `FORCE_HYPERLINK` | Defina como `1` para habilitar hyperlinks OSC 8 clicáveis quando seu terminal suporta mas não é detectado automaticamente, ou `0` para desabilitá-los |

346| `FORCE_PROMPT_CACHING_5M` | Defina como `1` para forçar o TTL de cache de prompt de 5 minutos mesmo quando o TTL de 1 hora se aplicaria de outra forma. Substitui `ENABLE_PROMPT_CACHING_1H` |356| `FORCE_PROMPT_CACHING_5M` | Defina como `1` para forçar o TTL de cache de prompt de 5 minutos mesmo quando o TTL de 1 hora se aplicaria de outra forma. Substitui `ENABLE_PROMPT_CACHING_1H` |

347| `HTTP_PROXY` | Especifique servidor proxy HTTP para conexões de rede |357| `HTTP_PROXY` | Especifique servidor proxy HTTP para conexões de rede |

348| `HTTPS_PROXY` | Especifique servidor proxy HTTPS para conexões de rede |358| `HTTPS_PROXY` | Especifique servidor proxy HTTPS para conexões de rede |

357| `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) |367| `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) |

358| `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) |368| `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) |

359| `MCP_TIMEOUT` | Tempo limite em milissegundos para inicialização do servidor MCP (padrão: 30000, ou 30 segundos) |369| `MCP_TIMEOUT` | Tempo limite em milissegundos para inicialização do servidor MCP (padrão: 30000, ou 30 segundos) |

360| `MCP_TOOL_TIMEOUT` | Tempo limite em milissegundos para execução de ferramentas MCP (padrão: 100000000, aproximadamente 28 horas). Um campo `timeout` por servidor em `.mcp.json` substitui isso para esse servidor. {/* min-version: 2.1.203 */}Um `timeout` por servidor de pelo menos 1000 também define a janela de inatividade mínima para as chamadas de ferramenta desse servidor, então `CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT` nunca as aborta mais cedo; este piso requer Claude Code v2.1.203 ou posterior. Para a variável env, valores abaixo de 1000 são fixados em um segundo; para o campo por servidor, valores abaixo de 1000 são ignorados |370| `MCP_TOOL_TIMEOUT` | Tempo limite em milissegundos para execução de ferramentas 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 tempo limite geral de execução de ferramenta mas deixa o limite por solicitação em 60 segundos. Servidores Stdio e WebSocket não têm temporizador por solicitação. Um campo `timeout` por servidor em `.mcp.json` substitui isso para esse servidor. {/* min-version: 2.1.203 */}Um `timeout` por servidor de pelo menos 1000 também define a janela de inatividade mínima para as chamadas de ferramenta desse servidor, então `CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT` nunca as aborta mais cedo; este piso requer Claude Code v2.1.203 ou posterior. Para a variável env, valores abaixo de 1000 são fixados em um segundo; para o campo por servidor, valores abaixo de 1000 são ignorados |

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

362| `OTEL_LOG_ASSISTANT_RESPONSES` | {/* min-version: 2.1.193 */}Defina como `1` para incluir o texto de resposta do modelo em eventos de log OpenTelemetry `assistant_response`. Quando não definido, o valor de `OTEL_LOG_USER_PROMPTS` é usado em vez disso. Defina como `0` para manter respostas redatadas mesmo quando `OTEL_LOG_USER_PROMPTS` está definido. Requer Claude Code v2.1.193 ou posterior. Veja [Monitoramento](/pt/monitoring-usage#assistant-response-event) |372| `OTEL_LOG_ASSISTANT_RESPONSES` | {/* min-version: 2.1.193 */}Defina como `1` para incluir o texto de resposta do modelo em eventos de log OpenTelemetry `assistant_response`. Quando não definido, o valor de `OTEL_LOG_USER_PROMPTS` é usado em vez disso. Defina como `0` para manter respostas redatadas mesmo quando `OTEL_LOG_USER_PROMPTS` está definido. Requer Claude Code v2.1.193 ou posterior. Veja [Monitoramento](/pt/monitoring-usage#assistant-response-event) |

363| `OTEL_LOG_RAW_API_BODIES` | Emita solicitação e resposta JSON da API Anthropic Messages como eventos de log `api_request_body` / `api_response_body`. Defina como `1` para corpos inline truncados em 60 KB, ou `file:<dir>` para escrever corpos não truncados em disco e emitir um caminho `body_ref` em vez disso. Desabilitado por padrão; corpos incluem todo o histórico de conversa. Veja [Monitoramento](/pt/monitoring-usage#api-request-body-event) |373| `OTEL_LOG_RAW_API_BODIES` | Emita solicitação e resposta JSON da API Anthropic Messages como eventos de log `api_request_body` / `api_response_body`. Defina como `1` para corpos inline truncados em 60 KB, ou `file:<dir>` para escrever corpos não truncados em disco e emitir um caminho `body_ref` em vez disso. Desabilitado por padrão; corpos incluem todo o histórico de conversa. Veja [Monitoramento](/pt/monitoring-usage#api-request-body-event) |

7> Referência para eventos de hooks do Claude Code, esquema de configuração, formatos de entrada/saída JSON, códigos de saída, hooks assíncronos, hooks HTTP, hooks de prompt e hooks de ferramentas MCP.7> Referência para eventos de hooks do Claude Code, esquema de configuração, formatos de entrada/saída JSON, códigos de saída, hooks assíncronos, hooks HTTP, hooks de prompt e hooks de ferramentas MCP.

8 8 

9<Tip>9<Tip>

10 Para um guia de início rápido com exemplos, consulte [Automatizar ações com hooks](/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 ou prompts LLM que executam automaticamente em pontos específicos do ciclo de vida do Claude Code. 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. Se você está configurando hooks pela primeira vez, comece com o [guia](/pt/hooks-guide) em vez disso.13Hooks são comandos shell definidos pelo usuário, endpoints HTTP ou prompts LLM que executam automaticamente em pontos específicos do ciclo de vida do Claude Code. 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. Se você está configurando hooks pela primeira vez, comece com o [guia](/docs/pt/hooks-guide) em vez disso.

14 14 

15<h2 id="hook-lifecycle">15<h2 id="hook-lifecycle">

16 Ciclo de vida do hook16 Ciclo de vida do hook

52| `TaskCompleted` | When a task is being marked as completed |52| `TaskCompleted` | When a task is being marked as completed |

53| `Stop` | When Claude finishes responding |53| `Stop` | When Claude finishes responding |

54| `StopFailure` | When the turn ends due to an API error. Output and exit code are ignored |54| `StopFailure` | When the turn ends due to an API error. Output and exit code are ignored |

55| `TeammateIdle` | When an [agent team](/en/agent-teams) teammate is about to go idle |55| `TeammateIdle` | When an [agent team](/docs/en/agent-teams) teammate is about to go idle |

56| `InstructionsLoaded` | When a CLAUDE.md or `.claude/rules/*.md` file is loaded into context. Fires at session start and when files are lazily loaded during a session |56| `InstructionsLoaded` | When a CLAUDE.md or `.claude/rules/*.md` file is loaded into context. Fires at session start and when files are lazily loaded during a session |

57| `ConfigChange` | When a configuration file changes during a session |57| `ConfigChange` | When a configuration file changes during a session |

58| `CwdChanged` | When the working directory changes, for example when Claude executes a `cd` command. Useful for reactive environment management with tools like direnv |58| `CwdChanged` | When the working directory changes, for example when Claude executes a `cd` command. Useful for reactive environment management with tools like direnv |

59| `FileChanged` | When a watched file changes on disk. The `matcher` field specifies which filenames to watch |59| `FileChanged` | When a watched file changes on disk. The `matcher` field specifies which filenames to watch |

60| `WorktreeCreate` | When a worktree is being created via `--worktree` or `isolation: "worktree"`. Replaces default git behavior |60| `WorktreeCreate` | When a worktree is being created via `--worktree`, `isolation: "worktree"`, or for a background session. Replaces default git behavior |

61| `WorktreeRemove` | When a worktree is being removed, either at session exit or when a subagent finishes |61| `WorktreeRemove` | When a worktree is being removed at session exit, when a subagent finishes, or when you delete a background session |

62| `PreCompact` | Before context compaction |62| `PreCompact` | Before context compaction |

63| `PostCompact` | After context compaction completes |63| `PostCompact` | After context compaction completes |

64| `Elicitation` | When an MCP server requests user input during a tool call |64| `Elicitation` | When an MCP server requests user input during a tool call |

147 }147 }

148 ```148 ```

149 149 

150 Se o comando tivesse sido uma variante mais segura de `rm` como `rm file.txt`, o script teria atingido `exit 0` em vez disso. Código de saída 0 sem saída significa que o hook não tem decisão a relatar, então a chamada da ferramenta continua através do [fluxo de permissão](/pt/permissions) normal. O hook pode negar a chamada, mas ficar em silêncio não a aprova.150 Se o comando tivesse sido uma variante mais segura de `rm` como `rm file.txt`, o script teria atingido `exit 0` em vez disso. Código de saída 0 sem saída significa que o hook não tem decisão a relatar, então a chamada da ferramenta continua através do [fluxo de permissão](/docs/pt/permissions) normal. O hook pode negar a chamada, mas ficar em silêncio não a aprova.

151 </Step>151 </Step>

152 152 

153 <Step title="Claude Code age sobre o resultado">153 <Step title="Claude Code age sobre o resultado">

185| `.claude/settings.json` | Projeto único | Sim, pode ser confirmado no repositório |185| `.claude/settings.json` | Projeto único | Sim, pode ser confirmado no repositório |

186| `.claude/settings.local.json` | Projeto único | Não, gitignored quando Claude Code o cria |186| `.claude/settings.local.json` | Projeto único | Não, gitignored quando Claude Code o cria |

187| Configurações de política gerenciada | Organização inteira | Sim, controlado por administrador |187| Configurações de política gerenciada | Organização inteira | Sim, controlado por administrador |

188| [Plugin](/pt/plugins) `hooks/hooks.json` | Quando o plugin está ativado | Sim, agrupado com o plugin |188| [Plugin](/docs/pt/plugins) `hooks/hooks.json` | Quando o plugin está ativado | Sim, agrupado com o plugin |

189| Frontmatter de [Skill](/pt/skills) ou [agente](/pt/sub-agents) | Enquanto o componente está ativo | Sim, definido no arquivo do componente |189| Frontmatter de [Skill](/docs/pt/skills) ou [agente](/docs/pt/sub-agents) | Enquanto o componente está ativo | Sim, definido no arquivo do componente |

190 190 

191Para detalhes sobre resolução de arquivo de configurações, consulte [configurações](/pt/settings). Administradores corporativos podem usar `allowManagedHooksOnly` para bloquear hooks de usuário, projeto e plugin. Hooks de plugins forçadamente ativados em configurações gerenciadas `enabledPlugins` são isentos, para que administradores possam distribuir hooks verificados através de um marketplace de organização. Consulte [Configuração de hook](/pt/settings#hook-configuration).191Para detalhes sobre resolução de arquivo de configurações, consulte [configurações](/docs/pt/settings). Administradores corporativos podem usar `allowManagedHooksOnly` para bloquear hooks de usuário, projeto e plugin. Hooks de plugins forçadamente ativados em configurações gerenciadas `enabledPlugins` são isentos, para que administradores possam distribuir hooks verificados através de um marketplace de organização. Consulte [Configuração de hook](/docs/pt/settings#hook-configuration).

192 192 

193<h3 id="matcher-patterns">193<h3 id="matcher-patterns">

194 Padrões de matcher194 Padrões de matcher

258 258 

259`UserPromptSubmit`, `PostToolBatch`, `Stop`, `TeammateIdle`, `TaskCreated`, `TaskCompleted`, `WorktreeCreate`, `WorktreeRemove`, `MessageDisplay` e `CwdChanged` não suportam matchers e sempre disparam em cada ocorrência. Se você adicionar um campo `matcher` a esses eventos, ele é silenciosamente ignorado.259`UserPromptSubmit`, `PostToolBatch`, `Stop`, `TeammateIdle`, `TaskCreated`, `TaskCompleted`, `WorktreeCreate`, `WorktreeRemove`, `MessageDisplay` e `CwdChanged` não suportam matchers e sempre disparam em cada ocorrência. Se você adicionar um campo `matcher` a esses eventos, ele é silenciosamente ignorado.

260 260 

261Para eventos de ferramenta, você pode filtrar mais estreitamente definindo o campo [`if`](#common-fields) em manipuladores de hook individuais. `if` usa [sintaxe de regra de permissão](/pt/permissions) para corresponder contra o nome da ferramenta e argumentos juntos, então `"Bash(git *)"` executa quando qualquer subcomando da entrada Bash corresponde a `git *` e `"Edit(*.ts)"` executa apenas para arquivos TypeScript.261Para eventos de ferramenta, você pode filtrar mais estreitamente definindo o campo [`if`](#common-fields) em manipuladores de hook individuais. `if` usa [sintaxe de regra de permissão](/docs/pt/permissions) para corresponder contra o nome da ferramenta e argumentos juntos, então `"Bash(git *)"` executa quando qualquer subcomando da entrada Bash corresponde a `git *` e `"Edit(*.ts)"` executa apenas para arquivos TypeScript.

262 262 

263<h4 id="match-mcp-tools">263<h4 id="match-mcp-tools">

264 Corresponder ferramentas MCP264 Corresponder ferramentas MCP

265</h4>265</h4>

266 266 

267Ferramentas de servidor [MCP](/pt/mcp) aparecem como ferramentas regulares em eventos de ferramenta (`PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`, `PermissionDenied`), então você pode corresponder a elas da mesma forma que corresponde a qualquer outro nome de ferramenta.267Ferramentas de servidor [MCP](/docs/pt/mcp) aparecem como ferramentas regulares em eventos de ferramenta (`PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`, `PermissionDenied`), então você pode corresponder a elas da mesma forma que corresponde a qualquer outro nome de ferramenta.

268 268 

269Ferramentas MCP seguem o padrão de nomenclatura `mcp__<server>__<tool>`, por exemplo:269Ferramentas MCP seguem o padrão de nomenclatura `mcp__<server>__<tool>`, por exemplo:

270 270 

280 280 

281Hífens no conjunto de correspondência exata requerem Claude Code v2.1.195 ou posterior. Em versões anteriores, um prefixo com hífen simples como `mcp__brave-search` é avaliado como uma expressão regular não ancorada e corresponde a cada ferramenta daquele servidor. A forma `mcp__brave-search__.*` funciona em todas as versões.281Hífens no conjunto de correspondência exata requerem Claude Code v2.1.195 ou posterior. Em versões anteriores, um prefixo com hífen simples como `mcp__brave-search` é avaliado como uma expressão regular não ancorada e corresponde a cada ferramenta daquele servidor. A forma `mcp__brave-search__.*` funciona em todas as versões.

282 282 

283Ferramentas de um [servidor MCP fornecido por plugin](/pt/mcp#plugin-provided-mcp-servers) usam um segmento de servidor com escopo que inclui o nome do plugin: `mcp__plugin_<plugin-name>_<server-name>__<tool>`. Um matcher escrito contra a chave do servidor simples nunca dispara para essas ferramentas. Para um plugin nomeado `my-plugin` que agrupa um servidor sob a chave `db`, uma ferramenta `query` aparece como `mcp__plugin_my-plugin_db__query`, então o matcher para cada ferramenta daquele servidor é `mcp__plugin_my-plugin_db__.*`. Use o mesmo nome de ferramenta com escopo no campo [`if`](#common-fields) de um manipulador. Consulte [Servidores MCP fornecidos por plugin](/pt/mcp#plugin-provided-mcp-servers) para saber como o nome com escopo é construído.283Ferramentas de um [servidor MCP fornecido por plugin](/docs/pt/mcp#plugin-provided-mcp-servers) usam um segmento de servidor com escopo que inclui o nome do plugin: `mcp__plugin_<plugin-name>_<server-name>__<tool>`. Um matcher escrito contra a chave do servidor simples nunca dispara para essas ferramentas. Para um plugin nomeado `my-plugin` que agrupa um servidor sob a chave `db`, uma ferramenta `query` aparece como `mcp__plugin_my-plugin_db__query`, então o matcher para cada ferramenta daquele servidor é `mcp__plugin_my-plugin_db__.*`. Use o mesmo nome de ferramenta com escopo no campo [`if`](#common-fields) de um manipulador. Consulte [Servidores MCP fornecidos por plugin](/docs/pt/mcp#plugin-provided-mcp-servers) para saber como o nome com escopo é construído.

284 284 

285Este exemplo registra todas as operações do servidor memory e valida operações de escrita de qualquer servidor MCP:285Este exemplo registra todas as operações do servidor memory e valida operações de escrita de qualquer servidor MCP:

286 286 

319 319 

320* **[Hooks de comando](#command-hook-fields)** (`type: "command"`): executam um comando shell. Seu script recebe a [entrada JSON](#hook-input-and-output) do evento em stdin e comunica resultados através de códigos de saída e stdout.320* **[Hooks de comando](#command-hook-fields)** (`type: "command"`): executam um comando shell. Seu script recebe a [entrada JSON](#hook-input-and-output) do evento em stdin e comunica resultados através de códigos de saída e stdout.

321* **[Hooks HTTP](#http-hook-fields)** (`type: "http"`): enviam a entrada JSON do evento como uma solicitação HTTP POST para uma URL. O endpoint comunica resultados através do corpo da resposta usando o mesmo [formato de saída JSON](#json-output) que hooks de comando.321* **[Hooks HTTP](#http-hook-fields)** (`type: "http"`): enviam a entrada JSON do evento como uma solicitação HTTP POST para uma URL. O endpoint comunica resultados através do corpo da resposta usando o mesmo [formato de saída JSON](#json-output) que hooks de comando.

322* **[Hooks de ferramenta MCP](#mcp-tool-hook-fields)** (`type: "mcp_tool"`): chamam uma ferramenta em um servidor [MCP](/pt/mcp) já conectado. A saída de texto da ferramenta é tratada como stdout de hook de comando.322* **[Hooks de ferramenta MCP](#mcp-tool-hook-fields)** (`type: "mcp_tool"`): chamam uma ferramenta em um servidor [MCP](/docs/pt/mcp) já conectado. A saída de texto da ferramenta é tratada como stdout de hook de comando.

323* **[Hooks de prompt](#prompt-and-agent-hook-fields)** (`type: "prompt"`): enviam um prompt para um modelo Claude para avaliação de turno único. O modelo retorna uma decisão sim/não como JSON. Consulte [Hooks baseados em prompt](#prompt-based-hooks).323* **[Hooks de prompt](#prompt-and-agent-hook-fields)** (`type: "prompt"`): enviam um prompt para um modelo Claude para avaliação de turno único. O modelo retorna uma decisão sim/não como JSON. Consulte [Hooks baseados em prompt](#prompt-based-hooks).

324* **[Hooks de agente](#prompt-and-agent-hook-fields)** (`type: "agent"`): geram um subagente que pode usar ferramentas como Read, Grep e Glob para verificar condições antes de retornar uma decisão. Hooks de agente são experimentais e podem mudar. Consulte [Hooks baseados em agente](#agent-based-hooks).324* **[Hooks de agente](#prompt-and-agent-hook-fields)** (`type: "agent"`): geram um subagente que pode usar ferramentas como Read, Grep e Glob para verificar condições antes de retornar uma decisão. Hooks de agente são experimentais e podem mudar. Consulte [Hooks baseados em agente](#agent-based-hooks).

325 325 

326Todos os hooks correspondentes executam em paralelo, e manipuladores idênticos são automaticamente desduplicados. Hooks de comando são desduplicados por string de comando e `args`, e hooks HTTP são desduplicados por URL.326Todos os hooks correspondentes executam em paralelo, e manipuladores idênticos são automaticamente desduplicados. Hooks de comando são desduplicados por string de comando e `args`, e hooks HTTP são desduplicados por URL.

327 327 

328Manipuladores executam no diretório atual com o ambiente do Claude Code. A variável de ambiente `$CLAUDE_CODE_REMOTE` é definida como `"true"` em ambientes web remotos e não é definida na CLI local. {/* min-version: 2.1.199 */}A partir de v2.1.199, [`$CLAUDE_CODE_BRIDGE_SESSION_ID`](/pt/env-vars) é definido para o ID de sessão [Remote Control](/pt/remote-control) enquanto a sessão local tem uma conexão Remote Control ativa.328Manipuladores executam no diretório atual com o ambiente do Claude Code. A variável de ambiente `$CLAUDE_CODE_REMOTE` é definida como `"true"` em ambientes web remotos e não é definida na CLI local. {/* min-version: 2.1.199 */}A partir de v2.1.199, [`$CLAUDE_CODE_BRIDGE_SESSION_ID`](/docs/pt/env-vars) é definido para o ID de sessão [Remote Control](/docs/pt/remote-control) enquanto a sessão local tem uma conexão Remote Control ativa.

329 329 

330<h4 id="common-fields">330<h4 id="common-fields">

331 Campos comuns331 Campos comuns

336| Campo | Obrigatório | Descrição |336| Campo | Obrigatório | Descrição |

337| :-------------- | :---------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |337| :-------------- | :---------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

338| `type` | sim | `"command"`, `"http"`, `"mcp_tool"`, `"prompt"` ou `"agent"` |338| `type` | sim | `"command"`, `"http"`, `"mcp_tool"`, `"prompt"` ou `"agent"` |

339| `if` | não | Sintaxe de regra de permissão para filtrar quando este hook executa, como `"Bash(git *)"` ou `"Edit(*.ts)"`. O comando do hook apenas é executado se a chamada de ferramenta corresponde ao padrão. Consulte a [tabela de correspondência Bash](#bash-if-matching) abaixo para saber como padrões Bash são avaliados contra subcomandos, `$()` e backticks. Apenas avaliado em eventos de ferramenta: `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest` e `PermissionDenied`. Em outros eventos, um hook com `if` definido nunca executa. Usa a mesma sintaxe que [regras de permissão](/pt/permissions) |339| `if` | não | Sintaxe de regra de permissão para filtrar quando este hook executa, como `"Bash(git *)"` ou `"Edit(*.ts)"`. O comando do hook apenas é executado se a chamada de ferramenta corresponde ao padrão. Consulte a [tabela de correspondência Bash](#bash-if-matching) abaixo para saber como padrões Bash são avaliados contra subcomandos, `$()` e backticks. Apenas avaliado em eventos de ferramenta: `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest` e `PermissionDenied`. Em outros eventos, um hook com `if` definido nunca executa. Usa a mesma sintaxe que [regras de permissão](/docs/pt/permissions) |

340| `timeout` | não | Segundos antes de cancelar. Padrões: 600 para `command`, `http` e `mcp_tool`; 30 para `prompt`; 60 para `agent`. [`UserPromptSubmit`](#userpromptsubmit) reduz o padrão de `command`, `http` e `mcp_tool` para 30, e [`MessageDisplay`](#messagedisplay) reduz para 10 |340| `timeout` | não | Segundos antes de cancelar. Padrões: 600 para `command`, `http` e `mcp_tool`; 30 para `prompt`; 60 para `agent`. [`UserPromptSubmit`](#userpromptsubmit) reduz o padrão de `command`, `http` e `mcp_tool` para 30, e [`MessageDisplay`](#messagedisplay) reduz para 10 |

341| `statusMessage` | não | Mensagem de spinner personalizada exibida enquanto o hook executa |341| `statusMessage` | não | Mensagem de spinner personalizada exibida enquanto o hook executa |

342| `once` | não | Se `true`, executa apenas uma vez por sessão e depois é removido. Apenas honrado para hooks declarados em [frontmatter de skill](#hooks-in-skills-and-agents); ignorado em arquivos de configurações e frontmatter de agente |342| `once` | não | Se `true`, executa apenas uma vez por sessão e depois é removido. Apenas honrado para hooks declarados em [frontmatter de skill](#hooks-in-skills-and-agents); ignorado em arquivos de configurações e frontmatter de agente |

353| `Bash(rm *)` | `echo $(date)` | não | nenhum subcomando corresponde a `rm *` |353| `Bash(rm *)` | `echo $(date)` | não | nenhum subcomando corresponde a `rm *` |

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

355 355 

356O filtro também falha aberto, executando seu hook independentemente do padrão, quando o comando Bash não pode ser analisado. Como o filtro `if` é melhor esforço, use o [sistema de permissão](/pt/permissions) em vez de um hook para impor um allow ou deny duro.356O filtro também falha aberto, executando seu hook independentemente do padrão, quando o comando Bash não pode ser analisado. 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.

357 357 

358<h4 id="command-hook-fields">358<h4 id="command-hook-fields">

359 Campos de hook de comando359 Campos de hook de comando

406 406 

407Ambas as formas suportam os mesmos [placeholders de caminho](#reference-scripts-by-path), e ambas os exportam como as variáveis de ambiente `CLAUDE_PROJECT_DIR`, `CLAUDE_PLUGIN_ROOT` e `CLAUDE_PLUGIN_DATA` no processo gerado, então um script pode ler `process.env.CLAUDE_PLUGIN_ROOT` independentemente de como foi lançado.407Ambas as formas suportam os mesmos [placeholders de caminho](#reference-scripts-by-path), e ambas os exportam como as variáveis de ambiente `CLAUDE_PROJECT_DIR`, `CLAUDE_PLUGIN_ROOT` e `CLAUDE_PLUGIN_DATA` no processo gerado, então um script pode ler `process.env.CLAUDE_PLUGIN_ROOT` independentemente de como foi lançado.

408 408 

409Um hook de plugin em forma shell cujo `command` referencia `${user_config.*}` falha com um [erro](/pt/errors#plugin-command-references-user-config) em vez de executar. Para usar um valor de opção de um hook em forma shell, leia a variável de ambiente `$CLAUDE_PLUGIN_OPTION_<KEY>`, como `$CLAUDE_PLUGIN_OPTION_WEBHOOK_URL` para uma opção `webhook_url`, ou defina `args` para mudar o hook para forma exec. Antes de v2.1.207, comandos de hook de plugin em forma shell também substituíam `${user_config.*}`.409Um hook de plugin em forma shell cujo `command` referencia `${user_config.*}` falha com um [erro](/docs/pt/errors#plugin-command-references-user-config) em vez de executar. Para usar um valor de opção de um hook em forma shell, leia a variável de ambiente `$CLAUDE_PLUGIN_OPTION_<KEY>`, como `$CLAUDE_PLUGIN_OPTION_WEBHOOK_URL` para uma opção `webhook_url`, ou defina `args` para mudar o hook para forma exec. Antes de v2.1.207, comandos de hook de plugin em forma shell também substituíam `${user_config.*}`.

410 410 

411<Note>411<Note>

412 Em forma exec, `command` é apenas o nome ou caminho do executável. Se `command` é um nome simples sem separador de caminho e contém espaço em branco junto com `args`, Claude Code registra um aviso porque o spawn falhará: não há executável nomeado `node script.js`. Mova os tokens extras para `args`. Caminhos absolutos com espaços, como `C:\Program Files\nodejs\node.exe`, são um executável válido único e não disparam o aviso.412 Em forma exec, `command` é apenas o nome ou caminho do executável. Se `command` é um nome simples sem separador de caminho e contém espaço em branco junto com `args`, Claude Code registra um aviso porque o spawn falhará: não há executável nomeado `node script.js`. Mova os tokens extras para `args`. Caminhos absolutos com espaços, como `C:\Program Files\nodejs\node.exe`, são um executável válido único e não disparam o aviso.

461 461 

462| Campo | Obrigatório | Descrição |462| Campo | Obrigatório | Descrição |

463| :------- | :---------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |463| :------- | :---------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

464| `server` | sim | Nome de um servidor MCP configurado. Para um [servidor fornecido por plugin](/pt/mcp#plugin-provided-mcp-servers), este é o nome com escopo `plugin:<plugin-name>:<server-name>`, como `plugin:my-plugin:db`, não a chave do servidor simples. O servidor já deve estar conectado; o hook nunca dispara um fluxo OAuth ou de conexão |464| `server` | sim | Nome de um servidor MCP configurado. Para um [servidor fornecido por plugin](/docs/pt/mcp#plugin-provided-mcp-servers), este é o nome com escopo `plugin:<plugin-name>:<server-name>`, como `plugin:my-plugin:db`, não a chave do servidor simples. O servidor já deve estar conectado; o hook nunca dispara um fluxo OAuth ou de conexão |

465| `tool` | sim | Nome da ferramenta a chamar naquele servidor |465| `tool` | sim | Nome da ferramenta a chamar naquele servidor |

466| `input` | não | Argumentos passados para a ferramenta. Valores de string suportam substituição `${path}` da [entrada JSON](#hook-input-and-output) do hook, como `"${tool_input.file_path}"` |466| `input` | não | Argumentos passados para a ferramenta. Valores de string suportam substituição `${path}` da [entrada JSON](#hook-input-and-output) do hook, como `"${tool_input.file_path}"` |

467 467 

508 508 

509Use esses placeholders para referenciar scripts de hook relativos à raiz do projeto ou plugin, independentemente do diretório de trabalho quando o hook executa:509Use esses placeholders para referenciar scripts de hook relativos à raiz do projeto ou plugin, independentemente do diretório de trabalho quando o hook executa:

510 510 

511* `${CLAUDE_PROJECT_DIR}`: a raiz do projeto. Claude Code também define essa variável no ambiente de [servidores MCP stdio](/pt/mcp#option-3-add-a-local-stdio-server) e servidores LSP de plugin.511* `${CLAUDE_PROJECT_DIR}`: a raiz do projeto. Claude Code também define essa variável no ambiente de [servidores MCP stdio](/docs/pt/mcp#option-3-add-a-local-stdio-server) e servidores LSP de plugin.

512* `${CLAUDE_PLUGIN_ROOT}`: o diretório de instalação do plugin, para scripts agrupados com um [plugin](/pt/plugins). Muda em cada atualização de plugin.512* `${CLAUDE_PLUGIN_ROOT}`: o diretório de instalação do plugin, para scripts agrupados com um [plugin](/docs/pt/plugins). Muda em cada atualização de plugin.

513* `${CLAUDE_PLUGIN_DATA}`: o [diretório de dados persistentes](/pt/plugins-reference#persistent-data-directory) do plugin, para dependências e estado que devem sobreviver a atualizações de plugin.513* `${CLAUDE_PLUGIN_DATA}`: o [diretório de dados persistentes](/docs/pt/plugins-reference#persistent-data-directory) do plugin, para dependências e estado que devem sobreviver a atualizações de plugin.

514 514 

515Prefira [forma exec](#exec-form-and-shell-form) para qualquer hook que referencie um placeholder de caminho. A forma exec passa cada elemento `args` como um argumento sem tokenização de shell, então caminhos com espaços ou caracteres especiais não precisam de aspas. Em forma shell, envolva cada placeholder em aspas duplas.515Prefira [forma exec](#exec-form-and-shell-form) para qualquer hook que referencie um placeholder de caminho. A forma exec passa cada elemento `args` como um argumento sem tokenização de shell, então caminhos com espaços ou caracteres especiais não precisam de aspas. Em forma shell, envolva cada placeholder em aspas duplas.

516 516 

564 }564 }

565 ```565 ```

566 566 

567 Consulte a [referência de componentes de plugin](/pt/plugins-reference#hooks) para detalhes sobre como criar hooks de plugin.567 Consulte a [referência de componentes de plugin](/docs/pt/plugins-reference#hooks) para detalhes sobre como criar hooks de plugin.

568 </Tab>568 </Tab>

569</Tabs>569</Tabs>

570 570 

572 Hooks em skills e agentes572 Hooks em skills e agentes

573</h3>573</h3>

574 574 

575Além de arquivos de configurações e plugins, hooks podem ser definidos diretamente em [skills](/pt/skills) e [subagentes](/pt/sub-agents) usando frontmatter. Esses hooks são escopo do ciclo de vida do componente e apenas executam quando esse componente está ativo.575Além de arquivos de configurações e plugins, hooks podem ser definidos diretamente em [skills](/docs/pt/skills) e [subagentes](/docs/pt/sub-agents) usando frontmatter. Esses hooks são escopo do ciclo de vida do componente e apenas executam quando esse componente está ativo.

576 576 

577Todos os eventos de hook são suportados. Para subagentes, hooks `Stop` são automaticamente convertidos para `SubagentStop` já que esse é o evento que dispara quando um subagente completa.577Todos os eventos de hook são suportados. Para subagentes, hooks `Stop` são automaticamente convertidos para `SubagentStop` já que esse é o evento que dispara quando um subagente completa.

578 578 

641| Campo | Descrição |641| Campo | Descrição |

642| :---------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |642| :---------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

643| `session_id` | Identificador de sessão atual |643| `session_id` | Identificador de sessão atual |

644| `prompt_id` | UUID identificando o prompt do usuário sendo processado atualmente. Corresponde ao [atributo `prompt.id` em eventos OpenTelemetry](/pt/monitoring-usage#event-correlation-attributes), para que você possa correlacionar saída de hook com telemetria para um único prompt. Ausente até a primeira entrada do usuário. {/* min-version: 2.1.196 */}Requer Claude Code v2.1.196 ou posterior |644| `prompt_id` | UUID identificando o prompt do usuário sendo processado atualmente. Corresponde ao [atributo `prompt.id` em eventos OpenTelemetry](/docs/pt/monitoring-usage#event-correlation-attributes), para que você possa correlacionar saída de hook com telemetria para um único prompt. Ausente até a primeira entrada do usuário. {/* min-version: 2.1.196 */}Requer Claude Code v2.1.196 ou posterior |

645| `transcript_path` | Caminho para JSON de conversa. O arquivo de transcrição é escrito de forma assíncrona e pode ficar atrás da conversa na memória, portanto pode não incluir ainda as mensagens mais recentes da rodada atual quando um hook dispara. Hooks que precisam do texto final do assistente da rodada atual devem usar `last_assistant_message` em [Stop](#stop) e [SubagentStop](#subagentstop) em vez de ler a transcrição |645| `transcript_path` | Caminho para JSON de conversa. O arquivo de transcrição é escrito de forma assíncrona e pode ficar atrás da conversa na memória, portanto pode não incluir ainda as mensagens mais recentes da rodada atual quando um hook dispara. Hooks que precisam do texto final do assistente da rodada atual devem usar `last_assistant_message` em [Stop](#stop) e [SubagentStop](#subagentstop) em vez de ler a transcrição |

646| `cwd` | Diretório de trabalho atual quando o hook é invocado |646| `cwd` | Diretório de trabalho atual quando o hook é invocado |

647| `permission_mode` | [Modo de permissão](/pt/permissions#permission-modes) atual: `"default"`, `"plan"`, `"acceptEdits"`, `"auto"`, `"dontAsk"` ou `"bypassPermissions"`. O modo rotulado **Manual** chega como `"default"`, nunca como `"manual"`, portanto scripts que correspondem a `"default"` continuam funcionando. Nem todos os eventos recebem este campo. Verifique o exemplo JSON em cada seção [evento de hook](#hook-events) |647| `permission_mode` | [Modo de permissão](/docs/pt/permissions#permission-modes) atual: `"default"`, `"plan"`, `"acceptEdits"`, `"auto"`, `"dontAsk"` ou `"bypassPermissions"`. O modo rotulado **Manual** chega como `"default"`, nunca como `"manual"`, portanto scripts que correspondem a `"default"` continuam funcionando. Nem todos os eventos recebem este campo. Verifique o exemplo JSON em cada seção [evento de hook](#hook-events) |

648| `effort` | Objeto com um campo `level` contendo o [nível de esforço](/pt/model-config#adjust-effort-level) ativo para a rodada: `"low"`, `"medium"`, `"high"`, `"xhigh"` ou `"max"`. Se o esforço solicitado do modelo exceder o que o modelo atual suporta, este é o nível reduzido que o modelo realmente usou. Ultracode não é um nível distinto e é relatado como `"xhigh"`. O objeto corresponde ao campo `effort` da [linha de status](/pt/statusline#available-data). Presente para eventos que disparam dentro de um contexto de uso de ferramenta, como `PreToolUse`, `PostToolUse`, `Stop` e `SubagentStop`, quando o modelo atual suporta o parâmetro de esforço. O nível também está disponível para comandos de hook e a ferramenta Bash como a variável de ambiente `$CLAUDE_EFFORT`. |648| `effort` | Objeto com um campo `level` contendo o [nível de esforço](/docs/pt/model-config#adjust-effort-level) ativo para a rodada: `"low"`, `"medium"`, `"high"`, `"xhigh"` ou `"max"`. Se o esforço solicitado do modelo exceder o que o modelo atual suporta, este é o nível reduzido que o modelo realmente usou. Ultracode não é um nível distinto e é relatado como `"xhigh"`. O objeto corresponde ao campo `effort` da [linha de status](/docs/pt/statusline#available-data). Presente para eventos que disparam dentro de um contexto de uso de ferramenta, como `PreToolUse`, `PostToolUse`, `Stop` e `SubagentStop`, quando o modelo atual suporta o parâmetro de esforço. O nível também está disponível para comandos de hook e a ferramenta Bash como a variável de ambiente `$CLAUDE_EFFORT`. |

649| `hook_event_name` | Nome do evento que disparou |649| `hook_event_name` | Nome do evento que disparou |

650 650 

651Ao executar com `--agent` ou dentro de um subagente, dois campos adicionais são incluídos:651Ao executar com `--agent` ou dentro de um subagente, dois campos adicionais são incluídos:

653| Campo | Descrição |653| Campo | Descrição |

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

655| `agent_id` | Identificador único para o subagente. Presente apenas quando o hook dispara dentro de uma chamada de subagente. Use isso para distinguir chamadas de hook de subagente de chamadas de thread principal. |655| `agent_id` | Identificador único para o subagente. Presente apenas quando o hook dispara dentro de uma chamada de subagente. Use isso para distinguir chamadas de hook de subagente de chamadas de thread principal. |

656| `agent_type` | Nome do agente (por exemplo, `"Explore"` ou `"security-reviewer"`). Presente quando a sessão usa `--agent` ou o hook dispara dentro de um subagente. Para subagentes, o tipo do subagente tem precedência sobre o valor `--agent` da sessão. Para [subagentes personalizados](/pt/sub-agents), este é o campo `name` do frontmatter do agente, não o nome do arquivo. Para subagentes fornecidos por um [plugin](/pt/plugins), este é o identificador com escopo de plugin como `my-plugin:reviewer`, não o nome de frontmatter simples. Consulte [SubagentStart](#subagentstart) para saber como escrever um matcher contra um nome com escopo de plugin. |656| `agent_type` | Nome do agente (por exemplo, `"Explore"` ou `"security-reviewer"`). Presente quando a sessão usa `--agent` ou o hook dispara dentro de um subagente. Para subagentes, o tipo do subagente tem precedência sobre o valor `--agent` da sessão. Para [subagentes personalizados](/docs/pt/sub-agents), este é o campo `name` do frontmatter do agente, não o nome do arquivo. Para subagentes fornecidos por um [plugin](/docs/pt/plugins), este é o identificador com escopo de plugin como `my-plugin:reviewer`, não o nome de frontmatter simples. Consulte [SubagentStart](#subagentstart) para saber como escrever um matcher contra um nome com escopo de plugin. |

657 657 

658Apenas hooks [`SessionStart`](#sessionstart) podem receber um campo `model`, e não é garantido que esteja presente. Não há variável de ambiente `$CLAUDE_MODEL`. Um processo de hook herda o ambiente pai, então pode ler `$ANTHROPIC_MODEL` se você defini-lo em seu shell, mas esse valor não muda quando você alterna modelos com `/model` durante uma sessão. Um conjunto de variáveis não é herdado: Claude Code [remove variáveis exportadoras `OTEL_*` de cada subprocesso que spawna](/pt/monitoring-usage#administrator-configuration), incluindo hooks.658Apenas hooks [`SessionStart`](#sessionstart) podem receber um campo `model`, e não é garantido que esteja presente. Não há variável de ambiente `$CLAUDE_MODEL`. Um processo de hook herda o ambiente pai, então pode ler `$ANTHROPIC_MODEL` se você defini-lo em seu shell, mas esse valor não muda quando você alterna modelos com `/model` durante uma sessão. Um conjunto de variáveis não é herdado: Claude Code [remove variáveis exportadoras `OTEL_*` de cada subprocesso que spawna](/docs/pt/monitoring-usage#administrator-configuration), incluindo hooks.

659 659 

660Por exemplo, um hook `PreToolUse` para um comando Bash recebe isso em stdin:660Por exemplo, um hook `PreToolUse` para um comando Bash recebe isso em stdin:

661 661 

774 Você deve escolher uma abordagem por hook, não ambas: ou use códigos de saída sozinhos para sinalizar, ou saia 0 e imprima JSON para controle estruturado. O Claude Code apenas processa JSON na saída 0. Se você sair 2, qualquer JSON é ignorado.774 Você deve escolher uma abordagem por hook, não ambas: ou use códigos de saída sozinhos para sinalizar, ou saia 0 e imprima JSON para controle estruturado. O Claude Code apenas processa JSON na saída 0. Se você sair 2, qualquer JSON é ignorado.

775</Note>775</Note>

776 776 

777O stdout do seu hook deve conter apenas o objeto JSON. Se seu perfil shell imprime texto na inicialização, pode interferir com análise JSON. Consulte [Validação JSON falhou](/pt/hooks-guide#json-validation-failed) no guia de troubleshooting.777O stdout do seu hook deve conter apenas o objeto JSON. Se seu perfil shell imprime texto na inicialização, pode interferir com análise JSON. Consulte [Validação JSON falhou](/docs/pt/hooks-guide#json-validation-failed) no guia de troubleshooting.

778 778 

779Saídas de hook, incluindo `additionalContext`, `systemMessage` e stdout simples, são limitadas a 10.000 caracteres. Saída que excede este limite é salva em um arquivo e substituída por uma visualização e caminho de arquivo, da mesma forma que resultados de ferramenta grandes são tratados.779Saídas de hook, incluindo `additionalContext`, `systemMessage` e stdout simples, são limitadas a 10.000 caracteres. Saída que excede este limite é salva em um arquivo e substituída por uma visualização e caminho de arquivo, da mesma forma que resultados de ferramenta grandes são tratados.

780 780 

866* **Regras de projeto condicional**: qual comando de teste se aplica ao arquivo que acabou de ser editado, quais diretórios são somente leitura nesta worktree866* **Regras de projeto condicional**: qual comando de teste se aplica ao arquivo que acabou de ser editado, quais diretórios são somente leitura nesta worktree

867* **Dados externos**: problemas abertos atribuídos a você, resultados recentes de CI, conteúdo obtido de um serviço interno867* **Dados externos**: problemas abertos atribuídos a você, resultados recentes de CI, conteúdo obtido de um serviço interno

868 868 

869Para instruções que nunca mudam, prefira [CLAUDE.md](/pt/memory). Ele carrega sem executar um script e é o lugar padrão para convenções de projeto estáticas.869Para instruções que nunca mudam, prefira [CLAUDE.md](/docs/pt/memory). Ele carrega sem executar um script e é o lugar padrão para convenções de projeto estáticas.

870 870 

871Escreva o texto como declarações factuais em vez de instruções de sistema imperativas. Frases como "O alvo de implantação é produção" ou "Este repositório usa `bun test`" lê como informação de projeto. Texto enquadrado como comandos de sistema fora de banda pode disparar as defesas de injeção de prompt do Claude, o que faz com que Claude superficialize o texto para você em vez de tratá-lo como contexto.871Escreva o texto como declarações factuais em vez de instruções de sistema imperativas. Frases como "O alvo de implantação é produção" ou "Este repositório usa `bun test`" lê como informação de projeto. Texto enquadrado como comandos de sistema fora de banda pode disparar as defesas de injeção de prompt do Claude, o que faz com que Claude superficialize o texto para você em vez de tratá-lo como contexto.

872 872 

948 </Tab>948 </Tab>

949</Tabs>949</Tabs>

950 950 

951Para exemplos estendidos incluindo validação de comando Bash, filtragem de prompt e scripts de aprovação automática, consulte [O que você pode automatizar](/pt/hooks-guide#what-you-can-automate) no guia e a [implementação de referência do validador de comando Bash](https://github.com/anthropics/claude-code/blob/main/examples/hooks/bash_command_validator_example.py).951Para exemplos estendidos incluindo validação de comando Bash, filtragem de prompt e scripts de aprovação automática, consulte [O que você pode automatizar](/docs/pt/hooks-guide#what-you-can-automate) no guia e a [implementação de referência do validador de comando Bash](https://github.com/anthropics/claude-code/blob/main/examples/hooks/bash_command_validator_example.py).

952 952 

953<h2 id="hook-events">953<h2 id="hook-events">

954 Eventos de hook954 Eventos de hook

960 SessionStart960 SessionStart

961</h3>961</h3>

962 962 

963Executa quando Claude Code inicia uma nova sessão ou retoma uma sessão existente. Útil para carregar contexto de desenvolvimento como problemas existentes ou mudanças recentes em seu codebase, ou configurar variáveis de ambiente. Para contexto estático que não requer um script, use [CLAUDE.md](/pt/memory) em vez disso.963Executa quando Claude Code inicia uma nova sessão ou retoma uma sessão existente. Útil para carregar contexto de desenvolvimento como problemas existentes ou mudanças recentes em seu codebase, ou configurar variáveis de ambiente. Para contexto estático que não requer um script, use [CLAUDE.md](/docs/pt/memory) em vez disso.

964 964 

965SessionStart executa em cada sessão, então mantenha esses hooks rápidos. Apenas hooks `type: "command"` e `type: "mcp_tool"` são suportados.965SessionStart executa em cada sessão, então mantenha esses hooks rápidos. Apenas hooks `type: "command"` e `type: "mcp_tool"` são suportados.

966 966 

1006| Campo | Descrição |1006| Campo | Descrição |

1007| :------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |1007| :------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

1008| `additionalContext` | String adicionada ao contexto de Claude no início da conversa, antes do primeiro prompt. Consulte [Adicionar contexto para Claude](#add-context-for-claude) para saber como o texto é entregue e o que colocar nele |1008| `additionalContext` | String adicionada ao contexto de Claude no início da conversa, antes do primeiro prompt. Consulte [Adicionar contexto para Claude](#add-context-for-claude) para saber como o texto é entregue e o que colocar nele |

1009| `initialUserMessage` | String usada como a primeira mensagem de usuário da sessão. Aplica-se em [modo não-interativo](/pt/headless) com a flag `-p`, onde se torna o primeiro turno mesmo se nenhum prompt for fornecido. Se um prompt for fornecido, ele segue como o próximo turno. Diferentemente de `additionalContext`, que se anexa a um turno existente, isso cria o turno |1009| `initialUserMessage` | String usada como a primeira mensagem de usuário da sessão. Aplica-se em [modo não-interativo](/docs/pt/headless) com a flag `-p`, onde se torna o primeiro turno mesmo se nenhum prompt for fornecido. Se um prompt for fornecido, ele segue como o próximo turno. Diferentemente de `additionalContext`, que se anexa a um turno existente, isso cria o turno |

1010| `sessionTitle` | Define o título da sessão, com o mesmo efeito que `/rename`. Use para nomear sessões automaticamente a partir da pasta de lançamento, branch git ou nome de worktree. Aplica-se apenas quando `source` é `"startup"` ou `"resume"`; ignorado em `"clear"` e `"compact"` |1010| `sessionTitle` | Define o título da sessão, com o mesmo efeito que `/rename`. Use para nomear sessões automaticamente a partir da pasta de lançamento, branch git ou nome de worktree. Aplica-se apenas quando `source` é `"startup"` ou `"resume"`; ignorado em `"clear"` e `"compact"` |

1011| `watchPaths` | Array de caminhos absolutos para monitorar eventos [FileChanged](#filechanged) durante esta sessão |1011| `watchPaths` | Array de caminhos absolutos para monitorar eventos [FileChanged](#filechanged) durante esta sessão |

1012| `reloadSkills` | Boolean. Quando `true`, Claude Code re-escaneia os diretórios [skill](/pt/skills) e comando após os hooks SessionStart completarem, então skills que o hook instalou estão disponíveis na mesma sessão, começando com o primeiro prompt |1012| `reloadSkills` | Boolean. Quando `true`, Claude Code re-escaneia os diretórios [skill](/docs/pt/skills) e comando após os hooks SessionStart completarem, então skills que o hook instalou estão disponíveis na mesma sessão, começando com o primeiro prompt |

1013 1013 

1014```json theme={null}1014```json theme={null}

1015{1015{

1083 Setup1083 Setup

1084</h3>1084</h3>

1085 1085 

1086Dispara apenas quando você lança Claude Code com `--init-only`, ou com `--init` ou `--maintenance` em [modo não-interativo](/pt/headless) com a flag `-p`. Não dispara na inicialização normal. Use-o para instalação de dependência única ou limpeza agendada que você aciona explicitamente de CI ou scripts, separado da inicialização de sessão normal. Para inicialização por sessão, use [SessionStart](#sessionstart) em vez disso.1086Dispara apenas quando você lança Claude Code com `--init-only`, ou com `--init` ou `--maintenance` em [modo não-interativo](/docs/pt/headless) com a flag `-p`. Não dispara na inicialização normal. Use-o para instalação de dependência única ou limpeza agendada que você aciona explicitamente de CI ou scripts, separado da inicialização de sessão normal. Para inicialização por sessão, use [SessionStart](#sessionstart) em vez disso.

1087 1087 

1088O valor do matcher corresponde à flag CLI que acionou o hook:1088O valor do matcher corresponde à flag CLI que acionou o hook:

1089 1089 

1094 1094 

1095`--init-only` executa hooks Setup e hooks SessionStart com o matcher `startup`, depois sai sem iniciar uma conversa. `--init` e `--maintenance` disparam hooks Setup apenas quando combinados com `-p`; em uma sessão interativa essas duas flags atualmente não disparam hooks Setup.1095`--init-only` executa hooks Setup e hooks SessionStart com o matcher `startup`, depois sai sem iniciar uma conversa. `--init` e `--maintenance` disparam hooks Setup apenas quando combinados com `-p`; em uma sessão interativa essas duas flags atualmente não disparam hooks Setup.

1096 1096 

1097Porque Setup não dispara em cada lançamento, um plugin que precisa de uma dependência instalada não pode confiar apenas em Setup. O padrão prático é verificar a dependência no primeiro uso e instalar se ausente, por exemplo um hook ou skill que testa `${CLAUDE_PLUGIN_DATA}/node_modules` e executa `npm install` se ausente. Consulte o [diretório de dados persistentes](/pt/plugins-reference#persistent-data-directory) para onde armazenar dependências instaladas.1097Porque Setup não dispara em cada lançamento, um plugin que precisa de uma dependência instalada não pode confiar apenas em Setup. O padrão prático é verificar a dependência no primeiro uso e instalar se ausente, por exemplo um hook ou skill que testa `${CLAUDE_PLUGIN_DATA}/node_modules` e executa `npm install` se ausente. Consulte o [diretório de dados persistentes](/docs/pt/plugins-reference#persistent-data-directory) para onde armazenar dependências instaladas.

1098 1098 

1099<h4 id="setup-input">1099<h4 id="setup-input">

1100 Entrada de Setup1100 Entrada de Setup

1116 Controle de decisão de Setup1116 Controle de decisão de Setup

1117</h4>1117</h4>

1118 1118 

1119Hooks Setup não podem bloquear. Qualquer código de saída não-zero, incluindo 2, superficializa stderr ao usuário como um aviso de `<hook name> hook error`, e a execução continua. Em [modo não-interativo](/pt/headless), a saída do hook aparece apenas quando você lança com `--verbose`.1119Hooks Setup não podem bloquear. Qualquer código de saída não-zero, incluindo 2, superficializa stderr ao usuário como um aviso de `<hook name> hook error`, e a execução continua. Em [modo não-interativo](/docs/pt/headless), a saída do hook aparece apenas quando você lança com `--verbose`.

1120 1120 

1121Para passar informação para o contexto de Claude, retorne `additionalContext` em saída JSON; stdout simples é escrito apenas no log de debug. Além dos [campos de saída JSON](#json-output) disponíveis para todos os hooks, você pode retornar esses campos específicos do evento:1121Para passar informação para o contexto de Claude, retorne `additionalContext` em saída JSON; stdout simples é escrito apenas no log de debug. Além dos [campos de saída JSON](#json-output) disponíveis para todos os hooks, você pode retornar esses campos específicos do evento:

1122 1122 

1186 1186 

1187Um hook `UserPromptSubmit` que atinge seu timeout é cancelado e sua saída, incluindo qualquer `additionalContext`, é descartada. O prompt ainda chega ao Claude sem esse contexto. A partir de v2.1.196, a transcrição mostra um aviso nomeando o hook, o timeout que disparou e que a saída foi descartada. Versões anteriores cancelam o hook sem aviso.1187Um hook `UserPromptSubmit` que atinge seu timeout é cancelado e sua saída, incluindo qualquer `additionalContext`, é descartada. O prompt ainda chega ao Claude sem esse contexto. A partir de v2.1.196, a transcrição mostra um aviso nomeando o hook, o timeout que disparou e que a saída foi descartada. Versões anteriores cancelam o hook sem aviso.

1188 1188 

1189Um hook de callback [Agent SDK](/pt/agent-sdk/hooks) em `UserPromptSubmit` que atinge seu timeout bloqueia o prompt com uma mensagem nomeando o hook e o timeout, porque um callback lá pode estar atuando como um portão de política que não deve falhar aberto. A sessão continua. Antes de v2.1.208, um timeout de callback naquele evento terminava o turno com um erro de execução.1189Um hook de callback [Agent SDK](/docs/pt/agent-sdk/hooks) em `UserPromptSubmit` que atinge seu timeout bloqueia o prompt com uma mensagem nomeando o hook e o timeout, porque um callback lá pode estar atuando como um portão de política que não deve falhar aberto. A sessão continua. Antes de v2.1.208, um timeout de callback naquele evento terminava o turno com um erro de execução.

1190 1190 

1191<h4 id="userpromptsubmit-input">1191<h4 id="userpromptsubmit-input">

1192 Entrada de UserPromptSubmit1192 Entrada de UserPromptSubmit

1441Executa após Claude criar parâmetros de ferramenta e antes de processar a chamada da ferramenta. Corresponde no nome da ferramenta: `Bash`, `Edit`, `Write`, `Read`, `Glob`, `Grep`, `Agent`, `WebFetch`, `WebSearch`, `AskUserQuestion`, `ExitPlanMode` e qualquer [nome de ferramenta MCP](#match-mcp-tools).1441Executa após Claude criar parâmetros de ferramenta e antes de processar a chamada da ferramenta. Corresponde no nome da ferramenta: `Bash`, `Edit`, `Write`, `Read`, `Glob`, `Grep`, `Agent`, `WebFetch`, `WebSearch`, `AskUserQuestion`, `ExitPlanMode` e qualquer [nome de ferramenta MCP](#match-mcp-tools).

1442 1442 

1443<Warning>1443<Warning>

1444 PreToolUse executa apenas quando Claude chama uma ferramenta. Arquivos que você [referencia com `@` em seu prompt](/pt/common-workflows#reference-files-and-directories) são adicionados sem qualquer chamada de ferramenta: Claude Code insere seus conteúdos enquanto constrói o prompt, então nenhum hook PreToolUse dispara para eles, incluindo hooks correspondendo a `Read`. Para bloquear caminhos específicos de referências `@`, use uma [regra de negação `Read`](/pt/permissions#read-and-edit) em vez disso.1444 PreToolUse executa apenas quando Claude chama uma ferramenta. Arquivos que você [referencia com `@` em seu prompt](/docs/pt/common-workflows#reference-files-and-directories) são adicionados sem qualquer chamada de ferramenta: Claude Code insere seus conteúdos enquanto constrói o prompt, então nenhum hook PreToolUse dispara para eles, incluindo hooks correspondendo a `Read`. Para bloquear caminhos específicos de referências `@`, use uma [regra de negação `Read`](/docs/pt/permissions#read-and-edit) em vez disso.

1445</Warning>1445</Warning>

1446 1446 

1447Use [Controle de decisão PreToolUse](#pretooluse-decision-control) para permitir, negar, pedir ou adiar a chamada da ferramenta.1447Use [Controle de decisão PreToolUse](#pretooluse-decision-control) para permitir, negar, pedir ou adiar a chamada da ferramenta.

1462| :------------------ | :------ | :----------------- | :------------------------------------------------------------------------------------------------------------------------------------------------ |1462| :------------------ | :------ | :----------------- | :------------------------------------------------------------------------------------------------------------------------------------------------ |

1463| `command` | string | `"npm test"` | O comando shell a executar |1463| `command` | string | `"npm test"` | O comando shell a executar |

1464| `description` | string | `"Run test suite"` | Descrição opcional do que o comando faz |1464| `description` | string | `"Run test suite"` | Descrição opcional do que o comando faz |

1465| `timeout` | number | `120000` | Timeout opcional em milissegundos. Valores acima do [máximo](/pt/tools-reference#bash-tool-behavior) são reduzidos ao máximo em vez de rejeitados |1465| `timeout` | number | `120000` | Timeout opcional em milissegundos. Valores acima do [máximo](/docs/pt/tools-reference#bash-tool-behavior) são reduzidos ao máximo em vez de rejeitados |

1466| `run_in_background` | boolean | `false` | Se o comando deve executar em background |1466| `run_in_background` | boolean | `false` | Se o comando deve executar em background |

1467 1467 

1468<h5 id="write">1468<h5 id="write">

1554 Agent1554 Agent

1555</h5>1555</h5>

1556 1556 

1557Gera um [subagente](/pt/sub-agents).1557Gera um [subagente](/docs/pt/sub-agents).

1558 1558 

1559| Campo | Tipo | Exemplo | Descrição |1559| Campo | Tipo | Exemplo | Descrição |

1560| :-------------- | :----- | :------------------------- | :-------------------------------------------------- |1560| :-------------- | :----- | :------------------------- | :-------------------------------------------------- |

1597 ExitPlanMode1597 ExitPlanMode

1598</h5>1598</h5>

1599 1599 

1600Apresenta um plano e pede ao usuário para aprová-lo antes do Claude sair do [modo de plano](/pt/permission-modes#analyze-before-you-edit-with-plan-mode). Claude escreve o plano em um arquivo no disco antes de chamar a ferramenta, então o `tool_input` literal do modelo é tipicamente vazio. Claude Code injeta o conteúdo do plano e o caminho do arquivo antes de passar a entrada para hooks.1600Apresenta um plano e pede ao usuário para aprová-lo antes do Claude sair do [modo de plano](/docs/pt/permission-modes#analyze-before-you-edit-with-plan-mode). Claude escreve o plano em um arquivo no disco antes de chamar a ferramenta, então o `tool_input` literal do modelo é tipicamente vazio. Claude Code injeta o conteúdo do plano e o caminho do arquivo antes de passar a entrada para hooks.

1601 1601 

1602| Campo | Tipo | Exemplo | Descrição |1602| Campo | Tipo | Exemplo | Descrição |

1603| :--------------- | :----- | :------------------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |1603| :--------------- | :----- | :------------------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

1615 1615 

1616| Campo | Descrição |1616| Campo | Descrição |

1617| :------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |1617| :------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

1618| `permissionDecision` | `"allow"` ignora o prompt de permissão, exceto para [ferramentas que requerem interação do usuário](#pretooluse-decision-control) e ferramentas conectoras [sua organização definiu para `ask`](/pt/mcp#organization-controls-on-connector-tools). `"deny"` previne a chamada da ferramenta. `"ask"` solicita ao usuário confirmar. `"defer"` sai graciosamente para que a ferramenta possa ser retomada mais tarde. [Regras de negação e pergunta](/pt/permissions#manage-permissions) ainda são avaliadas independentemente do que o hook retorna |1618| `permissionDecision` | `"allow"` ignora o prompt de permissão, exceto para [ferramentas que requerem interação do usuário](#pretooluse-decision-control) e ferramentas conectoras [sua organização definiu para `ask`](/docs/pt/mcp#organization-controls-on-connector-tools). `"deny"` previne a chamada da ferramenta. `"ask"` solicita ao usuário 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 |

1619| `permissionDecisionReason` | Para `"allow"` e `"ask"`, mostrado ao usuário mas não ao Claude. Para `"deny"`, mostrado ao Claude. Para `"defer"`, ignorado |1619| `permissionDecisionReason` | Para `"allow"` e `"ask"`, mostrado ao usuário mas não ao Claude. Para `"deny"`, mostrado ao Claude. Para `"defer"`, ignorado |

1620| `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. Combine com `"allow"` para aprovação automática ou `"ask"` para mostrar a entrada modificada ao usuário. Para `"defer"`, ignorado |1620| `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. Combine com `"allow"` para aprovação automática ou `"ask"` para mostrar a entrada modificada ao usuário. Para `"defer"`, ignorado |

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

1638}1638}

1639```1639```

1640 1640 

1641`AskUserQuestion` e `ExitPlanMode` requerem interação do usuário e normalmente bloqueiam em [modo não-interativo](/pt/headless) com a flag `-p`. Retornar `permissionDecision: "allow"` junto com `updatedInput` satisfaz esse requisito: o hook lê a entrada da ferramenta de stdin, coleta a resposta através de sua própria UI e a retorna em `updatedInput` para que a ferramenta execute sem solicitar. Retornar `"allow"` sozinho não é suficiente para essas ferramentas. Para `AskUserQuestion`, ecoar de volta o array `questions` original e adicionar um objeto [`answers`](#askuserquestion) mapeando o texto de cada pergunta para a resposta escolhida.1641`AskUserQuestion` e `ExitPlanMode` requerem interação do usuário e normalmente bloqueiam em [modo não-interativo](/docs/pt/headless) com a flag `-p`. Retornar `permissionDecision: "allow"` junto com `updatedInput` satisfaz esse requisito: o hook lê a entrada da ferramenta de stdin, coleta a resposta através de sua própria UI e a retorna em `updatedInput` para que a ferramenta execute sem solicitar. Retornar `"allow"` sozinho não é suficiente para essas ferramentas. Para `AskUserQuestion`, ecoar de volta o array `questions` original e adicionar um objeto [`answers`](#askuserquestion) mapeando o texto de cada pergunta para a resposta escolhida.

1642 1642 

1643Ferramentas conectoras [sua organização definiu para `ask`](/pt/mcp#organization-controls-on-connector-tools) solicitam mesmo quando um hook retorna `"allow"`.1643Ferramentas conectoras [sua organização definiu para `ask`](/docs/pt/mcp#organization-controls-on-connector-tools) solicitam mesmo quando um hook retorna `"allow"`.

1644 1644 

1645A partir de v2.1.199, uma ferramenta MCP cujo servidor a marca com [`_meta["anthropic/requiresUserInteraction"]`](/pt/mcp#require-approval-for-a-specific-tool) é mais rigorosa: um hook não pode pular seu prompt de aprovação com `"allow"`, com ou sem `updatedInput`, porque Claude Code não pode confirmar que o hook coletou a interação que a ferramenta precisa.1645A partir de v2.1.199, uma ferramenta MCP cujo servidor a marca com [`_meta["anthropic/requiresUserInteraction"]`](/docs/pt/mcp#require-approval-for-a-specific-tool) é mais rigorosa: um hook não pode pular seu prompt de aprovação com `"allow"`, com ou sem `updatedInput`, porque Claude Code não pode confirmar que o hook coletou a interação que a ferramenta precisa.

1646 1646 

1647<Note>1647<Note>

1648 PreToolUse anteriormente usava campos `decision` e `reason` de nível superior, mas esses estão deprecados para este evento. Use `hookSpecificOutput.permissionDecision` e `hookSpecificOutput.permissionDecisionReason` em vez disso. Os valores deprecados `"approve"` e `"block"` mapeiam para `"allow"` e `"deny"` respectivamente. Outros eventos como PostToolUse e Stop continuam usando `decision` e `reason` de nível superior como seu formato atual.1648 PreToolUse anteriormente usava campos `decision` e `reason` de nível superior, mas esses estão deprecados para este evento. Use `hookSpecificOutput.permissionDecision` e `hookSpecificOutput.permissionDecisionReason` em vez disso. Os valores deprecados `"approve"` e `"block"` mapeiam para `"allow"` e `"deny"` respectivamente. Outros eventos como PostToolUse e Stop continuam usando `decision` e `reason` de nível superior como seu formato atual.

1652 Adiar uma chamada de ferramenta para mais tarde1652 Adiar uma chamada de ferramenta para mais tarde

1653</h4>1653</h4>

1654 1654 

1655`"defer"` é para integrações que executam `claude -p` como um subprocesso e leem sua saída JSON, como um aplicativo Agent SDK ou uma UI personalizada construída em cima do Claude Code. Permite que esse processo chamador pause Claude em uma chamada de ferramenta, colete entrada através de sua própria interface e retome onde parou. Claude Code honra este valor apenas em [modo não-interativo](/pt/headless) com a flag `-p`. Em sessões interativas ele registra um aviso e ignora o resultado do hook.1655`"defer"` é para integrações que executam `claude -p` como um subprocesso e leem sua saída JSON, como um aplicativo Agent SDK ou uma UI personalizada construída em cima do Claude Code. Permite que esse processo chamador pause Claude em uma chamada de ferramenta, colete entrada através de sua própria interface e retome onde parou. Claude Code honra este valor apenas em [modo não-interativo](/docs/pt/headless) com a flag `-p`. Em sessões interativas ele registra um aviso e ignora o resultado do hook.

1656 1656 

1657A ferramenta `AskUserQuestion` é o caso típico: Claude quer fazer uma pergunta ao usuário, mas não há terminal para responder. A viagem de ida e volta funciona assim:1657A ferramenta `AskUserQuestion` é o caso típico: Claude quer fazer uma pergunta ao usuário, mas não há terminal para responder. A viagem de ida e volta funciona assim:

1658 1658 

1678}1678}

1679```1679```

1680 1680 

1681Não há timeout ou limite de tentativas. A sessão permanece no disco até que você a retome, sujeita à varredura de retenção [`cleanupPeriodDays`](/pt/settings#available-settings) que deleta arquivos de sessão após 30 dias por padrão. Se a resposta não estiver pronta quando você retomar, o hook pode retornar `"defer"` novamente e o processo sai da mesma forma. O processo chamador controla quando quebrar o loop eventualmente retornando `"allow"` ou `"deny"` do hook.1681Não há timeout ou limite de tentativas. A sessão permanece no disco até que você a retome, sujeita à varredura de retenção [`cleanupPeriodDays`](/docs/pt/settings#available-settings) que deleta arquivos de sessão após 30 dias por padrão. Se a resposta não estiver pronta quando você retomar, o hook pode retornar `"defer"` novamente e o processo sai da mesma forma. O processo chamador controla quando quebrar o loop eventualmente retornando `"allow"` ou `"deny"` do hook.

1682 1682 

1683`"defer"` apenas funciona quando Claude faz uma única chamada de ferramenta no turno. Se Claude faz várias chamadas de ferramenta de uma vez, `"defer"` é ignorado com um aviso e a ferramenta prossegue através do fluxo de permissão normal. A restrição existe porque resume pode apenas re-executar uma ferramenta: não há forma de adiar uma chamada de um lote sem deixar as outras não resolvidas.1683`"defer"` apenas funciona quando Claude faz uma única chamada de ferramenta no turno. Se Claude faz várias chamadas de ferramenta de uma vez, `"defer"` é ignorado com um aviso e a ferramenta prossegue através do fluxo de permissão normal. A restrição existe porque resume pode apenas re-executar uma ferramenta: não há forma de adiar uma chamada de um lote sem deixar as outras não resolvidas.

1684 1684 

1734 1734 

1735| Campo | Descrição |1735| Campo | Descrição |

1736| :------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |1736| :------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

1737| `behavior` | `"allow"` concede a permissão, `"deny"` nega. [Regras de negação e pergunta](/pt/permissions#manage-permissions) ainda são avaliadas, então um hook retornando `"allow"` não sobrescreve uma regra de negação correspondente |1737| `behavior` | `"allow"` concede a permissão, `"deny"` nega. [Regras de negação e pergunta](/docs/pt/permissions#manage-permissions) ainda são avaliadas, então um hook retornando `"allow"` não sobrescreve uma regra de negação correspondente |

1738| `updatedInput` | Apenas para `"allow"`: 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. A entrada modificada é re-avaliada contra regras de negação e pergunta |1738| `updatedInput` | Apenas para `"allow"`: 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. A entrada modificada é re-avaliada contra regras de negação e pergunta |

1739| `updatedPermissions` | Apenas para `"allow"`: array de [entradas de atualização de permissão](#permission-update-entries) a aplicar, como adicionar uma regra de permissão ou mudar o modo de permissão da sessão |1739| `updatedPermissions` | Apenas para `"allow"`: array de [entradas de atualização de permissão](#permission-update-entries) a aplicar, como adicionar uma regra de permissão ou mudar o modo de permissão da sessão |

1740| `message` | Apenas para `"deny"`: diz ao Claude por que a permissão foi negada |1740| `message` | Apenas para `"deny"`: diz ao Claude por que a permissão foi negada |

1770| `removeDirectories` | `directories`, `destination` | Remove diretórios de trabalho |1770| `removeDirectories` | `directories`, `destination` | Remove diretórios de trabalho |

1771 1771 

1772<Note>1772<Note>

1773 `setMode` com `bypassPermissions` apenas toma efeito se a sessão foi lançada com modo bypass já disponível: `--dangerously-skip-permissions`, `--permission-mode bypassPermissions`, `--allow-dangerously-skip-permissions` ou `permissions.defaultMode: "bypassPermissions"` em configurações, e o modo não é desabilitado por [`permissions.disableBypassPermissionsMode`](/pt/permissions#managed-settings). Caso contrário, a atualização é um no-op. `bypassPermissions` nunca é persistido como `defaultMode` independentemente de `destination`.1773 `setMode` com `bypassPermissions` apenas toma efeito se a sessão foi lançada com modo bypass já disponível: `--dangerously-skip-permissions`, `--permission-mode bypassPermissions`, `--allow-dangerously-skip-permissions` ou `permissions.defaultMode: "bypassPermissions"` em configurações, e o modo não é desabilitado por [`permissions.disableBypassPermissionsMode`](/docs/pt/permissions#managed-settings). Caso contrário, a atualização é um no-op. `bypassPermissions` nunca é persistido como `defaultMode` independentemente de `destination`.

1774</Note>1774</Note>

1775 1775 

1776O campo `destination` em cada entrada determina se a mudança fica em memória ou persiste em um arquivo de configurações.1776O campo `destination` em cada entrada determina se a mudança fica em memória ou persiste em um arquivo de configurações.

1989 PermissionDenied1989 PermissionDenied

1990</h3>1990</h3>

1991 1991 

1992Executa quando o classificador de [modo automático](/pt/permission-modes#eliminate-prompts-with-auto-mode) nega uma chamada de ferramenta. Este hook apenas dispara em modo automático: não executa quando você nega manualmente um diálogo de permissão, quando um hook `PreToolUse` bloqueia uma chamada ou quando uma regra `deny` corresponde. Use-o para registrar negações de classificador, ajustar configuração ou dizer ao modelo que pode tentar novamente a chamada de ferramenta.1992Executa quando o classificador de [modo automático](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode) nega uma chamada de ferramenta. Este hook apenas dispara em modo automático: não executa quando você nega manualmente um diálogo de permissão, quando um hook `PreToolUse` bloqueia uma chamada ou quando uma regra `deny` corresponde. Use-o para registrar negações de classificador, ajustar configuração ou dizer ao modelo que pode tentar novamente a chamada de ferramenta.

1993 1993 

1994Corresponde no nome da ferramenta, mesmos valores que PreToolUse.1994Corresponde no nome da ferramenta, mesmos valores que PreToolUse.

1995 1995 

2051| `elicitation_dialog` | Um servidor MCP abre um formulário de elicitação |2051| `elicitation_dialog` | Um servidor MCP abre um formulário de elicitação |

2052| `elicitation_complete` | Um formulário de elicitação MCP é submetido ou descartado |2052| `elicitation_complete` | Um formulário de elicitação MCP é submetido ou descartado |

2053| `elicitation_response` | Uma resposta de elicitação MCP é enviada de volta ao servidor |2053| `elicitation_response` | Uma resposta de elicitação MCP é enviada de volta ao servidor |

2054| `agent_needs_input` | Uma sessão em background começa esperando sua entrada. Dispara apenas enquanto [agent view](/pt/agent-view) está aberto em um terminal |2054| `agent_needs_input` | Uma sessão em background começa esperando sua entrada. Dispara apenas enquanto [agent view](/docs/pt/agent-view) está aberto em um terminal |

2055| `agent_completed` | Uma sessão em background termina ou falha. Dispara apenas enquanto [agent view](/pt/agent-view) está aberto em um terminal |2055| `agent_completed` | Uma sessão em background termina ou falha. Dispara apenas enquanto [agent view](/docs/pt/agent-view) está aberto em um terminal |

2056 2056 

2057Os tipos `agent_needs_input` e `agent_completed` requerem Claude Code v2.1.198 ou posterior.2057Os tipos `agent_needs_input` e `agent_completed` requerem Claude Code v2.1.198 ou posterior.

2058 2058 

2109 SubagentStart2109 SubagentStart

2110</h3>2110</h3>

2111 2111 

2112Executa quando um subagente do Claude Code é gerado via ferramenta Agent. Suporta matchers para filtrar por nome de tipo de agente. Para agentes integrados, este é o nome do agente como `general-purpose`, `Explore` ou `Plan`. Para [subagentes personalizados](/pt/sub-agents), este é o campo `name` do frontmatter do agente, não o nome do arquivo.2112Executa quando um subagente do Claude Code é gerado via ferramenta Agent. Suporta matchers para filtrar por nome de tipo de agente. Para agentes integrados, este é o nome do agente como `general-purpose`, `Explore` ou `Plan`. Para [subagentes personalizados](/docs/pt/sub-agents), este é o campo `name` do frontmatter do agente, não o nome do arquivo.

2113 2113 

2114Para subagentes fornecidos por um [plugin](/pt/plugins), o tipo de agente é o identificador com escopo de plugin como `my-plugin:reviewer`, não o nome frontmatter simples. O dois-pontos coloca um nome com escopo de plugin no caminho de expressão regular, então ancorize o matcher com `^` e `$` para uma correspondência exata: `^my-plugin:reviewer$`.2114Para subagentes fornecidos por um [plugin](/docs/pt/plugins), o tipo de agente é o identificador com escopo de plugin como `my-plugin:reviewer`, não o nome frontmatter simples. O dois-pontos coloca um nome com escopo de plugin no caminho de expressão regular, então ancorize o matcher com `^` e `$` para uma correspondência exata: `^my-plugin:reviewer$`.

2115 2115 

2116<h4 id="subagentstart-input">2116<h4 id="subagentstart-input">

2117 Entrada de SubagentStart2117 Entrada de SubagentStart

2243 TaskCompleted2243 TaskCompleted

2244</h3>2244</h3>

2245 2245 

2246Executa quando uma tarefa está sendo marcada como concluída. Isso dispara em duas situações: quando qualquer agente marca explicitamente uma tarefa como concluída através da ferramenta TaskUpdate, ou quando um colega de [equipe de agente](/pt/agent-teams) termina seu turno com tarefas em progresso. Use isso para impor critérios de conclusão como testes aprovados ou verificações de lint antes de uma tarefa fechar.2246Executa quando uma tarefa está sendo marcada como concluída. Isso dispara em duas situações: quando qualquer agente marca explicitamente uma tarefa como concluída através da ferramenta TaskUpdate, ou quando um colega de [equipe de agente](/docs/pt/agent-teams) termina seu turno com tarefas em progresso. Use isso para impor critérios de conclusão como testes aprovados ou verificações de lint antes de uma tarefa fechar.

2247 2247 

2248Quando um hook `TaskCompleted` sai com código 2, a tarefa não é marcada como concluída e a mensagem de stderr é alimentada de volta ao modelo como feedback. Para parar o colega inteiramente em vez de re-executá-lo, retorne JSON com `{"continue": false, "stopReason": "..."}`. Hooks TaskCompleted não suportam matchers e disparam em cada ocorrência.2248Quando um hook `TaskCompleted` sai com código 2, a tarefa não é marcada como concluída e a mensagem de stderr é alimentada de volta ao modelo como feedback. Para parar o colega inteiramente em vez de re-executá-lo, retorne JSON com `{"continue": false, "stopReason": "..."}`. Hooks TaskCompleted não suportam matchers e disparam em cada ocorrência.

2249 2249 

2308Executa quando o agente Claude Code principal terminou de responder. Não executa se a parada ocorreu devido a uma interrupção do usuário. Erros de API disparam [StopFailure](#stopfailure) em vez disso.2308Executa quando o agente Claude Code principal terminou de responder. Não executa se a parada ocorreu devido a uma interrupção do usuário. Erros de API disparam [StopFailure](#stopfailure) em vez disso.

2309 2309 

2310<Tip>2310<Tip>

2311 O comando [`/goal`](/pt/goal) é um atalho integrado para um hook Stop baseado em prompt com escopo de sessão. Use-o quando você quiser que Claude continue trabalhando até que uma condição se mantenha sem escrever configuração de hook.2311 O comando [`/goal`](/docs/pt/goal) é um atalho integrado para um hook Stop baseado em prompt com escopo de sessão. Use-o quando você quiser que Claude continue trabalhando até que uma condição se mantenha sem escrever configuração de hook.

2312</Tip>2312</Tip>

2313 2313 

2314<h4 id="stop-input">2314<h4 id="stop-input">

2441 TeammateIdle2441 TeammateIdle

2442</h3>2442</h3>

2443 2443 

2444Executa quando um colega de [equipe de agente](/pt/agent-teams) está prestes a ficar ocioso após terminar seu turno. Use isso para impor portões de qualidade antes de um colega parar de trabalhar, como exigir verificações de lint aprovadas ou verificar que arquivos de saída existem.2444Executa quando um colega de [equipe de agente](/docs/pt/agent-teams) está prestes a ficar ocioso após terminar seu turno. Use isso para impor portões de qualidade antes de um colega parar de trabalhar, como exigir verificações de lint aprovadas ou verificar que arquivos de saída existem.

2445 2445 

2446Quando um hook `TeammateIdle` sai com código 2, o colega recebe a mensagem de stderr como feedback e continua trabalhando em vez de ficar ocioso. Para parar o colega inteiramente em vez de re-executá-lo, retorne JSON com `{"continue": false, "stopReason": "..."}`. Hooks TeammateIdle não suportam matchers e disparam em cada ocorrência.2446Quando um hook `TeammateIdle` sai com código 2, o colega recebe a mensagem de stderr como feedback e continua trabalhando em vez de ficar ocioso. Para parar o colega inteiramente em vez de re-executá-lo, retorne JSON com `{"continue": false, "stopReason": "..."}`. Hooks TeammateIdle não suportam matchers e disparam em cada ocorrência.

2447 2447 

2655 WorktreeCreate2655 WorktreeCreate

2656</h3>2656</h3>

2657 2657 

2658Executa quando um worktree está sendo criado, seja de `claude --worktree` ou de um [subagente usando `isolation: "worktree"`](/pt/sub-agents#choose-the-subagent-scope). Por padrão Claude Code cria a cópia de trabalho isolada com `git worktree`. Configurar um hook WorktreeCreate substitui esse comportamento git padrão, permitindo que você use um sistema de controle de versão diferente como SVN, Perforce ou Mercurial.2658Executa quando um worktree está sendo criado, seja de `claude --worktree` ou de um [subagente usando `isolation: "worktree"`](/docs/pt/sub-agents#choose-the-subagent-scope). Por padrão Claude Code cria a cópia de trabalho isolada com `git worktree`. Configurar um hook WorktreeCreate substitui esse comportamento git padrão, permitindo que você use um sistema de controle de versão diferente como SVN, Perforce ou Mercurial.

2659 2659 

2660Porque o hook substitui o comportamento padrão inteiramente, [`.worktreeinclude`](/pt/worktrees#copy-gitignored-files-into-worktrees) não é processado. Se você precisar copiar arquivos de configuração local como `.env` para o novo worktree, faça isso dentro de seu script de hook.2660Porque o hook substitui o comportamento padrão inteiramente, [`.worktreeinclude`](/docs/pt/worktrees#copy-gitignored-files-into-worktrees) não é processado. Se você precisar copiar arquivos de configuração local como `.env` para o novo worktree, faça isso dentro de seu script de hook.

2661 2661 

2662O hook deve retornar o caminho para o diretório worktree criado. Claude Code usa este caminho como o diretório de trabalho para a sessão isolada. Consulte [Saída de WorktreeCreate](#worktreecreate-output) para como cada tipo de hook retorna o caminho.2662O hook deve retornar o caminho para o diretório worktree criado. Claude Code usa este caminho como o diretório de trabalho para a sessão isolada. Consulte [Saída de WorktreeCreate](#worktreecreate-output) para como cada tipo de hook retorna o caminho.

2663 2663 

3110 Verificar múltiplas condições antes de parar3110 Verificar múltiplas condições antes de parar

3111</h3>3111</h3>

3112 3112 

3113Este hook `Stop` usa um prompt detalhado para verificar três condições antes de permitir que Claude pare. Hooks `SubagentStop` usam o mesmo formato para avaliar se um [subagente](/pt/sub-agents) deve parar. Se `"ok"` for `false`, Claude continua trabalhando com a razão fornecida como sua próxima instrução:3113Este hook `Stop` usa um prompt detalhado para verificar três condições antes de permitir que Claude pare. Hooks `SubagentStop` usam o mesmo formato para avaliar se um [subagente](/docs/pt/sub-agents) deve parar. Se `"ok"` for `false`, Claude continua trabalhando com a razão fornecida como sua próxima instrução:

3114 3114 

3115```json theme={null}3115```json theme={null}

3116{3116{

3383 3383 

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

3385 3385 

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

10 10 

11Para decisões que exigem julgamento em vez de regras determinísticas, você também pode usar [hooks baseados em prompt](#prompt-based-hooks) ou [hooks baseados em agente](#agent-based-hooks) que usam um modelo Claude para avaliar condições.11Para decisões que exigem julgamento em vez de regras determinísticas, você também pode usar [hooks baseados em prompt](#prompt-based-hooks) ou [hooks baseados em agente](#agent-based-hooks) que usam um modelo Claude para avaliar condições.

12 12 

13Para outras formas de estender Claude Code, consulte [skills](/pt/skills) para dar ao Claude instruções adicionais e comandos executáveis, [subagents](/pt/sub-agents) para executar tarefas em contextos isolados e [plugins](/pt/plugins) para empacotar extensões para compartilhar entre projetos.13Para outras formas de estender Claude Code, consulte [skills](/docs/pt/skills) para dar ao Claude instruções adicionais e comandos executáveis, [subagents](/docs/pt/sub-agents) para executar tarefas em contextos isolados e [plugins](/docs/pt/plugins) para empacotar extensões para compartilhar entre projetos.

14 14 

15<Tip>15<Tip>

16 Este guia cobre casos de uso comuns e como começar. Para esquemas de eventos completos, formatos de entrada/saída JSON e recursos avançados como hooks assíncronos e hooks de ferramentas MCP, consulte a [referência de Hooks](/pt/hooks).16 Este guia cobre casos de uso comuns e como começar. Para esquemas de eventos completos, formatos de entrada/saída JSON e recursos avançados como hooks assíncronos e hooks de ferramentas MCP, consulte a [referência de Hooks](/docs/pt/hooks).

17</Tip>17</Tip>

18 18 

19<h2 id="set-up-your-first-hook">19<h2 id="set-up-your-first-hook">

85 O que você pode automatizar85 O que você pode automatizar

86</h2>86</h2>

87 87 

88Hooks permitem executar código em pontos-chave do ciclo de vida do Claude Code: formatar arquivos após edições, bloquear comandos antes de executarem, enviar notificações quando Claude precisa de entrada, injetar contexto no início da sessão e muito mais. Para a lista completa de eventos de hook, consulte a [referência de Hooks](/pt/hooks#hook-lifecycle).88Hooks permitem executar código em pontos-chave do ciclo de vida do Claude Code: formatar arquivos após edições, bloquear comandos antes de executarem, enviar notificações quando Claude precisa de entrada, injetar contexto no início da sessão e muito mais. Para a lista completa de eventos de hook, consulte a [referência de Hooks](/docs/pt/hooks#hook-lifecycle).

89 89 

90Cada exemplo inclui um bloco de configuração pronto para usar que você adiciona a um [arquivo de configuração](#configure-hook-location).90Cada exemplo inclui um bloco de configuração pronto para usar que você adiciona a um [arquivo de configuração](#configure-hook-location).

91 91 

92Para um exemplo de produção de hooks que executam uma revisão de modelo separada e alimentam as descobertas de volta à sessão, consulte [como o plugin `security-guidance` se integra com Claude Code](/pt/security-guidance#how-the-plugin-integrates-with-claude-code).92Para um exemplo de produção de hooks que executam uma revisão de modelo separada e alimentam as descobertas de volta à sessão, consulte [como o plugin `security-guidance` se integra com Claude Code](/docs/pt/security-guidance#how-the-plugin-integrates-with-claude-code).

93 93 

94<h3 id="get-notified-when-claude-needs-input">94<h3 id="get-notified-when-claude-needs-input">

95 Receba notificações quando Claude precisa de entrada95 Receba notificações quando Claude precisa de entrada

181| `elicitation_dialog` | Um servidor MCP abre um formulário de elicitação |181| `elicitation_dialog` | Um servidor MCP abre um formulário de elicitação |

182| `elicitation_complete` | Um formulário de elicitação MCP é enviado ou descartado |182| `elicitation_complete` | Um formulário de elicitação MCP é enviado ou descartado |

183| `elicitation_response` | Uma resposta de elicitação MCP é enviada de volta ao servidor |183| `elicitation_response` | Uma resposta de elicitação MCP é enviada de volta ao servidor |

184| `agent_needs_input` | Uma sessão em segundo plano começa a aguardar sua entrada. Dispara apenas enquanto a [visualização de agente](/pt/agent-view) está aberta |184| `agent_needs_input` | Uma sessão em segundo plano começa a aguardar sua entrada. Dispara apenas enquanto a [visualização de agente](/docs/pt/agent-view) está aberta |

185| `agent_completed` | Uma sessão em segundo plano termina ou falha. Dispara apenas enquanto a [visualização de agente](/pt/agent-view) está aberta |185| `agent_completed` | Uma sessão em segundo plano termina ou falha. Dispara apenas enquanto a [visualização de agente](/docs/pt/agent-view) está aberta |

186 186 

187Os matchers `agent_needs_input` e `agent_completed` exigem Claude Code v2.1.198 ou posterior.187Os matchers `agent_needs_input` e `agent_completed` exigem Claude Code v2.1.198 ou posterior.

188 188 

189Digite `/hooks` e selecione `Notification` para confirmar que o hook está registrado. Para o esquema de evento completo, consulte a [referência de Notification](/pt/hooks#notification).189Digite `/hooks` e selecione `Notification` para confirmar que o hook está registrado. Para o esquema de evento completo, consulte a [referência de Notification](/docs/pt/hooks#notification).

190 190 

191<h3 id="auto-format-code-after-edits">191<h3 id="auto-format-code-after-edits">

192 Formatar código automaticamente após edições192 Formatar código automaticamente após edições

309}309}

310```310```

311 311 

312Você pode substituir o `echo` por qualquer comando que produza saída dinâmica, como `git log --oneline -5` para mostrar commits recentes. Para injetar contexto em cada início de sessão, considere usar [CLAUDE.md](/pt/memory) em vez disso. Para variáveis de ambiente, consulte [`CLAUDE_ENV_FILE`](/pt/hooks#persist-environment-variables) na referência.312Você pode substituir o `echo` por qualquer comando que produza saída dinâmica, como `git log --oneline -5` para mostrar commits recentes. Para injetar contexto em cada início de sessão, considere usar [CLAUDE.md](/docs/pt/memory) em vez disso. Para variáveis de ambiente, consulte [`CLAUDE_ENV_FILE`](/docs/pt/hooks#persist-environment-variables) na referência.

313 313 

314<h3 id="audit-configuration-changes">314<h3 id="audit-configuration-changes">

315 Auditar mudanças de configuração315 Auditar mudanças de configuração

337}337}

338```338```

339 339 

340O matcher filtra por tipo de configuração: `user_settings`, `project_settings`, `local_settings`, `policy_settings` ou `skills`. Para bloquear uma mudança de entrar em vigor, saia com código 2 ou retorne `{"decision": "block"}`. Consulte a [referência de ConfigChange](/pt/hooks#configchange) para o esquema de entrada completo.340O matcher filtra por tipo de configuração: `user_settings`, `project_settings`, `local_settings`, `policy_settings` ou `skills`. Para bloquear uma mudança de entrar em vigor, saia com código 2 ou retorne `{"decision": "block"}`. Consulte a [referência de ConfigChange](/docs/pt/hooks#configchange) para o esquema de entrada completo.

341 341 

342<h3 id="reload-environment-when-directory-or-files-change">342<h3 id="reload-environment-when-directory-or-files-change">

343 Recarregar ambiente quando diretório ou arquivos mudam343 Recarregar ambiente quando diretório ou arquivos mudam

376 376 

377Execute `direnv allow` uma vez em cada diretório que tenha um `.envrc` para que direnv tenha permissão para carregá-lo. Se você usar devbox ou nix em vez de direnv, o mesmo padrão funciona com `devbox shellenv` ou `devbox global shellenv` no lugar de `direnv export bash`.377Execute `direnv allow` uma vez em cada diretório que tenha um `.envrc` para que direnv tenha permissão para carregá-lo. Se você usar devbox ou nix em vez de direnv, o mesmo padrão funciona com `devbox shellenv` ou `devbox global shellenv` no lugar de `direnv export bash`.

378 378 

379Para reagir a arquivos específicos em vez de cada mudança de diretório, use `FileChanged` com um `matcher` listando os nomes de arquivo para observar, separados por `|`. Ao construir a lista de observação, Claude Code divide este valor em nomes de arquivo literais em vez de avaliá-lo como uma regex. Consulte [FileChanged](/pt/hooks#filechanged) para como o mesmo valor também filtra quais grupos de hook executam quando um arquivo muda. Este exemplo observa `.envrc` e `.env` no diretório de trabalho:379Para reagir a arquivos específicos em vez de cada mudança de diretório, use `FileChanged` com um `matcher` listando os nomes de arquivo para observar, separados por `|`. Ao construir a lista de observação, Claude Code divide este valor em nomes de arquivo literais em vez de avaliá-lo como uma regex. Consulte [FileChanged](/docs/pt/hooks#filechanged) para como o mesmo valor também filtra quais grupos de hook executam quando um arquivo muda. Este exemplo observa `.envrc` e `.env` no diretório de trabalho:

380 380 

381```json theme={null}381```json theme={null}

382{382{

396}396}

397```397```

398 398 

399Consulte as entradas de referência [CwdChanged](/pt/hooks#cwdchanged) e [FileChanged](/pt/hooks#filechanged) para esquemas de entrada, saída `watchPaths` e detalhes de `CLAUDE_ENV_FILE`.399Consulte as entradas de referência [CwdChanged](/docs/pt/hooks#cwdchanged) e [FileChanged](/docs/pt/hooks#filechanged) para esquemas de entrada, saída `watchPaths` e detalhes de `CLAUDE_ENV_FILE`.

400 400 

401<h3 id="auto-approve-specific-permission-prompts">401<h3 id="auto-approve-specific-permission-prompts">

402 Aprovar automaticamente prompts de permissão específicos402 Aprovar automaticamente prompts de permissão específicos

431Para definir um modo de permissão específico em vez disso, a saída do seu hook pode incluir um array `updatedPermissions` com uma entrada `setMode`. O valor `mode` é qualquer modo de permissão como `default`, `acceptEdits` ou `bypassPermissions`, e `destination: "session"` o aplica apenas para a sessão atual.431Para definir um modo de permissão específico em vez disso, a saída do seu hook pode incluir um array `updatedPermissions` com uma entrada `setMode`. O valor `mode` é qualquer modo de permissão como `default`, `acceptEdits` ou `bypassPermissions`, e `destination: "session"` o aplica apenas para a sessão atual.

432 432 

433<Note>433<Note>

434 `bypassPermissions` só se aplica se a sessão foi iniciada com modo bypass já disponível: `--dangerously-skip-permissions`, `--permission-mode bypassPermissions`, `--allow-dangerously-skip-permissions`, ou `permissions.defaultMode: "bypassPermissions"` em configurações, e não desabilitado por [`permissions.disableBypassPermissionsMode`](/pt/permissions#managed-settings). Nunca é persistido como `defaultMode`.434 `bypassPermissions` só se aplica se a sessão foi iniciada com modo bypass já disponível: `--dangerously-skip-permissions`, `--permission-mode bypassPermissions`, `--allow-dangerously-skip-permissions`, ou `permissions.defaultMode: "bypassPermissions"` em configurações, e não desabilitado por [`permissions.disableBypassPermissionsMode`](/docs/pt/permissions#managed-settings). Nunca é persistido como `defaultMode`.

435</Note>435</Note>

436 436 

437Para mudar a sessão para `acceptEdits`, seu hook escreve este JSON para stdout:437Para mudar a sessão para `acceptEdits`, seu hook escreve este JSON para stdout:

450}450}

451```451```

452 452 

453Mantenha o matcher o mais restrito possível. Corresponder a `.*` ou deixar o matcher vazio aprovaria automaticamente cada prompt de permissão, incluindo escritas de arquivo e comandos shell. Consulte a [referência de PermissionRequest](/pt/hooks#permissionrequest-decision-control) para o conjunto completo de campos de decisão.453Mantenha o matcher o mais restrito possível. Corresponder a `.*` ou deixar o matcher vazio aprovaria automaticamente cada prompt de permissão, incluindo escritas de arquivo e comandos shell. Consulte a [referência de PermissionRequest](/docs/pt/hooks#permissionrequest-decision-control) para o conjunto completo de campos de decisão.

454 454 

455<h2 id="how-hooks-work">455<h2 id="how-hooks-work">

456 Como hooks funcionam456 Como hooks funcionam

478| `TaskCompleted` | When a task is being marked as completed |478| `TaskCompleted` | When a task is being marked as completed |

479| `Stop` | When Claude finishes responding |479| `Stop` | When Claude finishes responding |

480| `StopFailure` | When the turn ends due to an API error. Output and exit code are ignored |480| `StopFailure` | When the turn ends due to an API error. Output and exit code are ignored |

481| `TeammateIdle` | When an [agent team](/en/agent-teams) teammate is about to go idle |481| `TeammateIdle` | When an [agent team](/docs/en/agent-teams) teammate is about to go idle |

482| `InstructionsLoaded` | When a CLAUDE.md or `.claude/rules/*.md` file is loaded into context. Fires at session start and when files are lazily loaded during a session |482| `InstructionsLoaded` | When a CLAUDE.md or `.claude/rules/*.md` file is loaded into context. Fires at session start and when files are lazily loaded during a session |

483| `ConfigChange` | When a configuration file changes during a session |483| `ConfigChange` | When a configuration file changes during a session |

484| `CwdChanged` | When the working directory changes, for example when Claude executes a `cd` command. Useful for reactive environment management with tools like direnv |484| `CwdChanged` | When the working directory changes, for example when Claude executes a `cd` command. Useful for reactive environment management with tools like direnv |

485| `FileChanged` | When a watched file changes on disk. The `matcher` field specifies which filenames to watch |485| `FileChanged` | When a watched file changes on disk. The `matcher` field specifies which filenames to watch |

486| `WorktreeCreate` | When a worktree is being created via `--worktree` or `isolation: "worktree"`. Replaces default git behavior |486| `WorktreeCreate` | When a worktree is being created via `--worktree`, `isolation: "worktree"`, or for a background session. Replaces default git behavior |

487| `WorktreeRemove` | When a worktree is being removed, either at session exit or when a subagent finishes |487| `WorktreeRemove` | When a worktree is being removed at session exit, when a subagent finishes, or when you delete a background session |

488| `PreCompact` | Before context compaction |488| `PreCompact` | Before context compaction |

489| `PostCompact` | After context compaction completes |489| `PostCompact` | After context compaction completes |

490| `Elicitation` | When an MCP server requests user input during a tool call |490| `Elicitation` | When an MCP server requests user input during a tool call |

494Cada hook tem um `type` que determina como ele executa. A maioria dos hooks usa `"type": "command"`, que executa um comando shell. Quatro outros tipos estão disponíveis:494Cada hook tem um `type` que determina como ele executa. A maioria dos hooks usa `"type": "command"`, que executa um comando shell. Quatro outros tipos estão disponíveis:

495 495 

496* `"type": "http"`: POST dados de evento para uma URL. Consulte [HTTP hooks](#http-hooks).496* `"type": "http"`: POST dados de evento para uma URL. Consulte [HTTP hooks](#http-hooks).

497* `"type": "mcp_tool"`: chamar uma ferramenta em um servidor MCP já conectado. Consulte [MCP tool hooks](/pt/hooks#mcp-tool-hook-fields).497* `"type": "mcp_tool"`: chamar uma ferramenta em um servidor MCP já conectado. Consulte [MCP tool hooks](/docs/pt/hooks#mcp-tool-hook-fields).

498* `"type": "prompt"`: avaliação LLM de turno único. Consulte [Prompt-based hooks](#prompt-based-hooks).498* `"type": "prompt"`: avaliação LLM de turno único. Consulte [Prompt-based hooks](#prompt-based-hooks).

499* `"type": "agent"`: verificação multi-turno com acesso a ferramentas. Agent hooks são experimentais e podem mudar. Consulte [Agent-based hooks](#agent-based-hooks).499* `"type": "agent"`: verificação multi-turno com acesso a ferramentas. Agent hooks são experimentais e podem mudar. Consulte [Agent-based hooks](#agent-based-hooks).

500 500 

556}556}

557```557```

558 558 

559Seu script pode analisar esse JSON e agir em qualquer um desses campos. Hooks `UserPromptSubmit` obtêm o texto `prompt` em vez disso, hooks `SessionStart` obtêm a `source` de `startup`, `resume`, `clear` ou `compact`, e assim por diante. Consulte [Campos de entrada comuns](/pt/hooks#common-input-fields) na referência para campos compartilhados, e a seção de cada evento para esquemas específicos do evento.559Seu script pode analisar esse JSON e agir em qualquer um desses campos. Hooks `UserPromptSubmit` obtêm o texto `prompt` em vez disso, hooks `SessionStart` obtêm a `source` de `startup`, `resume`, `clear` ou `compact`, e assim por diante. Consulte [Campos de entrada comuns](/docs/pt/hooks#common-input-fields) na referência para campos compartilhados, e a seção de cada evento para esquemas específicos do evento.

560 560 

561<h4 id="hook-output">561<h4 id="hook-output">

562 Saída do hook562 Saída do hook

579 579 

580O código de saída determina o que acontece a seguir:580O código de saída determina o que acontece a seguir:

581 581 

582* **Exit 0**: o hook não relata objeção e a ação prossegue normalmente. Para um hook `PreToolUse` isso não aprova a chamada de ferramenta: o [fluxo de permissão](/pt/permissions) normal ainda se aplica. Para hooks `UserPromptSubmit`, `UserPromptExpansion` e `SessionStart`, qualquer coisa que você escrever para stdout é adicionada ao contexto do Claude.582* **Exit 0**: o hook não relata objeção e a ação prossegue normalmente. Para um hook `PreToolUse` isso não aprova a chamada de ferramenta: o [fluxo de permissão](/docs/pt/permissions) normal ainda se aplica. Para hooks `UserPromptSubmit`, `UserPromptExpansion` e `SessionStart`, qualquer coisa que você escrever para stdout é adicionada ao contexto do Claude.

583* **Exit 2**: a ação é bloqueada. Escreva um motivo para stderr, e Claude o recebe como feedback para que possa se ajustar. Alguns eventos não podem ser bloqueados: para `SessionStart`, `Setup`, `Notification` e outros, exit 2 mostra stderr ao usuário e a execução continua. Consulte [comportamento do código de saída 2 por evento](/pt/hooks#exit-code-2-behavior-per-event) para a lista completa.583* **Exit 2**: a ação é bloqueada. Escreva um motivo para stderr, e Claude o recebe como feedback para que possa se ajustar. Alguns eventos não podem ser bloqueados: para `SessionStart`, `Setup`, `Notification` e outros, exit 2 mostra stderr ao usuário e a execução continua. Consulte [comportamento do código de saída 2 por evento](/docs/pt/hooks#exit-code-2-behavior-per-event) para a lista completa.

584* **Qualquer outro código de saída**: a ação prossegue. A transcrição mostra um aviso `<hook name> hook error` seguido pela primeira linha de stderr; o stderr completo vai para o [log de debug](/pt/hooks#debug-hooks).584* **Qualquer outro código de saída**: a ação prossegue. A transcrição mostra um aviso `<hook name> hook error` seguido pela primeira linha de stderr; o stderr completo vai para o [log de debug](/docs/pt/hooks#debug-hooks).

585 585 

586<h4 id="structured-json-output">586<h4 id="structured-json-output">

587 Saída JSON estruturada587 Saída JSON estruturada

607 607 

608Com `"deny"`, Claude Code cancela a chamada de ferramenta e alimenta `permissionDecisionReason` de volta ao Claude. Esses valores `permissionDecision` são específicos para `PreToolUse`:608Com `"deny"`, Claude Code cancela a chamada de ferramenta e alimenta `permissionDecisionReason` de volta ao Claude. Esses valores `permissionDecision` são específicos para `PreToolUse`:

609 609 

610* `"allow"`: pular o prompt de permissão interativo. Regras de negação e pedido, incluindo listas de negação gerenciadas por empresa, ainda se aplicam, assim como prompts para ferramentas de conector [que sua organização definiu como `ask`](/pt/mcp#organization-controls-on-connector-tools) e ferramentas MCP marcadas [`requiresUserInteraction`](/pt/mcp#require-approval-for-a-specific-tool)610* `"allow"`: pular o prompt de permissão interativo. Regras de negação e pedido, incluindo listas de negação gerenciadas por empresa, ainda se aplicam, assim como prompts para ferramentas 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)

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

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

613 613 

614Um quarto valor, `"defer"`, está disponível em [modo não-interativo](/pt/headless) com a flag `-p`. Ele sai do processo com a chamada de ferramenta preservada para que um wrapper do Agent SDK possa coletar entrada e retomar. Consulte [Adiar uma chamada de ferramenta para depois](/pt/hooks#defer-a-tool-call-for-later) na referência.614Um quarto valor, `"defer"`, está disponível em [modo não-interativo](/docs/pt/headless) com a flag `-p`. Ele sai do processo com a chamada de ferramenta preservada para que um wrapper do Agent SDK possa coletar entrada e retomar. Consulte [Adiar uma chamada de ferramenta para depois](/docs/pt/hooks#defer-a-tool-call-for-later) na referência.

615 615 

616Retornar `"allow"` pula o prompt interativo mas não substitui [regras de permissão](/pt/permissions#manage-permissions). Se uma regra de negação corresponder à chamada de ferramenta, a chamada é bloqueada mesmo quando seu hook retorna `"allow"`. Se uma regra de pedido corresponder, o usuário ainda é solicitado, assim como ferramentas de conector [que sua organização definiu como `ask`](/pt/mcp#organization-controls-on-connector-tools) e ferramentas MCP marcadas [`requiresUserInteraction`](/pt/mcp#require-approval-for-a-specific-tool). Isto significa que regras de negação de qualquer escopo de configuração, incluindo [configurações gerenciadas](/pt/settings#settings-files), sempre têm precedência sobre aprovações de hook.616Retornar `"allow"` pula o prompt interativo mas não substitui [regras de permissão](/docs/pt/permissions#manage-permissions). Se uma regra de negação corresponder à chamada de ferramenta, a chamada é bloqueada mesmo quando seu hook retorna `"allow"`. Se uma regra de pedido corresponder, o usuário ainda é solicitado, assim como 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). Isto significa que regras de negação de qualquer escopo de configuração, incluindo [configurações gerenciadas](/docs/pt/settings#settings-files), sempre têm precedência sobre aprovações de hook.

617 617 

618Outros eventos usam padrões de decisão diferentes. Por exemplo, hooks `PostToolUse` e `Stop` usam um campo `decision: "block"` de nível superior, enquanto `PermissionRequest` usa `hookSpecificOutput.decision.behavior`. Consulte a [tabela de resumo](/pt/hooks#decision-control) na referência para uma análise completa por evento.618Outros eventos usam padrões de decisão diferentes. Por exemplo, hooks `PostToolUse` e `Stop` usam um campo `decision: "block"` de nível superior, enquanto `PermissionRequest` usa `hookSpecificOutput.decision.behavior`. Consulte a [tabela de resumo](/docs/pt/hooks#decision-control) na referência para uma análise completa por evento.

619 619 

620Para hooks `UserPromptSubmit`, use `hookSpecificOutput.additionalContext` em vez disso para injetar texto no contexto do Claude. Aninhe `additionalContext` dentro de `hookSpecificOutput`; se você o colocar no nível superior do JSON, Claude Code o ignora silenciosamente. Por exemplo, esta saída adiciona o estado do branch atual a cada prompt:620Para hooks `UserPromptSubmit`, use `hookSpecificOutput.additionalContext` em vez disso para injetar texto no contexto do Claude. Aninhe `additionalContext` dentro de `hookSpecificOutput`; se você o colocar no nível superior do JSON, Claude Code o ignora silenciosamente. Por exemplo, esta saída adiciona o estado do branch atual a cada prompt:

621 621 

628}628}

629```629```

630 630 

631Consulte [Controle de decisão UserPromptSubmit](/pt/hooks#userpromptsubmit-decision-control) para a forma de saída completa, incluindo bloqueio de prompts e definição do título da sessão.631Consulte [Controle de decisão UserPromptSubmit](/docs/pt/hooks#userpromptsubmit-decision-control) para a forma de saída completa, incluindo bloqueio de prompts e definição do título da sessão.

632 632 

633Hooks com `type: "prompt"` lidam com saída de forma diferente: consulte [Prompt-based hooks](#prompt-based-hooks).633Hooks com `type: "prompt"` lidam com saída de forma diferente: consulte [Prompt-based hooks](#prompt-based-hooks).

634 634 

653}653}

654```654```

655 655 

656O matcher `"Edit|Write"` dispara apenas quando Claude usa a ferramenta `Edit` ou `Write`, não quando usa `Bash`, `Read` ou qualquer outra ferramenta. {/* min-version: 2.1.191 */}No Claude Code v2.1.191 ou posterior, uma vírgula separa alternativas da mesma forma, então `"Edit, Write"` é equivalente. Consulte [Padrões de matcher](/pt/hooks#matcher-patterns) para como nomes simples e expressões regulares são avaliados.656O matcher `"Edit|Write"` dispara apenas quando Claude usa a ferramenta `Edit` ou `Write`, não quando usa `Bash`, `Read` ou qualquer outra ferramenta. {/* min-version: 2.1.191 */}No Claude Code v2.1.191 ou posterior, uma vírgula separa alternativas da mesma forma, então `"Edit, Write"` é equivalente. Consulte [Padrões de matcher](/docs/pt/hooks#matcher-patterns) para como nomes simples e expressões regulares são avaliados.

657 657 

658<Note>658<Note>

659 Claude também pode criar ou modificar arquivos executando comandos shell através da ferramenta `Bash`. Se seu hook deve ver cada mudança de arquivo, como para varredura de conformidade ou registro de auditoria, adicione um hook [`Stop`](/pt/hooks#stop) que varre a árvore de trabalho uma vez por turno. Para cobertura por chamada em vez disso, também corresponda `Bash` e tenha seu script listar arquivos modificados e não rastreados com `git status --porcelain`.659 Claude também pode criar ou modificar arquivos executando comandos shell através da ferramenta `Bash`. Se seu hook deve ver cada mudança de arquivo, como para varredura de conformidade ou registro de auditoria, adicione um hook [`Stop`](/docs/pt/hooks#stop) que varre a árvore de trabalho uma vez por turno. Para cobertura por chamada em vez disso, também corresponda `Bash` e tenha seu script listar arquivos modificados e não rastreados com `git status --porcelain`.

660</Note>660</Note>

661 661 

662Cada tipo de evento corresponde a um campo específico:662Cada tipo de evento corresponde a um campo específico:

676| `InstructionsLoaded` | motivo de carregamento | `session_start`, `nested_traversal`, `path_glob_match`, `include`, `compact` |676| `InstructionsLoaded` | motivo de carregamento | `session_start`, `nested_traversal`, `path_glob_match`, `include`, `compact` |

677| `Elicitation` | nome do servidor MCP | seus nomes de servidor MCP configurados |677| `Elicitation` | nome do servidor MCP | seus nomes de servidor MCP configurados |

678| `ElicitationResult` | nome do servidor MCP | mesmos valores que `Elicitation` |678| `ElicitationResult` | nome do servidor MCP | mesmos valores que `Elicitation` |

679| `FileChanged` | nomes de arquivo literais para observar (consulte [FileChanged](/pt/hooks#filechanged)) | `.envrc\|.env` |679| `FileChanged` | nomes de arquivo literais para observar (consulte [FileChanged](/docs/pt/hooks#filechanged)) | `.envrc\|.env` |

680| `UserPromptExpansion` | nome do comando | seus nomes de skill ou comando |680| `UserPromptExpansion` | nome do comando | seus nomes de skill ou comando |

681| `UserPromptSubmit`, `PostToolBatch`, `Stop`, `TeammateIdle`, `TaskCreated`, `TaskCompleted`, `WorktreeCreate`, `WorktreeRemove`, `CwdChanged`, `MessageDisplay` | sem suporte a matcher | sempre dispara em cada ocorrência |681| `UserPromptSubmit`, `PostToolBatch`, `Stop`, `TeammateIdle`, `TaskCreated`, `TaskCompleted`, `WorktreeCreate`, `WorktreeRemove`, `CwdChanged`, `MessageDisplay` | sem suporte a matcher | sempre dispara em cada ocorrência |

682 682 

706 </Tab>706 </Tab>

707 707 

708 <Tab title="Corresponder ferramentas MCP">708 <Tab title="Corresponder ferramentas MCP">

709 Ferramentas MCP usam uma convenção de nomenclatura diferente das ferramentas integradas: `mcp__<server>__<tool>`, onde `<server>` é o nome do servidor MCP e `<tool>` é a ferramenta que fornece. Por exemplo, `mcp__github__search_repositories` ou `mcp__filesystem__read_file`. Ferramentas de um [servidor MCP fornecido por plugin](/pt/mcp#plugin-provided-mcp-servers) usam um segmento de servidor com escopo em vez disso, como `mcp__plugin_my-plugin_db__query`. Use um matcher regex para direcionar todas as ferramentas de um servidor específico, ou corresponder entre servidores com um padrão como `mcp__.*__write.*`. Consulte [Corresponder ferramentas MCP](/pt/hooks#match-mcp-tools) na referência para a lista completa de exemplos.709 Ferramentas MCP usam uma convenção de nomenclatura diferente das ferramentas integradas: `mcp__<server>__<tool>`, onde `<server>` é o nome do servidor MCP e `<tool>` é a ferramenta que fornece. Por exemplo, `mcp__github__search_repositories` ou `mcp__filesystem__read_file`. Ferramentas de um [servidor MCP fornecido por plugin](/docs/pt/mcp#plugin-provided-mcp-servers) usam um segmento de servidor com escopo em vez disso, como `mcp__plugin_my-plugin_db__query`. Use um matcher regex para direcionar todas as ferramentas de um servidor específico, ou corresponder entre servidores com um padrão como `mcp__.*__write.*`. Consulte [Corresponder ferramentas MCP](/docs/pt/hooks#match-mcp-tools) na referência para a lista completa de exemplos.

710 710 

711 O comando abaixo extrai o nome da ferramenta da entrada JSON do hook com `jq` e o escreve para stderr. Escrever para stderr mantém stdout limpo para saída JSON e envia a mensagem para o [log de debug](/pt/hooks#debug-hooks):711 O comando abaixo extrai o nome da ferramenta da entrada JSON do hook com `jq` e o escreve para stderr. Escrever para stderr mantém stdout limpo para saída JSON e envia a mensagem para o [log de debug](/docs/pt/hooks#debug-hooks):

712 712 

713 ```json theme={null}713 ```json theme={null}

714 {714 {

752 </Tab>752 </Tab>

753</Tabs>753</Tabs>

754 754 

755Para sintaxe completa de matcher, consulte a [referência de Hooks](/pt/hooks#configuration).755Para sintaxe completa de matcher, consulte a [referência de Hooks](/docs/pt/hooks#configuration).

756 756 

757<h4 id="filter-by-tool-name-and-arguments-with-the-if-field">757<h4 id="filter-by-tool-name-and-arguments-with-the-if-field">

758 Filtrar por nome de ferramenta e argumentos com o campo `if`758 Filtrar por nome de ferramenta e argumentos com o campo `if`

759</h4>759</h4>

760 760 

761O campo `if` usa [sintaxe de regra de permissão](/pt/permissions) para filtrar hooks por nome de ferramenta e argumentos juntos, para que o processo do hook apenas seja gerado quando a chamada de ferramenta corresponder. Isto vai além de `matcher`, que filtra no nível do grupo apenas por nome de ferramenta.761O campo `if` usa [sintaxe de regra de permissão](/docs/pt/permissions) para filtrar hooks por nome de ferramenta e argumentos juntos, para que o processo do hook apenas seja gerado quando a chamada de ferramenta corresponder. Isto vai além de `matcher`, que filtra no nível do grupo apenas por nome de ferramenta.

762 762 

763Por exemplo, esta configuração executa um hook apenas quando Claude usa comandos `git` em vez de todos os comandos Bash:763Por exemplo, esta configuração executa um hook apenas quando Claude usa comandos `git` em vez de todos os comandos Bash:

764 764 

791| `Bash(git *)` | `echo $(date)` | não | nenhum subcomando corresponde a `git *` |791| `Bash(git *)` | `echo $(date)` | não | nenhum subcomando corresponde a `git *` |

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

793 793 

794O filtro também falha aberto, executando seu hook independentemente do padrão, quando o comando Bash não pode ser analisado. Como o filtro é melhor esforço, use o [sistema de permissão](/pt/permissions) em vez de um hook para impor um allow ou deny difícil.794O filtro também falha aberto, executando seu hook independentemente do padrão, quando o comando Bash não pode ser analisado. Como o filtro é melhor esforço, use o [sistema de permissão](/docs/pt/permissions) em vez de um hook para impor um allow ou deny difícil.

795 795 

796O campo `if` aceita os mesmos padrões que regras de permissão: `"Bash(git *)"`, `"Edit(*.ts)"`, e assim por diante. Para corresponder múltiplos nomes de ferramenta, use manipuladores separados cada um com seu próprio valor `if`, ou corresponda no nível `matcher` onde alternação de pipe é suportada.796O campo `if` aceita os mesmos padrões que regras de permissão: `"Bash(git *)"`, `"Edit(*.ts)"`, e assim por diante. Para corresponder múltiplos nomes de ferramenta, use manipuladores separados cada um com seu próprio valor `if`, ou corresponda no nível `matcher` onde alternação de pipe é suportada.

797 797 

809| `.claude/settings.json` | Projeto único | Sim, pode ser commitado no repo |809| `.claude/settings.json` | Projeto único | Sim, pode ser commitado no repo |

810| `.claude/settings.local.json` | Projeto único | Não, gitignored quando Claude Code o cria |810| `.claude/settings.local.json` | Projeto único | Não, gitignored quando Claude Code o cria |

811| Configurações de política gerenciada | Organização inteira | Sim, controlado por admin |811| Configurações de política gerenciada | Organização inteira | Sim, controlado por admin |

812| [Plugin](/pt/plugins) `hooks/hooks.json` | Quando o plugin está habilitado | Sim, empacotado com o plugin |812| [Plugin](/docs/pt/plugins) `hooks/hooks.json` | Quando o plugin está habilitado | Sim, empacotado com o plugin |

813| [Skill](/pt/skills) ou [agente](/pt/sub-agents) frontmatter | Enquanto a skill ou agente está ativo | Sim, definido no arquivo do componente |813| [Skill](/docs/pt/skills) ou [agente](/docs/pt/sub-agents) frontmatter | Enquanto a skill ou agente está ativo | Sim, definido no arquivo do componente |

814 814 

815Execute [`/hooks`](/pt/hooks#the-%2Fhooks-menu) no Claude Code para navegar por todos os hooks configurados agrupados por evento.815Execute [`/hooks`](/docs/pt/hooks#the-%2Fhooks-menu) no Claude Code para navegar por todos os hooks configurados agrupados por evento.

816 816 

817Para desabilitar hooks, defina `"disableAllHooks": true` no seu arquivo de configuração. Hooks configurados em configurações gerenciadas ainda executam a menos que `disableAllHooks` também esteja definido lá.817Para desabilitar hooks, defina `"disableAllHooks": true` no seu arquivo de configuração. Hooks configurados em configurações gerenciadas ainda executam a menos que `disableAllHooks` também esteja definido lá.

818 818 

851}851}

852```852```

853 853 

854Para opções de configuração completas, consulte [Hooks baseados em prompt](/pt/hooks#prompt-based-hooks) na referência.854Para opções de configuração completas, consulte [Hooks baseados em prompt](/docs/pt/hooks#prompt-based-hooks) na referência.

855 855 

856<h2 id="agent-based-hooks">856<h2 id="agent-based-hooks">

857 Hooks baseados em agente857 Hooks baseados em agente

858</h2>858</h2>

859 859 

860<Warning>860<Warning>

861 Hooks de agente são experimentais. Comportamento e configuração podem mudar em futuras versões. Para fluxos de trabalho de produção, prefira [hooks de comando](/pt/hooks#command-hook-fields).861 Hooks de agente são experimentais. Comportamento e configuração podem mudar em futuras versões. Para fluxos de trabalho de produção, prefira [hooks de comando](/docs/pt/hooks#command-hook-fields).

862</Warning>862</Warning>

863 863 

864Quando a verificação exige inspecionar arquivos ou executar comandos, use hooks `type: "agent"`. Diferentemente de hooks de prompt que fazem uma única chamada LLM, hooks de agente geram um subagente que pode ler arquivos, pesquisar código e usar outras ferramentas para verificar condições antes de retornar uma decisão.864Quando a verificação exige inspecionar arquivos ou executar comandos, use hooks `type: "agent"`. Diferentemente de hooks de prompt que fazem uma única chamada LLM, hooks de agente geram um subagente que pode ler arquivos, pesquisar código e usar outras ferramentas para verificar condições antes de retornar uma decisão.

887 887 

888Use hooks de prompt quando os dados de entrada do hook sozinhos são suficientes para tomar uma decisão. Use hooks de agente quando você precisa verificar algo contra o estado real da base de código.888Use hooks de prompt quando os dados de entrada do hook sozinhos são suficientes para tomar uma decisão. Use hooks de agente quando você precisa verificar algo contra o estado real da base de código.

889 889 

890Para opções de configuração completas, consulte [Hooks baseados em agente](/pt/hooks#agent-based-hooks) na referência.890Para opções de configuração completas, consulte [Hooks baseados em agente](/docs/pt/hooks#agent-based-hooks) na referência.

891 891 

892<h2 id="http-hooks">892<h2 id="http-hooks">

893 HTTP hooks893 HTTP hooks

920}920}

921```921```

922 922 

923O endpoint deve retornar um corpo de resposta JSON usando o mesmo [formato de saída](/pt/hooks#json-output) que hooks de comando. Para bloquear uma chamada de ferramenta, retorne uma resposta 2xx com os campos `hookSpecificOutput` apropriados. Códigos de status HTTP sozinhos não podem bloquear ações.923O endpoint deve retornar um corpo de resposta JSON usando o mesmo [formato de saída](/docs/pt/hooks#json-output) que hooks de comando. Para bloquear uma chamada de ferramenta, retorne uma resposta 2xx com os campos `hookSpecificOutput` apropriados. Códigos de status HTTP sozinhos não podem bloquear ações.

924 924 

925Valores de header suportam interpolação de variável de ambiente usando sintaxe `$VAR_NAME` ou `${VAR_NAME}`. Apenas variáveis listadas no array `allowedEnvVars` são resolvidas; todas as outras referências `$VAR` permanecem vazias.925Valores de header suportam interpolação de variável de ambiente usando sintaxe `$VAR_NAME` ou `${VAR_NAME}`. Apenas variáveis listadas no array `allowedEnvVars` são resolvidas; todas as outras referências `$VAR` permanecem vazias.

926 926 

927Para opções de configuração completas e manipulação de resposta, consulte [HTTP hooks](/pt/hooks#http-hook-fields) na referência.927Para opções de configuração completas e manipulação de resposta, consulte [HTTP hooks](/docs/pt/hooks#http-hook-fields) na referência.

928 928 

929<h2 id="limitations-and-troubleshooting">929<h2 id="limitations-and-troubleshooting">

930 Limitações e solução de problemas930 Limitações e solução de problemas

942 * `prompt`: 30 segundos.942 * `prompt`: 30 segundos.

943 * `agent`: 60 segundos.943 * `agent`: 60 segundos.

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

945* Hooks `PermissionRequest` não disparam em [modo não-interativo](/pt/headless) com a flag `-p`. Use hooks `PreToolUse` para decisões de permissão automatizadas.945* Hooks `PermissionRequest` não disparam em [modo não-interativo](/docs/pt/headless) com a flag `-p`. Use hooks `PreToolUse` para decisões de permissão automatizadas.

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

947* Quando múltiplos hooks `PreToolUse` retornam [`updatedInput`](/pt/hooks#pretooluse) para reescrever argumentos de uma ferramenta, o último a terminar vence. Como hooks executam em paralelo, a ordem é não-determinística. Evite ter mais de um hook modificando a entrada da mesma ferramenta.947* Quando múltiplos hooks `PreToolUse` retornam [`updatedInput`](/docs/pt/hooks#pretooluse) para reescrever argumentos de uma ferramenta, o último a terminar vence. Como hooks executam em paralelo, a ordem é não-determinística. Evite ter mais de um hook modificando a entrada da mesma ferramenta.

948 948 

949<h3 id="hooks-and-permission-modes">949<h3 id="hooks-and-permission-modes">

950 Hooks e modos de permissão950 Hooks e modos de permissão

952 952 

953Hooks `PreToolUse` disparam antes de qualquer verificação de modo de permissão. 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.953Hooks `PreToolUse` disparam antes de qualquer verificação de modo de permissão. 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.

954 954 

955O 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 de conector [que sua organização definiu como `ask`](/pt/mcp#organization-controls-on-connector-tools) ou ferramentas MCP marcadas [`requiresUserInteraction`](/pt/mcp#require-approval-for-a-specific-tool). Hooks podem apertar restrições mas não afrouxá-las além do que regras de permissão permitem.955O 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 de conector [que sua organização definiu como `ask`](/docs/pt/mcp#organization-controls-on-connector-tools) ou ferramentas MCP marcadas [`requiresUserInteraction`](/docs/pt/mcp#require-approval-for-a-specific-tool). Hooks podem apertar restrições mas não afrouxá-las além do que regras de permissão permitem.

956 956 

957<h3 id="hook-not-firing">957<h3 id="hook-not-firing">

958 Hook não dispara958 Hook não dispara

976 echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | ./my-hook.sh976 echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | ./my-hook.sh

977 echo $? # Verifique o código de saída977 echo $? # Verifique o código de saída

978 ```978 ```

979* Se você vir "command not found", use caminhos absolutos ou `${CLAUDE_PROJECT_DIR}` para referenciar scripts. Para evitar quoting de shell completamente, adicione `"args": []` para mudar para [forma exec](/pt/hooks#exec-form-and-shell-form), que gera o script diretamente sem um shell979* Se você vir "command not found", use caminhos absolutos ou `${CLAUDE_PROJECT_DIR}` para referenciar scripts. Para evitar quoting de shell completamente, adicione `"args": []` para mudar para [forma exec](/docs/pt/hooks#exec-form-and-shell-form), que gera o script diretamente sem um shell

980* Se você vir "jq: command not found", instale `jq` ou use Python/Node.js para análise JSON980* Se você vir "jq: command not found", instale `jq` ou use Python/Node.js para análise JSON

981* Se o script não está executando em tudo, torne-o executável: `chmod +x ./my-hook.sh`981* Se o script não está executando em tudo, torne-o executável: `chmod +x ./my-hook.sh`

982 982 

1007# ... resto da lógica do seu hook1007# ... resto da lógica do seu hook

1008```1008```

1009 1009 

1010Se seu hook legitimamente precisa de mais de oito iterações para convergir, aumente o limite com [`CLAUDE_CODE_STOP_HOOK_BLOCK_CAP`](/pt/env-vars).1010Se seu hook legitimamente precisa de mais de oito iterações para convergir, aumente o limite com [`CLAUDE_CODE_STOP_HOOK_BLOCK_CAP`](/docs/pt/env-vars).

1011 1011 

1012<h3 id="json-validation-failed">1012<h3 id="json-validation-failed">

1013 Validação JSON falhou1013 Validação JSON falhou

1045 Saiba mais1045 Saiba mais

1046</h2>1046</h2>

1047 1047 

1048* [Referência de Hooks](/pt/hooks): esquemas de eventos completos, formato de saída JSON, hooks assíncronos e hooks de ferramentas MCP1048* [Referência de Hooks](/docs/pt/hooks): esquemas de eventos completos, formato de saída JSON, hooks assíncronos e hooks de ferramentas MCP

1049* [Considerações de segurança](/pt/hooks#security-considerations): revise antes de implantar hooks em ambientes compartilhados ou de produção1049* [Considerações de segurança](/docs/pt/hooks#security-considerations): revise antes de implantar hooks em ambientes compartilhados ou de produção

1050* [Exemplo de validador de comando Bash](https://github.com/anthropics/claude-code/blob/main/examples/hooks/bash_command_validator_example.py): implementação de referência completa1050* [Exemplo de validador de comando Bash](https://github.com/anthropics/claude-code/blob/main/examples/hooks/bash_command_validator_example.py): implementação de referência completa

7> Referência técnica completa para o sistema de plugins do Claude Code, incluindo esquemas, comandos CLI e especificações de componentes.7> Referência técnica completa para o sistema de plugins do Claude Code, incluindo esquemas, comandos CLI e especificações de componentes.

8 8 

9<Tip>9<Tip>

10 Procurando instalar plugins? Veja [Descobrir e instalar plugins](/pt/discover-plugins). Para criar plugins, veja [Plugins](/pt/plugins). Para distribuir plugins, veja [Marketplaces de plugins](/pt/plugin-marketplaces).10 Procurando instalar plugins? Veja [Descobrir e instalar plugins](/docs/pt/discover-plugins). Para criar plugins, veja [Plugins](/docs/pt/plugins). Para distribuir plugins, veja [Marketplaces de plugins](/docs/pt/plugin-marketplaces).

11</Tip>11</Tip>

12 12 

13Esta referência fornece especificações técnicas completas para o sistema de plugins do Claude Code, incluindo esquemas de componentes, comandos CLI e ferramentas de desenvolvimento.13Esta referência fornece especificações técnicas completas para o sistema de plugins do Claude Code, incluindo esquemas de componentes, comandos CLI e ferramentas de desenvolvimento.

48 48 

49Se um plugin não tem diretório `skills/` e nenhum campo manifest `skills`, um `SKILL.md` na raiz do plugin é carregado como uma única skill. Defina o campo frontmatter `name` para controlar o nome de invocação da skill. Sem ele, Claude Code volta para o nome do diretório de instalação, que para plugins instalados do marketplace é uma string de versão que muda a cada atualização. Para plugins que fornecem mais de uma skill, use o layout de diretório `skills/` mostrado acima.49Se um plugin não tem diretório `skills/` e nenhum campo manifest `skills`, um `SKILL.md` na raiz do plugin é carregado como uma única skill. Defina o campo frontmatter `name` para controlar o nome de invocação da skill. Sem ele, Claude Code volta para o nome do diretório de instalação, que para plugins instalados do marketplace é uma string de versão que muda a cada atualização. Para plugins que fornecem mais de uma skill, use o layout de diretório `skills/` mostrado acima.

50 50 

51Para detalhes completos, veja [Skills](/pt/skills).51Para detalhes completos, veja [Skills](/docs/pt/skills).

52 52 

53<h3 id="agents">53<h3 id="agents">

54 Agents54 Agents

79 79 

80**Pontos de integração**:80**Pontos de integração**:

81 81 

82* Agents aparecem na typeahead [@-mention](/pt/sub-agents#invoke-subagents-explicitly) sob seu nome com escopo, como `my-plugin:code-reviewer`, uma vez que o plugin está habilitado82* Agents aparecem na typeahead [@-mention](/docs/pt/sub-agents#invoke-subagents-explicitly) sob seu nome com escopo, como `my-plugin:code-reviewer`, uma vez que o plugin está habilitado

83* Claude pode invocar agents automaticamente com base no contexto da tarefa83* Claude pode invocar agents automaticamente com base no contexto da tarefa

84* Agents podem ser invocados manualmente por usuários84* Agents podem ser invocados manualmente por usuários

85* Agents de plugin funcionam ao lado de agents Claude integrados85* Agents de plugin funcionam ao lado de agents Claude integrados

86 86 

87Para detalhes completos, veja [Subagents](/pt/sub-agents).87Para detalhes completos, veja [Subagents](/docs/pt/sub-agents).

88 88 

89<h3 id="hooks">89<h3 id="hooks">

90 Hooks90 Hooks

116}116}

117```117```

118 118 

119Os hooks de plugin respondem aos mesmos eventos de ciclo de vida que [hooks definidos pelo usuário](/pt/hooks):119Os hooks de plugin respondem aos mesmos eventos de ciclo de vida que [hooks definidos pelo usuário](/docs/pt/hooks):

120 120 

121| Event | When it fires |121| Event | When it fires |

122| :-------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- |122| :-------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- |

138| `TaskCompleted` | When a task is being marked as completed |138| `TaskCompleted` | When a task is being marked as completed |

139| `Stop` | When Claude finishes responding |139| `Stop` | When Claude finishes responding |

140| `StopFailure` | When the turn ends due to an API error. Output and exit code are ignored |140| `StopFailure` | When the turn ends due to an API error. Output and exit code are ignored |

141| `TeammateIdle` | When an [agent team](/en/agent-teams) teammate is about to go idle |141| `TeammateIdle` | When an [agent team](/docs/en/agent-teams) teammate is about to go idle |

142| `InstructionsLoaded` | When a CLAUDE.md or `.claude/rules/*.md` file is loaded into context. Fires at session start and when files are lazily loaded during a session |142| `InstructionsLoaded` | When a CLAUDE.md or `.claude/rules/*.md` file is loaded into context. Fires at session start and when files are lazily loaded during a session |

143| `ConfigChange` | When a configuration file changes during a session |143| `ConfigChange` | When a configuration file changes during a session |

144| `CwdChanged` | When the working directory changes, for example when Claude executes a `cd` command. Useful for reactive environment management with tools like direnv |144| `CwdChanged` | When the working directory changes, for example when Claude executes a `cd` command. Useful for reactive environment management with tools like direnv |

145| `FileChanged` | When a watched file changes on disk. The `matcher` field specifies which filenames to watch |145| `FileChanged` | When a watched file changes on disk. The `matcher` field specifies which filenames to watch |

146| `WorktreeCreate` | When a worktree is being created via `--worktree` or `isolation: "worktree"`. Replaces default git behavior |146| `WorktreeCreate` | When a worktree is being created via `--worktree`, `isolation: "worktree"`, or for a background session. Replaces default git behavior |

147| `WorktreeRemove` | When a worktree is being removed, either at session exit or when a subagent finishes |147| `WorktreeRemove` | When a worktree is being removed at session exit, when a subagent finishes, or when you delete a background session |

148| `PreCompact` | Before context compaction |148| `PreCompact` | Before context compaction |

149| `PostCompact` | After context compaction completes |149| `PostCompact` | After context compaction completes |

150| `Elicitation` | When an MCP server requests user input during a tool call |150| `Elicitation` | When an MCP server requests user input during a tool call |

155 155 

156* `command`: executar comandos shell ou scripts156* `command`: executar comandos shell ou scripts

157* `http`: enviar o JSON do evento como uma solicitação POST para uma URL157* `http`: enviar o JSON do evento como uma solicitação POST para uma URL

158* `mcp_tool`: chamar uma ferramenta em um servidor [MCP](/pt/mcp) configurado158* `mcp_tool`: chamar uma ferramenta em um servidor [MCP](/docs/pt/mcp) configurado

159* `prompt`: avaliar um prompt com um LLM (usa placeholder `$ARGUMENTS` para contexto)159* `prompt`: avaliar um prompt com um LLM (usa placeholder `$ARGUMENTS` para contexto)

160* `agent`: executar um verificador agentic com ferramentas para tarefas de verificação complexas160* `agent`: executar um verificador agentic com ferramentas para tarefas de verificação complexas

161 161 

162Os hooks que visam o próprio servidor [MCP agrupado](#mcp-servers) do plugin devem usar seus nomes com escopo. Os matchers de ferramenta e campos `if` usam o nome de ferramenta com escopo `mcp__plugin_<plugin-name>_<server-name>__<tool>`, e o campo `server` de um hook `mcp_tool` usa `plugin:<plugin-name>:<server-name>`. Um matcher escrito contra a chave de servidor simples nunca dispara. Veja [Match MCP tools](/pt/hooks#match-mcp-tools) e [Plugin-provided MCP servers](/pt/mcp#plugin-provided-mcp-servers).162Os hooks que visam o próprio servidor [MCP agrupado](#mcp-servers) do plugin devem usar seus nomes com escopo. Os matchers de ferramenta e campos `if` usam o nome de ferramenta com escopo `mcp__plugin_<plugin-name>_<server-name>__<tool>`, e o campo `server` de um hook `mcp_tool` usa `plugin:<plugin-name>:<server-name>`. Um matcher escrito contra a chave de servidor simples nunca dispara. Veja [Match MCP tools](/docs/pt/hooks#match-mcp-tools) e [Plugin-provided MCP servers](/docs/pt/mcp#plugin-provided-mcp-servers).

163 163 

164<h3 id="mcp-servers">164<h3 id="mcp-servers">

165 MCP servers165 MCP servers

300 300 

301Os plugins podem declarar monitors de fundo que Claude Code inicia automaticamente quando o plugin está ativo. Cada monitor executa um comando shell pela duração da sessão e entrega cada linha stdout a Claude como uma notificação, para que Claude possa reagir a entradas de log, mudanças de status ou eventos pesquisados sem ser solicitado a iniciar o watch em si.301Os plugins podem declarar monitors de fundo que Claude Code inicia automaticamente quando o plugin está ativo. Cada monitor executa um comando shell pela duração da sessão e entrega cada linha stdout a Claude como uma notificação, para que Claude possa reagir a entradas de log, mudanças de status ou eventos pesquisados sem ser solicitado a iniciar o watch em si.

302 302 

303Os monitors de plugin usam o mesmo mecanismo que a [ferramenta Monitor](/pt/tools-reference#monitor-tool) e compartilham suas restrições de disponibilidade. Eles são executados apenas em sessões CLI interativas, executados sem sandbox no mesmo nível de confiança que [hooks](#hooks), e são ignorados em hosts onde a ferramenta Monitor não está disponível.303Os monitors de plugin usam o mesmo mecanismo que a [ferramenta Monitor](/docs/pt/tools-reference#monitor-tool) e compartilham suas restrições de disponibilidade. Eles são executados apenas em sessões CLI interativas, executados sem sandbox no mesmo nível de confiança que [hooks](#hooks), e são ignorados em hosts onde a ferramenta Monitor não está disponível.

304 304 

305**Localização**: `monitors/monitors.json` na raiz do plugin, ou inline em `plugin.json`305**Localização**: `monitors/monitors.json` na raiz do plugin, ou inline em `plugin.json`

306 306 

342 342 

343O valor `command` suporta as [substituições de caminho](#environment-variables) `${CLAUDE_PLUGIN_ROOT}`, `${CLAUDE_PLUGIN_DATA}` e `${CLAUDE_PROJECT_DIR}`, mais qualquer `${ENV_VAR}` do ambiente. Prefixe o comando com `cd "${CLAUDE_PLUGIN_ROOT}" && ` se o script precisa ser executado do próprio diretório do plugin.343O valor `command` suporta as [substituições de caminho](#environment-variables) `${CLAUDE_PLUGIN_ROOT}`, `${CLAUDE_PLUGIN_DATA}` e `${CLAUDE_PROJECT_DIR}`, mais qualquer `${ENV_VAR}` do ambiente. Prefixe o comando com `cd "${CLAUDE_PLUGIN_ROOT}" && ` se o script precisa ser executado do próprio diretório do plugin.

344 344 

345Um comando `command` de monitor não pode referenciar valores [`${user_config.*}`](#user-configuration). O comando é executado através de um shell, então Claude Code rejeita o monitor com um [erro](/pt/errors#plugin-command-references-user-config) em vez de substituir o valor. Processos de monitor não recebem variáveis de ambiente `CLAUDE_PLUGIN_OPTION_<KEY>`, então faça o script de monitor ler o valor de um arquivo de configuração que ele possui. Antes de v2.1.207, comandos de monitor substituíam valores `${user_config.*}`.345Um comando `command` de monitor não pode referenciar valores [`${user_config.*}`](#user-configuration). O comando é executado através de um shell, então Claude Code rejeita o monitor com um [erro](/docs/pt/errors#plugin-command-references-user-config) em vez de substituir o valor. Processos de monitor não recebem variáveis de ambiente `CLAUDE_PLUGIN_OPTION_<KEY>`, então faça o script de monitor ler o valor de um arquivo de configuração que ele possui. Antes de v2.1.207, comandos de monitor substituíam valores `${user_config.*}`.

346 346 

347Desabilitar um plugin no meio da sessão não para monitors que já estão em execução. Eles param quando a sessão termina.347Desabilitar um plugin no meio da sessão não para monitors que já estão em execução. Eles param quando a sessão termina.

348 348 

379| `user` | `~/.claude/settings.json` | Plugins pessoais disponíveis em todos os projetos (padrão) |379| `user` | `~/.claude/settings.json` | Plugins pessoais disponíveis em todos os projetos (padrão) |

380| `project` | `.claude/settings.json` | Plugins de equipe compartilhados via controle de versão |380| `project` | `.claude/settings.json` | Plugins de equipe compartilhados via controle de versão |

381| `local` | `.claude/settings.local.json` | Plugins específicos do projeto, gitignored |381| `local` | `.claude/settings.local.json` | Plugins específicos do projeto, gitignored |

382| `managed` | [Configurações gerenciadas](/pt/settings#settings-files) | Plugins gerenciados (somente leitura, apenas atualizar) |382| `managed` | [Configurações gerenciadas](/docs/pt/settings#settings-files) | Plugins gerenciados (somente leitura, apenas atualizar) |

383 383 

384Os plugins usam o mesmo sistema de escopo que outras configurações do Claude Code. Para instruções de instalação e flags de escopo, veja [Instalar plugins](/pt/discover-plugins#install-plugins). Para uma explicação completa de escopos, veja [Escopos de configuração](/pt/settings#configuration-scopes).384Os plugins usam o mesmo sistema de escopo que outras configurações do Claude Code. Para instruções de instalação e flags de escopo, veja [Instalar plugins](/docs/pt/discover-plugins#install-plugins). Para uma explicação completa de escopos, veja [Escopos de configuração](/docs/pt/settings#configuration-scopes).

385 385 

386***386***

387 387 

395 395 

396| O que você tem | O que é |396| O que você tem | O que é |

397| :-------------------------------------------- | :-------------------------------------------------------------------------------------- |397| :-------------------------------------------- | :-------------------------------------------------------------------------------------- |

398| `<skills-dir>/foo/SKILL.md` sem manifesto | Uma [skill](/pt/skills) simples nomeada `foo` |398| `<skills-dir>/foo/SKILL.md` sem manifesto | Uma [skill](/docs/pt/skills) simples nomeada `foo` |

399| `<skills-dir>/foo/.claude-plugin/plugin.json` | Um plugin `foo@skills-dir`, que pode agrupar suas próprias skills, agents, hooks e mais |399| `<skills-dir>/foo/.claude-plugin/plugin.json` | Um plugin `foo@skills-dir`, que pode agrupar suas próprias skills, agents, hooks e mais |

400| `<plugin>/skills/bar/SKILL.md` | Uma skill `bar` empacotada dentro de um plugin |400| `<plugin>/skills/bar/SKILL.md` | Uma skill `bar` empacotada dentro de um plugin |

401 401 

406| Diretório de skills | Escopo | Carrega |406| Diretório de skills | Escopo | Carrega |

407| :---------------------- | :------ | :------------------------------------------------------------------------------------------------ |407| :---------------------- | :------ | :------------------------------------------------------------------------------------------------ |

408| `~/.claude/skills/` | pessoal | Em cada projeto, já que a localização é apenas sua |408| `~/.claude/skills/` | pessoal | Em cada projeto, já que a localização é apenas sua |

409| `<cwd>/.claude/skills/` | projeto | Apenas depois que você aceita o [diálogo de confiança](/pt/settings) do workspace para essa pasta |409| `<cwd>/.claude/skills/` | projeto | Apenas depois que você aceita o [diálogo de confiança](/docs/pt/settings) do workspace para essa pasta |

410 410 

411Um plugin de escopo de projeto é verificado no repositório e alcança cada colaborador que o clona. Como esse conteúdo vem do repositório em vez de você, ele carrega apenas após o mesmo portão de confiança que governa `.claude/settings.json`, e componentes que executam código são ainda mais restritos:411Um plugin de escopo de projeto é verificado no repositório e alcança cada colaborador que o clona. Como esse conteúdo vem do repositório em vez de você, ele carrega apenas após o mesmo portão de confiança que governa `.claude/settings.json`, e componentes que executam código são ainda mais restritos:

412 412 

413* Servidores MCP que declara passam pela [mesma aprovação por servidor](/pt/mcp) que um `.mcp.json` de projeto413* Servidores MCP que declara passam pela [mesma aprovação por servidor](/docs/pt/mcp) que um `.mcp.json` de projeto

414* Servidores LSP iniciam apenas depois que você confia no workspace414* Servidores LSP iniciam apenas depois que você confia no workspace

415* [Monitors de fundo](#monitors) não carregam415* [Monitors de fundo](#monitors) não carregam

416 416 

417Plugins de escopo pessoal não têm nenhuma dessas restrições.417Plugins de escopo pessoal não têm nenhuma dessas restrições.

418 418 

419<Warning>419<Warning>

420 Plugins `@skills-dir` de escopo de projeto carregam apenas de `.claude/skills/` do diretório onde você inicia Claude Code. Eles não [caminham até a raiz do repositório](/pt/skills#automatic-discovery-from-parent-and-nested-directories) da maneira que skills e comandos simples fazem, então iniciar de um subdiretório perde um plugin que vive na raiz do repo. Inicie da raiz do repositório, ou execute `/reload-plugins` após mudar de diretório.420 Plugins `@skills-dir` de escopo de projeto carregam apenas de `.claude/skills/` do diretório onde você inicia Claude Code. Eles não [caminham até a raiz do repositório](/docs/pt/skills#automatic-discovery-from-parent-and-nested-directories) da maneira que skills e comandos simples fazem, então iniciar de um subdiretório perde um plugin que vive na raiz do repo. Inicie da raiz do repositório, ou execute `/reload-plugins` após mudar de diretório.

421</Warning>421</Warning>

422 422 

423<h3 id="edit-reload-and-disable-a-skills-directory-plugin">423<h3 id="edit-reload-and-disable-a-skills-directory-plugin">

424 Editar, recarregar e desabilitar um plugin de diretório de skills424 Editar, recarregar e desabilitar um plugin de diretório de skills

425</h3>425</h3>

426 426 

427As alterações que você faz no `SKILL.md` de uma skill têm efeito imediatamente na sessão atual. Alterações em outros componentes do plugin, como `hooks/`, `.mcp.json`, `agents/` e `output-styles/`, não têm. Execute `/reload-plugins` ou reinicie Claude Code para pegá-las. Veja [Detecção de mudança ao vivo](/pt/skills#live-change-detection).427As alterações que você faz no `SKILL.md` de uma skill têm efeito imediatamente na sessão atual. Alterações em outros componentes do plugin, como `hooks/`, `.mcp.json`, `agents/` e `output-styles/`, não têm. Execute `/reload-plugins` ou reinicie Claude Code para pegá-las. Veja [Detecção de mudança ao vivo](/docs/pt/skills#live-change-detection).

428 428 

429Para parar de carregar um plugin de diretório de skills, delete sua pasta ou desabilite-o por nome. Não há etapa de `uninstall` porque nada foi instalado de um marketplace.429Para parar de carregar um plugin de diretório de skills, delete sua pasta ou desabilite-o por nome. Não há etapa de `uninstall` porque nada foi instalado de um marketplace.

430 430 

487 487 

488| Campo | Tipo | Descrição | Exemplo |488| Campo | Tipo | Descrição | Exemplo |

489| :----- | :----- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------- |489| :----- | :----- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------- |

490| `name` | string | Identificador único (kebab-case, sem espaços). Quando uma [entrada do marketplace](/pt/plugin-marketplaces#plugin-entries) lista o plugin com um nome diferente, o nome da entrada do marketplace é o que `enabledPlugins` usa e `/plugin` usa | `"deployment-tools"` |490| `name` | string | Identificador único (kebab-case, sem espaços). Quando uma [entrada do marketplace](/docs/pt/plugin-marketplaces#plugin-entries) lista o plugin com um nome diferente, o nome da entrada do marketplace é o que `enabledPlugins` usa e `/plugin` usa | `"deployment-tools"` |

491 491 

492Este nome é usado para namespacing de componentes. Por exemplo, na UI, o agent `agent-creator` para o plugin com nome `plugin-dev` aparecerá como `plugin-dev:agent-creator`.492Este nome é usado para namespacing de componentes. Por exemplo, na UI, o agent `agent-creator` para o plugin com nome `plugin-dev` aparecerá como `plugin-dev:agent-creator`.

493 493 

533`defaultEnabled` é o fallback quando nada mais decidiu o estado do plugin. Duas coisas têm precedência sobre ele:533`defaultEnabled` é o fallback quando nada mais decidiu o estado do plugin. Duas coisas têm precedência sobre ele:

534 534 

535* **A configuração do usuário**: uma entrada para o plugin em `enabledPlugins` em qualquer escopo de configurações. Uma vez escrita, persiste entre atualizações e reinstalações de plugin, então mudar `defaultEnabled` em uma versão posterior não inverte um usuário existente.535* **A configuração do usuário**: uma entrada para o plugin em `enabledPlugins` em qualquer escopo de configurações. Uma vez escrita, persiste entre atualizações e reinstalações de plugin, então mudar `defaultEnabled` em uma versão posterior não inverte um usuário existente.

536* **Um requisito de dependência**: quando um plugin é necessário por outro que está ativo, Claude Code escreve `true` para ele no momento da instalação ou habilitação. Isso lhe dá uma configuração explícita, então seu próprio padrão não se aplica mais. Veja [Habilitar ou desabilitar um plugin com dependências](/pt/plugin-dependencies#enable-or-disable-a-plugin-with-dependencies).536* **Um requisito de dependência**: quando um plugin é necessário por outro que está ativo, Claude Code escreve `true` para ele no momento da instalação ou habilitação. Isso lhe dá uma configuração explícita, então seu próprio padrão não se aplica mais. Veja [Habilitar ou desabilitar um plugin com dependências](/docs/pt/plugin-dependencies#enable-or-disable-a-plugin-with-dependencies).

537 537 

538O mesmo campo pode aparecer na entrada do marketplace de um plugin, onde tem precedência sobre o valor em `plugin.json`. Veja [Campos de plugin opcionais](/pt/plugin-marketplaces#optional-plugin-fields).538O mesmo campo pode aparecer na entrada do marketplace de um plugin, onde tem precedência sobre o valor em `plugin.json`. Veja [Campos de plugin opcionais](/docs/pt/plugin-marketplaces#optional-plugin-fields).

539 539 

540<h3 id="component-path-fields">540<h3 id="component-path-fields">

541 Campos de caminho de componente541 Campos de caminho de componente

551| `outputStyles` | string\|array | Arquivos/diretórios de estilo de saída personalizados (substitui padrão `output-styles/`) | `"./styles/"` |551| `outputStyles` | string\|array | Arquivos/diretórios de estilo de saída personalizados (substitui padrão `output-styles/`) | `"./styles/"` |

552| `lspServers` | string\|array\|object | Configurações [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) para inteligência de código (ir para definição, encontrar referências, etc.) | `"./.lsp.json"` |552| `lspServers` | string\|array\|object | Configurações [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) para inteligência de código (ir para definição, encontrar referências, etc.) | `"./.lsp.json"` |

553| `experimental.themes` | string\|array | Arquivos/diretórios de tema de cor (substitui padrão `themes/`). Veja [Temas](#themes) | `"./themes/"` |553| `experimental.themes` | string\|array | Arquivos/diretórios de tema de cor (substitui padrão `themes/`). Veja [Temas](#themes) | `"./themes/"` |

554| `experimental.monitors` | string\|array | Configurações de [Monitor](/pt/tools-reference#monitor-tool) de fundo que iniciam automaticamente quando o plugin está ativo. Veja [Monitors](#monitors) | `"./monitors.json"` |554| `experimental.monitors` | string\|array | Configurações de [Monitor](/docs/pt/tools-reference#monitor-tool) de fundo que iniciam automaticamente quando o plugin está ativo. Veja [Monitors](#monitors) | `"./monitors.json"` |

555| `userConfig` | object | Valores configuráveis pelo usuário solicitados no momento da habilitação. Veja [Configuração do usuário](#user-configuration) | Veja abaixo |555| `userConfig` | object | Valores configuráveis pelo usuário solicitados no momento da habilitação. Veja [Configuração do usuário](#user-configuration) | Veja abaixo |

556| `channels` | array | Declarações de canal para injeção de mensagens (estilo Telegram, Slack, Discord). Veja [Canais](#channels) | Veja abaixo |556| `channels` | array | Declarações de canal para injeção de mensagens (estilo Telegram, Slack, Discord). Veja [Canais](#channels) | Veja abaixo |

557| `dependencies` | array | Outros plugins que este plugin requer, opcionalmente com restrições de versão semver. Veja [Restringir versões de dependência de plugin](/pt/plugin-dependencies) | `[{ "name": "secrets-vault", "version": "~2.1.0" }]` |557| `dependencies` | array | Outros plugins que este plugin requer, opcionalmente com restrições de versão semver. Veja [Restringir versões de dependência de plugin](/docs/pt/plugin-dependencies) | `[{ "name": "secrets-vault", "version": "~2.1.0" }]` |

558 558 

559<h3 id="experimental-components">559<h3 id="experimental-components">

560 Componentes experimentais560 Componentes experimentais

601 601 

602Cada valor está disponível para substituição como `${user_config.KEY}` em configurações de servidor MCP e LSP e comandos de hook. Valores não sensíveis também podem ser substituídos em conteúdo de skill e agent. Todos os valores são exportados para processos de hook como variáveis de ambiente `CLAUDE_PLUGIN_OPTION_<KEY>`, onde `<KEY>` é a chave de opção em maiúsculas.602Cada valor está disponível para substituição como `${user_config.KEY}` em configurações de servidor MCP e LSP e comandos de hook. Valores não sensíveis também podem ser substituídos em conteúdo de skill e agent. Todos os valores são exportados para processos de hook como variáveis de ambiente `CLAUDE_PLUGIN_OPTION_<KEY>`, onde `<KEY>` é a chave de opção em maiúsculas.

603 603 

604Campos que executam em um shell rejeitam `${user_config.*}`: substituir um valor configurado em um comando shell deixaria o shell executar o que quer que esse valor contenha, então o componente falha com um [erro](/pt/errors#plugin-command-references-user-config) em vez disso. Cada campo rejeitado tem uma forma alternativa de passar o valor:604Campos que executam em um shell rejeitam `${user_config.*}`: substituir um valor configurado em um comando shell deixaria o shell executar o que quer que esse valor contenha, então o componente falha com um [erro](/docs/pt/errors#plugin-command-references-user-config) em vez disso. Cada campo rejeitado tem uma forma alternativa de passar o valor:

605 605 

606| Campo rejeitado | Como passar o valor |606| Campo rejeitado | Como passar o valor |

607| :--------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------ |607| :--------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------ |

608| Comandos de hook de forma shell | Use [forma exec](/pt/hooks#exec-form-and-shell-form) com `args`, ou leia `CLAUDE_PLUGIN_OPTION_<KEY>` do ambiente do hook |608| Comandos de hook de forma shell | Use [forma exec](/docs/pt/hooks#exec-form-and-shell-form) com `args`, ou leia `CLAUDE_PLUGIN_OPTION_<KEY>` do ambiente do hook |

609| Comandos de [Monitor](#monitors) | Leia o valor de um arquivo de configuração no script |609| Comandos de [Monitor](#monitors) | Leia o valor de um arquivo de configuração no script |

610| MCP [`headersHelper`](/pt/mcp#use-dynamic-headers-for-custom-authentication) | Leia o valor de um arquivo de configuração no script |610| MCP [`headersHelper`](/docs/pt/mcp#use-dynamic-headers-for-custom-authentication) | Leia o valor de um arquivo de configuração no script |

611 611 

612Antes de v2.1.207, esses campos substituíam valores `${user_config.KEY}`; atualize plugins que dependiam disso.612Antes de v2.1.207, esses campos substituíam valores `${user_config.KEY}`; atualize plugins que dependiam disso.

613 613 

614Valores não sensíveis são armazenados sob a chave [`pluginConfigs`](/pt/settings#pluginconfigs) em `settings.json` como `pluginConfigs[<plugin-id>].options`. {/* min-version: 2.1.207 */}Claude Code escreve a chave para configurações do usuário e a lê de volta de configurações do usuário, a flag `--settings` e configurações gerenciadas apenas; entradas em `.claude/settings.json` ou `.claude/settings.local.json` de um projeto são ignoradas. Antes de v2.1.207, Claude Code também lia configurações de projeto e local.614Valores não sensíveis são armazenados sob a chave [`pluginConfigs`](/docs/pt/settings#pluginconfigs) em `settings.json` como `pluginConfigs[<plugin-id>].options`. {/* min-version: 2.1.207 */}Claude Code escreve a chave para configurações do usuário e a lê de volta de configurações do usuário, a flag `--settings` e configurações gerenciadas apenas; entradas em `.claude/settings.json` ou `.claude/settings.local.json` de um projeto são ignoradas. Antes de v2.1.207, Claude Code também lia configurações de projeto e local.

615 615 

616Valores sensíveis vão para o Keychain do macOS, ou para `~/.claude/.credentials.json` em plataformas onde nenhum keychain suportado está disponível. O armazenamento em keychain é compartilhado com tokens OAuth e tem um limite total aproximado de 2 KB, então mantenha valores sensíveis pequenos.616Valores sensíveis vão para o Keychain do macOS, ou para `~/.claude/.credentials.json` em plataformas onde nenhum keychain suportado está disponível. O armazenamento em keychain é compartilhado com tokens OAuth e tem um limite total aproximado de 2 KB, então mantenha valores sensíveis pequenos.

617 617 

653Se um caminho personalizado substitui ou estende o diretório padrão do plugin depende do campo:653Se um caminho personalizado substitui ou estende o diretório padrão do plugin depende do campo:

654 654 

655* **Substitui o padrão**: `commands`, `agents`, `outputStyles`, `experimental.themes`, `experimental.monitors`. Por exemplo, quando o manifesto especifica `commands`, o diretório padrão `commands/` não é verificado. Para manter o padrão e adicionar mais, liste-o explicitamente: `"commands": ["./commands/", "./extras/"]`655* **Substitui o padrão**: `commands`, `agents`, `outputStyles`, `experimental.themes`, `experimental.monitors`. Por exemplo, quando o manifesto especifica `commands`, o diretório padrão `commands/` não é verificado. Para manter o padrão e adicionar mais, liste-o explicitamente: `"commands": ["./commands/", "./extras/"]`

656* **Adiciona ao padrão**: `skills`. O diretório padrão `skills/` é sempre verificado, e diretórios listados em `skills` são carregados junto com ele. Exceção: para uma [entrada do marketplace cuja `source` resolve para a raiz do marketplace](/pt/plugin-marketplaces#advanced-plugin-entries), declarar subdiretórios específicos substitui a verificação padrão `skills/`656* **Adiciona ao padrão**: `skills`. O diretório padrão `skills/` é sempre verificado, e diretórios listados em `skills` são carregados junto com ele. Exceção: para uma [entrada do marketplace cuja `source` resolve para a raiz do marketplace](/docs/pt/plugin-marketplaces#advanced-plugin-entries), declarar subdiretórios específicos substitui a verificação padrão `skills/`

657* **Regras de mesclagem próprias**: [hooks](#hooks), [MCP servers](#mcp-servers) e [LSP servers](#lsp-servers). Veja cada seção para como múltiplas fontes se combinam657* **Regras de mesclagem próprias**: [hooks](#hooks), [MCP servers](#mcp-servers) e [LSP servers](#lsp-servers). Veja cada seção para como múltiplas fontes se combinam

658 658 

659Quando um plugin tem tanto uma pasta padrão quanto a chave de manifesto correspondente, Claude Code v2.1.140 e posterior sinaliza a pasta ignorada em `claude plugin list` e a visualização de detalhes `/plugin`. O plugin ainda carrega usando os caminhos do manifesto. Claude Code não avisa quando a chave de manifesto aponta para a pasta padrão, por exemplo `"commands": ["./commands/deploy.md"]`, porque esse caminho nomeia a pasta explicitamente.659Quando um plugin tem tanto uma pasta padrão quanto a chave de manifesto correspondente, Claude Code v2.1.140 e posterior sinaliza a pasta ignorada em `claude plugin list` e a visualização de detalhes `/plugin`. O plugin ainda carrega usando os caminhos do manifesto. Claude Code não avisa quando a chave de manifesto aponta para a pasta padrão, por exemplo `"commands": ["./commands/deploy.md"]`, porque esse caminho nomeia a pasta explicitamente.

704| Servidores MCP `http`, `sse`, `ws` | `url`, `headers`, `headersHelper` |704| Servidores MCP `http`, `sse`, `ws` | `url`, `headers`, `headersHelper` |

705| Servidores LSP | `command`, `args`, `env`, `workspaceFolder` |705| Servidores LSP | `command`, `args`, `env`, `workspaceFolder` |

706 706 

707Em comandos de hook, use [forma exec](/pt/hooks#exec-form-and-shell-form) com `args` para que cada caminho seja passado como um argumento sem citação. Em hooks de forma shell e comandos de monitor, envolva as variáveis em aspas duplas, como em `"${CLAUDE_PROJECT_DIR}/scripts/server.sh"`. Este hook de forma shell executa um script agrupado com um plugin:707Em comandos de hook, use [forma exec](/docs/pt/hooks#exec-form-and-shell-form) com `args` para que cada caminho seja passado como um argumento sem citação. Em hooks de forma shell e comandos de monitor, envolva as variáveis em aspas duplas, como em `"${CLAUDE_PROJECT_DIR}/scripts/server.sh"`. Este hook de forma shell executa um script agrupado com um plugin:

708 708 

709```json theme={null}709```json theme={null}

710{710{

727 727 

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

729 729 

730Servidores MCP também podem chamar a solicitação `roots/list` para ler os diretórios de trabalho da sessão em tempo de execução. Veja [o que `roots/list` retorna e quando Claude Code notifica o servidor de mudanças](/pt/mcp#option-3-add-a-local-stdio-server).730Servidores MCP também podem chamar a solicitação `roots/list` para ler os diretórios de trabalho da sessão em tempo de execução. Veja [o que `roots/list` retorna e quando Claude Code notifica o servidor de mudanças](/docs/pt/mcp#option-3-add-a-local-stdio-server).

731 731 

732<h4 id="persistent-data-directory">732<h4 id="persistent-data-directory">

733 Diretório de dados persistente733 Diretório de dados persistente

893| **LSP servers** | `.lsp.json` | Configurações de servidor de linguagem |893| **LSP servers** | `.lsp.json` | Configurações de servidor de linguagem |

894| **Monitors** | `monitors/monitors.json` | Configurações de monitor de fundo |894| **Monitors** | `monitors/monitors.json` | Configurações de monitor de fundo |

895| **Executáveis** | `bin/` | Executáveis adicionados ao `PATH` da ferramenta Bash. Arquivos aqui são invocáveis como comandos bare em qualquer chamada de ferramenta Bash enquanto o plugin está habilitado |895| **Executáveis** | `bin/` | Executáveis adicionados ao `PATH` da ferramenta Bash. Arquivos aqui são invocáveis como comandos bare em qualquer chamada de ferramenta Bash enquanto o plugin está habilitado |

896| **Configurações** | `settings.json` | Configuração padrão aplicada quando o plugin é habilitado. Atualmente apenas as chaves [`agent`](/pt/sub-agents) e [`subagentStatusLine`](/pt/statusline#subagent-status-lines) são suportadas |896| **Configurações** | `settings.json` | Configuração padrão aplicada quando o plugin é habilitado. Atualmente apenas as chaves [`agent`](/docs/pt/sub-agents) e [`subagentStatusLine`](/docs/pt/statusline#subagent-status-lines) são suportadas |

897 897 

898***898***

899 899 

942| `mcp` | Um `.mcp.json` com exemplos de servidor HTTP e stdio |942| `mcp` | Um `.mcp.json` com exemplos de servidor HTTP e stdio |

943| `lsp` | Um exemplo `.lsp.json` de language-server |943| `lsp` | Um exemplo `.lsp.json` de language-server |

944| `output-style` | Um `output-styles/<name>.md` que se aplica automaticamente enquanto o plugin está habilitado |944| `output-style` | Um `output-styles/<name>.md` que se aplica automaticamente enquanto o plugin está habilitado |

945| `channel` | Um [canal](/pt/channels) baseado em MCP: um servidor stdio (`server.ts`), seu `.mcp.json` e um `package.json` |945| `channel` | Um [canal](/docs/pt/channels) baseado em MCP: um servidor stdio (`server.ts`), seu `.mcp.json` e um `package.json` |

946 946 

947O plugin criado usa a fonte `@skills-dir` em vez de um marketplace. Administradores podem bloquear essa fonte com `strictKnownMarketplaces` ou adicionando `{"source": "skills-dir"}` a `blockedMarketplaces` em [configurações gerenciadas](/pt/plugin-marketplaces#managed-marketplace-restrictions). Quando bloqueado, `plugin init` falha antes de escrever.947O plugin criado usa a fonte `@skills-dir` em vez de um marketplace. Administradores podem bloquear essa fonte com `strictKnownMarketplaces` ou adicionando `{"source": "skills-dir"}` a `blockedMarketplaces` em [configurações gerenciadas](/docs/pt/plugin-marketplaces#managed-marketplace-restrictions). Quando bloqueado, `plugin init` falha antes de escrever.

948 948 

949**Exemplos:**949**Exemplos:**

950 950 

1027 plugin prune1027 plugin prune

1028</h3>1028</h3>

1029 1029 

1030Remova dependências de plugin auto-instaladas que não são mais necessárias por nenhum plugin instalado. Dependências que Claude Code puxou para satisfazer o campo [`dependencies`](/pt/plugin-dependencies) de outro plugin são removidas; plugins que você instalou diretamente nunca são tocados.1030Remova dependências de plugin auto-instaladas que não são mais necessárias por nenhum plugin instalado. Dependências que Claude Code puxou para satisfazer o campo [`dependencies`](/docs/pt/plugin-dependencies) de outro plugin são removidas; plugins que você instalou diretamente nunca são tocados.

1031 1031 

1032```bash theme={null}1032```bash theme={null}

1033claude plugin prune [options]1033claude plugin prune [options]

1054 plugin enable1054 plugin enable

1055</h3>1055</h3>