18| :- | :- |18| :- | :- |
19| `SessionStart` | Quando uma sessão começa ou é retomada |19| `SessionStart` | Quando uma sessão começa ou é retomada |
20| `Setup` | Quando você inicia Claude Code com `--init-only`, ou com `--init` ou `--maintenance` no modo `-p`. Para preparação única em CI ou scripts |20| `Setup` | Quando você inicia Claude Code com `--init-only`, ou com `--init` ou `--maintenance` no modo `-p`. Para preparação única em CI ou scripts |
21| `UserPromptSubmit` | Quando você envia um prompt, antes de Claude processá-lo |21| `UserPromptSubmit` | Quando um prompt é enviado, antes de Claude processá-lo. Também dispara em [turnos que Claude Code inicia por conta própria](/docs/pt/hooks#userpromptsubmit) |
22| `UserPromptExpansion` | Quando um comando digitado pelo usuário se expande em um prompt, antes de chegar a Claude. Pode bloquear a expansão |22| `UserPromptExpansion` | Quando um comando digitado pelo usuário se expande em um prompt, antes de chegar a Claude. Pode bloquear a expansão |
23| `PreToolUse` | Antes de uma chamada de ferramenta ser executada. Pode bloqueá-la |23| `PreToolUse` | Antes de uma chamada de ferramenta ser executada. Pode bloqueá-la |
24| `PermissionRequest` | Quando uma chamada de ferramenta precisa de uma decisão de permissão |24| `PermissionRequest` | Quando uma chamada de ferramenta precisa de uma decisão de permissão |
76| :- | :- |76| :- | :- |
77| `SessionStart` | Quando uma sessão começa ou é retomada |77| `SessionStart` | Quando uma sessão começa ou é retomada |
78| `Setup` | Quando você inicia Claude Code com `--init-only`, ou com `--init` ou `--maintenance` no modo `-p`. Para preparação única em CI ou scripts |78| `Setup` | Quando você inicia Claude Code com `--init-only`, ou com `--init` ou `--maintenance` no modo `-p`. Para preparação única em CI ou scripts |
79| `UserPromptSubmit` | Quando você envia um prompt, antes de Claude processá-lo |79| `UserPromptSubmit` | Quando um prompt é enviado, antes de Claude processá-lo. Também dispara em [turnos que Claude Code inicia por conta própria](/docs/pt/hooks#userpromptsubmit) |
80| `UserPromptExpansion` | Quando um comando digitado pelo usuário se expande em um prompt, antes de chegar a Claude. Pode bloquear a expansão |80| `UserPromptExpansion` | Quando um comando digitado pelo usuário se expande em um prompt, antes de chegar a Claude. Pode bloquear a expansão |
81| `PreToolUse` | Antes de uma chamada de ferramenta ser executada. Pode bloqueá-la |81| `PreToolUse` | Antes de uma chamada de ferramenta ser executada. Pode bloqueá-la |
82| `PermissionRequest` | Quando uma chamada de ferramenta precisa de uma decisão de permissão |82| `PermissionRequest` | Quando uma chamada de ferramenta precisa de uma decisão de permissão |
1195 Eventos de hook1195 Eventos de hook
1196</h2>1196</h2>
1197 1197
1198Cada evento corresponde a um ponto no ciclo de vida do Claude Code onde hooks podem ser executados. As seções abaixo estão ordenadas para corresponder ao ciclo de vida: desde a configuração da sessão através do loop agentico até o final da sessão. Cada seção descreve quando o evento é disparado, quais matchers ele suporta, a entrada JSON que recebe e como controlar o comportamento através da saída.1198Cada evento corresponde a um ponto no ciclo de vida do Claude Code em que os hooks podem ser executados. As seções abaixo estão ordenadas de acordo com o ciclo de vida: da configuração da sessão, passando pelo loop agêntico, até o fim da sessão. Cada seção descreve quando o evento é disparado, quais matchers ele suporta, a entrada JSON que ele recebe e como controlar o comportamento por meio da saída.
1199 1199
1200<h3 id="sessionstart">1200<h3 id="sessionstart">
1201 SessionStart1201 SessionStart
1202</h3>1202</h3>
1203 1203
1204Executa 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 no seu código, 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.1204É executado quando o Claude Code inicia uma nova sessão ou retoma uma sessão existente. Útil para carregar contexto de desenvolvimento, como issues existentes ou alterações recentes na sua base de código, ou para configurar variáveis de ambiente. Para contexto estático que não exige um script, use o [CLAUDE.md](/docs/pt/memory).
1205 1205
1206SessionStart é executado em cada sessão, então mantenha esses hooks rápidos. Apenas hooks `type: "command"` e `type: "mcp_tool"` são suportados. Veja [campos de hook de ferramenta MCP](#mcp-tool-hook-fields) para quando hooks `mcp_tool` são executados.1206O SessionStart é executado em todas as sessões, então mantenha esses hooks rápidos. Somente hooks `type: "command"` e `type: "mcp_tool"` são suportados. Consulte [Campos de hook de ferramenta MCP](#mcp-tool-hook-fields) para saber quando os hooks `mcp_tool` são executados.
1207 1207
1208O valor do matcher corresponde a como a sessão foi iniciada:1208O valor do matcher corresponde à forma como a sessão foi iniciada:
1209 1209
1210| Matcher | Quando é disparado |1210| Matcher | Quando é disparado |
1211| :- | :- |1211| :- | :- |
1212| `startup` | Nova sessão |1212| `startup` | Nova sessão |
1213| `resume` | `--resume`, `--continue`, ou `/resume` |1213| `resume` | `--resume`, `--continue` ou `/resume` |
1214| `clear` | `/clear` |1214| `clear` | `/clear` |
1215| `compact` | Compactação automática ou manual |1215| `compact` | Compactação automática ou manual |
1216| `fork` | Uma nova sessão bifurcada de uma existente: `--fork-session` com `--resume` ou `--continue`, a cópia de fundo `/fork`, `/branch` ou uma conversa que você [move para o fundo](/docs/pt/agent-view#from-inside-a-session) |1216| `fork` | Uma nova sessão bifurcada de uma existente: `--fork-session` com `--resume` ou `--continue`, a cópia em segundo plano de `/fork`, `/branch` ou uma conversa que você [move para o segundo plano](/docs/pt/agent-view#from-inside-a-session) |
1217 1217
1218Antes da v2.1.214, sessões bifurcadas relatavam fonte `"resume"`.1218Antes da v2.1.214, sessões bifurcadas informavam a origem `"resume"`.
1219 1219
1220Quando você inicia uma sessão interativa, retoma uma conversa no lançamento com `--continue` ou `--resume`, ou executa `/clear`, hooks SessionStart são executados em segundo plano. Você pode digitar imediatamente, e uma conversa que você retomou aparece sem esperar pelos hooks. A primeira resposta do Claude ainda espera os hooks terminarem, então seu contexto chega ao Claude.1220Quando você inicia uma sessão interativa, retoma uma conversa na inicialização com `--continue` ou `--resume`, ou executa `/clear`, os hooks SessionStart são executados em segundo plano. Você pode digitar imediatamente, e uma conversa retomada aparece sem esperar pelos hooks. A primeira resposta do Claude ainda espera os hooks terminarem, para que o contexto deles chegue ao Claude.
1221 1221
1222Quando você muda de conversas com `/resume` dentro de uma sessão, a mudança espera os hooks terminarem. Se você executar `/clear` ou mudar para outra conversa enquanto hooks de fundo ainda estão em execução, nada que eles retornem se aplica à sessão.1222Quando você alterna entre conversas com `/resume` dentro de uma sessão, a troca espera os hooks terminarem. Se você executar `/clear` ou alternar para outra conversa enquanto hooks em segundo plano ainda estiverem em execução, nada do que eles retornarem se aplica à sessão.
1223 1223
1224A mesma espera se aplica no lançamento, incluindo uma sessão retomada: um prompt que você envia enquanto hooks SessionStart ainda estão em execução não chega ao Claude até que terminem.1224A mesma espera se aplica na inicialização, incluindo uma sessão retomada: um prompt que você envia enquanto os hooks SessionStart ainda estão em execução não chega ao Claude até que eles terminem.
1225 1225
1226Durante qualquer espera, pressione `Esc` para levar o prompt de volta para a entrada sem enviá-lo. Os hooks continuam em execução.1226Durante qualquer uma dessas esperas, pressione `Esc` para trazer o prompt de volta à entrada sem enviá-lo. Os hooks continuam em execução.
1227 1227
1228<h4 id="sessionstart-input">1228<h4 id="sessionstart-input">
1229 Entrada SessionStart1229 Entrada do SessionStart
1230</h4>1230</h4>
1231 1231
1232Além dos [campos de entrada comuns](#common-input-fields), hooks SessionStart recebem `source` e opcionalmente `model`, `agent_type` e `session_title`:1232Além dos [campos de entrada comuns](#common-input-fields), os hooks SessionStart recebem `source` e, opcionalmente, `model`, `agent_type` e `session_title`:
1233 1233
1234| Campo | Descrição |1234| Campo | Descrição |
1235| :- | :- |1235| :- | :- |
1236| `source` | Como a sessão começou: `"startup"` para novas sessões, `"resume"` para sessões retomadas, `"clear"` após `/clear`, `"compact"` após compactação, ou `"fork"` para uma nova sessão bifurcada de uma existente |1236| `source` | Como a sessão começou: `"startup"` para novas sessões, `"resume"` para sessões retomadas, `"clear"` após `/clear`, `"compact"` após a compactação ou `"fork"` para uma nova sessão bifurcada de uma existente |
1237| `model` | O identificador do modelo ativo. Pode ser omitido, por exemplo após `/clear` ou quando uma sessão é restaurada através de recuperação de conversa, então verifique o campo antes de lê-lo |1237| `model` | O identificador do modelo ativo. Ele pode ser omitido, por exemplo após `/clear` ou quando uma sessão é restaurada pela recuperação de conversa, então verifique a existência do campo antes de lê-lo |
1238| `agent_type` | O nome do agente, presente quando você inicia Claude Code com `claude --agent <name>` |1238| `agent_type` | O nome do agente, presente quando você inicia o Claude Code com `claude --agent <name>` |
1239| `session_title` | O título da sessão atual se um já estiver definido, por exemplo via `--name` ou `/rename`. Um hook que emite `sessionTitle` pode verificar `session_title` primeiro para evitar sobrescrever um título que o usuário definiu explicitamente |1239| `session_title` | O título personalizado da sessão, presente quando um está definido, por exemplo com `--name`, `/rename`, a saída `sessionTitle` de um hook ou `renameSession()` do Agent SDK. Um hook que emite `sessionTitle` pode verificar esse campo primeiro para evitar sobrescrever um título personalizado existente |
1240 1240
1241A sessão que você não nomeou ainda pode ter um [título gerado](/docs/pt/sessions#name-your-sessions). Esse título não é um título personalizado e não aparece em `session_title`.1241Uma sessão que você não nomeou ainda pode ter um [título gerado](/docs/pt/sessions#name-your-sessions). Esse título não é um título personalizado e não aparece em `session_title`.
1242 1242
1243Quando `source` é `"resume"` ou `"fork"` e a transcrição contém pelo menos uma resposta do Claude, hooks SessionStart também recebem os quatro campos abaixo. Seu hook pode usá-los para relatar qual é o custo de retomar uma conversa obsoleta antes da primeira solicitação, por exemplo em um [`systemMessage`](#json-output). Esses campos requerem Claude Code v2.1.251 ou posterior.1243Quando `source` é `"resume"` ou `"fork"` e a transcrição contém pelo menos uma resposta do Claude, os hooks SessionStart também recebem os quatro campos abaixo. Seu hook pode usá-los para informar quanto custa retomar uma conversa antiga antes da primeira requisição, por exemplo em um [`systemMessage`](#json-output). Esses campos exigem o Claude Code v2.1.251 ou posterior.
1244 1244
1245| Campo | Descrição |1245| Campo | Descrição |
1246| :- | :- |1246| :- | :- |
1247| `seconds_since_last_response` | Segundos de tempo real desde a última resposta na transcrição retomada |1247| `seconds_since_last_response` | Segundos de tempo real desde a última resposta na transcrição retomada |
1248| `context_tokens` | Tokens que a primeira solicitação da sessão retomada reenvia como seu prompt |1248| `context_tokens` | Tokens que a primeira requisição da sessão retomada reenvia como seu prompt |
1249| `prompt_cache_likely_expired` | `true` quando a última resposta é mais antiga que o [tempo de vida do cache de prompt](/docs/pt/prompt-caching#cache-lifetime) da sessão ou uma compactação posterior substituiu a conversa em cache |1249| `prompt_cache_likely_expired` | `true` quando a última resposta é mais antiga que o [tempo de vida do cache de prompt](/docs/pt/prompt-caching#cache-lifetime) da sessão ou quando uma compactação posterior substituiu a conversa em cache |
1250| `estimated_cache_write_usd` | Custo estimado em dólares americanos de escrever `context_tokens` no cache de prompt no modelo da sessão, excluindo a resposta |1250| `estimated_cache_write_usd` | Custo estimado em dólares americanos de gravar `context_tokens` no cache de prompt no modelo da sessão, excluindo a resposta |
1251 1251
1252Este exemplo mostra a entrada para uma sessão retomada 90 minutos após sua última resposta:1252Este exemplo mostra a entrada para uma sessão retomada 90 minutos após sua última resposta:
1253 1253
1267```1267```
1268 1268
1269<h4 id="sessionstart-decision-control">1269<h4 id="sessionstart-decision-control">
1270 Controle de decisão SessionStart1270 Controle de decisão do SessionStart
1271</h4>1271</h4>
1272 1272
1273Claude Code adiciona stdout que [trata como texto simples](#exit-code-0) ao contexto do Claude. 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:1273O Claude Code adiciona ao contexto do Claude o stdout que ele [trata como texto simples](#exit-code-0). Além dos [campos de saída JSON](#json-output) disponíveis para todos os hooks, você pode retornar estes campos específicos do evento:
1274 1274
1275| Campo | Descrição |1275| Campo | Descrição |
1276| :- | :- |1276| :- | :- |
1277| `additionalContext` | String adicionada ao contexto do Claude no início da conversa, antes do primeiro prompt. Veja [Adicionar contexto para Claude](#add-context-for-claude) para como o texto é entregue e o que colocar nele |1277| `additionalContext` | String adicionada ao contexto do Claude no início da conversa, antes do primeiro prompt. Consulte [Adicionar contexto para o Claude](#add-context-for-claude) para saber como o texto é entregue e o que colocar nele |
1278| `initialUserMessage` | String usada como a primeira mensagem do 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 que nenhum prompt seja fornecido. Se um prompt for fornecido, ele segue como o próximo turno. Ao contrário de `additionalContext`, que se anexa a um turno existente, isso cria o turno |1278| `initialUserMessage` | String usada como a primeira mensagem do usuário da sessão. Aplica-se no [modo não interativo](/docs/pt/headless) com a flag `-p`, onde se torna o primeiro turno mesmo que nenhum prompt seja fornecido. Se um prompt for fornecido, ele vem em seguida como o próximo turno. Diferentemente de `additionalContext`, que se anexa a um turno existente, isso cria o turno |
1279| `sessionTitle` | Define o título da sessão, com o mesmo efeito de `/rename`. Use para nomear sessões automaticamente a partir da pasta de lançamento, branch git ou nome de worktree. Aplica-se quando `source` é `"startup"`, `"resume"` ou `"fork"`; ignorado em `"clear"` e `"compact"` |1279| `sessionTitle` | Define o título da sessão, com o mesmo efeito de `/rename`. Use para nomear sessões automaticamente a partir da pasta de inicialização, do branch do git ou do nome do worktree. Aplica-se quando `source` é `"startup"`, `"resume"` ou `"fork"`; ignorado em `"clear"` e `"compact"` |
1280| `watchPaths` | Array de caminhos absolutos para observar eventos [FileChanged](#filechanged) durante esta sessão |1280| `watchPaths` | Array de caminhos absolutos a observar para eventos [FileChanged](#filechanged) durante esta sessão |
1281| `reloadSkills` | Booleano. Quando `true`, Claude Code verifica novamente os diretórios de [skill](/docs/pt/skills) e comando após os hooks SessionStart serem concluídos, para que skills que o hook instalou estejam disponíveis na mesma sessão, começando com o primeiro prompt |1281| `reloadSkills` | Booleano. Quando `true`, o Claude Code examina novamente os diretórios de [skills](/docs/pt/skills) e comandos após a conclusão dos hooks SessionStart, para que as skills instaladas pelo hook estejam disponíveis na mesma sessão, a partir do primeiro prompt |
1282 1282
1283```json theme={null}1283```json theme={null}
1284{1284{
1290}1290}
1291```1291```
1292 1292
1293Como stdout simples já chega ao Claude para este evento, um hook que apenas carrega contexto pode imprimir para stdout diretamente sem construir JSON. Use a forma JSON quando você precisa combinar contexto com outros campos como `sessionTitle`.1293Como o stdout simples já chega ao Claude para este evento, um hook que apenas carrega contexto pode imprimir diretamente no stdout sem montar JSON. Use o formato JSON quando precisar combinar contexto com outros campos, como `sessionTitle`.
1294 1294
1295Use `reloadSkills` quando um hook SessionStart instala ou atualiza skills. A descoberta de skills normalmente é executada antes dos hooks SessionStart terminarem, então arquivos que o hook escreve em `~/.claude/skills/` ou `.claude/skills/` caso contrário só apareceriam na próxima sessão. Este exemplo sincroniza um repositório de skills compartilhado e solicita a nova verificação:1295Use `reloadSkills` quando um hook SessionStart instala ou atualiza skills. A descoberta de skills normalmente é executada antes de os hooks SessionStart terminarem, então os arquivos que o hook grava em `~/.claude/skills/` ou `.claude/skills/` só apareceriam, de outra forma, na próxima sessão. Este exemplo sincroniza um repositório de skills compartilhado e solicita a nova varredura:
1296 1296
1297```bash theme={null}1297```bash theme={null}
1298#!/bin/bash1298#!/bin/bash
1303echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "reloadSkills": true}}'1303echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "reloadSkills": true}}'
1304```1304```
1305 1305
1306A URL do repositório é um espaço reservado; substitua-a pelo seu próprio repositório de skills. Com o espaço reservado, o clone falha e imprime uma mensagem `fatal:` para stderr. Stderr de um hook SessionStart que sai com 0 é apenas informativo, então a solicitação `reloadSkills` ainda se aplica.1306A URL do repositório é um placeholder; substitua-a pelo seu próprio repositório de skills. Com o placeholder, o clone falha e imprime uma mensagem `fatal:` no stderr. O stderr de um hook SessionStart que sai com 0 é apenas informativo, então a solicitação `reloadSkills` ainda se aplica.
1307 1307
1308<h4 id="persist-environment-variables">1308<h4 id="persist-environment-variables">
1309 Persistir variáveis de ambiente1309 Persistir variáveis de ambiente
1310</h4>1310</h4>
1311 1311
1312Hooks SessionStart têm acesso à variável de ambiente `CLAUDE_ENV_FILE`, que fornece um caminho de arquivo onde você pode persistir variáveis de ambiente para comandos Bash subsequentes.1312Os hooks SessionStart têm acesso à variável de ambiente `CLAUDE_ENV_FILE`, que fornece um caminho de arquivo onde você pode persistir variáveis de ambiente para comandos Bash subsequentes.
1313 1313
1314Para definir variáveis de ambiente individuais, escreva instruções `export` para `CLAUDE_ENV_FILE`. Use append (`>>`) para preservar variáveis definidas por outros hooks:1314Para definir variáveis de ambiente individuais, grave instruções `export` em `CLAUDE_ENV_FILE`. Use anexação (`>>`) para preservar variáveis definidas por outros hooks:
1315 1315
1316```bash theme={null}1316```bash theme={null}
1317#!/bin/bash1317#!/bin/bash
1325exit 01325exit 0
1326```1326```
1327 1327
1328Para capturar todas as mudanças de ambiente de comandos de configuração, compare as variáveis exportadas antes e depois:1328Para capturar todas as alterações de ambiente feitas por comandos de configuração, compare as variáveis exportadas antes e depois:
1329 1329
1330```bash theme={null}1330```bash theme={null}
1331#!/bin/bash1331#!/bin/bash
1345```1345```
1346 1346
1347<Note>1347<Note>
1348 `CLAUDE_ENV_FILE` está disponível para hooks SessionStart, [Setup](#setup), [CwdChanged](#cwdchanged) e [FileChanged](#filechanged). Outros tipos de hook não têm acesso a esta variável.1348 `CLAUDE_ENV_FILE` está disponível para hooks SessionStart, [Setup](#setup), [CwdChanged](#cwdchanged) e [FileChanged](#filechanged). Outros tipos de hook não têm acesso a essa variável.
1349</Note>1349</Note>
1350 1350
1351<h3 id="setup">1351<h3 id="setup">
1352 Setup1352 Setup
1353</h3>1353</h3>
1354 1354
1355Dispara apenas quando você inicia 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 no startup normal. Use-o para instalação de dependência única ou limpeza agendada que você dispara explicitamente de CI ou scripts, separado do startup normal da sessão. Para inicialização por sessão, use [SessionStart](#sessionstart) em vez disso.1355É disparado somente quando você inicia o Claude Code com `--init-only`, ou com `--init` ou `--maintenance` no [modo não interativo](/docs/pt/headless) com a flag `-p`. Ele não é disparado na inicialização normal. Use-o para instalação única de dependências ou limpeza agendada que você aciona explicitamente a partir de CI ou scripts, separadamente da inicialização normal da sessão. Para inicialização por sessão, use o [SessionStart](#sessionstart).
1356 1356
1357O valor do matcher corresponde à flag CLI que disparou o hook:1357O valor do matcher corresponde à flag da CLI que acionou o hook:
1358 1358
1359| Matcher | Quando é disparado |1359| Matcher | Quando é disparado |
1360| :- | :- |1360| :- | :- |
1361| `init` | `claude --init-only` ou `claude -p --init` |1361| `init` | `claude --init-only` ou `claude -p --init` |
1362| `maintenance` | `claude -p --maintenance` |1362| `maintenance` | `claude -p --maintenance` |
1363 1363
1364Quando você executa `claude --init-only`, Claude Code executa hooks Setup e hooks `SessionStart` com o matcher `startup`, depois sai sem iniciar uma conversa.1364Quando você executa `claude --init-only`, o Claude Code executa os hooks Setup e os hooks `SessionStart` com o matcher `startup` e, em seguida, sai sem iniciar uma conversa.
1365 1365
1366Quando você inicia ou continua uma conversa com `-p`, você também precisa fornecer um prompt, como um argumento ou canalizado em stdin. Você pode pular o prompt quando um hook `SessionStart` fornece [`initialUserMessage`](#sessionstart-decision-control) ou quando você retoma uma sessão com uma [chamada de ferramenta adiada](#defer-a-tool-call-for-later).1366Quando você inicia ou continua uma conversa com `-p`, também precisa fornecer um prompt, como argumento ou via pipe no stdin. Você pode omitir o prompt quando um hook `SessionStart` fornece [`initialUserMessage`](#sessionstart-decision-control) ou quando você retoma uma sessão com uma [chamada de ferramenta adiada](#defer-a-tool-call-for-later).
1367 1367
1368No sucesso, `--init-only` não imprime nada no terminal. Para confirmar que os hooks foram executados, comece com `claude --debug-file <path> --init-only`, substituindo `<path>` por um local de arquivo de log, e verifique o log para as entradas de hook Setup e SessionStart.1368Em caso de sucesso, `--init-only` não imprime nada no terminal. Para confirmar que os hooks foram executados, inicie com `claude --debug-file <path> --init-only`, substituindo `<path>` por um local de arquivo de log, e verifique no log as entradas dos hooks Setup e SessionStart.
1369 1369
1370Como Setup não dispara em cada lançamento, um plugin que precisa de uma dependência instalada não pode contar apenas com 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. Veja o [diretório de dados persistentes](/docs/pt/plugins/components#path-variables-and-persistent-data) para onde armazenar dependências instaladas. Se você distribuir seu plugin através de um marketplace, você pode não precisar deste padrão: Claude Code [instala automaticamente dependências de pacote Node.js elegíveis](/docs/pt/plugins/loading#node-js-package-dependencies) quando armazena em cache o plugin.1370Como o Setup não é disparado a cada inicialização, um plugin que precisa de uma dependência instalada não pode depender apenas do Setup. O padrão prático é verificar a dependência no primeiro uso e instalá-la se estiver ausente, por exemplo um hook ou skill que testa `${CLAUDE_PLUGIN_DATA}/node_modules` e executa `npm install` se não existir. Consulte o [diretório de dados persistentes](/docs/pt/plugins/components#path-variables-and-persistent-data) para saber onde armazenar dependências instaladas. Se você distribui seu plugin por meio de um marketplace, talvez não precise desse padrão: o Claude Code [instala automaticamente as dependências de pacotes Node.js elegíveis](/docs/pt/plugins/loading#node-js-package-dependencies) ao armazenar o plugin em cache.
1371 1371
1372<h4 id="setup-input">1372<h4 id="setup-input">
1373 Entrada Setup1373 Entrada do Setup
1374</h4>1374</h4>
1375 1375
1376Além dos [campos de entrada comuns](#common-input-fields), hooks Setup recebem um campo `trigger` definido como `"init"` ou `"maintenance"`:1376Além dos [campos de entrada comuns](#common-input-fields), os hooks Setup recebem um campo `trigger` definido como `"init"` ou `"maintenance"`:
1377 1377
1378```json theme={null}1378```json theme={null}
1379{1379{
1386```1386```
1387 1387
1388<h4 id="setup-decision-control">1388<h4 id="setup-decision-control">
1389 Controle de decisão Setup1389 Controle de decisão do Setup
1390</h4>1390</h4>
1391 1391
1392Hooks Setup não podem bloquear; a execução continua em qualquer código de saída. Em cada código de saída, Claude Code descarta [campos de saída JSON](#json-output) de um hook Setup, como `systemMessage`, `continue` e `hookSpecificOutput.additionalContext`. Com `-p`, stdout, stderr e código de saída de um hook Setup aparecem na saída da execução apenas como [eventos `hook_response`](/docs/pt/headless#read-session-metadata) quando você inicia com `--output-format stream-json --verbose`.1392Os hooks Setup não podem bloquear; a execução continua com qualquer código de saída. Em todo código de saída, o Claude Code descarta os [campos de saída JSON](#json-output) de um hook Setup, como `systemMessage`, `continue` e `hookSpecificOutput.additionalContext`. Com `-p`, o stdout, o stderr e o código de saída de um hook Setup aparecem na saída da execução somente como [eventos `hook_response`](/docs/pt/headless#read-session-metadata) quando você inicia com `--output-format stream-json --verbose`.
1393 1393
1394Hooks Setup têm acesso a `CLAUDE_ENV_FILE`. Variáveis escritas nesse arquivo persistem em comandos Bash subsequentes para a sessão, assim como em [hooks SessionStart](#persist-environment-variables). Apenas hooks `type: "command"` são executados em `Setup`. Um hook `type: "mcp_tool"` em `Setup` é sempre ignorado, conforme descrito em [campos de hook de ferramenta MCP](#mcp-tool-hook-fields).1394Os hooks Setup têm acesso a `CLAUDE_ENV_FILE`. As variáveis gravadas nesse arquivo persistem nos comandos Bash subsequentes da sessão, assim como nos [hooks SessionStart](#persist-environment-variables). Somente hooks `type: "command"` são executados em `Setup`. Um hook `type: "mcp_tool"` em `Setup` é sempre ignorado, conforme descrito em [Campos de hook de ferramenta MCP](#mcp-tool-hook-fields).
1395 1395
1396<h3 id="instructionsloaded">1396<h3 id="instructionsloaded">
1397 InstructionsLoaded1397 InstructionsLoaded
1398</h3>1398</h3>
1399 1399
1400Dispara quando um arquivo `CLAUDE.md` ou `.claude/rules/*.md` é carregado no contexto. Este evento dispara no início da sessão para arquivos carregados com entusiasmo e novamente mais tarde quando arquivos são carregados preguiçosamente, por exemplo quando Claude acessa um subdiretório que contém um `CLAUDE.md` aninhado ou quando regras condicionais com frontmatter `paths:` correspondem. O hook não suporta bloqueio ou controle de decisão. Ele é executado de forma assíncrona para fins de observabilidade.1400É disparado quando um arquivo `CLAUDE.md` ou `.claude/rules/*.md` é carregado no contexto. Este evento é disparado no início da sessão para arquivos carregados de forma antecipada e novamente mais tarde quando arquivos são carregados de forma tardia, por exemplo quando o Claude acessa um subdiretório que contém um `CLAUDE.md` aninhado ou quando regras condicionais com frontmatter `paths:` correspondem. O hook não suporta bloqueio nem controle de decisão. Ele é executado de forma assíncrona para fins de observabilidade.
1401 1401
1402Este evento não dispara quando Claude [lê `AGENTS.md` diretamente](/docs/pt/memory#agents-md) através da configuração **Project instructions**. Ele dispara quando um `CLAUDE.md` importa seu `AGENTS.md`, com `load_reason` definido como `include` como para qualquer outro arquivo importado, e quando `CLAUDE.md` é um symlink para ele, como um carregamento normal de `CLAUDE.md`.1402Este evento não é disparado quando o Claude [lê `AGENTS.md` diretamente](/docs/pt/memory#agents-md) por meio da configuração **Project instructions**. Ele é disparado quando um `CLAUDE.md` importa seu `AGENTS.md`, com `load_reason` definido como `include`, como para qualquer outro arquivo importado, e quando `CLAUDE.md` é um link simbólico para ele, como um carregamento normal de `CLAUDE.md`.
1403 1403
1404O matcher é executado contra `load_reason`. Por exemplo, use `"matcher": "session_start"` para disparar apenas para arquivos carregados no início da sessão, ou `"matcher": "path_glob_match|nested_traversal"` para disparar apenas para carregamentos preguiçosos.1404O matcher é avaliado contra `load_reason`. Por exemplo, use `"matcher": "session_start"` para disparar somente para arquivos carregados no início da sessão, ou `"matcher": "path_glob_match|nested_traversal"` para disparar somente para carregamentos tardios.
1405 1405
1406<h4 id="instructionsloaded-input">1406<h4 id="instructionsloaded-input">
1407 Entrada InstructionsLoaded1407 Entrada do InstructionsLoaded
1408</h4>1408</h4>
1409 1409
1410Além dos [campos de entrada comuns](#common-input-fields), hooks InstructionsLoaded recebem esses campos:1410Além dos [campos de entrada comuns](#common-input-fields), os hooks InstructionsLoaded recebem estes campos:
1411 1411
1412| Campo | Descrição |1412| Campo | Descrição |
1413| :- | :- |1413| :- | :- |
1414| `file_path` | Caminho absoluto para o arquivo de instrução que foi carregado |1414| `file_path` | Caminho absoluto para o arquivo de instruções que foi carregado |
1415| `memory_type` | Escopo do arquivo: `"User"`, `"Project"`, `"Local"` ou `"Managed"` |1415| `memory_type` | Escopo do arquivo: `"User"`, `"Project"`, `"Local"` ou `"Managed"` |
1416| `load_reason` | Por que o arquivo foi carregado: `"session_start"`, `"nested_traversal"`, `"path_glob_match"`, `"include"` ou `"compact"`. O valor `"compact"` dispara quando arquivos de instrução são recarregados após um evento de compactação |1416| `load_reason` | Por que o arquivo foi carregado: `"session_start"`, `"nested_traversal"`, `"path_glob_match"`, `"include"` ou `"compact"`. O valor `"compact"` é disparado quando os arquivos de instruções são recarregados após um evento de compactação |
1417| `globs` | Padrões de glob de caminho do frontmatter `paths:` do arquivo, se houver. Presente apenas para carregamentos `path_glob_match` |1417| `globs` | Padrões glob de caminho do frontmatter `paths:` do arquivo, se houver. Presente somente para carregamentos `path_glob_match` |
1418| `trigger_file_path` | Caminho para o arquivo cujo acesso disparou este carregamento, para carregamentos preguiçosos |1418| `trigger_file_path` | Caminho para o arquivo cujo acesso acionou este carregamento, para carregamentos tardios |
1419| `parent_file_path` | Caminho para o arquivo de instrução pai que incluiu este, para carregamentos `include` |1419| `parent_file_path` | Caminho para o arquivo de instruções pai que incluiu este, para carregamentos `include` |
1420 1420
1421```json theme={null}1421```json theme={null}
1422{1422{
1431```1431```
1432 1432
1433<h4 id="instructionsloaded-decision-control">1433<h4 id="instructionsloaded-decision-control">
1434 Controle de decisão InstructionsLoaded1434 Controle de decisão do InstructionsLoaded
1435</h4>1435</h4>
1436 1436
1437Hooks InstructionsLoaded não têm controle de decisão. Eles não podem bloquear ou modificar o carregamento de instruções. Claude Code descarta seus [campos de saída JSON](#json-output), como `systemMessage` e `continue`. Use este evento para auditoria de log, rastreamento de conformidade ou observabilidade.1437Os hooks InstructionsLoaded não têm controle de decisão. Eles não podem bloquear nem modificar o carregamento de instruções. O Claude Code descarta seus [campos de saída JSON](#json-output), como `systemMessage` e `continue`. Use este evento para log de auditoria, rastreamento de conformidade ou observabilidade.
1438 1438
1439<h3 id="userpromptsubmit">1439<h3 id="userpromptsubmit">
1440 UserPromptSubmit1440 UserPromptSubmit
1441</h3>1441</h3>
1442 1442
1443Executa quando o usuário envia um prompt, antes de Claude processá-lo. Isso permite que você adicione contexto adicional com base no prompt/conversa, valide prompts ou bloqueie certos tipos de prompts.1443É executado quando um prompt é enviado, antes que o Claude o processe. Isso permite
1444que você adicione contexto adicional com base no prompt/conversa, valide prompts ou
1445bloqueie certos tipos de prompts.
1444 1446
1445Hooks `UserPromptSubmit` têm um tempo limite padrão de 30 segundos para tipos `command`, `http` e `mcp_tool`, mais curto que o padrão de 600 segundos para esses tipos na maioria dos outros eventos. Como este hook é executado antes de cada prompt e bloqueia o processamento do modelo até ser concluído, um hook travado paralisa a sessão. Se seu hook precisar de mais tempo, defina o campo `timeout` na entrada do hook.1447Os hooks `UserPromptSubmit` não são disparados apenas em prompts que você digita. O Claude Code também os executa quando:
1446 1448
1447Além de um hook de comando que você executa com [`async: true`](#run-hooks-in-the-background), um hook `UserPromptSubmit` command, HTTP ou MCP tool que atinge seu tempo limite é cancelado e sua saída, incluindo qualquer `additionalContext`, é descartada. O prompt ainda chega ao Claude sem esse contexto. A transcrição mostra um aviso nomeando o hook, o tempo limite que disparou e que a saída foi descartada.1449* Uma [tarefa agendada](/docs/pt/scheduled-tasks) é disparada, incluindo uma iteração de `/loop`
1450* Um [subagente em segundo plano](/docs/pt/sub-agents#run-subagents-in-foreground-or-background) reporta de volta à sessão que o iniciou
1451* Uma [mensagem que outra sessão envia](/docs/pt/cross-session-messaging) chega à sua conversa principal
1448 1452
1449Um hook de callback [Agent SDK](/docs/pt/agent-sdk/hooks) em `UserPromptSubmit` que atinge seu tempo limite bloqueia o prompt com uma mensagem nomeando o hook e o tempo limite, porque um callback lá pode estar agindo como uma porta de política que não deve falhar aberta. A sessão continua. Antes da v2.1.208, um tempo limite de callback naquele evento terminava o turno com um erro de execução.1453Os hooks `UserPromptSubmit` têm um timeout padrão de 30 segundos para os tipos `command`, `http` e `mcp_tool`, menor que o padrão de 600 segundos desses tipos na maioria dos outros eventos. Como este hook é executado antes de cada prompt e bloqueia o processamento do modelo até ser concluído, um hook travado paralisa a sessão. Se o seu hook precisar de mais tempo, defina o campo `timeout` na entrada do hook.
1454
1455Exceto por um hook de comando que você executa com [`async: true`](#run-hooks-in-the-background), um hook `UserPromptSubmit` de comando, HTTP ou ferramenta MCP que atinge seu timeout é cancelado e sua saída, incluindo qualquer `additionalContext`, é descartada. O prompt ainda chega ao Claude sem esse contexto. A transcrição mostra um aviso nomeando o hook, o timeout que foi atingido e que a saída foi descartada.
1456
1457Um [hook de callback do 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 nesse ponto pode estar atuando como uma barreira de política que não deve falhar de forma aberta. A sessão continua. Antes da v2.1.208, um timeout de callback nesse evento encerrava o turno com um erro de execução.
1450 1458
1451<h4 id="userpromptsubmit-input">1459<h4 id="userpromptsubmit-input">
1452 Entrada UserPromptSubmit1460 Entrada do UserPromptSubmit
1453</h4>1461</h4>
1454 1462
1455Além dos [campos de entrada comuns](#common-input-fields), hooks UserPromptSubmit recebem o campo `prompt` contendo o texto que o usuário enviou. Conteúdo colado que colapsou para um espaço reservado `[Pasted text #N]` chega expandido no lugar. Em sessões onde Claude Code [marca texto colado para Claude](/docs/pt/terminal-config#how-claude-treats-pasted-text), esse conteúdo expandido fica entre uma linha `<pasted_content id="…">` e uma linha `</pasted_content id="…">`, então leve em conta essas linhas se seu hook analisa o prompt.1463Além dos [campos de entrada comuns](#common-input-fields), os hooks UserPromptSubmit recebem o campo `prompt` contendo o texto enviado. Conteúdo colado que foi recolhido em um espaço reservado `[Pasted text #N]` chega expandido no lugar. Em sessões em que o Claude Code [marca o texto colado para o Claude](/docs/pt/terminal-config#how-claude-treats-pasted-text), esse conteúdo expandido fica entre uma linha `<pasted_content id="…">` e uma linha `</pasted_content id="…">`, então leve essas linhas em conta se o seu hook analisar o prompt.
1456 1464
1457Hooks UserPromptSubmit também recebem `session_title` quando a sessão tem um título personalizado, com o mesmo significado que o [campo `session_title` de SessionStart](#sessionstart-input).1465Os hooks UserPromptSubmit também recebem `session_title` quando a sessão tem um título personalizado, com o mesmo significado do [campo `session_title` do SessionStart](#sessionstart-input).
1458 1466
1459```json theme={null}1467```json theme={null}
1460{1468{
1468```1476```
1469 1477
1470<h4 id="userpromptsubmit-decision-control">1478<h4 id="userpromptsubmit-decision-control">
1471 Controle de decisão UserPromptSubmit1479 Controle de decisão do UserPromptSubmit
1472</h4>1480</h4>
1473 1481
1474Hooks `UserPromptSubmit` podem controlar se um prompt do usuário é processado e adicionar contexto. Todos os [campos de saída JSON](#json-output) estão disponíveis.1482Os hooks `UserPromptSubmit` podem controlar se um prompt enviado é processado e adicionar contexto. Todos os [campos de saída JSON](#json-output) estão disponíveis.
1475 1483
1476Existem duas maneiras de adicionar contexto à conversa no código de saída 0:1484Há duas formas de adicionar contexto à conversa com código de saída 0:
1477 1485
1478* **Stdout de texto simples**: Claude Code adiciona stdout que [trata como texto simples](#exit-code-0) ao contexto do Claude1486* **Stdout de texto simples**: o Claude Code adiciona ao contexto do Claude o stdout que ele [trata como texto simples](#exit-code-0)
1479* **JSON com `additionalContext`**: use o formato JSON abaixo para mais controle. O campo `additionalContext` é adicionado como contexto1487* **JSON com `additionalContext`**: use o formato JSON abaixo para ter mais controle. O campo `additionalContext` é adicionado como contexto
1480 1488
1481Nenhum canal produz uma entrada de transcrição visível. Stdout simples e o valor `additionalContext` são cada um injetados como um lembrete do sistema que começa com o nome do hook; Claude lê ambos. Para confirmar a entrega, verifique o [log de depuração](#debug-hooks).1489Nenhum dos canais produz uma entrada visível na transcrição. O stdout simples e o valor de `additionalContext` são, cada um, injetados como um lembrete do sistema que começa com o nome do hook; o Claude lê ambos. Para confirmar a entrega, verifique o [log de depuração](#debug-hooks).
1482 1490
1483Para bloquear um prompt, retorne um objeto JSON com `decision` definido como `"block"`:1491Para bloquear um prompt, retorne um objeto JSON com `decision` definido como `"block"`:
1484 1492
1485| Campo | Descrição |1493| Campo | Descrição |
1486| :- | :- |1494| :- | :- |
1487| `decision` | `"block"` impede que o prompt seja processado. Omita para permitir que o prompt prossiga |1495| `decision` | `"block"` interrompe o prompt antes que ele chegue ao Claude. Omita para permitir que o prompt prossiga |
1488| `reason` | Mostrado ao usuário quando `decision` é `"block"`. Não adicionado ao contexto |1496| `reason` | Mostrado ao usuário quando `decision` é `"block"`. Não é adicionado ao contexto |
1489| `additionalContext` | String adicionada ao contexto do Claude junto com o prompt enviado. Veja [Adicionar contexto para Claude](#add-context-for-claude) |1497| `additionalContext` | String adicionada ao contexto do Claude junto com o prompt enviado. Consulte [Adicionar contexto para o Claude](#add-context-for-claude) |
1490| `sessionTitle` | Define o título da sessão. Use para nomear sessões automaticamente com base no conteúdo do prompt |1498| `sessionTitle` | Define o título da sessão. Use para nomear sessões automaticamente com base no conteúdo do prompt |
1491| `suppressOriginalPrompt` | Se `true` quando o hook bloqueia o prompt, deixa o texto do prompt original fora da mensagem de bloqueio. Veja [O que um prompt bloqueado deixa para trás](#what-a-blocked-prompt-leaves-behind) |1499| `suppressOriginalPrompt` | Se `true` quando o hook bloqueia o prompt, deixa o texto do prompt fora da mensagem de bloqueio. Consulte [O que um prompt bloqueado deixa para trás](#what-a-blocked-prompt-leaves-behind) |
1492 1500
1493Um hook que bloqueia ao sair com 2 roteia da mesma forma que `reason`: a mensagem de bloqueio mostra o texto stderr ao usuário, e não é adicionada ao contexto.1501Um hook que bloqueia saindo com 2 é encaminhado da mesma forma que `reason`: a mensagem de bloqueio mostra o texto do stderr ao usuário, e ele não é adicionado ao contexto.
1494 1502
1495```json theme={null}1503```json theme={null}
1496{1504{
1509 O que um prompt bloqueado deixa para trás1517 O que um prompt bloqueado deixa para trás
1510</h4>1518</h4>
1511 1519
1512Um prompt bloqueado nunca chega ao Claude, mas seu texto não é removido em todos os lugares. Por padrão, a mensagem de bloqueio mostrada ao usuário termina com `Original prompt:` seguido pelo texto enviado, e Claude Code escreve essa mensagem no arquivo de transcrição da sessão no disco. Para deixar o texto fora da mensagem, imprima JSON com `"suppressOriginalPrompt": true` dentro de `hookSpecificOutput`. Isso funciona se o hook bloqueia com `decision: "block"` ou ao sair com 2. Um hook de saída 2 que não imprime JSON sempre obtém o texto do prompt em sua mensagem de bloqueio.1520Um prompt bloqueado nunca chega ao Claude, mas seu texto não é removido de todos os lugares. Por padrão, a mensagem de bloqueio mostrada ao usuário termina com `Original prompt:` seguido do texto enviado, e o Claude Code grava essa mensagem no arquivo de transcrição da sessão no disco. Para deixar o texto fora da mensagem, imprima JSON com `"suppressOriginalPrompt": true` dentro de `hookSpecificOutput`. Isso funciona tanto se o hook bloquear com `decision: "block"` quanto saindo com 2. Um hook com saída 2 que não imprime JSON sempre recebe o texto do prompt em sua mensagem de bloqueio.
1513 1521
1514`suppressOriginalPrompt` muda apenas a mensagem de bloqueio. O texto enviado ainda pode aparecer em arquivos locais como a transcrição da sessão e seu histórico de prompts, então um hook de bloqueio não é uma maneira de manter um segredo fora do disco. Para limitar ou remover esses arquivos, veja [Armazenamento em texto simples](/docs/pt/claude-directory#plaintext-storage) e [Limpar dados locais](/docs/pt/claude-directory#clear-local-data).1522`suppressOriginalPrompt` altera apenas a mensagem de bloqueio. O texto enviado ainda pode aparecer em arquivos locais, como a transcrição da sessão e seu histórico de prompts, então um hook de bloqueio não é uma forma de manter um segredo fora do disco. Para limitar ou remover esses arquivos, consulte [Armazenamento em texto simples](/docs/pt/claude-directory#plaintext-storage) e [Limpar dados locais](/docs/pt/claude-directory#clear-local-data).
1515 1523
1516<h3 id="userpromptexpansion">1524<h3 id="userpromptexpansion">
1517 UserPromptExpansion1525 UserPromptExpansion
1518</h3>1526</h3>
1519 1527
1520Executa quando um comando digitado pelo usuário se expande em um prompt antes de chegar ao Claude. Use isso para bloquear comandos específicos de invocação direta, injetar contexto para uma skill particular ou registrar quais comandos os usuários invocam. Por exemplo, um hook correspondente a `deploy` pode bloquear `/deploy` a menos que um arquivo de aprovação esteja presente, ou um hook correspondente a uma skill de revisão pode anexar a lista de verificação de revisão da equipe como `additionalContext`.1528É executado quando um comando digitado pelo usuário se expande em um prompt antes de chegar ao Claude. Use isso para impedir que comandos específicos sejam invocados diretamente, injetar contexto para uma skill específica ou registrar em log quais comandos os usuários invocam. Por exemplo, um hook que corresponde a `deploy` pode bloquear `/deploy` a menos que um arquivo de aprovação esteja presente, ou um hook que corresponde a uma skill de revisão pode anexar a checklist de revisão da equipe como `additionalContext`.
1521 1529
1522Este evento cobre o caminho que `PreToolUse` não cobre: um hook `PreToolUse` correspondente à ferramenta `Skill` dispara apenas quando Claude chama a ferramenta, mas digitar `/skillname` diretamente ignora `PreToolUse`. `UserPromptExpansion` dispara naquele caminho direto.1530Este evento cobre o caminho que o `PreToolUse` não cobre: um hook `PreToolUse` que corresponde à ferramenta `Skill` é disparado somente quando o Claude chama a ferramenta, mas digitar `/skillname` diretamente contorna o `PreToolUse`. O `UserPromptExpansion` é disparado nesse caminho direto.
1523 1531
1524Corresponde a `command_name`. Deixe o matcher vazio para disparar em cada comando do tipo prompt.1532Faz a correspondência em `command_name`. Deixe o matcher vazio para disparar em todo comando do tipo prompt.
1525 1533
1526<h4 id="userpromptexpansion-input">1534<h4 id="userpromptexpansion-input">
1527 Entrada UserPromptExpansion1535 Entrada do UserPromptExpansion
1528</h4>1536</h4>
1529 1537
1530Além dos [campos de entrada comuns](#common-input-fields), hooks UserPromptExpansion recebem `expansion_type`, `command_name`, `command_args`, `command_source` e a string `prompt` original. O campo `expansion_type` é `slash_command` para skills e comandos personalizados, ou `mcp_prompt` para prompts do servidor MCP.1538Além dos [campos de entrada comuns](#common-input-fields), os hooks UserPromptExpansion recebem `expansion_type`, `command_name`, `command_args`, `command_source` e a string `prompt` original. O campo `expansion_type` é `slash_command` para skills e comandos personalizados, ou `mcp_prompt` para prompts de servidor MCP.
1531 1539
1532```json theme={null}1540```json theme={null}
1533{1541{
1545```1553```
1546 1554
1547<h4 id="userpromptexpansion-decision-control">1555<h4 id="userpromptexpansion-decision-control">
1548 Controle de decisão UserPromptExpansion1556 Controle de decisão do UserPromptExpansion
1549</h4>1557</h4>
1550 1558
1551Hooks `UserPromptExpansion` podem bloquear a expansão ou adicionar contexto. Todos os [campos de saída JSON](#json-output) estão disponíveis.1559Os hooks `UserPromptExpansion` podem bloquear a expansão ou adicionar contexto. Todos os [campos de saída JSON](#json-output) estão disponíveis.
1552 1560
1553| Campo | Descrição |1561| Campo | Descrição |
1554| :- | :- |1562| :- | :- |
1555| `decision` | `"block"` impede que o comando se expanda. Omita para permitir que prossiga |1563| `decision` | `"block"` impede que o comando se expanda. Omita para permitir que ele prossiga |
1556| `reason` | Mostrado ao usuário quando `decision` é `"block"` |1564| `reason` | Mostrado ao usuário quando `decision` é `"block"` |
1557| `additionalContext` | String adicionada ao contexto do Claude junto com o prompt expandido. Veja [Adicionar contexto para Claude](#add-context-for-claude) |1565| `additionalContext` | String adicionada ao contexto do Claude junto com o prompt expandido. Consulte [Adicionar contexto para o Claude](#add-context-for-claude) |
1558 1566
1559Um hook que bloqueia ao sair com 2 roteia da mesma forma que `reason`: a mensagem de bloqueio mostra o texto stderr ao usuário.1567Um hook que bloqueia saindo com 2 é encaminhado da mesma forma que `reason`: a mensagem de bloqueio mostra o texto do stderr ao usuário.
1560 1568
1561```json theme={null}1569```json theme={null}
1562{1570{
1573 MessageDisplay1581 MessageDisplay
1574</h3>1582</h3>
1575 1583
1576Executa enquanto uma mensagem do assistente é transmitida para a tela. Claude Code exibe a mensagem em incrementos: cada vez que um lote de linhas recém-concluídas está pronto para renderizar, o hook é executado uma vez com essas linhas e Claude Code renderiza o texto de substituição do hook em seu lugar. Uma mensagem longa produz várias chamadas; uma mensagem curta pode produzir apenas uma.1584É executado enquanto uma mensagem do assistente é transmitida para a tela. O Claude Code exibe a mensagem em incrementos: cada vez que um lote de linhas recém-concluídas está pronto para renderização, o hook é executado uma vez com essas linhas e o Claude Code renderiza o texto de substituição do hook no lugar delas. Uma mensagem longa produz várias chamadas; uma mensagem curta pode produzir apenas uma.
1577 1585
1578Use MessageDisplay para:1586Use o MessageDisplay para:
1579 1587
1580* remover markdown para uma exibição mínima1588* remover markdown para uma exibição mínima
1581* transformar o texto que um aplicativo Agent SDK mostra aos seus usuários1589* transformar o texto que uma aplicação do Agent SDK mostra aos seus usuários
1582* redactar chaves de API ou nomes de host internos das respostas do Claude1590* ocultar chaves de API ou hostnames internos das respostas do Claude
1583 1591
1584Claude Code mantém cada lote até que seu hook retorne, então mantenha o hook rápido. Se o hook falhar ou atingir o tempo limite, Claude Code exibe o texto original. O tempo limite padrão para este evento é 10 segundos; se seu hook precisar de mais tempo, defina o campo `timeout` na entrada do hook.1592O Claude Code retém cada lote até que seu hook retorne, então mantenha o hook rápido. Se o hook falhar ou atingir o timeout, o Claude Code exibe o texto original. O timeout padrão para este evento é de 10 segundos; se o seu hook precisar de mais tempo, defina o campo `timeout` na entrada do hook.
1585 1593
1586MessageDisplay é apenas para exibição: o texto de substituição muda apenas o que é renderizado na tela. A transcrição e o que Claude vê mantêm o texto original, então Claude nunca vê a substituição, e o modo detalhado mostra o original. O hook recebe apenas texto de mensagem do assistente, então resultados de ferramentas e o texto que você digita são renderizados inalterados.1594O MessageDisplay serve apenas para exibição: o texto de substituição altera somente o que é renderizado na tela. A transcrição e o que o Claude vê mantêm o texto original, então o Claude nunca vê a substituição, e o modo verbose mostra o original. O hook recebe apenas o texto das mensagens do assistente, então os resultados de ferramentas e o texto que você digita são renderizados sem alteração.
1587 1595
1588MessageDisplay não suporta matchers e dispara para cada mensagem do assistente que transmite texto; mensagens sem texto, como respostas apenas de chamada de ferramenta, não o disparam.1596O MessageDisplay não suporta matchers e é disparado para toda mensagem do assistente que transmite texto; mensagens sem texto, como respostas que contêm apenas chamadas de ferramenta, não o acionam.
1589 1597
1590Em execuções não interativas, incluindo consultas Agent SDK e `claude -p`, MessageDisplay é executado uma vez por mensagem do assistente em vez de uma vez por lote de linhas. A chamada única chega após a mensagem ser concluída e carrega o texto completo da mensagem: `index` é `0`, `final` é `true` e `delta` contém a mensagem inteira. Um hook que coleta o texto `delta` para cada mensagem recebe o mesmo texto total em ambos os modos.1598Em execuções não interativas, incluindo consultas do Agent SDK e `claude -p`, o MessageDisplay é executado uma vez por mensagem do assistente em vez de uma vez por lote de linhas. A chamada única chega depois que a mensagem é concluída e carrega o texto completo da mensagem: `index` é `0`, `final` é `true` e `delta` contém a mensagem inteira. Um hook que coleta o texto de `delta` de cada mensagem recebe o mesmo texto total em ambos os modos.
1591 1599
1592<h4 id="messagedisplay-input">1600<h4 id="messagedisplay-input">
1593 Entrada MessageDisplay1601 Entrada do MessageDisplay
1594</h4>1602</h4>
1595 1603
1596Além dos [campos de entrada comuns](#common-input-fields), hooks MessageDisplay recebem identificadores para o turno e mensagem, a posição desta chamada dentro da mensagem e o novo texto em `delta`. Os limites de lote dependem de como o texto é transmitido, então use `index` e `final` para rastrear o progresso através de uma mensagem em vez de esperar que as linhas sejam agrupadas de uma forma particular.1604Além dos [campos de entrada comuns](#common-input-fields), os hooks MessageDisplay recebem identificadores do turno e da mensagem, a posição desta chamada dentro da mensagem e o novo texto em `delta`. Os limites dos lotes dependem de como o texto é transmitido, então use `index` e `final` para acompanhar o progresso de uma mensagem em vez de esperar que as linhas sejam agrupadas de uma forma específica.
1597 1605
1598| Campo | Descrição |1606| Campo | Descrição |
1599| :- | :- |1607| :- | :- |
1600| `turn_id` | UUID do turno atual |1608| `turn_id` | UUID do turno atual |
1601| `message_id` | UUID da mensagem do assistente sendo exibida. Estável em cada lote da mesma mensagem. Este não é o ID `msg_…` da API, então não pode ser correlacionado com IDs de mensagem de transcrição |1609| `message_id` | UUID da mensagem do assistente sendo exibida. Estável em todos os lotes da mesma mensagem. Este não é o id `msg_…` da API, então não pode ser correlacionado com os ids de mensagens da transcrição |
1602| `index` | Índice baseado em zero deste lote dentro da mensagem |1610| `index` | Índice, começando em zero, deste lote dentro da mensagem |
1603| `final` | `true` no último lote da mensagem. Cada mensagem tem exatamente um lote final |1611| `final` | `true` no último lote da mensagem. Cada mensagem tem exatamente um lote final |
1604| `delta` | As linhas recém-concluídas desde o lote anterior, incluindo quebras de linha finais. Sempre linhas inteiras, exceto o lote final que pode terminar no meio da linha. Em execuções interativas, o delta do lote final está vazio quando a mensagem termina em uma quebra de linha, então trate `final`, não um delta não vazio, como o sinal de fim de mensagem. Em execuções Agent SDK e `claude -p`, a chamada única carrega a mensagem inteira |1612| `delta` | As linhas recém-concluídas desde o lote anterior, incluindo as quebras de linha finais. Sempre linhas inteiras, exceto o lote final, que pode terminar no meio de uma linha. Em execuções interativas, o delta do lote final fica vazio quando a mensagem termina com uma quebra de linha, então trate `final`, e não um delta não vazio, como o sinal de fim da mensagem. Em execuções do Agent SDK e de `claude -p`, a chamada única carrega a mensagem inteira |
1605 1613
1606```json theme={null}1614```json theme={null}
1607{1615{
1618```1626```
1619 1627
1620<h4 id="messagedisplay-output">1628<h4 id="messagedisplay-output">
1621 Saída MessageDisplay1629 Saída do MessageDisplay
1622</h4>1630</h4>
1623 1631
1624Além dos [campos de saída JSON](#json-output) disponíveis para todos os hooks, hooks MessageDisplay podem retornar `displayContent` para substituir o delta na tela:1632Além dos [campos de saída JSON](#json-output) disponíveis para todos os hooks, os hooks MessageDisplay podem retornar `displayContent` para substituir o delta na tela:
1625 1633
1626| Campo | Descrição |1634| Campo | Descrição |
1627| :- | :- |1635| :- | :- |
1628| `displayContent` | Texto exibido no lugar do delta. Omita para exibir o original |1636| `displayContent` | Texto exibido no lugar do delta. Omita-o para exibir o original |
1629 1637
1630Hooks MessageDisplay não têm controle de decisão. Eles não podem bloquear a mensagem ou mudar o que é armazenado na transcrição ou enviado ao Claude. Claude Code age em `displayContent` de sua saída JSON e descarta `systemMessage` e `continue`.1638Os hooks MessageDisplay não têm controle de decisão. Eles não podem bloquear a mensagem nem alterar o que é armazenado na transcrição ou enviado ao Claude. O Claude Code age com base em `displayContent` da saída JSON deles e descarta `systemMessage` e `continue`.
1631 1639
1632Este exemplo remove formatação markdown das respostas do Claude para uma exibição de texto simples. O script lê cada lote de stdin, remove marcadores em negrito e backticks de código inline de `delta` e retorna o resultado como `displayContent`.1640Este exemplo remove a formatação markdown das respostas do Claude para uma exibição em texto simples. O script lê cada lote do stdin, remove os marcadores de negrito e os acentos graves de código inline de `delta` e retorna o resultado como `displayContent`.
1633 1641
1634<Tabs>1642<Tabs>
1635 <Tab title="macOS/Linux">1643 <Tab title="macOS/Linux">
1636 Registre um hook de comando para o evento em seu arquivo de configurações:1644 Registre um hook de comando para o evento no seu arquivo de configurações:
1637 1645
1638 ```json theme={null}1646 ```json theme={null}
1639 {1647 {
1653 }1661 }
1654 ```1662 ```
1655 1663
1656 Salve este script em `.claude/hooks/plain-display.sh` em seu projeto e torne-o executável com `chmod +x`:1664 Salve este script em `.claude/hooks/plain-display.sh` no seu projeto e torne-o executável com `chmod +x`:
1657 1665
1658 ```bash theme={null}1666 ```bash theme={null}
1659 #!/bin/bash1667 #!/bin/bash
1662 </Tab>1670 </Tab>
1663 1671
1664 <Tab title="Windows (PowerShell)">1672 <Tab title="Windows (PowerShell)">
1665 Registre um hook de comando que executa o script através do PowerShell:1673 Registre um hook de comando que executa o script por meio do PowerShell:
1666 1674
1667 ```json theme={null}1675 ```json theme={null}
1668 {1676 {
1688 }1696 }
1689 ```1697 ```
1690 1698
1691 A flag `-NoProfile` pula o carregamento de seu perfil do PowerShell para que o hook comece rápido, e `-ExecutionPolicy Bypass` permite que o PowerShell execute o arquivo de script local.1699 A flag `-NoProfile` pula o carregamento do seu perfil do PowerShell para que o hook inicie rapidamente, e `-ExecutionPolicy Bypass` permite que o PowerShell execute o arquivo de script local.
1692 1700
1693 Salve este script em `.claude/hooks/plain-display.ps1` em seu projeto:1701 Salve este script em `.claude/hooks/plain-display.ps1` no seu projeto:
1694 1702
1695 ```powershell theme={null}1703 ```powershell theme={null}
1696 $batch = [Console]::In.ReadToEnd() | ConvertFrom-Json1704 $batch = [Console]::In.ReadToEnd() | ConvertFrom-Json
1705 </Tab>1713 </Tab>
1706</Tabs>1714</Tabs>
1707 1715
1708Lotes sem markdown passam inalterados. Se o script falhar, por exemplo porque `jq` está faltando, Claude Code exibe o texto original e nota a falha apenas em [saída de depuração](#debug-hooks), não na sessão.1716Lotes sem markdown passam sem alteração. Se o script falhar, por exemplo porque o `jq` não está instalado, o Claude Code exibe o texto original e registra a falha somente na [saída de depuração](#debug-hooks), não na sessão.
1709 1717
1710<h3 id="pretooluse">1718<h3 id="pretooluse">
1711 PreToolUse1719 PreToolUse
1712</h3>1720</h3>
1713 1721
1714Executa após Claude criar parâmetros de ferramenta e antes de processar a chamada de ferramenta. Corresponde a qualquer nome de ferramenta exceto `EndConversation`: ferramentas integradas como `Bash`, `PowerShell`, `Edit`, `Write`, `Read`, `Glob`, `Grep`, `Agent`, `Workflow`, `WebFetch`, `WebSearch`, `AskUserQuestion` e `ExitPlanMode`, e qualquer [nome de ferramenta MCP](#match-mcp-tools).1722É executado depois que o Claude cria os parâmetros da ferramenta e antes de processar a chamada de ferramenta. Faz a correspondência com qualquer nome de ferramenta exceto `EndConversation`: ferramentas integradas como `Bash`, `PowerShell`, `Edit`, `Write`, `Read`, `Glob`, `Grep`, `Agent`, `Workflow`, `WebFetch`, `WebSearch`, `AskUserQuestion` e `ExitPlanMode`, e quaisquer [nomes de ferramentas MCP](#match-mcp-tools).
1715 1723
1716Para executar um hook quando um arquivo específico muda no disco, seja qual for o que o escreveu, use [FileChanged](#filechanged) em vez de corresponder a ferramentas de edição de arquivo por nome. Ao contrário de PreToolUse, Claude Code executa hooks FileChanged após a mudança, e eles não têm controle de decisão, então não podem bloquear a escrita.1724Para executar um hook quando um arquivo específico muda no disco, independentemente de quem o gravou, use o [FileChanged](#filechanged) em vez de fazer a correspondência de ferramentas de edição de arquivos pelo nome. Diferentemente do PreToolUse, o Claude Code executa os hooks FileChanged após a alteração, e eles não têm controle de decisão, então não podem bloquear a gravação.
1717 1725
1718<Warning>1726<Warning>
1719 PreToolUse é executado 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 nenhuma chamada de ferramenta: Claude Code insere seu conteúdo ao construir o prompt, então nenhum hook PreToolUse dispara para eles, incluindo hooks correspondentes 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.1727 O PreToolUse é executado somente quando o Claude chama uma ferramenta. Os arquivos que você [referencia com `@` no seu prompt](/docs/pt/common-workflows#reference-files-and-directories) são adicionados sem nenhuma chamada de ferramenta: o Claude Code insere o conteúdo deles ao montar o prompt, então nenhum hook PreToolUse é disparado para eles, incluindo hooks que correspondem a `Read`. Para impedir caminhos específicos em referências `@`, use uma [regra de negação de `Read`](/docs/pt/permissions#read-and-edit).
1720 1728
1721 PreToolUse também não dispara para [`EndConversation`](/docs/pt/tools-reference#endconversation-tool-behavior).1729 O PreToolUse também não é disparado para [`EndConversation`](/docs/pt/tools-reference#endconversation-tool-behavior).
1722</Warning>1730</Warning>
1723 1731
1724Use [controle de decisão PreToolUse](#pretooluse-decision-control) para permitir, negar, perguntar ou adiar a chamada de ferramenta.1732Use o [controle de decisão do PreToolUse](#pretooluse-decision-control) para permitir, negar, perguntar ou adiar a chamada de ferramenta.
1725 1733
1726Um hook de callback [Agent SDK](/docs/pt/agent-sdk/hooks) em `PreToolUse` que excede seu tempo limite bloqueia a chamada de ferramenta, e Claude recebe um resultado de erro nomeando o tempo limite. Uma negação explícita retornada por outro hook ainda tem precedência.1734Um [hook de callback do Agent SDK](/docs/pt/agent-sdk/hooks) em `PreToolUse` que excede seu timeout bloqueia a chamada de ferramenta, e o Claude recebe um resultado de erro nomeando o timeout. Uma negação explícita retornada por outro hook ainda tem precedência.
1727 1735
1728<h4 id="pretooluse-input">1736<h4 id="pretooluse-input">
1729 Entrada PreToolUse1737 Entrada do PreToolUse
1730</h4>1738</h4>
1731 1739
1732Além dos [campos de entrada comuns](#common-input-fields), hooks PreToolUse recebem `tool_name`, `tool_input` e `tool_use_id`.1740Além dos [campos de entrada comuns](#common-input-fields), os hooks PreToolUse recebem `tool_name`, `tool_input` e `tool_use_id`.
1733 1741
1734Para uma [ferramenta MCP](#match-mcp-tools), a entrada também carrega `mcp_server`, um objeto com o `name` do servidor e uma `source` que diz de onde veio a definição do servidor. Os valores `source` incluem `plugin`, `sdk` e escopos de configuração como `user` e `project`. [`McpServerProvenance`](/docs/pt/agent-sdk/typescript#mcpserverprovenance) na referência Agent SDK lista todos eles e diz como tratar um que você não reconhece. Baseie decisões de confiança em `source` em vez de em `name` ou no prefixo de nome de ferramenta `mcp__<server>__`. O campo `mcp_server` requer Claude Code v2.1.274 ou posterior.1742Para uma [ferramenta MCP](#match-mcp-tools), a entrada também carrega `mcp_server`, um objeto com o `name` do servidor e um `source` que informa de onde veio a definição do servidor. Os valores de `source` incluem `plugin`, `sdk` e escopos de configuração como `user` e `project`. [`McpServerProvenance`](/docs/pt/agent-sdk/typescript#mcpserverprovenance) na referência do Agent SDK lista todos eles e explica como tratar um que você não reconhece. Baseie as decisões de confiança em `source`, e não em `name` ou no prefixo de nome de ferramenta `mcp__<server>__`. O campo `mcp_server` exige o Claude Code v2.1.274 ou posterior.
1735 1743
1736Para as ferramentas de arquivo `Write`, `Edit` e `Read`, `tool_input.file_path` é sempre absoluto:1744Para as ferramentas de arquivo `Write`, `Edit` e `Read`, `tool_input.file_path` é sempre absoluto:
1737 1745
1738* Claude Code expande `~` e caminhos relativos antes dos hooks serem executados, então um hook que corresponde a caminhos não pode ser contornado via `~` ou uma ortografia relativa do mesmo caminho1746* O Claude Code expande `~` e caminhos relativos antes de os hooks serem executados, então um hook que faz correspondência em caminhos não pode ser contornado via `~` ou uma forma relativa de escrever o mesmo caminho
1739* No Windows, o caminho chega com separadores de barra invertida, mesmo quando seu hook é executado sob Git Bash onde `$PWD` parece `/c/project`1747* No Windows, o caminho chega com separadores de barra invertida, mesmo quando seu hook é executado no Git Bash, onde `$PWD` se parece com `/c/project`
1740* Uma comparação escrita com barras para frente, como uma verificação `/src/`, nunca corresponde a um caminho de barra invertida, e a chamada de ferramenta prossegue como se o hook não tivesse nada a bloquear1748* Uma comparação escrita com barras normais, como uma verificação de `/src/`, nunca corresponde a um caminho com barras invertidas, e a chamada de ferramenta prossegue como se o hook não tivesse nada a bloquear
1741* Normalize separadores antes de comparar: `FILE_PATH="${FILE_PATH//\\//}"` em Bash, ou `file_path.replace("\\", "/")` em Python, depois corresponda a um segmento de caminho como `/src/` em vez de ancorar com `^`, já que o caminho é absoluto1749* Normalize os separadores antes de comparar: `FILE_PATH="${FILE_PATH//\\//}"` no Bash, ou `file_path.replace("\\", "/")` no Python, e então faça a correspondência de um segmento de caminho como `/src/` em vez de ancorar com `^`, já que o caminho é absoluto
1742 1750
1743Uma chamada `Write` no Windows entrega:1751Uma chamada `Write` no Windows entrega:
1744 1752
1754}1762}
1755```1763```
1756 1764
1757Os campos `tool_input` dependem da ferramenta:1765Os campos de `tool_input` dependem da ferramenta:
1758 1766
1759<a id="bash" />1767<a id="bash" />
1760 1768
1766 1774
1767| Campo | Tipo | Exemplo | Descrição |1775| Campo | Tipo | Exemplo | Descrição |
1768| :- | :- | :- | :- |1776| :- | :- | :- | :- |
1769| `command` | string | `"npm test"` | O comando de shell a executar |1777| `command` | string | `"npm test"` | O comando de shell a ser executado |
1770| `description` | string | `"Run test suite"` | Descrição opcional do que o comando faz |1778| `description` | string | `"Run test suite"` | Descrição opcional do que o comando faz |
1771| `timeout` | number | `120000` | Tempo limite 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 |1779| `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 |
1772| `run_in_background` | boolean | `false` | Se o comando deve ser executado em segundo plano |1780| `run_in_background` | boolean | `false` | Se o comando deve ser executado em segundo plano |
1773 1781
1774Quando um comando Bash muda arquivos em um repositório Git, Claude Code pode registrar o que mudou. Ele registra as mudanças em cada modo de permissão quando a configuração [`bashEditDiffEnabled`](/docs/pt/settings-reference#basheditdiffenabled) ativa o registro; a entrada dessa configuração diz quais arquivos podem defini-la. Caso contrário, ele as registra apenas em modo automático e modo `bypassPermissions`, e apenas quando Claude Code direciona Claude a editar arquivos através de Bash. Defina `bashEditDiffEnabled` como `false` para desativar o registro. Comandos de fundo e comandos somente leitura não carregam diff.1782Quando um comando Bash altera arquivos em um repositório Git, o Claude Code pode registrar o que mudou. Ele registra as alterações em todos os modos de permissão quando a configuração [`bashEditDiffEnabled`](/docs/pt/settings-reference#basheditdiffenabled) ativa o registro; a entrada dessa configuração informa quais arquivos podem defini-la. Caso contrário, ele as registra somente no modo auto e no modo `bypassPermissions`, e somente quando o Claude Code orienta o Claude a editar arquivos por meio do Bash. Defina `bashEditDiffEnabled` como `false` para desativar o registro. Comandos em segundo plano e comandos somente leitura não carregam diff.
1775 1783
1776Seu hook [PostToolUse](#posttooluse) então recebe os arquivos alterados em `tool_response.bashEditDiff`. A lista cobre o que mudou sob o repositório enquanto o comando era executado. Arquivos que Git ignora e arquivos em submódulos não são listados. Requer Claude Code v2.1.269 ou posterior.1784Seu [hook PostToolUse](#posttooluse) então recebe os arquivos alterados em `tool_response.bashEditDiff`. A lista cobre o que mudou no repositório enquanto o comando era executado. Arquivos que o Git ignora e arquivos em submódulos não são listados. Exige o Claude Code v2.1.269 ou posterior.
1777 1785
1778<Note>1786<Note>
1779 A lista é melhor esforço e em beta público. Claude Code pode perder uma mudança, incluir um arquivo que outro processo mudou ao mesmo tempo, ou parar em seus limites de tamanho. A forma do campo pode mudar. Use a lista para encontrar o que revisar, não para impor uma política.1787 A lista é de melhor esforço e está em beta público. O Claude Code pode deixar de detectar uma alteração, incluir um arquivo que outro processo alterou ao mesmo tempo ou parar em seus limites de tamanho. O formato do campo pode mudar. Use a lista para encontrar o que revisar, não para impor uma política.
1780</Note>1788</Note>
1781 1789
1782`changedFiles` e `files` listam o que o comando mudou; os campos restantes dizem como completo e confiável é essa lista.1790`changedFiles` e `files` listam o que o comando alterou; os campos restantes informam quão completa e quão confiável é essa lista.
1783 1791
1784| Campo | Tipo | Exemplo | Descrição |1792| Campo | Tipo | Exemplo | Descrição |
1785| :- | :- | :- | :- |1793| :- | :- | :- | :- |
1786| `changedFiles` | array | `["/path/to/src/app.ts"]` | Caminhos absolutos dos arquivos que o comando mudou, no máximo 200. Presente sempre que `files` contém um diff ou `moreFiles` está acima de zero |1794| `changedFiles` | array | `["/path/to/src/app.ts"]` | Caminhos absolutos dos arquivos que o comando alterou, no máximo 200. Presente sempre que `files` contém um diff ou `moreFiles` é maior que zero |
1787| `files` | array | `[{"filePath": "/path/to/src/app.ts", "hunks": [...]}]` | Diffs de até 5 arquivos alterados, para exibição. `created` ou `deleted` é `true` para um arquivo que o comando adicionou ou removeu |1795| `files` | array | `[{"filePath": "/path/to/src/app.ts", "hunks": [...]}]` | Diffs de até 5 arquivos alterados, para exibição. `created` ou `deleted` é `true` para um arquivo que o comando adicionou ou removeu |
1788| `moreFiles` | number | `2` | Contagem de arquivos alterados sem diff em `files` |1796| `moreFiles` | number | `2` | Contagem de arquivos alterados sem diff em `files` |
1789| `unavailable` | boolean | `true` | Definido quando o diff está incompleto ou não pôde ser obtido |1797| `unavailable` | boolean | `true` | Definido quando o diff está incompleto ou não pôde ser obtido |
1790| `skipped` | boolean | `true` | Definido para um comando Git que move a árvore de trabalho, como `git checkout` ou `git stash`, então Claude Code não obtém diff |1798| `skipped` | boolean | `true` | Definido para um comando Git que move a árvore de trabalho, como `git checkout` ou `git stash`, de modo que o Claude Code não obtém diff |
1791| `shared` | boolean | `true` | Definido quando outra chamada de ferramenta Bash, como a de um subagente, foi executada no mesmo repositório ao mesmo tempo, então algumas mudanças listadas podem ser daquele comando |1799| `shared` | boolean | `true` | Definido quando outra chamada da ferramenta Bash, como a de um subagente, foi executada no mesmo repositório ao mesmo tempo, de modo que algumas alterações listadas podem ser desse comando |
1792 1800
1793<a id="powershell" />1801<a id="powershell" />
1794 1802
1796 PowerShell1804 PowerShell
1797</h5>1805</h5>
1798 1806
1799Executa comandos do PowerShell. Veja a [ferramenta PowerShell](/docs/pt/tools-reference#powershell-tool) para disponibilidade por plataforma.1807Executa comandos do PowerShell. Consulte a [ferramenta PowerShell](/docs/pt/tools-reference#powershell-tool) para ver a disponibilidade por plataforma.
1800 1808
1801Os campos correspondem à ferramenta Bash, com a string de comando em `command`:1809Os campos correspondem aos da ferramenta Bash, com a string do comando em `command`:
1802 1810
1803| Campo | Tipo | Exemplo | Descrição |1811| Campo | Tipo | Exemplo | Descrição |
1804| :- | :- | :- | :- |1812| :- | :- | :- | :- |
1805| `command` | string | `"Get-ChildItem -Recurse"` | O comando do PowerShell a executar |1813| `command` | string | `"Get-ChildItem -Recurse"` | O comando do PowerShell a ser executado |
1806| `description` | string | `"List files recursively"` | Descrição opcional do que o comando faz |1814| `description` | string | `"List files recursively"` | Descrição opcional do que o comando faz |
1807| `timeout` | number | `120000` | Tempo limite opcional em milissegundos |1815| `timeout` | number | `120000` | Timeout opcional em milissegundos |
1808| `run_in_background` | boolean | `false` | Se o comando deve ser executado em segundo plano |1816| `run_in_background` | boolean | `false` | Se o comando deve ser executado em segundo plano |
1809 1817
1810Corresponda a `Bash|PowerShell` em hooks que inspecionam comandos de shell, para que cubram ambas as ferramentas:1818Use `Bash|PowerShell` como matcher em hooks que inspecionam comandos de shell, para que cubram ambas as ferramentas:
1811 1819
1812* No Windows, onde quer que a ferramenta PowerShell esteja habilitada, Claude trata PowerShell como o shell primário e roteia comandos de shell através dele.1820* No Windows, onde quer que a ferramenta PowerShell esteja habilitada, o Claude trata o PowerShell como o shell principal e encaminha os comandos de shell por meio dele.
1813* No Windows sem Git Bash, a ferramenta é habilitada automaticamente e Claude Code não registra a ferramenta Bash.1821* No Windows sem Git Bash, a ferramenta é habilitada automaticamente e o Claude Code não registra a ferramenta Bash.
1814* Um hook que corresponde apenas a `Bash` nunca dispara lá.1822* Um hook que corresponde apenas a `Bash` nunca é disparado nesse caso.
1815 1823
1816<h5 id="write">1824<h5 id="write">
1817 Write1825 Write
1821 1829
1822| Campo | Tipo | Exemplo | Descrição |1830| Campo | Tipo | Exemplo | Descrição |
1823| :- | :- | :- | :- |1831| :- | :- | :- | :- |
1824| `file_path` | string | `"/path/to/file.txt"` | Caminho absoluto para o arquivo a escrever |1832| `file_path` | string | `"/path/to/file.txt"` | Caminho absoluto para o arquivo a ser gravado |
1825| `content` | string | `"file content"` | Conteúdo a escrever no arquivo |1833| `content` | string | `"file content"` | Conteúdo a ser gravado no arquivo |
1826 1834
1827<h5 id="edit">1835<h5 id="edit">
1828 Edit1836 Edit
1832 1840
1833| Campo | Tipo | Exemplo | Descrição |1841| Campo | Tipo | Exemplo | Descrição |
1834| :- | :- | :- | :- |1842| :- | :- | :- | :- |
1835| `file_path` | string | `"/path/to/file.txt"` | Caminho absoluto para o arquivo a editar |1843| `file_path` | string | `"/path/to/file.txt"` | Caminho absoluto para o arquivo a ser editado |
1836| `old_string` | string | `"original text"` | Texto a encontrar e substituir |1844| `old_string` | string | `"original text"` | Texto a ser encontrado e substituído |
1837| `new_string` | string | `"replacement text"` | Texto de substituição |1845| `new_string` | string | `"replacement text"` | Texto de substituição |
1838| `replace_all` | boolean | `false` | Se deve substituir todas as ocorrências |1846| `replace_all` | boolean | `false` | Se todas as ocorrências devem ser substituídas |
1839 1847
1840<h5 id="read">1848<h5 id="read">
1841 Read1849 Read
1842</h5>1850</h5>
1843 1851
1844Lê conteúdo de arquivo.1852Lê o conteúdo de arquivos.
1845 1853
1846| Campo | Tipo | Exemplo | Descrição |1854| Campo | Tipo | Exemplo | Descrição |
1847| :- | :- | :- | :- |1855| :- | :- | :- | :- |
1848| `file_path` | string | `"/path/to/file.txt"` | Caminho absoluto para o arquivo a ler |1856| `file_path` | string | `"/path/to/file.txt"` | Caminho absoluto para o arquivo a ser lido |
1849| `offset` | number | `10` | Número de linha opcional para começar a ler |1857| `offset` | number | `10` | Número de linha opcional a partir do qual começar a leitura |
1850| `limit` | number | `50` | Número opcional de linhas a ler |1858| `limit` | number | `50` | Número opcional de linhas a serem lidas |
1851 1859
1852<h5 id="glob">1860<h5 id="glob">
1853 Glob1861 Glob
1854</h5>1862</h5>
1855 1863
1856Encontra arquivos correspondentes a um padrão glob.1864Encontra arquivos que correspondem a um padrão glob.
1857 1865
1858| Campo | Tipo | Exemplo | Descrição |1866| Campo | Tipo | Exemplo | Descrição |
1859| :- | :- | :- | :- |1867| :- | :- | :- | :- |
1860| `pattern` | string | `"**/*.ts"` | Padrão glob para corresponder arquivos |1868| `pattern` | string | `"**/*.ts"` | Padrão glob com o qual os arquivos serão comparados |
1861| `path` | string | `"/path/to/dir"` | Diretório opcional para pesquisar. Padrão é diretório de trabalho atual |1869| `path` | string | `"/path/to/dir"` | Diretório opcional no qual pesquisar. O padrão é o diretório de trabalho atual |
1862 1870
1863<h5 id="grep">1871<h5 id="grep">
1864 Grep1872 Grep
1865</h5>1873</h5>
1866 1874
1867Pesquisa conteúdo de arquivo com expressões regulares.1875Pesquisa o conteúdo de arquivos com expressões regulares.
1868 1876
1869| Campo | Tipo | Exemplo | Descrição |1877| Campo | Tipo | Exemplo | Descrição |
1870| :- | :- | :- | :- |1878| :- | :- | :- | :- |
1871| `pattern` | string | `"TODO.*fix"` | Padrão de expressão regular para pesquisar |1879| `pattern` | string | `"TODO.*fix"` | Padrão de expressão regular a ser pesquisado |
1872| `path` | string | `"/path/to/dir"` | Arquivo ou diretório opcional para pesquisar |1880| `path` | string | `"/path/to/dir"` | Arquivo ou diretório opcional no qual pesquisar |
1873| `glob` | string | `"*.ts"` | Padrão glob opcional para filtrar arquivos |1881| `glob` | string | `"*.ts"` | Padrão glob opcional para filtrar arquivos |
1874| `output_mode` | string | `"content"` | `"content"`, `"files_with_matches"` ou `"count"`. Padrão é `"files_with_matches"` |1882| `output_mode` | string | `"content"` | `"content"`, `"files_with_matches"` ou `"count"`. O padrão é `"files_with_matches"` |
1875| `-i` | boolean | `true` | Pesquisa insensível a maiúsculas e minúsculas |1883| `-i` | boolean | `true` | Pesquisa sem diferenciar maiúsculas de minúsculas |
1876| `multiline` | boolean | `false` | Habilitar correspondência multilinha |1884| `multiline` | boolean | `false` | Habilita a correspondência em várias linhas |
1877 1885
1878<h5 id="webfetch">1886<h5 id="webfetch">
1879 WebFetch1887 WebFetch
1883 1891
1884| Campo | Tipo | Exemplo | Descrição |1892| Campo | Tipo | Exemplo | Descrição |
1885| :- | :- | :- | :- |1893| :- | :- | :- | :- |
1886| `url` | string | `"https://example.com/api"` | URL para buscar conteúdo |1894| `url` | string | `"https://example.com/api"` | URL da qual buscar o conteúdo |
1887| `prompt` | string | `"Extract the API endpoints"` | Prompt para executar no conteúdo buscado |1895| `prompt` | string | `"Extract the API endpoints"` | Prompt a ser executado sobre o conteúdo buscado |
1888 1896
1889<h5 id="websearch">1897<h5 id="websearch">
1890 WebSearch1898 WebSearch
1891</h5>1899</h5>
1892 1900
1893Pesquisa a web.1901Pesquisa na web.
1894 1902
1895| Campo | Tipo | Exemplo | Descrição |1903| Campo | Tipo | Exemplo | Descrição |
1896| :- | :- | :- | :- |1904| :- | :- | :- | :- |
1897| `query` | string | `"react hooks best practices"` | Consulta de pesquisa |1905| `query` | string | `"react hooks best practices"` | Consulta de pesquisa |
1898| `allowed_domains` | array | `["docs.example.com"]` | Opcional: incluir apenas resultados desses domínios |1906| `allowed_domains` | array | `["docs.example.com"]` | Opcional: incluir somente resultados destes domínios |
1899| `blocked_domains` | array | `["spam.example.com"]` | Opcional: excluir resultados desses domínios |1907| `blocked_domains` | array | `["spam.example.com"]` | Opcional: excluir resultados destes domínios |
1900 1908
1901<h5 id="agent">1909<h5 id="agent">
1902 Agent1910 Agent
1903</h5>1911</h5>
1904 1912
1905Gera um [subagente](/docs/pt/sub-agents).1913Inicia um [subagente](/docs/pt/sub-agents).
1906 1914
1907| Campo | Tipo | Exemplo | Descrição |1915| Campo | Tipo | Exemplo | Descrição |
1908| :- | :- | :- | :- |1916| :- | :- | :- | :- |
1909| `prompt` | string | `"Find all API endpoints"` | A tarefa para o agente executar |1917| `prompt` | string | `"Find all API endpoints"` | A tarefa que o agente deve executar |
1910| `description` | string | `"Find API endpoints"` | Descrição curta da tarefa |1918| `description` | string | `"Find API endpoints"` | Descrição curta da tarefa |
1911| `subagent_type` | string | `"Explore"` | Tipo de agente especializado a usar |1919| `subagent_type` | string | `"Explore"` | Tipo de agente especializado a ser usado |
1912| `model` | string | `"sonnet"` | Alias de modelo opcional para sobrescrever o padrão |1920| `model` | string | `"sonnet"` | Alias de modelo opcional para sobrescrever o padrão |
1913 1921
1914Quando uma chamada Agent em primeiro plano é concluída, seu hook [PostToolUse](#posttooluse) recebe o resultado do subagente e telemetria de execução em `tool_response`. Leia esses campos para inspecionar a execução; para rollups de token e custo entre subagentes, use os [contadores de token e custo](/docs/pt/monitoring-usage#token-counter) filtrados para `query_source` `"subagent"`, já que `totalTokens` e `usage` cobrem apenas a solicitação final:1922Quando uma chamada Agent em primeiro plano é concluída, seu [hook PostToolUse](#posttooluse) recebe o resultado do subagente e a telemetria da execução em `tool_response`. Leia esses campos para inspecionar a execução; para totais de tokens e custos entre subagentes, use os [contadores de tokens e custos](/docs/pt/monitoring-usage#token-counter) filtrados por `query_source` `"subagent"`, já que `totalTokens` e `usage` cobrem apenas a requisição final:
1915 1923
1916| Campo | Tipo | Exemplo | Descrição |1924| Campo | Tipo | Exemplo | Descrição |
1917| :- | :- | :- | :- |1925| :- | :- | :- | :- |
1918| `status` | string | `"completed"` | `"completed"` para subagentes em primeiro plano, `"async_launched"` para subagentes em segundo plano. Os subagentes são executados em segundo plano por padrão, então uma chamada Agent que omite `run_in_background` também produz `"async_launched"` |1926| `status` | string | `"completed"` | `"completed"` para subagentes em primeiro plano, `"async_launched"` para subagentes em segundo plano. Os subagentes são executados em segundo plano por padrão, então uma chamada Agent que omite `run_in_background` também produz `"async_launched"` |
1919| `agentId` | string | `"a4d2c8f1e0b3a297"` | Identificador para a execução do subagente |1927| `agentId` | string | `"a4d2c8f1e0b3a297"` | Identificador da execução do subagente |
1920| `content` | array | `[{"type": "text", "text": "Found 12 endpoints..."}]` | Os blocos de texto final do subagente, ou, para um subagente cujo relatório passa por `SubagentHandback`, uma nota breve sobre esse handback em seu lugar |1928| `content` | array | `[{"type": "text", "text": "Found 12 endpoints..."}]` | Os blocos de texto finais do subagente ou, para um subagente cujo relatório passa por `SubagentHandback`, uma nota curta sobre essa entrega no lugar deles |
1921| `resolvedModel` | string | `"claude-sonnet-4-5"` | Modelo em que o subagente começou, que pode diferir do modelo solicitado |1929| `resolvedModel` | string | `"claude-sonnet-4-5"` | Modelo com o qual o subagente começou, que pode ser diferente do modelo solicitado |
1922| `modelsUsed` | array | `["claude-sonnet-4-5", "claude-haiku-4-5"]` | Modelos usados em ordem, com repetições consecutivas colapsadas; definido apenas quando o modelo foi trocado durante a execução. Requer Claude Code v2.1.212 ou posterior |1930| `modelsUsed` | array | `["claude-sonnet-4-5", "claude-haiku-4-5"]` | Modelos usados em ordem, com repetições consecutivas recolhidas; definido somente quando o modelo foi trocado no meio da execução. Exige o Claude Code v2.1.212 ou posterior |
1923| `totalTokens` | number | `12450` | Contagem de tokens da solicitação final da API do subagente: tokens de entrada, saída e cache combinados. Isso não é um total em toda a execução |1931| `totalTokens` | number | `12450` | Contagem de tokens da requisição final de API do subagente: tokens de entrada, de saída e de cache combinados. Não é um total de toda a execução |
1924| `totalDurationMs` | number | `48211` | Duração de tempo real da execução do subagente |1932| `totalDurationMs` | number | `48211` | Duração em tempo real da execução do subagente |
1925| `totalToolUseCount` | number | `7` | Contagem de chamadas de ferramenta que o subagente fez |1933| `totalToolUseCount` | number | `7` | Contagem de chamadas de ferramenta feitas pelo subagente |
1926| `usage` | object | `{"input_tokens": 8320, ...}` | Divisão de tokens por tipo da solicitação final da API: `input_tokens`, `output_tokens`, `cache_creation_input_tokens`, `cache_read_input_tokens` |1934| `usage` | object | `{"input_tokens": 8320, ...}` | Detalhamento de tokens por tipo da requisição final de API: `input_tokens`, `output_tokens`, `cache_creation_input_tokens`, `cache_read_input_tokens` |
1927 1935
1928No Claude Code v2.1.271 ou posterior, um subagente que é executado com a ferramenta [`SubagentHandback`](/docs/pt/tools-reference), que Claude Code fornece em [modo automático](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode), entrega seu relatório através dessa ferramenta em vez de retorná-lo como texto. O campo `content` de seu resultado `completed` então carrega uma nota breve sobre esse handback em vez do relatório em si. Para ler o relatório, corresponda um hook `PreToolUse` ou `PostToolUse` em `SubagentHandback` e leia `tool_input.message`.1936No Claude Code v2.1.271 ou posterior, um subagente que é executado com a ferramenta [`SubagentHandback`](/docs/pt/tools-reference), que o Claude Code fornece no [modo auto](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode), entrega seu relatório por meio dessa ferramenta em vez de retorná-lo como texto. O campo `content` do seu resultado `completed` então carrega uma nota curta sobre essa entrega em vez do próprio relatório. Para ler o relatório, faça a correspondência de um hook `PreToolUse` ou `PostToolUse` em `SubagentHandback` e leia `tool_input.message`.
1929 1937
1930Para subagentes em segundo plano, a ferramenta retorna quando a tarefa se move para o segundo plano, então `tool_response` não carrega campos de uso: um lançamento em segundo plano retorna imediatamente, e uma tarefa em primeiro plano que Claude Code coloca em segundo plano durante a execução retorna nessa transição. Ele tem `status: "async_launched"`, `agentId`, `description`, `prompt`, `outputFile` e `resolvedModel`.1938Para subagentes em segundo plano, a ferramenta retorna quando a tarefa passa para o segundo plano, então `tool_response` não carrega campos de uso: uma inicialização em segundo plano retorna imediatamente, e uma tarefa em primeiro plano que o Claude Code move para o segundo plano no meio da execução retorna nessa transição. Ela tem `status: "async_launched"`, `agentId`, `description`, `prompt`, `outputFile` e `resolvedModel`.
1931 1939
1932Em uma resposta `completed`, `resolvedModel` nomeia o modelo em que o subagente começou, que pode diferir do valor `model` em `tool_input`, como quando `availableModels` ou outra sobrescrita se aplica. Em uma resposta `async_launched`, `resolvedModel` nomeia o modelo em uso quando o agente se moveu para o segundo plano, então uma troca que aconteceu antes de colocar em segundo plano é refletida lá. `modelsUsed` e o comportamento de `resolvedModel` no tempo de colocação em segundo plano requerem Claude Code v2.1.212 ou posterior.1940Em uma resposta `completed`, `resolvedModel` nomeia o modelo com o qual o subagente começou, que pode ser diferente do valor de `model` em `tool_input`, como quando `availableModels` ou outra substituição se aplica. Em uma resposta `async_launched`, `resolvedModel` nomeia o modelo em uso quando o agente passou para o segundo plano, de modo que uma troca que ocorreu antes disso é refletida ali. `modelsUsed` e o comportamento de `resolvedModel` no momento da passagem para o segundo plano exigem o Claude Code v2.1.212 ou posterior.
1933 1941
1934<a id="askuserquestion" />1942<a id="askuserquestion" />
1935 1943
1937 AskUserQuestion1945 AskUserQuestion
1938</h5>1946</h5>
1939 1947
1940Faz ao usuário uma a quatro perguntas de múltipla escolha.1948Faz ao usuário de uma a quatro perguntas de múltipla escolha.
1941 1949
1942| Campo | Tipo | Exemplo | Descrição |1950| Campo | Tipo | Exemplo | Descrição |
1943| :- | :- | :- | :- |1951| :- | :- | :- | :- |
1944| `questions` | array | `[{"question": "Which framework?", "header": "Framework", "options": [{"label": "React"}], "multiSelect": false}]` | Perguntas a apresentar, cada uma com uma string `question`, `header` curto, array `options` e flag `multiSelect` opcional |1952| `questions` | array | `[{"question": "Which framework?", "header": "Framework", "options": [{"label": "React"}], "multiSelect": false}]` | Perguntas a apresentar, cada uma com uma string `question`, um `header` curto, um array `options` e uma flag `multiSelect` opcional |
1945| `answers` | object | `{"Which framework?": "React"}` | Opcional. Mapeia texto de pergunta para rótulo de opção selecionada. Respostas de seleção múltipla unem rótulos com vírgulas. Claude não define este campo; forneça-o via `updatedInput` para responder programaticamente |1953| `answers` | object | `{"Which framework?": "React"}` | Opcional. Mapeia o texto da pergunta para o rótulo da opção selecionada. Respostas de seleção múltipla unem os rótulos com vírgulas. O Claude não define este campo; forneça-o via `updatedInput` para responder programaticamente |
1946 1954
1947<h5 id="exitplanmode">1955<h5 id="exitplanmode">
1948 ExitPlanMode1956 ExitPlanMode
1949</h5>1957</h5>
1950 1958
1951Apresenta um plano e pede ao usuário para aprová-lo antes de 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.1959Apresenta um plano e pede ao usuário que o aprove antes que o Claude saia do [modo de planejamento](/docs/pt/permission-modes#analyze-before-you-edit-with-plan-mode). O Claude grava o plano em um arquivo no disco antes de chamar a ferramenta, então o `tool_input` literal vindo do modelo normalmente está vazio. O Claude Code injeta o conteúdo do plano e o caminho do arquivo antes de passar a entrada aos hooks.
1952 1960
1953| Campo | Tipo | Exemplo | Descrição |1961| Campo | Tipo | Exemplo | Descrição |
1954| :- | :- | :- | :- |1962| :- | :- | :- | :- |
1955| `plan` | string | `"## Refactor auth\n1. Extract..."` | Conteúdo do plano em Markdown. Injetado do arquivo de plano no disco |1963| `plan` | string | `"## Refactor auth\n1. Extract..."` | Conteúdo do plano em Markdown. Injetado a partir do arquivo do plano no disco |
1956| `planFilePath` | string | `"/Users/.../plans/refactor-auth.md"` | Caminho para o arquivo de plano. Injetado |1964| `planFilePath` | string | `"/Users/.../plans/refactor-auth.md"` | Caminho para o arquivo do plano. Injetado |
1957| `allowedPrompts` | array | `[{"tool": "Bash", "prompt": "run tests"}]` | Descontinuado. Claude Code aceita o campo mas o ignora. Antes da v2.1.205, ele carregava permissões baseadas em prompt que Claude solicitou para implementar o plano |1965| `allowedPrompts` | array | `[{"tool": "Bash", "prompt": "run tests"}]` | Descontinuado. O Claude Code aceita o campo, mas o ignora. Antes da v2.1.205, ele carregava permissões baseadas em prompt que o Claude solicitava para implementar o plano |
1958 1966
1959Em `PostToolUse`, `tool_response` é um objeto com campos `plan` e `filePath` contendo o plano aprovado, mais flags de status interno. Leia `tool_response.plan` para o conteúdo do plano em vez de reler o arquivo do disco.1967No `PostToolUse`, `tool_response` é um objeto com os campos `plan` e `filePath` contendo o plano aprovado, além de flags de status internas. Leia `tool_response.plan` para obter o conteúdo do plano em vez de ler o arquivo novamente do disco.
1960 1968
1961<h4 id="pretooluse-decision-control">1969<h4 id="pretooluse-decision-control">
1962 Controle de decisão PreToolUse1970 Controle de decisão do PreToolUse
1963</h4>1971</h4>
1964 1972
1965Hooks `PreToolUse` podem controlar se uma chamada de ferramenta prossegue. Ao contrário de outros hooks que usam um campo `decision` de nível superior, PreToolUse retorna sua decisão dentro de um objeto `hookSpecificOutput`. Isso lhe dá controle mais rico: quatro resultados (permitir, negar, perguntar ou adiar) mais a capacidade de modificar a entrada da ferramenta antes da execução.1973Os hooks `PreToolUse` podem controlar se uma chamada de ferramenta prossegue. Diferentemente de outros hooks que usam um campo `decision` de nível superior, o PreToolUse retorna sua decisão dentro de um objeto `hookSpecificOutput`. Isso lhe dá um controle mais rico: quatro resultados (allow, deny, ask ou defer), além da capacidade de modificar a entrada da ferramenta antes da execução.
1966 1974
1967| Campo | Descrição |1975| Campo | Descrição |
1968| :- | :- |1976| :- | :- |
1969| `permissionDecision` | `"allow"` pula o prompt de permissão, exceto para as [ações que nenhum modo auto-aprova](/docs/pt/permission-modes#actions-no-mode-auto-approves) e para `AskUserQuestion` e `ExitPlanMode`, que precisam de [`updatedInput` emparelhado com ele](#allow-with-updatedinput). `"deny"` impede a chamada de ferramenta. `"ask"` solicita ao usuário para confirmar. `"defer"` sai graciosamente para que a ferramenta possa ser retomada mais tarde. [Regras de negação e pergunta](/docs/pt/permissions#manage-permissions) ainda são avaliadas independentemente do que o hook retorna |1977| `permissionDecision` | `"allow"` pula o prompt de permissão, exceto para as [ações que nenhum modo aprova automaticamente](/docs/pt/permission-modes#actions-no-mode-auto-approves) e para `AskUserQuestion` e `ExitPlanMode`, que precisam de [`updatedInput` combinado a ele](#allow-with-updatedinput). `"deny"` impede a chamada de ferramenta. `"ask"` solicita a confirmação do usuário. `"defer"` sai de forma controlada para que a ferramenta possa ser retomada depois. As [regras deny e ask](/docs/pt/permissions#manage-permissions) ainda são avaliadas independentemente do que o hook retornar |
1970| `permissionDecisionReason` | Para `"ask"`, mostrado ao usuário mas não ao Claude. Para `"deny"`, mostrado ao Claude. Para `"allow"` e `"defer"`, escrito apenas no [log de depuração](#debug-hooks) |1978| `permissionDecisionReason` | Para `"ask"`, mostrado ao usuário no prompt de permissão. Quando o Claude Code [nega a chamada](/docs/pt/headless#turn-off-permission-prompts-in-unattended-runs) em uma execução `-p` na qual ninguém pode responder a esse prompt, o Claude lê o motivo no resultado da ferramenta. Para `"deny"`, mostrado ao Claude. Para `"allow"` e `"defer"`, gravado somente no [log de depuração](#debug-hooks) |
1971| `updatedInput` | Modifica os parâmetros de entrada da ferramenta antes da execução. Substitui o objeto de entrada inteiro, então inclua campos inalterados junto com os modificados. Claude Code avalia regras de permissão e a elegibilidade de [colocação em segundo plano automático](/docs/pt/tools-reference#foreground-commands-that-move-to-the-background) de um comando Bash contra a entrada que seu hook retorna, não a entrada que Claude enviou. Combine com `"allow"` para auto-aprovar, ou `"ask"` para mostrar a entrada modificada ao usuário. Para `"defer"`, ignorado |1979| `updatedInput` | Modifica os parâmetros de entrada da ferramenta antes da execução. Substitui o objeto de entrada inteiro, então inclua os campos inalterados junto com os modificados. O Claude Code avalia as regras de permissão e a [elegibilidade para segundo plano automático](/docs/pt/tools-reference#foreground-commands-that-move-to-the-background) de um comando Bash com base na entrada que seu hook retorna, e não na entrada que o Claude enviou. Combine com `"allow"` para aprovar automaticamente, ou com `"ask"` para mostrar a entrada modificada ao usuário. Para `"defer"`, ignorado |
1972| `additionalContext` | String adicionada ao contexto do Claude junto com o resultado da ferramenta. Ignorado quando `permissionDecision` é `"defer"`. Veja [Adicionar contexto para Claude](#add-context-for-claude) |1980| `additionalContext` | String adicionada ao contexto do Claude junto com o resultado da ferramenta. Ignorado quando `permissionDecision` é `"defer"`. Consulte [Adicionar contexto para o Claude](#add-context-for-claude) |
1973 1981
1974Quando vários hooks PreToolUse retornam decisões diferentes, a precedência é `deny` > `defer` > `ask` > `allow`.1982Quando vários hooks PreToolUse retornam decisões diferentes, a precedência é `deny` > `defer` > `ask` > `allow`.
1975 1983
1976Um hook que bloqueia ao sair com 2 roteia da mesma forma que `"deny"`: Claude vê a mensagem stderr como o motivo da negação.1984Um hook que bloqueia saindo com 2 é encaminhado da mesma forma que `"deny"`: o Claude vê a mensagem do stderr como o motivo da negação.
1977 1985
1978Quando um hook retorna `"ask"`, o prompt de permissão exibido ao usuário inclui um rótulo identificando de onde o hook veio: `[settings]` para um hook de qualquer arquivo de configurações ou de frontmatter de agente, `[plugin:<name>]` para um hook de plugin, ou `[skill]` para um hook de frontmatter de skill. Isso ajuda os usuários a entender qual fonte de configuração está solicitando confirmação.1986Quando um hook retorna `"ask"`, o prompt de permissão exibido ao usuário inclui um rótulo que identifica a origem do hook: `[settings]` para um hook de qualquer arquivo de configurações ou do frontmatter de um agente, `[plugin:<name>]` para o hook de um plugin ou `[skill]` para um hook do frontmatter de uma skill. Isso ajuda os usuários a entender qual fonte de configuração está solicitando a confirmação.
1979 1987
1980Um `"ask"` de um hook também força um prompt de permissão em [modo automático](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode): o classificador ainda pode negar a chamada de ferramenta, mas não pode aprovar a chamada silenciosamente. Antes da v2.1.211, o classificador poderia aprovar um comando Bash executado fora do [sandbox](/docs/pt/sandboxing) sem mostrar o prompt que o hook solicitou; o classificador ainda aplicava suas próprias regras de segurança a esse comando, e uma negação de hook `"deny"` era sempre honrada.1988O `"ask"` de um hook também força um prompt de permissão no [modo auto](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode): o classificador ainda pode negar a chamada de ferramenta, mas não pode aprová-la silenciosamente. Antes da v2.1.211, o classificador podia aprovar um comando Bash executado fora do [sandbox](/docs/pt/sandboxing) sem mostrar o prompt solicitado pelo hook; o classificador ainda aplicava suas próprias regras de segurança a esse comando, e um `"deny"` de hook era sempre respeitado.
1981 1989
1982```json theme={null}1990```json theme={null}
1983{1991{
1995 2003
1996<span id="allow-with-updatedinput" />2004<span id="allow-with-updatedinput" />
1997 2005
1998Em [modo não interativo](/docs/pt/headless) com a flag `-p`, Claude Code oferece `AskUserQuestion` e `ExitPlanMode` apenas quando a execução tem um [host de permissão](/docs/pt/headless#turn-off-permission-prompts-in-unattended-runs) para receber o prompt, como um callback `canUseTool` do Agent SDK. Essas ferramentas requerem interação do usuário. 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 seja executada 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.2006No [modo não interativo](/docs/pt/headless) com a flag `-p`, o Claude Code oferece `AskUserQuestion` e `ExitPlanMode` somente quando a execução tem um [host de permissão](/docs/pt/headless#turn-off-permission-prompts-in-unattended-runs) para receber o prompt, como um callback `canUseTool` do Agent SDK. Essas ferramentas exigem interação do usuário. Retornar `permissionDecision: "allow"` junto com `updatedInput` satisfaz esse requisito: o hook lê a entrada da ferramenta do stdin, coleta a resposta por meio da sua própria UI e a retorna em `updatedInput` para que a ferramenta seja executada sem solicitar confirmação. Retornar apenas `"allow"` não é suficiente para essas ferramentas. Para `AskUserQuestion`, devolva o array `questions` original e adicione um objeto [`answers`](#askuserquestion) que mapeia o texto de cada pergunta para a resposta escolhida.
1999 2007
2000A partir da 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.2008Uma ferramenta MCP cujo servidor a marca com [`_meta["anthropic/requiresUserInteraction"]`](/docs/pt/mcp#require-approval-for-a-specific-tool) é mais restrita: um hook não pode pular seu prompt de aprovação com `"allow"`, com ou sem `updatedInput`, porque o Claude Code não consegue confirmar que o hook coletou a interação de que a ferramenta precisa.
2001 2009
2002<Note>2010<Note>
2003 PreToolUse anteriormente usava campos `decision` e `reason` de nível superior, mas estes estão descontinuados para este evento. Use `hookSpecificOutput.permissionDecision` e `hookSpecificOutput.permissionDecisionReason` em vez disso. Os valores descontinuados `"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.2011 O PreToolUse usava anteriormente os campos de nível superior `decision` e `reason`, mas eles estão descontinuados para este evento. Use `hookSpecificOutput.permissionDecision` e `hookSpecificOutput.permissionDecisionReason`. Os valores descontinuados `"approve"` e `"block"` correspondem a `"allow"` e `"deny"`, respectivamente. Outros eventos, como PostToolUse e Stop, continuam usando `decision` e `reason` de nível superior como seu formato atual.
2004</Note>2012</Note>
2005 2013
2006<h4 id="defer-a-tool-call-for-later">2014<h4 id="defer-a-tool-call-for-later">
2007 Adiar uma chamada de ferramenta para mais tarde2015 Adiar uma chamada de ferramenta para mais tarde
2008</h4>2016</h4>
2009 2017
2010`"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 sobre Claude Code. Permite que esse processo de chamada 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.2018`"defer"` é para integrações que executam `claude -p` como subprocesso e leem sua saída JSON, como um app do Agent SDK ou uma UI personalizada construída sobre o Claude Code. Ele permite que esse processo chamador pause o Claude em uma chamada de ferramenta, colete a entrada por meio da sua própria interface e retome de onde parou. O Claude Code respeita este valor somente no [modo não interativo](/docs/pt/headless) com a flag `-p`. Em sessões interativas, ele registra um aviso em log e ignora o resultado do hook.
2011 2019
2012A ferramenta `AskUserQuestion` é o caso típico: Claude quer fazer uma pergunta ao usuário, mas não há terminal para responder. Uma execução `-p` oferece `AskUserQuestion` apenas quando tem um [host de permissão](/docs/pt/headless#turn-off-permission-prompts-in-unattended-runs), como uma ferramenta MCP que você passa com `--permission-prompt-tool`, então comece a execução com um. A viagem de ida e volta funciona assim:2020A ferramenta `AskUserQuestion` é o caso típico: o Claude quer perguntar algo ao usuário, mas não há terminal para responder. Uma execução `-p` oferece `AskUserQuestion` somente quando tem um [host de permissão](/docs/pt/headless#turn-off-permission-prompts-in-unattended-runs), como uma ferramenta MCP que você passa com `--permission-prompt-tool`, então inicie a execução com um. O ciclo funciona assim:
2013 2021
20141. Claude chama `AskUserQuestion`. O hook `PreToolUse` dispara.20221. O Claude chama `AskUserQuestion`. O hook `PreToolUse` é disparado.
20152. O hook retorna `permissionDecision: "defer"`. A ferramenta não é executada. O processo sai com `stop_reason: "tool_deferred"` e a chamada de ferramenta pendente preservada na transcrição.20232. O hook retorna `permissionDecision: "defer"`. A ferramenta não é executada. O processo sai com `stop_reason: "tool_deferred"` e a chamada de ferramenta pendente preservada na transcrição.
20163. O processo de chamada lê `deferred_tool_use` do resultado do SDK, exibe a pergunta em sua própria UI e espera por uma resposta.20243. O processo chamador lê `deferred_tool_use` do resultado do SDK, apresenta a pergunta na sua própria UI e aguarda uma resposta.
20174. O processo de chamada executa `claude -p --resume <session-id>` com o mesmo host de permissão. A mesma chamada de ferramenta dispara `PreToolUse` novamente.20254. O processo chamador executa `claude -p --resume <session-id>` com o mesmo host de permissão. A mesma chamada de ferramenta dispara o `PreToolUse` novamente.
20185. O hook retorna `permissionDecision: "allow"` com a resposta em `updatedInput`. A ferramenta é executada e Claude continua.20265. O hook retorna `permissionDecision: "allow"` com a resposta em `updatedInput`. A ferramenta é executada e o Claude continua.
2019 2027
2020O campo `deferred_tool_use` carrega o `id`, `name` e `input` da ferramenta. O `input` são os parâmetros que Claude gerou para a chamada de ferramenta, capturados antes da execução:2028O campo `deferred_tool_use` carrega o `id`, o `name` e o `input` da ferramenta. O `input` são os parâmetros que o Claude gerou para a chamada de ferramenta, capturados antes da execução:
2021 2029
2022```json theme={null}2030```json theme={null}
2023{2031{
2033}2041}
2034```2042```
2035 2043
2036Não há tempo limite ou limite de tentativas. A sessão permanece no disco até que você a retome, sujeita à varredura de retenção [`cleanupPeriodDays`](/docs/pt/settings-reference#cleanupperioddays), que exclui arquivos de sessão após 30 dias por padrão, seguindo as [regras de varredura de retenção](/docs/pt/claude-directory#cleaned-up-automatically). 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 de chamada controla quando quebrar o loop eventualmente retornando `"allow"` ou `"deny"` do hook.2044Não há timeout nem limite de novas tentativas. A sessão permanece no disco até que você a retome, sujeita à limpeza de retenção [`cleanupPeriodDays`](/docs/pt/settings-reference#cleanupperioddays), que exclui os arquivos de sessão após 30 dias por padrão, seguindo as [regras de limpeza de retenção](/docs/pt/claude-directory#cleaned-up-automatically). 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 interromper o loop, retornando eventualmente `"allow"` ou `"deny"` do hook.
2037 2045
2038`"defer"` funciona apenas 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 retomar pode apenas re-executar uma ferramenta: não há maneira de adiar uma chamada de um lote sem deixar as outras não resolvidas.2046`"defer"` só funciona quando o Claude faz uma única chamada de ferramenta no turno. Se o Claude fizer várias chamadas de ferramenta de uma vez, `"defer"` é ignorado com um aviso e a ferramenta prossegue pelo fluxo normal de permissões. A restrição existe porque a retomada só pode executar novamente uma ferramenta: não há como adiar uma chamada de um lote sem deixar as outras sem resolução.
2039 2047
2040Se a ferramenta adiada não estiver mais disponível quando você retomar, o processo sai com `stop_reason: "tool_deferred_unavailable"` e `is_error: true` antes do hook disparar. Isso acontece quando um servidor MCP que forneceu a ferramenta não está conectado para a sessão retomada. O payload `deferred_tool_use` ainda é incluído para que você possa identificar qual ferramenta desapareceu.2048Se a ferramenta adiada não estiver mais disponível quando você retomar, o processo sai com `stop_reason: "tool_deferred_unavailable"` e `is_error: true` antes que o hook seja disparado. Isso acontece quando um servidor MCP que fornecia a ferramenta não está conectado na sessão retomada. O payload `deferred_tool_use` ainda é incluído para que você possa identificar qual ferramenta ficou ausente.
2041 2049
2042<Note>2050<Note>
2043 Para retomar uma sessão adiada em modo de plano, passe [`--permission-prompt-tool`](/docs/pt/cli-reference#cli-flags) junto com `--resume` para que Claude Code possa apresentar o plano para aprovação. Se você passar certas outras flags de lançamento, a execução retomada não retorna ao modo de plano; veja [Retomar em modo de plano com `-p`](/docs/pt/sessions#resume-in-plan-mode-with-p). Requer Claude Code v2.1.246 ou posterior.2051 Para retomar uma sessão adiada no modo de planejamento, passe [`--permission-prompt-tool`](/docs/pt/cli-reference#cli-flags) junto com `--resume` para que o Claude Code possa apresentar o plano para aprovação. Se você passar certas outras flags de inicialização, a execução retomada não volta ao modo de planejamento; consulte [Retomar no modo de planejamento com `-p`](/docs/pt/sessions#resume-in-plan-mode-with-p). Exige o Claude Code v2.1.246 ou posterior.
2044 2052
2045 Quando você retoma com `-p`, Claude Code não restaura nenhum outro modo de permissão armazenado. Ele inicia a execução no modo de permissão que uma nova execução `claude -p` iniciaria, então passe `--permission-mode` ou `--dangerously-skip-permissions` novamente se a sessão adiada usou um. Quando você retoma com `claude --resume <session-id>` sem `-p`, Claude Code restaura o modo de permissão armazenado, com as exceções listadas em [modo de permissão ao retomar](/docs/pt/sessions#permission-mode-on-resume).2053 Quando você retoma com `-p`, o Claude Code não restaura nenhum outro modo de permissão armazenado. Ele inicia a execução no modo de permissão em que uma nova execução `claude -p` iniciaria, então passe `--permission-mode` ou `--dangerously-skip-permissions` novamente se a sessão adiada usava um deles. Quando você retoma com `claude --resume <session-id>` sem `-p`, o Claude Code restaura o modo de permissão armazenado, com as exceções listadas em [modo de permissão na retomada](/docs/pt/sessions#permission-mode-on-resume).
2046</Note>2054</Note>
2047 2055
2048<h3 id="permissionrequest">2056<h3 id="permissionrequest">
2049 PermissionRequest2057 PermissionRequest
2050</h3>2058</h3>
2051 2059
2052É executado quando o Claude Code está prestes a pedir a você permissão para usar uma ferramenta. Em sessões que não podem mostrar um prompt, como subagentes em segundo plano no [modo não interativo](/docs/pt/headless), o Claude Code ainda executa esses hooks e, se nenhum hook retornar uma decisão, nega a chamada de ferramenta. Para uma chamada que chega a um `--permission-prompt-tool` ou ao [callback `canUseTool`](/docs/pt/agent-sdk/permissions) do Agent SDK, os hooks são executados junto com o seu host, e o que decidir primeiro é aplicado.2060É executado quando o Claude Code está prestes a pedir sua permissão para usar uma ferramenta. Em sessões que não podem mostrar um prompt, como subagentes em segundo plano no [modo não interativo](/docs/pt/headless), o Claude Code ainda executa esses hooks e, se nenhum hook retornar uma decisão, ele nega a chamada de ferramenta. Para uma chamada que chega a um `--permission-prompt-tool` ou ao [callback `canUseTool`](/docs/pt/agent-sdk/permissions) do Agent SDK, os hooks são executados junto com o seu host, e o que decidir primeiro se aplica.
2053Use o [controle de decisão do PermissionRequest](#permissionrequest-decision-control) para permitir ou negar em nome do usuário.2061Use o [controle de decisão do PermissionRequest](#permissionrequest-decision-control) para permitir ou negar em nome do usuário.
2054 2062
2055Use este evento quando você precisa de um sinal no momento em que Claude pede permissão para usar uma ferramenta. Claude Code executa um hook [Notification](#notification) com o tipo `permission_prompt` apenas após o prompt ter esperado cerca de seis segundos.2063Use este evento quando precisar de um sinal no momento em que o Claude pede permissão para usar uma ferramenta. O Claude Code executa um hook [Notification](#notification) com o tipo `permission_prompt` somente depois que o prompt esperou cerca de seis segundos.
2056 2064
2057Claude Code não executa hooks PermissionRequest para a [solicitação de rede](/docs/pt/sandboxing#network-isolation) de um comando em sandbox. Para obter um sinal para esse prompt, use o tipo de notificação `permission_prompt`.2065O Claude Code não executa hooks PermissionRequest para a [requisição de rede](/docs/pt/sandboxing#network-isolation) de um comando em sandbox. Para obter um sinal para esse prompt, use o tipo de notificação `permission_prompt`.
2058 2066
2059Corresponde ao nome da ferramenta, mesmos valores que PreToolUse.2067Faz a correspondência com o nome da ferramenta, com os mesmos valores do PreToolUse.
2060 2068
2061<h4 id="permissionrequest-input">2069<h4 id="permissionrequest-input">
2062 Entrada PermissionRequest2070 Entrada do PermissionRequest
2063</h4>2071</h4>
2064 2072
2065Hooks PermissionRequest recebem campos `tool_name` e `tool_input` como hooks PreToolUse, mas sem `tool_use_id`. Para uma ferramenta MCP, eles também recebem o objeto [`mcp_server`](#pretooluse-input). Um array `permission_suggestions` opcional contém as [atualizações de permissão](#permission-update-entries) que Claude Code sugere para esta solicitação, como adicionar uma regra de permissão ou mudar o modo de permissão.2073Os hooks PermissionRequest recebem os campos `tool_name` e `tool_input` como os hooks PreToolUse, mas sem `tool_use_id`. Para uma ferramenta MCP, eles também recebem o objeto [`mcp_server`](#pretooluse-input). Um array opcional `permission_suggestions` contém as [atualizações de permissão](#permission-update-entries) que o Claude Code sugere para esta solicitação, como adicionar uma regra allow ou alterar o modo de permissão.
2066 2074
2067O array `permission_suggestions` não é uma lista exata das opções que você vê, porque cada diálogo de permissão constrói suas próprias opções. Alguns diálogos, como o para edições de arquivo, não leem o array e derivam suas opções da solicitação em si. Um diálogo que o lê pode ainda reter uma opção cuja sugestão fica no array, por exemplo quando [`allowManagedPermissionRulesOnly`](/docs/pt/settings-reference#allowmanagedpermissionrulesonly) oculta opções de salvamento de regra. Ele também pode oferecer opções que não têm entrada de sugestão, como [**Sim, e mude para modo automático**](/docs/pt/permission-modes#switch-permission-modes), que muda o modo de permissão diretamente em vez de através de uma atualização de permissão.2075O array `permission_suggestions` não é uma lista exata das opções que você vê, porque cada diálogo de permissão monta suas próprias opções. Alguns diálogos, como o de edições de arquivos, não leem o array de forma alguma e derivam suas opções da própria solicitação. Um diálogo que o lê ainda pode omitir uma opção cuja sugestão permanece no array, por exemplo quando [`allowManagedPermissionRulesOnly`](/docs/pt/settings-reference#allowmanagedpermissionrulesonly) oculta as opções de salvar regras. Ele também pode oferecer opções que não têm entrada de sugestão, como [**Yes, and switch to auto mode**](/docs/pt/permission-modes#switch-permission-modes), que altera o modo de permissão diretamente em vez de por meio de uma atualização de permissão.
2068 2076
2069Hooks PreToolUse são executados antes de cada chamada de ferramenta, independentemente de precisar de permissão. Hooks PermissionRequest são executados apenas quando Claude Code está prestes a pedir permissão, ou quando caso contrário auto-negaria uma chamada que não pode solicitar. Nenhum evento dispara para [`EndConversation`](/docs/pt/tools-reference#endconversation-tool-behavior).2077Os hooks PreToolUse são executados antes de cada chamada de ferramenta, precise ela de permissão ou não. Os hooks PermissionRequest são executados somente quando o Claude Code está prestes a pedir sua permissão, ou quando, de outra forma, ele negaria automaticamente uma chamada que não pode exibir um prompt. Nenhum dos dois eventos é disparado para [`EndConversation`](/docs/pt/tools-reference#endconversation-tool-behavior).
2070 2078
2071```json theme={null}2079```json theme={null}
2072{2080{
2092```2100```
2093 2101
2094<h4 id="permissionrequest-decision-control">2102<h4 id="permissionrequest-decision-control">
2095 Controle de decisão PermissionRequest2103 Controle de decisão do PermissionRequest
2096</h4>2104</h4>
2097 2105
2098Hooks `PermissionRequest` podem permitir ou negar solicitações de permissão. Além dos [campos de saída JSON](#json-output) disponíveis para todos os hooks, seu script de hook pode retornar um objeto `decision` com esses campos específicos do evento:2106Os hooks `PermissionRequest` podem permitir ou negar solicitações de permissão. Além dos [campos de saída JSON](#json-output) disponíveis para todos os hooks, seu script de hook pode retornar um objeto `decision` com estes campos específicos do evento:
2099 2107
2100| Campo | Descrição |2108| Campo | Descrição |
2101| :- | :- |2109| :- | :- |
2102| `behavior` | `"allow"` concede a permissão, `"deny"` a 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 |2110| `behavior` | `"allow"` concede a permissão, `"deny"` a nega. As [regras deny e ask](/docs/pt/permissions#manage-permissions) ainda são avaliadas, então um hook que retorna `"allow"` não sobrescreve uma regra deny correspondente |
2103| `updatedInput` | Para `"allow"` apenas: 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 |2111| `updatedInput` | Somente para `"allow"`: modifica os parâmetros de entrada da ferramenta antes da execução. Substitui o objeto de entrada inteiro, então inclua os campos inalterados junto com os modificados. A entrada modificada é reavaliada com base nas regras deny e ask |
2104| `updatedPermissions` | Para `"allow"` apenas: 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 |2112| `updatedPermissions` | Somente para `"allow"`: array de [entradas de atualização de permissão](#permission-update-entries) a serem aplicadas, como adicionar uma regra allow ou alterar o modo de permissão da sessão |
2105| `message` | Para `"deny"` apenas: diz ao Claude por que a permissão foi negada |2113| `message` | Somente para `"deny"`: informa ao Claude por que a permissão foi negada |
2106| `interrupt` | Para `"deny"` apenas: se `true`, para Claude |2114| `interrupt` | Somente para `"deny"`: se `true`, interrompe o Claude |
2107 2115
2108Um hook que sai com 2 sem um objeto `decision` deixa o fluxo de permissão inalterado, e seu stderr é descartado. Apenas o objeto `decision` pode conceder ou negar a solicitação.2116Um hook que sai com 2 sem um objeto `decision` deixa o fluxo de permissões inalterado, e seu stderr é descartado. Somente o objeto `decision` pode conceder ou negar a solicitação.
2109 2117
2110```json theme={null}2118```json theme={null}
2111{2119{
2125 Entradas de atualização de permissão2133 Entradas de atualização de permissão
2126</h4>2134</h4>
2127 2135
2128O campo de saída `updatedPermissions` e o campo de entrada [`permission_suggestions`](#permissionrequest-input) ambos usam o mesmo array de objetos de entrada. Cada entrada tem um `type` que determina seus outros campos, e um `destination` que controla onde a mudança é escrita.2136O campo de saída `updatedPermissions` e o [campo de entrada `permission_suggestions`](#permissionrequest-input) usam o mesmo array de objetos de entrada. Cada entrada tem um `type` que determina seus outros campos e um `destination` que controla onde a alteração é gravada.
2129 2137
2130| `type` | Campos | Efeito |2138| `type` | Campos | Efeito |
2131| :- | :- | :- |2139| :- | :- | :- |
2132| `addRules` | `rules`, `behavior`, `destination` | Adiciona regras de permissão. `rules` é um array de objetos `{toolName, ruleContent?}`. Omita `ruleContent` para corresponder a toda a ferramenta. `behavior` é `"allow"`, `"deny"` ou `"ask"` |2140| `addRules` | `rules`, `behavior`, `destination` | Adiciona regras de permissão. `rules` é um array de objetos `{toolName, ruleContent?}`. Omita `ruleContent` para corresponder à ferramenta inteira. `behavior` é `"allow"`, `"deny"` ou `"ask"` |
2133| `replaceRules` | `rules`, `behavior`, `destination` | Substitui todas as regras do `behavior` dado no `destination` pelas `rules` fornecidas |2141| `replaceRules` | `rules`, `behavior`, `destination` | Substitui todas as regras do `behavior` informado no `destination` pelas `rules` fornecidas |
2134| `removeRules` | `rules`, `behavior`, `destination` | Remove regras correspondentes do `behavior` dado |2142| `removeRules` | `rules`, `behavior`, `destination` | Remove as regras correspondentes do `behavior` informado |
2135| `setMode` | `mode`, `destination` | Muda o modo de permissão. Modos válidos são `default`, `auto`, `acceptEdits`, `dontAsk`, `bypassPermissions`, `plan` e `manual` como um alias para `default`. O alias `manual` requer Claude Code v2.1.200 ou posterior |2143| `setMode` | `mode`, `destination` | Altera o modo de permissão. Os modos válidos são `default`, `auto`, `acceptEdits`, `dontAsk`, `bypassPermissions`, `plan` e `manual` como alias de `default`. O alias `manual` exige o Claude Code v2.1.200 ou posterior |
2136| `addDirectories` | `directories`, `destination` | Adiciona diretórios de trabalho. `directories` é um array de strings de caminho |2144| `addDirectories` | `directories`, `destination` | Adiciona diretórios de trabalho. `directories` é um array de strings de caminho |
2137| `removeDirectories` | `directories`, `destination` | Remove diretórios de trabalho |2145| `removeDirectories` | `directories`, `destination` | Remove diretórios de trabalho |
2138 2146
2139<Note>2147<Note>
2140 `setMode` com `bypassPermissions` só tem efeito se você iniciou a sessão com modo bypass já disponível: `--dangerously-skip-permissions`, `--permission-mode bypassPermissions`, `--allow-dangerously-skip-permissions` ou `permissions.defaultMode: "bypassPermissions"` em [configurações de usuário, `--settings` ou gerenciadas](/docs/pt/settings-reference#permissions-defaultmode). Caso contrário, a atualização é uma não-operação. A atualização também é uma não-operação quando [`permissions.disableBypassPermissionsMode`](/docs/pt/permissions#managed-settings) desabilita o modo, ou quando a sessão começa em [modo restrito](/docs/pt/cli-reference#cli-flags).2148 `setMode` com `bypassPermissions` só tem efeito se você iniciou a sessão com o modo bypass já disponível: `--dangerously-skip-permissions`, `--permission-mode bypassPermissions`, `--allow-dangerously-skip-permissions` ou `permissions.defaultMode: "bypassPermissions"` nas [configurações de usuário, de `--settings` ou gerenciadas](/docs/pt/settings-reference#permissions-defaultmode). Caso contrário, a atualização não tem efeito. A atualização também não tem efeito quando [`permissions.disableBypassPermissionsMode`](/docs/pt/permissions#managed-settings) desativa o modo, ou quando a sessão inicia em [modo restrito](/docs/pt/cli-reference#cli-flags).
2141 2149
2142 `bypassPermissions` nunca é persistido como `defaultMode` independentemente de `destination`.2150 `bypassPermissions` nunca é persistido como `defaultMode`, independentemente de `destination`.
2143</Note>2151</Note>
2144 2152
2145O campo `destination` em cada entrada determina se a mudança fica na memória ou persiste em um arquivo de configurações.2153O campo `destination` em cada entrada determina se a alteração permanece na memória ou é persistida em um arquivo de configurações.
2146 2154
2147| `destination` | Escreve para |2155| `destination` | Grava em |
2148| :- | :- |2156| :- | :- |
2149| `session` | apenas na memória, descartado quando a sessão termina |2157| `session` | somente na memória, descartado quando a sessão termina |
2150| `localSettings` | `.claude/settings.local.json` |2158| `localSettings` | `.claude/settings.local.json` |
2151| `projectSettings` | `.claude/settings.json` |2159| `projectSettings` | `.claude/settings.json` |
2152| `userSettings` | `~/.claude/settings.json` |2160| `userSettings` | `~/.claude/settings.json` |
2157 PostToolUse2165 PostToolUse
2158</h3>2166</h3>
2159 2167
2160Executa imediatamente após uma ferramenta ser concluída com sucesso.2168É executado imediatamente após uma ferramenta ser concluída com sucesso.
2161 2169
2162Corresponde ao nome da ferramenta, mesmos valores que PreToolUse.2170Faz correspondência pelo nome da ferramenta, com os mesmos valores de PreToolUse.
2163 2171
2164Corresponda mais amplamente quando o nome da ferramenta não é o filtro certo:2172Faça uma correspondência mais ampla quando o nome da ferramenta não for o filtro adequado:
2165 2173
2166* Para executar um hook após qualquer ferramenta ser concluída com sucesso, omita o `matcher` ou defina-o como `"*"`. Seu hook pode então descobrir o que mudou por si mesmo, por exemplo executando `git status --porcelain`, que também lista arquivos não rastreados que `git diff` perde. Para chamadas de ferramenta que falham, adicione o mesmo hook em [PostToolUseFailure](#posttoolusefailure).2174* Para executar um hook após qualquer ferramenta ser concluída com sucesso, omita o `matcher` ou defina-o como `"*"`. Seu hook pode então descobrir por conta própria o que mudou, por exemplo executando `git status --porcelain`, que também lista arquivos não rastreados que o `git diff` não mostra. Para chamadas de ferramenta que falham, adicione o mesmo hook em [PostToolUseFailure](#posttoolusefailure).
2167* Para executar um hook quando um arquivo específico muda no disco, seja qual for o que o escreveu, use [FileChanged](#filechanged). Claude Code não executa um hook `PostToolUse` correspondente a `Edit|Write` quando um comando `Bash` ou um processo fora de Claude Code reescreve o mesmo arquivo.2175* Para executar um hook quando um arquivo específico muda no disco, independentemente de quem o gravou, use [FileChanged](#filechanged). O Claude Code não executa um hook `PostToolUse` que corresponde a `Edit|Write` quando um comando `Bash` ou um processo fora do Claude Code reescreve o mesmo arquivo.
2168 2176
2169<h4 id="posttooluse-input">2177<h4 id="posttooluse-input">
2170 Entrada PostToolUse2178 Entrada do PostToolUse
2171</h4>2179</h4>
2172 2180
2173Hooks `PostToolUse` disparam após uma ferramenta já ter sido executada com sucesso. A entrada inclui tanto `tool_input`, os argumentos enviados para a ferramenta, quanto `tool_response`, o resultado que ela retornou. O esquema exato para ambos depende da ferramenta. Caminhos `tool_input` de ferramentas de arquivo chegam no mesmo formato que para [PreToolUse](#pretooluse-input): sempre absoluto, com os separadores nativos da plataforma, então barras invertidas no Windows. Para uma ferramenta MCP, a entrada também carrega o objeto [`mcp_server`](#pretooluse-input).2181Os hooks `PostToolUse` são disparados depois que uma ferramenta já foi executada com sucesso. A entrada inclui tanto `tool_input`, os argumentos enviados à ferramenta, quanto `tool_response`, o resultado que ela retornou. O esquema exato de ambos depende da ferramenta. Os caminhos em `tool_input` de ferramentas de arquivo chegam no mesmo formato que em [PreToolUse](#pretooluse-input): sempre absolutos, com os separadores nativos da plataforma, portanto barras invertidas no Windows. Para uma ferramenta MCP, a entrada também inclui o objeto [`mcp_server`](#pretooluse-input).
2174 2182
2175```json theme={null}2183```json theme={null}
2176{2184{
2195 2203
2196| Campo | Descrição |2204| Campo | Descrição |
2197| :- | :- |2205| :- | :- |
2198| `duration_ms` | Opcional. Tempo de execução da ferramenta em milissegundos. Exclui tempo gasto em prompts de permissão e hooks PreToolUse |2206| `duration_ms` | Opcional. Tempo de execução da ferramenta em milissegundos. Exclui o tempo gasto em prompts de permissão e em hooks PreToolUse |
2199 2207
2200<h4 id="posttooluse-decision-control">2208<h4 id="posttooluse-decision-control">
2201 Controle de decisão PostToolUse2209 Controle de decisão do PostToolUse
2202</h4>2210</h4>
2203 2211
2204Hooks `PostToolUse` podem fornecer feedback ao Claude após a execução da ferramenta. Além dos [campos de saída JSON](#json-output) disponíveis para todos os hooks, seu script de hook pode retornar esses campos específicos do evento:2212Os hooks `PostToolUse` podem fornecer feedback ao Claude após a execução da ferramenta. Além dos [campos de saída JSON](#json-output) disponíveis para todos os hooks, seu script de hook pode retornar estes campos específicos do evento:
2205 2213
2206| Campo | Descrição |2214| Campo | Descrição |
2207| :- | :- |2215| :- | :- |
2208| `decision` | `"block"` adiciona o `reason` ao lado do resultado da ferramenta. Claude ainda vê a saída original; para substituí-la, use `updatedToolOutput` |2216| `decision` | `"block"` adiciona o `reason` ao lado do resultado da ferramenta. O Claude ainda vê a saída original; para substituí-la, use `updatedToolOutput` |
2209| `reason` | Explicação mostrada ao Claude quando `decision` é `"block"` |2217| `reason` | Explicação mostrada ao Claude quando `decision` é `"block"` |
2210| `additionalContext` | String adicionada ao contexto do Claude junto com o resultado da ferramenta. Veja [Adicionar contexto para Claude](#add-context-for-claude) |2218| `additionalContext` | String adicionada ao contexto do Claude junto com o resultado da ferramenta. Consulte [Adicionar contexto para o Claude](#add-context-for-claude) |
2211| `classifierContext` | Nota breve sobre o resultado desta chamada para o classificador de [modo automático](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode) em vez de para Claude. Veja [Anotar um resultado para o classificador de modo automático](#annotate-a-result-for-the-auto-mode-classifier). Requer Claude Code v2.1.236 ou posterior |2219| `classifierContext` | Nota curta sobre o resultado desta chamada destinada ao classificador do [modo auto](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode), e não ao Claude. Consulte [Anotar um resultado para o classificador do modo auto](#annotate-a-result-for-the-auto-mode-classifier). Requer Claude Code v2.1.236 ou posterior |
2212| `updatedToolOutput` | Substitui a saída da ferramenta pelo valor fornecido antes de ser enviado ao Claude. O valor deve corresponder à forma de saída da ferramenta |2220| `updatedToolOutput` | Substitui a saída da ferramenta pelo valor fornecido antes de ela ser enviada ao Claude. O valor deve corresponder ao formato de saída da ferramenta |
2213| `updatedMCPToolOutput` | Substitui a saída para [ferramentas MCP](#match-mcp-tools) apenas. Prefira `updatedToolOutput`, que funciona para todas as ferramentas |2221| `updatedMCPToolOutput` | Substitui a saída somente para [ferramentas MCP](#match-mcp-tools). Prefira `updatedToolOutput`, que funciona para todas as ferramentas |
2214 2222
2215O exemplo abaixo substitui a saída de uma chamada `Bash`. O valor de substituição corresponde à forma de saída da ferramenta `Bash`:2223O exemplo abaixo substitui a saída de uma chamada `Bash`. O valor de substituição corresponde ao formato de saída da ferramenta `Bash`:
2216 2224
2217```json theme={null}2225```json theme={null}
2218{2226{
2230```2238```
2231 2239
2232<Warning>2240<Warning>
2233 `updatedToolOutput` apenas muda o que Claude vê. A ferramenta já foi executada no momento em que o hook dispara, então quaisquer arquivos escritos, comandos executados ou solicitações de rede enviadas já tiveram efeito. Telemetria como spans de ferramentas OpenTelemetry e eventos de análise também capturam a saída original antes do hook ser executado. Para impedir ou modificar uma chamada de ferramenta antes de ser executada, use um hook [PreToolUse](#pretooluse) em vez disso.2241 `updatedToolOutput` altera apenas o que o Claude vê. A ferramenta já foi executada quando o hook é disparado, portanto quaisquer arquivos gravados, comandos executados ou requisições de rede enviadas já surtiram efeito. A telemetria, como spans de ferramentas do OpenTelemetry e eventos de análise, também captura a saída original antes de o hook ser executado. Para impedir ou modificar uma chamada de ferramenta antes de ela ser executada, use um hook [PreToolUse](#pretooluse).
2234 2242
2235 O valor de substituição deve corresponder à forma de saída da ferramenta. Ferramentas integradas retornam objetos estruturados em vez de strings simples. Por exemplo, `Bash` retorna um objeto com campos `stdout`, `stderr`, `interrupted` e `isImage`. Para ferramentas integradas, um valor que não corresponde ao esquema de saída da ferramenta é ignorado e a saída original é usada. A saída de ferramentas MCP é passada sem validação de esquema. Remover detalhes de erro que Claude precisa pode fazer com que ele prossiga em uma suposição falsa.2243 O valor de substituição deve corresponder ao formato de saída da ferramenta. As ferramentas integradas retornam objetos estruturados em vez de strings simples. Por exemplo, `Bash` retorna um objeto com os campos `stdout`, `stderr`, `interrupted` e `isImage`. Para ferramentas integradas, um valor que não corresponde ao esquema de saída da ferramenta é ignorado e a saída original é usada. A saída de ferramentas MCP é repassada sem validação de esquema. Remover detalhes de erro de que o Claude precisa pode fazê-lo prosseguir com base em uma suposição falsa.
2236</Warning>2244</Warning>
2237 2245
2238<h4 id="annotate-a-result-for-the-auto-mode-classifier">2246<h4 id="annotate-a-result-for-the-auto-mode-classifier">
2239 Anotar um resultado para o classificador de modo automático2247 Anotar um resultado para o classificador do modo auto
2240</h4>2248</h4>
2241 2249
2242Retorne `classifierContext` para enviar uma nota breve sobre o resultado da chamada de ferramenta para o classificador de [modo automático](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode) em vez de para Claude. O classificador [nunca recebe resultados de ferramentas em si](/docs/pt/permission-modes#how-the-classifier-evaluates-actions), então este campo é a forma suportada de dizer algo sobre o que uma chamada retornou antes de revisar ações posteriores. O campo requer Claude Code v2.1.236 ou posterior.2250Retorne `classifierContext` para enviar uma nota curta sobre o resultado da chamada de ferramenta ao classificador do [modo auto](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode), e não ao Claude. O classificador [nunca recebe os próprios resultados das ferramentas](/docs/pt/permission-modes#how-the-classifier-evaluates-actions), então este campo é a forma suportada de informá-lo sobre o que uma chamada retornou antes que ele revise ações posteriores. O campo requer Claude Code v2.1.236 ou posterior.
2243 2251
2244O exemplo abaixo diz ao classificador de onde a saída de uma consulta veio:2252O exemplo abaixo informa ao classificador de onde veio a saída de uma consulta:
2245 2253
2246```json theme={null}2254```json theme={null}
2247{2255{
2252}2260}
2253```2261```
2254 2262
2255Quanto peso o classificador dá à nota depende de onde você configurou o hook:2263O peso que o classificador dá à nota depende de onde você configurou o hook:
2256 2264
2257* **Hooks configurados em Claude Code**: para hooks de arquivos de configurações, plugins, skills e frontmatter de agente, o classificador trata a nota como contexto não verificado fornecido pela aplicação. A nota nunca estabelece intenção do usuário, e se ela afirma que você aprovou ou solicitou algo, o classificador verifica essa afirmação contra suas próprias mensagens na conversa2265* **Hooks configurados no Claude Code**: para hooks de arquivos de configurações, plugins, skills e frontmatter de agentes, o classificador trata a nota como contexto não verificado fornecido pela aplicação. A nota nunca estabelece a intenção do usuário e, se afirmar que você aprovou ou solicitou algo, o classificador verifica essa afirmação com base nas suas próprias mensagens na conversa
2258* **Callbacks Agent SDK em processo**: quando um aplicativo incorporando Claude Code registra o hook como um [callback SDK TypeScript](/docs/pt/agent-sdk/hooks) e retorna a nota durante a sessão ao vivo, o classificador pode pesar uma declaração do usuário retransmitida na nota como intenção do usuário. Tal declaração pode satisfazer um requisito de consentimento que o classificador aceitaria de uma mensagem que você envia, mas nunca levanta um bloqueio que sua própria mensagem não pudesse levantar também. Após uma sessão retomar, Claude Code trata notas restauradas como contexto não verificado. Quando hooks de ambos os grupos anotam a mesma chamada, o classificador trata a nota combinada como não verificada2266* **Callbacks in-process do Agent SDK**: quando uma aplicação que incorpora o Claude Code registra o hook como um [callback do TypeScript SDK](/docs/pt/agent-sdk/hooks) e retorna a nota durante a sessão ativa, o classificador pode considerar uma declaração do usuário repassada na nota como intenção do usuário. Tal declaração pode satisfazer um requisito de consentimento que o classificador aceitaria de uma mensagem enviada por você, mas nunca remove um bloqueio que sua própria mensagem também não conseguiria remover. Depois que uma sessão é retomada, o Claude Code trata as notas restauradas como contexto não verificado. Quando hooks de ambos os grupos anotam a mesma chamada, o classificador trata a nota combinada como não verificada
2259 2267
2260Claude Code aplica esses limites ao entregar a nota:2268O Claude Code aplica estes limites ao entregar a nota:
2261 2269
2262* **Comprimento**: Claude Code limita as notas para uma chamada de ferramenta a 2.000 caracteres e trunca o resto. O limite é compartilhado entre cada hook que responde a essa chamada2270* **Tamanho**: o Claude Code limita as notas de uma chamada de ferramenta a 2.000 caracteres e trunca o restante. O limite é compartilhado entre todos os hooks que respondem a essa chamada
2263* **Apenas respostas síncronas**: Claude Code ignora o campo na resposta de um hook que [é executado em segundo plano](#run-hooks-in-the-background), porque essa resposta chega após Claude Code registrar o resultado da ferramenta2271* **Somente respostas síncronas**: o Claude Code ignora o campo na resposta de um hook que [é executado em segundo plano](#run-hooks-in-the-background), porque essa resposta chega depois que o Claude Code registra o resultado da ferramenta
2264* **Chamadas que o classificador não registra**: a transcrição do classificador omite buscas somente leitura como leituras de arquivo e pesquisas. Claude Code descarta uma nota anexada a uma dessas chamadas2272* **Chamadas que o classificador não registra**: a transcrição do classificador omite consultas somente leitura, como leituras de arquivos e buscas. O Claude Code descarta uma nota anexada a uma dessas chamadas
2265* **Interação com reescritas**: quando a nota descreve saída que você está substituindo com `updatedToolOutput`, retorne ambos os campos na mesma resposta do hook. Claude Code descarta a nota se essa reescrita for rejeitada ou outra reescrita do hook a substituir. Claude Code entrega uma nota que você retorna sem uma reescrita mesmo quando outro hook reescreve a saída2273* **Interação com reescritas**: quando a nota descreve uma saída que você está substituindo com `updatedToolOutput`, retorne ambos os campos na mesma resposta do hook. O Claude Code descarta a nota se essa reescrita for rejeitada ou se a reescrita de outro hook a substituir. O Claude Code entrega uma nota que você retorna sem reescrita mesmo quando outro hook reescreve a saída
2266 2274
2267<Warning>2275<Warning>
2268 O classificador lê conteúdo que você coloca em `classifierContext` como informação do aplicativo hospedando a sessão, então não copie saída de ferramenta não confiável ou texto de terceiros nele. Mantenha a nota para uma afirmação breve sobre esta uma chamada, como um fato sobre sua origem ou uma declaração do usuário sobre ela; não use o campo para entregar mensagens não relacionadas ou um fluxo de eventos.2276 O classificador lê o conteúdo que você coloca em `classifierContext` como informação da aplicação que hospeda a sessão, portanto não copie saídas de ferramentas não confiáveis ou texto de terceiros para ele. Limite a nota a uma afirmação curta sobre essa única chamada, como um fato sobre sua origem ou uma declaração do usuário a respeito dela; não use o campo para entregar mensagens não relacionadas ou um fluxo de eventos.
2269</Warning>2277</Warning>
2270 2278
2271<h3 id="posttoolusefailure">2279<h3 id="posttoolusefailure">
2272 PostToolUseFailure2280 PostToolUseFailure
2273</h3>2281</h3>
2274 2282
2275Executa quando uma ferramenta que começou a executar falha: a ferramenta lançou um erro, ou uma ferramenta MCP retornou um resultado de erro. Use isso para registrar falhas, enviar alertas ou fornecer feedback corretivo ao Claude.2283É executado quando uma ferramenta que começou a ser executada falha: a ferramenta lançou um erro ou uma ferramenta MCP retornou um resultado de erro. Use-o para registrar falhas em log, enviar alertas ou fornecer feedback corretivo ao Claude.
2276 2284
2277Corresponde ao nome da ferramenta, mesmos valores que PreToolUse.2285Faz correspondência pelo nome da ferramenta, com os mesmos valores de PreToolUse.
2278 2286
2279<Note>2287<Note>
2280 Este evento não dispara para chamadas de ferramenta rejeitadas antes da execução: um nome de ferramenta desconhecido, entrada que falha na validação de esquema ou específica da ferramenta, ou uma negação de permissão. Rejeições de validação são retornadas como resultados `tool_use_error` e acontecem antes dos hooks serem executados, então não disparam nem `PreToolUse` nem `PostToolUseFailure`. Negações de permissão disparam `PreToolUse` mas não este evento; veja [PermissionDenied](#permissiondenied).2288 Este evento não é disparado para chamadas de ferramenta rejeitadas antes da execução: um nome de ferramenta desconhecido, uma entrada que falha na validação de esquema ou específica da ferramenta, ou uma negação de permissão. As rejeições de validação são retornadas como resultados `tool_use_error` e ocorrem antes da execução dos hooks, portanto não disparam nem `PreToolUse` nem `PostToolUseFailure`. As negações de permissão disparam `PreToolUse`, mas não este evento; consulte [PermissionDenied](#permissiondenied).
2281</Note>2289</Note>
2282 2290
2283<h4 id="posttoolusefailure-input">2291<h4 id="posttoolusefailure-input">
2284 Entrada PostToolUseFailure2292 Entrada do PostToolUseFailure
2285</h4>2293</h4>
2286 2294
2287Hooks PostToolUseFailure recebem os mesmos campos `tool_name` e `tool_input` que PostToolUse, junto com informações de erro como campos de nível superior. Para uma ferramenta MCP, eles também recebem o objeto [`mcp_server`](#pretooluse-input). Por exemplo, um comando `npm test` falhado pode entregar:2295Os hooks PostToolUseFailure recebem os mesmos campos `tool_name` e `tool_input` que o PostToolUse, junto com informações de erro como campos de nível superior. Para uma ferramenta MCP, eles também recebem o objeto [`mcp_server`](#pretooluse-input). Por exemplo, um comando `npm test` com falha pode entregar:
2288 2296
2289```json theme={null}2297```json theme={null}
2290{2298{
2307 2315
2308| Campo | Descrição |2316| Campo | Descrição |
2309| :- | :- |2317| :- | :- |
2310| `error` | String descrevendo o que deu errado. O formato depende da ferramenta que falhou |2318| `error` | String que descreve o que deu errado. O formato depende da ferramenta que falhou |
2311| `is_interrupt` | Booleano opcional. True quando a falha chegou ao Claude Code como um aborto em vez de um erro que a ferramenta relatou. Cancelar uma ferramenta em execução não dispara este hook; o resultado da ferramenta carrega a mensagem de interrupção em vez disso |2319| `is_interrupt` | Booleano opcional. Verdadeiro quando a falha chegou ao Claude Code como uma interrupção, e não como um erro relatado pela ferramenta. Cancelar uma ferramenta em execução não dispara este hook; em vez disso, o resultado da ferramenta contém a mensagem de interrupção |
2312| `duration_ms` | Opcional. Tempo de execução da ferramenta em milissegundos. Exclui tempo gasto em prompts de permissão e hooks PreToolUse |2320| `duration_ms` | Opcional. Tempo de execução da ferramenta em milissegundos. Exclui o tempo gasto em prompts de permissão e em hooks PreToolUse |
2313 2321
2314A string `error` é geralmente o mesmo texto que Claude recebe como resultado da ferramenta falhada. Seu formato varia por ferramenta e falha. Chave seu hook em `tool_name`, `is_interrupt` e a primeira linha `Exit code N`; trate o resto da string como texto de exibição, não um formato estável.2322A string `error` geralmente é o mesmo texto que o Claude recebe como resultado da ferramenta que falhou. Seu formato varia conforme a ferramenta e a falha. Baseie seu hook em `tool_name`, `is_interrupt` e na primeira linha `Exit code N`; trate o restante da string como texto de exibição, não como um formato estável.
2315 2323
2316* Para Bash e PowerShell, um comando que foi executado e saiu produz uma primeira linha `Exit code N`, depois qualquer saída que o comando produziu como um bloco com stdout e stderr intercalados2324* Para Bash e PowerShell, um comando que foi executado e encerrado produz uma primeira linha `Exit code N`, seguida de qualquer saída que o comando produziu como um único bloco com stdout e stderr intercalados
2317* Um payload também pode carregar uma mensagem de falha simples sem linha de código de saída, quando Claude Code não pôde iniciar o próprio processo de shell2325* Um payload também pode conter uma mensagem de falha simples sem linha de código de saída, quando o Claude Code não conseguiu iniciar o próprio processo do shell
2318* Claude Code trunca no meio strings longas em torno de um marcador `... [N characters truncated] ...`, e pode inserir linhas suas próprias, como `Command timed out after 2m 0s`2326* O Claude Code trunca strings longas no meio em torno de um marcador `... [N characters truncated] ...` e pode inserir linhas próprias, como `Command timed out after 2m 0s`
2319 2327
2320<h4 id="posttoolusefailure-decision-control">2328<h4 id="posttoolusefailure-decision-control">
2321 Controle de decisão PostToolUseFailure2329 Controle de decisão do PostToolUseFailure
2322</h4>2330</h4>
2323 2331
2324Hooks `PostToolUseFailure` podem fornecer contexto ao Claude após uma falha de ferramenta. Além dos [campos de saída JSON](#json-output) disponíveis para todos os hooks, seu script de hook pode retornar esses campos específicos do evento:2332Os hooks `PostToolUseFailure` podem fornecer contexto ao Claude após uma falha de ferramenta. Além dos [campos de saída JSON](#json-output) disponíveis para todos os hooks, seu script de hook pode retornar estes campos específicos do evento:
2325 2333
2326| Campo | Descrição |2334| Campo | Descrição |
2327| :- | :- |2335| :- | :- |
2328| `additionalContext` | String adicionada ao contexto do Claude junto com o erro. Veja [Adicionar contexto para Claude](#add-context-for-claude) |2336| `additionalContext` | String adicionada ao contexto do Claude junto com o erro. Consulte [Adicionar contexto para o Claude](#add-context-for-claude) |
2329 2337
2330```json theme={null}2338```json theme={null}
2331{2339{
2340 PostToolBatch2348 PostToolBatch
2341</h3>2349</h3>
2342 2350
2343Executa uma vez após cada chamada de ferramenta em um lote ter sido resolvida, antes de Claude Code enviar a próxima solicitação para o modelo. `PostToolUse` dispara uma vez por ferramenta, o que significa que dispara concorrentemente quando Claude faz chamadas de ferramenta paralelas. `PostToolBatch` dispara exatamente uma vez com o lote completo, então é o lugar certo para injetar contexto que depende do conjunto de ferramentas que foram executadas em vez de em qualquer ferramenta única. Não há matcher para este evento.2351É executado uma vez depois que todas as chamadas de ferramenta de um lote foram resolvidas, antes de o Claude Code enviar a próxima requisição ao modelo. `PostToolUse` é disparado uma vez por ferramenta, o que significa que é disparado simultaneamente quando o Claude faz chamadas de ferramenta em paralelo. `PostToolBatch` é disparado exatamente uma vez com o lote completo, portanto é o lugar certo para injetar contexto que depende do conjunto de ferramentas executadas, e não de uma única ferramenta. Não há matcher para este evento.
2344 2352
2345<h4 id="posttoolbatch-input">2353<h4 id="posttoolbatch-input">
2346 Entrada PostToolBatch2354 Entrada do PostToolBatch
2347</h4>2355</h4>
2348 2356
2349Além dos [campos de entrada comuns](#common-input-fields), hooks PostToolBatch recebem `tool_calls`, um array descrevendo cada chamada de ferramenta no lote:2357Além dos [campos de entrada comuns](#common-input-fields), os hooks PostToolBatch recebem `tool_calls`, um array que descreve cada chamada de ferramenta no lote:
2350 2358
2351```json theme={null}2359```json theme={null}
2352{2360{
2372}2380}
2373```2381```
2374 2382
2375`tool_response` contém o mesmo conteúdo que o modelo recebe no bloco `tool_result` correspondente. O valor é uma string serializada ou array de bloco de conteúdo, exatamente como a ferramenta o emitiu. Para `Read`, isso significa texto com prefixo de número de linha em vez de conteúdo de arquivo bruto. Respostas podem ser grandes, então analise apenas os campos que você precisa.2383`tool_response` contém o mesmo conteúdo que o modelo recebe no bloco `tool_result` correspondente. O valor é uma string serializada ou um array de blocos de conteúdo, exatamente como a ferramenta o emitiu. Para `Read`, isso significa texto prefixado com números de linha em vez do conteúdo bruto do arquivo. As respostas podem ser grandes, portanto analise apenas os campos de que você precisa.
2376 2384
2377<Note>2385<Note>
2378 A forma `tool_response` difere da de `PostToolUse`. `PostToolUse` passa o objeto `Output` estruturado da ferramenta, como `{filePath: "...", type: "create"}` para `Write`; `PostToolBatch` passa o conteúdo `tool_result` serializado que o modelo vê.2386 O formato de `tool_response` difere do de `PostToolUse`. `PostToolUse` passa o objeto `Output` estruturado da ferramenta, como `{filePath: "...", type: "create"}` para `Write`; `PostToolBatch` passa o conteúdo serializado de `tool_result` que o modelo vê.
2379</Note>2387</Note>
2380 2388
2381<h4 id="posttoolbatch-decision-control">2389<h4 id="posttoolbatch-decision-control">
2382 Controle de decisão PostToolBatch2390 Controle de decisão do PostToolBatch
2383</h4>2391</h4>
2384 2392
2385Hooks `PostToolBatch` podem injetar contexto para Claude. Além dos [campos de saída JSON](#json-output) disponíveis para todos os hooks, seu script de hook pode retornar esses campos específicos do evento:2393Os hooks `PostToolBatch` podem injetar contexto para o Claude. Além dos [campos de saída JSON](#json-output) disponíveis para todos os hooks, seu script de hook pode retornar estes campos específicos do evento:
2386 2394
2387| Campo | Descrição |2395| Campo | Descrição |
2388| :- | :- |2396| :- | :- |
2389| `additionalContext` | String de contexto injetada uma vez antes da próxima chamada do modelo. Veja [Adicionar contexto para Claude](#add-context-for-claude) para detalhes de entrega, o que colocar nela e como sessões retomadas lidam com valores passados |2397| `additionalContext` | String de contexto injetada uma vez antes da próxima chamada ao modelo. Consulte [Adicionar contexto para o Claude](#add-context-for-claude) para detalhes de entrega, o que incluir e como sessões retomadas lidam com valores anteriores |
2390 2398
2391```json theme={null}2399```json theme={null}
2392{2400{
2397}2405}
2398```2406```
2399 2407
2400Retornar `decision: "block"` ou `continue: false` para o loop agentico antes da próxima chamada do modelo. A mensagem de bloqueio vem do JSON `reason` ou `stopReason`, ou de stderr ao sair com 2. Você a vê como um aviso na transcrição, e ela fica na conversa, então Claude a vê quando a conversa continua.2408Retornar `decision: "block"` ou `continue: false` interrompe o loop agêntico antes da próxima chamada ao modelo. A mensagem de bloqueio vem do `reason` ou `stopReason` do JSON, ou do stderr no código de saída 2. Você a vê como um aviso na transcrição, e ela permanece na conversa, então o Claude a vê quando a conversa continua.
2401 2409
2402<h3 id="permissiondenied">2410<h3 id="permissiondenied">
2403 PermissionDenied2411 PermissionDenied
2404</h3>2412</h3>
2405 2413
2406Executa quando [modo automático](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode) nega uma chamada de ferramenta, incluindo quando nega sem um veredicto do classificador porque [uma verificação de segurança separada do modo automático recusou a própria solicitação do classificador](/docs/pt/errors#auto-mode-cannot-determine-the-safety-of-an-action) ou sua resposta não foi analisada. Este hook dispara apenas em modo automático: não é executado 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, ajustar configuração ou dizer ao modelo que pode tentar novamente a chamada de ferramenta.2414É executado quando o [modo auto](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode) nega uma chamada de ferramenta, inclusive quando nega sem um veredito do classificador porque [uma verificação de segurança separada do modo auto recusou a própria requisição do classificador](/docs/pt/errors#auto-mode-cannot-determine-the-safety-of-an-action) ou porque a resposta dele não pôde ser analisada. Este hook só é disparado no modo auto: ele não é executado quando você nega manualmente uma caixa de diálogo de permissão, quando um hook `PreToolUse` bloqueia uma chamada ou quando uma regra `deny` corresponde. Use-o para registrar negações em log, ajustar a configuração ou informar ao modelo que ele pode tentar novamente a chamada de ferramenta.
2407 2415
2408Corresponde ao nome da ferramenta, mesmos valores que PreToolUse.2416Faz correspondência pelo nome da ferramenta, com os mesmos valores de PreToolUse.
2409 2417
2410<h4 id="permissiondenied-input">2418<h4 id="permissiondenied-input">
2411 Entrada PermissionDenied2419 Entrada do PermissionDenied
2412</h4>2420</h4>
2413 2421
2414Além dos [campos de entrada comuns](#common-input-fields), hooks PermissionDenied recebem `tool_name`, `tool_input`, `tool_use_id` e `reason`. Para uma ferramenta MCP, eles também recebem o objeto [`mcp_server`](#pretooluse-input).2422Além dos [campos de entrada comuns](#common-input-fields), os hooks PermissionDenied recebem `tool_name`, `tool_input`, `tool_use_id` e `reason`. Para uma ferramenta MCP, eles também recebem o objeto [`mcp_server`](#pretooluse-input).
2415 2423
2416```json theme={null}2424```json theme={null}
2417{2425{
2432 2440
2433| Campo | Descrição |2441| Campo | Descrição |
2434| :- | :- |2442| :- | :- |
2435| `reason` | O motivo da negação. Para um veredicto do classificador, na maioria das sessões ele nomeia a regra correspondente entre colchetes, como `[Data Exfiltration]`; veja [Revisar negações](/docs/pt/auto-mode-config#review-denials) para as outras formas. Para uma [negação sem veredicto](#permissiondenied-decision-control), começa com `Auto mode could not evaluate this action and is blocking it for safety`. Para uma negação porque o modelo do classificador não estava disponível, é o texto fixo `Classifier unavailable` |2443| `reason` | O motivo da negação. Para um veredito do classificador, na maioria das sessões ele nomeia a regra correspondente entre colchetes, como `[Data Exfiltration]`; consulte [Revisar negações](/docs/pt/auto-mode-config#review-denials) para as outras formas. Para uma [negação sem veredito](#permissiondenied-decision-control), ele começa com `Auto mode could not evaluate this action and is blocking it for safety`. Para uma negação porque o modelo classificador estava indisponível, é o texto fixo `Classifier unavailable` |
2436 2444
2437<h4 id="permissiondenied-decision-control">2445<h4 id="permissiondenied-decision-control">
2438 Controle de decisão PermissionDenied2446 Controle de decisão do PermissionDenied
2439</h4>2447</h4>
2440 2448
2441Hooks PermissionDenied podem dizer ao modelo que pode tentar novamente a chamada de ferramenta negada. Retorne um objeto JSON com `hookSpecificOutput.retry` definido como `true`:2449Os hooks PermissionDenied podem informar ao modelo que ele pode tentar novamente a chamada de ferramenta negada. Retorne um objeto JSON com `hookSpecificOutput.retry` definido como `true`:
2442 2450
2443```json theme={null}2451```json theme={null}
2444{2452{
2449}2457}
2450```2458```
2451 2459
2452Quando `retry` é `true`, Claude Code adiciona uma mensagem à conversa dizendo ao modelo que pode tentar novamente a chamada de ferramenta. Claude Code não reverte a negação em si. Se seu hook não retornar JSON, ou retornar `retry: false`, a negação permanece e o modelo recebe a mensagem de rejeição original.2460Quando `retry` é `true`, o Claude Code adiciona uma mensagem à conversa informando ao modelo que ele pode tentar novamente a chamada de ferramenta. O próprio Claude Code não reverte a negação. Se o seu hook não retornar JSON, ou retornar `retry: false`, a negação se mantém e o modelo recebe a mensagem de rejeição original.
2453 2461
2454Claude Code ignora `retry: true` quando o classificador produziu [nenhum veredicto sobre a ação](/docs/pt/errors#auto-mode-cannot-determine-the-safety-of-an-action): sua resposta não foi analisada, ou uma verificação de segurança separada do modo automático recusou a solicitação do classificador. Para essas negações, Claude Code já diz ao modelo na mensagem de rejeição se deve tentar novamente mais tarde ou prosseguir.2462O Claude Code ignora `retry: true` quando o classificador não produziu [nenhum veredito sobre a ação](/docs/pt/errors#auto-mode-cannot-determine-the-safety-of-an-action): sua resposta não pôde ser analisada, ou uma verificação de segurança separada do modo auto recusou a própria requisição do classificador. Para essas negações, o Claude Code já informa ao modelo, na mensagem de rejeição, se deve tentar novamente mais tarde ou seguir em frente.
2455 2463
2456<h3 id="notification">2464<h3 id="notification">
2457 Notification2465 Notification
2458</h3>2466</h3>
2459 2467
2460Executa quando Claude Code envia notificações. Corresponde ao tipo de notificação. Omita o matcher para executar hooks para todos os tipos de notificação.2468É executado quando o Claude Code envia notificações. Faz correspondência pelo tipo de notificação. Omita o matcher para executar hooks para todos os tipos de notificação.
2461 2469
2462Você recebe esses eventos de hook mesmo com notificações de desktop desativadas: a configuração `preferredNotifChannel`, incluindo `notifications_disabled`, muda apenas como você é alertado, não se seu hook é executado.2470Você recebe esses eventos de hook mesmo com as notificações da área de trabalho desativadas: a configuração `preferredNotifChannel`, incluindo `notifications_disabled`, altera apenas como você é alertado, não se o seu hook é executado.
2463 2471
2464| Matcher | Quando é disparado |2472| Matcher | Quando é disparado |
2465| :- | :- |2473| :- | :- |
2466| `permission_prompt` | Claude precisa de sua aprovação para usar uma ferramenta ou a [solicitação de rede](/docs/pt/sandboxing#network-isolation) de um comando em sandbox, e o prompt esperou cerca de seis segundos |2474| `permission_prompt` | O Claude precisa que você aprove o uso de uma ferramenta ou uma [requisição de rede](/docs/pt/sandboxing#network-isolation) de um comando em sandbox, e o prompt está aguardando há cerca de seis segundos |
2467| `idle_prompt` | Claude terminou de responder cerca de 60 segundos atrás e você não digitou desde então |2475| `idle_prompt` | O Claude terminou de responder há cerca de 60 segundos e você não digitou nada desde então |
2468| `auth_success` | Autenticação é concluída |2476| `auth_success` | A autenticação é concluída |
2469| `elicitation_dialog` | Um servidor MCP abre um formulário de elicitação e você não digitou por cerca de seis segundos |2477| `elicitation_dialog` | Um servidor MCP abre um formulário de elicitação e você não digitou nada por cerca de seis segundos |
2470| `elicitation_url_dialog` | Um servidor MCP pede que você abra uma URL do navegador e você não digitou por cerca de seis segundos |2478| `elicitation_url_dialog` | Um servidor MCP pede que você abra uma URL no navegador e você não digitou nada por cerca de seis segundos |
2471| `elicitation_complete` | Um servidor MCP relata que uma [elicitação de modo URL](#elicitation-input) está completa |2479| `elicitation_complete` | Um servidor MCP informa que uma [elicitação no modo URL](#elicitation-input) foi concluída |
2472| `elicitation_response` | Uma resposta de elicitação MCP é enviada de volta para o servidor |2480| `elicitation_response` | Uma resposta de elicitação MCP é enviada de volta ao servidor |
2473| `agent_needs_input` | Uma sessão de fundo começa a esperar sua entrada enquanto [visualização de agente](/docs/pt/agent-view) está aberta em um terminal. Também dispara quando uma sessão de terminal mostra a você uma [pergunta de configuração de terminal de colega de equipe de agente](/docs/pt/agent-teams#choose-a-display-mode) ou aviso de modo automático sobre [cobranças de solicitação do classificador](/docs/pt/auto-mode-classifier-billing) e você não digitou por cerca de seis segundos |2481| `agent_needs_input` | Uma sessão em segundo plano começa a aguardar sua entrada enquanto a [visualização de agentes](/docs/pt/agent-view) está aberta em um terminal. Também é disparado quando uma sessão de terminal mostra a você uma [pergunta de configuração de terminal de um colega de equipe de agentes](/docs/pt/agent-teams#choose-a-display-mode) ou o aviso do modo auto sobre [cobranças por requisições do classificador](/docs/pt/auto-mode-classifier-billing) e você não digitou nada por cerca de seis segundos |
2474| `agent_completed` | Uma sessão de fundo termina ou falha. Dispara apenas enquanto [visualização de agente](/docs/pt/agent-view) está aberta em um terminal |2482| `agent_completed` | Uma sessão em segundo plano termina ou falha. É disparado somente enquanto a [visualização de agentes](/docs/pt/agent-view) está aberta em um terminal |
2475| `quota_auto_resume_fired` | Claude Code continua sua tarefa após um limite de uso de claude.ai pausá-la: na redefinição, ou mais cedo quando algo que você faz em Claude Code durante a espera, como adicionar créditos de uso, atualizar seu plano ou mudar modelos, torna o uso disponível novamente, com a [exceção de configuração de modelo](/docs/pt/interactive-mode#wait-for-a-usage-limit-to-reset) |2483| `quota_auto_resume_fired` | O Claude Code continua sua tarefa depois que um limite de uso do claude.ai a pausou: na redefinição, ou antes quando algo que você faz no Claude Code durante a espera, como adicionar créditos de uso, fazer upgrade do seu plano ou trocar de modelo, torna o uso disponível novamente, com a [exceção da configuração de modelo](/docs/pt/interactive-mode#wait-for-a-usage-limit-to-reset) |
2476| `quota_auto_resume_stale` | Um limite de uso de claude.ai foi redefinido enquanto seu computador dormia por mais de cerca de 30 minutos. Claude Code espera que você pressione `Enter` em vez de continuar. Após um sono mais curto, ele continua e dispara `quota_auto_resume_fired` em vez disso |2484| `quota_auto_resume_stale` | Um limite de uso do claude.ai foi redefinido enquanto seu computador estava em suspensão por mais de cerca de 30 minutos. O Claude Code aguarda você pressionar `Enter` em vez de continuar. Após uma suspensão mais curta, ele continua e dispara `quota_auto_resume_fired` |
2477| `quota_auto_resume_disabled` | Claude Code termina sua espera por um limite de uso de claude.ai sem continuar sua tarefa: [`autoContinueAtUsageLimit`](/docs/pt/settings-reference#autocontinueatusagelimit) foi desativado ou a redefinição se moveu mais de 24 horas durante uma espera que Claude Code iniciou por conta própria, a tarefa continuada continuou atingindo o limite, ou a continuação foi bloqueada antes de chegar ao modelo. Não dispara quando você pressiona `Esc` ou `Ctrl+C`, ou escolhe **Don't continue automatically** |2485| `quota_auto_resume_disabled` | O Claude Code encerra sua espera por um limite de uso do claude.ai sem continuar sua tarefa: [`autoContinueAtUsageLimit`](/docs/pt/settings-reference#autocontinueatusagelimit) foi desativado ou a redefinição passou para mais de 24 horas adiante durante uma espera que o Claude Code iniciou por conta própria, a tarefa continuada continuou atingindo o limite, ou a continuação foi bloqueada antes de chegar ao modelo. Não é disparado quando você pressiona `Esc` ou `Ctrl+C`, ou escolhe **Don't continue automatically** |
2478 2486
2479Os tipos `quota_auto_resume_fired`, `quota_auto_resume_stale` e `quota_auto_resume_disabled` requerem Claude Code v2.1.234 ou posterior.2487Os tipos `quota_auto_resume_fired`, `quota_auto_resume_stale` e `quota_auto_resume_disabled` requerem Claude Code v2.1.234 ou posterior.
2480 2488
2481Em sessões de terminal, `permission_prompt` para a solicitação de rede de um comando em sandbox requer Claude Code v2.1.246 ou posterior.2489Em sessões de terminal, `permission_prompt` para a requisição de rede de um comando em sandbox requer Claude Code v2.1.246 ou posterior.
2482 2490
2483`agent_needs_input` para a pergunta de configuração de terminal de um colega de equipe requer Claude Code v2.1.248 ou posterior.2491`agent_needs_input` para a pergunta de configuração de terminal de um colega de equipe requer Claude Code v2.1.248 ou posterior.
2484 2492
2485<Note>2493<Note>
2486 Os tipos `permission_prompt`, `idle_prompt`, `elicitation_dialog` e `elicitation_url_dialog` compartilham seu tempo com notificações de desktop, então em sessões de terminal você só os vê quando parece que você está longe do terminal:2494 Os tipos `permission_prompt`, `idle_prompt`, `elicitation_dialog` e `elicitation_url_dialog` compartilham seu tempo com as notificações da área de trabalho, portanto, em sessões de terminal, você só os vê quando parece estar longe do terminal:
2487 2495
2488 * Espere `permission_prompt` uma vez que você não digitou por cerca de seis segundos. O temporizador começa quando o prompt de permissão aparece, e cada pressionamento de tecla o adia. Para executar um hook imediatamente quando Claude pede permissão para usar uma ferramenta, use [PermissionRequest](#permissionrequest) em vez disso.2496 * Espere `permission_prompt` quando você não tiver digitado nada por cerca de seis segundos. O temporizador começa quando o prompt de permissão aparece, e cada tecla pressionada o adia. Para executar um hook imediatamente quando o Claude pede permissão para usar uma ferramenta, use [PermissionRequest](#permissionrequest).
2489 * Espere `idle_prompt` cerca de 60 segundos após Claude terminar de responder, e apenas se você não digitou desde então. Claude Code não envia `idle_prompt` enquanto espera um limite de uso de claude.ai ser redefinido. Quando a espera termina por conta própria, um dos tipos `quota_auto_resume_*` dispara em vez disso.2497 * Espere `idle_prompt` cerca de 60 segundos depois que o Claude terminar de responder, e somente se você não tiver digitado nada desde então e nenhum agente em segundo plano, como um [subagente](/docs/pt/sub-agents) em segundo plano, ainda estiver em execução. O Claude Code não envia `idle_prompt` enquanto aguarda a redefinição de um limite de uso do claude.ai. Quando a espera termina por conta própria, um dos tipos `quota_auto_resume_*` é disparado.
2490 * Espere `elicitation_dialog` para um formulário de elicitação, ou `elicitation_url_dialog` para uma solicitação de URL do navegador, uma vez que você não digitou por cerca de seis segundos. Ambos compartilham o mesmo portão de seis segundos que `permission_prompt`: o temporizador começa quando o diálogo aparece, e cada pressionamento de tecla o adia.2498 * Espere `elicitation_dialog` para um formulário de elicitação, ou `elicitation_url_dialog` para uma solicitação de URL do navegador, quando você não tiver digitado nada por cerca de seis segundos. Ambos compartilham o mesmo limite de seis segundos de `permission_prompt`: o temporizador começa quando a caixa de diálogo aparece, e cada tecla pressionada o adia.
2491 2499
2492 Uma solicitação de permissão ou elicitação que chega enquanto outro diálogo está na tela mantém o mesmo portão de seis segundos, cronometrado a partir de quando a solicitação chega. Sua notificação pode alcançá-lo enquanto a solicitação ainda espera atrás do diálogo aberto.2500 Uma solicitação de permissão ou elicitação que chega enquanto outra caixa de diálogo está na tela mantém o mesmo limite de seis segundos, contado a partir da chegada da solicitação. Sua notificação pode chegar até você enquanto a solicitação ainda aguarda atrás da caixa de diálogo aberta.
2493</Note>2501</Note>
2494 2502
2495Claude Code cronometra `permission_prompt` diferentemente em sessões onde envia solicitações de permissão para o callback [`canUseTool`](/docs/pt/agent-sdk/user-input) do Agent SDK, que é como Claude Desktop e a extensão VS Code hospedam Claude Code:2503O Claude Code cronometra `permission_prompt` de forma diferente em sessões nas quais envia solicitações de permissão ao [callback `canUseTool`](/docs/pt/agent-sdk/user-input) do Agent SDK, que é como o Claude Desktop e a extensão do VS Code hospedam o Claude Code:
2496 2504
2497* Espere `permission_prompt` cerca de seis segundos após Claude pedir permissão. Claude Code não o adia enquanto você digita.2505* Espere `permission_prompt` cerca de seis segundos depois que o Claude pede permissão. O Claude Code não o adia enquanto você digita.
2498* Se você ou um hook [PermissionRequest](#permissionrequest) responder mais cedo, Claude Code não executa `permission_prompt`.2506* Se você ou um hook [PermissionRequest](#permissionrequest) responder antes, o Claude Code não executa `permission_prompt`.
2499* Defina [`CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS`](/docs/pt/env-vars) como `1` para desativar `permission_prompt` nessas sessões.2507* Defina [`CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS`](/docs/pt/env-vars) como `1` para desativar `permission_prompt` nessas sessões.
2500 2508
2501Antes da v2.1.233, `permission_prompt` não disparava nessas sessões.2509Antes da v2.1.233, `permission_prompt` não era disparado nessas sessões.
2502 2510
2503Use matchers separados para executar diferentes manipuladores dependendo do tipo de notificação. Esta configuração dispara um script de alerta específico de permissão quando Claude precisa de aprovação de permissão e uma notificação diferente quando Claude está ocioso:2511Use matchers separados para executar handlers diferentes dependendo do tipo de notificação. Esta configuração aciona um script de alerta específico de permissão quando o Claude precisa de aprovação de permissão e uma notificação diferente quando o Claude está ocioso:
2504 2512
2505```json theme={null}2513```json theme={null}
2506{2514{
2530```2538```
2531 2539
2532<h4 id="notification-input">2540<h4 id="notification-input">
2533 Entrada Notification2541 Entrada do Notification
2534</h4>2542</h4>
2535 2543
2536Além dos [campos de entrada comuns](#common-input-fields), hooks Notification recebem `message` com o texto de notificação, um `title` opcional e `notification_type` indicando qual tipo disparou.2544Além dos [campos de entrada comuns](#common-input-fields), os hooks Notification recebem `message` com o texto da notificação, um `title` opcional e `notification_type` indicando qual tipo foi disparado.
2537 2545
2538```json theme={null}2546```json theme={null}
2539{2547{
2547}2555}
2548```2556```
2549 2557
2550Hooks Notification não podem bloquear ou modificar notificações. Claude Code descarta seus campos `systemMessage` e `continue` mas ainda emite [`terminalSequence`](#emit-terminal-notifications), que é o que o exemplo de notificação de desktop depende. Hooks Notification são destinados a efeitos colaterais como encaminhar a notificação para um serviço externo.2558Os hooks Notification não podem bloquear nem modificar notificações. O Claude Code descarta seus campos `systemMessage` e `continue`, mas ainda emite [`terminalSequence`](#emit-terminal-notifications), que é o que o exemplo de notificação da área de trabalho utiliza. Os hooks Notification destinam-se a efeitos colaterais, como encaminhar a notificação para um serviço externo.
2551 2559
2552<h3 id="subagentstart">2560<h3 id="subagentstart">
2553 SubagentStart2561 SubagentStart
2554</h3>2562</h3>
2555 2563
2556Executa quando Claude gera um subagente com a ferramenta Agent, quando Claude [retoma um subagente](/docs/pt/sub-agents#resume-subagents) e cada vez que um colega de equipe de [agente de equipe](/docs/pt/agent-teams) em processo lida com uma nova mensagem. 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.2564É executado quando o Claude cria um subagente com a ferramenta Agent, quando o Claude [retoma um subagente](/docs/pt/sub-agents#resume-subagents) e sempre que um colega de uma [equipe de agentes](/docs/pt/agent-teams) in-process processa uma nova mensagem. Suporta matchers para filtrar pelo nome do tipo de agente. Para agentes integrados, é o nome do agente, como `general-purpose`, `Explore` ou `Plan`. Para [subagentes personalizados](/docs/pt/sub-agents), é o campo `name` do frontmatter do agente, não o nome do arquivo.
2557 2565
2558Para subagentes enviados por um [plugin](/docs/pt/plugins/overview), o tipo de agente é o identificador com escopo de plugin como `my-plugin:reviewer`, não o nome de 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$`.2566Para subagentes fornecidos por um [plugin](/docs/pt/plugins/overview), o tipo de agente é o identificador com escopo de plugin, como `my-plugin:reviewer`, não o nome simples do frontmatter. Os dois-pontos colocam um nome com escopo de plugin no caminho de expressão regular, portanto ancore o matcher com `^` e `$` para uma correspondência exata: `^my-plugin:reviewer$`.
2559 2567
2560<h4 id="subagentstart-input">2568<h4 id="subagentstart-input">
2561 Entrada SubagentStart2569 Entrada do SubagentStart
2562</h4>2570</h4>
2563 2571
2564Além dos [campos de entrada comuns](#common-input-fields), hooks SubagentStart recebem `agent_id` com o identificador único para o subagente e `agent_type` com o nome do agente que o matcher filtra.2572Além dos [campos de entrada comuns](#common-input-fields), os hooks SubagentStart recebem `agent_id` com o identificador único do subagente e `agent_type` com o nome do agente pelo qual o matcher filtra.
2565 2573
2566```json theme={null}2574```json theme={null}
2567{2575{
2574}2582}
2575```2583```
2576 2584
2577Hooks SubagentStart não podem bloquear a criação de subagente, mas podem injetar contexto no subagente. Além dos [campos de saída JSON](#json-output) disponíveis para todos os hooks, você pode retornar:2585Os hooks SubagentStart não podem bloquear a criação de subagentes, mas podem injetar contexto no subagente. Além dos [campos de saída JSON](#json-output) disponíveis para todos os hooks, você pode retornar:
2578 2586
2579| Campo | Descrição |2587| Campo | Descrição |
2580| :- | :- |2588| :- | :- |
2581| `additionalContext` | String adicionada ao contexto do subagente no início de sua conversa, antes de seu primeiro prompt. Veja [Adicionar contexto para Claude](#add-context-for-claude) |2589| `additionalContext` | String adicionada ao contexto do subagente no início de sua conversa, antes de seu primeiro prompt. Consulte [Adicionar contexto para o Claude](#add-context-for-claude) |
2582 2590
2583```json theme={null}2591```json theme={null}
2584{2592{
2589}2597}
2590```2598```
2591 2599
2592Quando o hook é executado novamente para o mesmo subagente, Claude Code injeta o contexto retornado apenas quando o contexto do subagente não já contém a cópia de uma execução anterior. A cópia injetada no lançamento permanece no lugar, deixando o [cache de prompt](/docs/pt/prompt-caching#subagents-and-the-cache) do subagente intacto. Após [compactação automática](/docs/pt/sub-agents#auto-compaction) descartar essa cópia, Claude Code injeta o contexto da próxima execução novamente.2600Quando o hook é executado novamente para o mesmo subagente, o Claude Code injeta o contexto retornado somente quando o contexto do subagente ainda não contém a cópia de uma execução anterior. A cópia injetada na inicialização permanece no lugar, mantendo intacto o [cache de prompt](/docs/pt/prompt-caching#subagents-and-the-cache) do subagente. Depois que a [compactação automática](/docs/pt/sub-agents#auto-compaction) descarta essa cópia, o Claude Code injeta novamente o contexto da próxima execução.
2593 2601
2594<h3 id="subagentstop">2602<h3 id="subagentstop">
2595 SubagentStop2603 SubagentStop
2596</h3>2604</h3>
2597 2605
2598Executa quando um subagente Claude Code terminou de responder. Corresponde ao tipo de agente, mesmos valores que SubagentStart.2606É executado quando um subagente do Claude Code termina de responder. Faz correspondência pelo tipo de agente, com os mesmos valores de SubagentStart.
2599 2607
2600<h4 id="subagentstop-input">2608<h4 id="subagentstop-input">
2601 Entrada SubagentStop2609 Entrada do SubagentStop
2602</h4>2610</h4>
2603 2611
2604Além dos [campos de entrada comuns](#common-input-fields), hooks SubagentStop recebem `stop_hook_active`, `agent_id`, `agent_type`, `agent_transcript_path` e `last_assistant_message`. O campo `agent_type` é o valor usado para filtragem de matcher. O `transcript_path` é a transcrição da sessão principal, enquanto `agent_transcript_path` é a própria transcrição do subagente armazenada em uma pasta `subagents/` aninhada. O campo `last_assistant_message` contém o conteúdo de texto da resposta final do subagente, então hooks podem acessá-lo sem analisar o arquivo de transcrição.2612Além dos [campos de entrada comuns](#common-input-fields), os hooks SubagentStop recebem `stop_hook_active`, `agent_id`, `agent_type`, `agent_transcript_path` e `last_assistant_message`. O campo `agent_type` é o valor usado para a filtragem do matcher. O `transcript_path` é a transcrição da sessão principal, enquanto `agent_transcript_path` é a transcrição do próprio subagente, armazenada em uma pasta aninhada `subagents/`. O campo `last_assistant_message` contém o conteúdo de texto da resposta final do subagente, para que os hooks possam acessá-lo sem analisar o arquivo de transcrição.
2605 2613
2606Nem todo evento SubagentStop vem de um subagente que Claude gerou. Claude Code também executa agentes internos para alguns de seus próprios recursos, como [sugestões de prompt](/docs/pt/interactive-mode#prompt-suggestions) e [perguntas laterais `/btw`](/docs/pt/interactive-mode#side-questions-with-%2Fbtw), e SubagentStop dispara quando um desses termina também. Para esses eventos, `agent_type` é o nome do agente que a sessão em si executa, como um definido com [`--agent`](/docs/pt/cli-reference#cli-flags) ou a configuração [`agent`](/docs/pt/settings-reference#agent), e uma string vazia quando a sessão é executada sem um.2614Nem todo evento SubagentStop vem de um subagente criado pelo Claude. O Claude Code também executa agentes internos para alguns de seus próprios recursos, como [sugestões de prompt](/docs/pt/interactive-mode#prompt-suggestions) e [perguntas paralelas com `/btw`](/docs/pt/interactive-mode#side-questions-with-%2Fbtw), e o SubagentStop também é disparado quando um deles termina. Para esses eventos, `agent_type` é o nome do agente com o qual a própria sessão é executada, como um definido com [`--agent`](/docs/pt/cli-reference#cli-flags) ou com a [configuração `agent`](/docs/pt/settings-reference#agent), e uma string vazia quando a sessão é executada sem um.
2607 2615
2608Um `matcher` que nomeia tipos de agente não corresponde a um `agent_type` vazio. Um hook cujo matcher é omitido, `""` ou `"*"`, ou é uma expressão regular que corresponde a uma string vazia, é executado para eventos com um `agent_type` vazio também.2616Um `matcher` que nomeia tipos de agente não corresponde a um `agent_type` vazio. Um hook cujo matcher é omitido, `""` ou `"*"`, ou é uma expressão regular que corresponde a uma string vazia, também é executado para eventos com `agent_type` vazio.
2609 2617
2610No Claude Code v2.1.271 ou posterior, um subagente que é executado com a ferramenta [`SubagentHandback`](/docs/pt/tools-reference) entrega seu relatório através dessa ferramenta antes de parar. O campo `last_assistant_message` então contém o texto de fechamento do subagente, se houver, que não é o relatório entregue. O relatório é a entrada `message` dessa chamada, que um hook `PreToolUse` ou `PostToolUse` correspondente a `SubagentHandback` recebe como `tool_input.message`.2618No Claude Code v2.1.271 ou posterior, um subagente executado com a ferramenta [`SubagentHandback`](/docs/pt/tools-reference) entrega seu relatório por meio dessa ferramenta antes de parar. O campo `last_assistant_message` passa então a conter o texto final do subagente, se houver, que não é o relatório entregue. O relatório é a entrada `message` dessa chamada, que um hook `PreToolUse` ou `PostToolUse` com correspondência em `SubagentHandback` recebe como `tool_input.message`.
2611 2619
2612Hooks SubagentStop também recebem os arrays `background_tasks` e `session_crons` descritos em [entrada Stop](#stop-input). Ambos os arrays estão no escopo da sessão pai, não do subagente.2620Os hooks SubagentStop também recebem os arrays `background_tasks` e `session_crons` descritos em [Entrada do Stop](#stop-input). Ambos os arrays têm escopo na sessão pai, não no subagente.
2613 2621
2614```json theme={null}2622```json theme={null}
2615{2623{
2628}2636}
2629```2637```
2630 2638
2631Hooks SubagentStop usam o mesmo formato de controle de decisão que [hooks Stop](#stop-decision-control), incluindo `hookSpecificOutput.additionalContext` com `hookEventName` definido como `"SubagentStop"`, para feedback sem erro que mantém o subagente em execução. Retornar `decision: "block"` com um `reason` mantém o subagente em execução e entrega `reason` ao subagente como sua próxima instrução. Um hook que bloqueia ao sair com 2 entrega sua mensagem stderr da mesma forma. Para injetar contexto na sessão pai após um subagente retornar, use um hook [`PostToolUse`](#posttooluse) na ferramenta `Agent` em vez disso.2639Os hooks SubagentStop usam o mesmo formato de controle de decisão dos [hooks Stop](#stop-decision-control), incluindo `hookSpecificOutput.additionalContext` com `hookEventName` definido como `"SubagentStop"`, para feedback que não é de erro e que mantém o subagente em execução. Retornar `decision: "block"` com um `reason` mantém o subagente em execução e entrega `reason` ao subagente como sua próxima instrução. Um hook que bloqueia saindo com código 2 entrega sua mensagem de stderr da mesma forma. Para injetar contexto na sessão pai depois que um subagente retorna, use um hook [`PostToolUse`](#posttooluse) na ferramenta `Agent`.
2632 2640
2633<h3 id="taskcreated">2641<h3 id="taskcreated">
2634 TaskCreated2642 TaskCreated
2635</h3>2643</h3>
2636 2644
2637Executa quando uma tarefa está sendo criada via ferramenta `TaskCreate`. Use isso para impor convenções de nomenclatura, exigir descrições de tarefa ou impedir que certas tarefas sejam criadas. Em uma [sessão sem as ferramentas Task](/docs/pt/tools-reference#task-tool-availability), este evento não dispara.2645É executado quando uma tarefa está sendo criada por meio da ferramenta `TaskCreate`. Use-o para impor convenções de nomenclatura, exigir descrições de tarefas ou impedir que determinadas tarefas sejam criadas. Em uma [sessão sem as ferramentas Task](/docs/pt/tools-reference#task-tool-availability), este evento não é disparado.
2638 2646
2639Hooks TaskCreated não suportam matchers e disparam em cada ocorrência.2647Os hooks TaskCreated não suportam matchers e são disparados em todas as ocorrências.
2640 2648
2641<h4 id="taskcreated-input">2649<h4 id="taskcreated-input">
2642 Entrada TaskCreated2650 Entrada do TaskCreated
2643</h4>2651</h4>
2644 2652
2645Além dos [campos de entrada comuns](#common-input-fields), hooks TaskCreated recebem `task_id`, `task_subject` e opcionalmente `task_description`, `teammate_name` e `team_name`.2653Além dos [campos de entrada comuns](#common-input-fields), os hooks TaskCreated recebem `task_id`, `task_subject` e, opcionalmente, `task_description`, `teammate_name` e `team_name`.
2646 2654
2647```json theme={null}2655```json theme={null}
2648{2656{
2660 2668
2661| Campo | Descrição |2669| Campo | Descrição |
2662| :- | :- |2670| :- | :- |
2663| `task_id` | Identificador da tarefa sendo criada |2671| `task_id` | Identificador da tarefa que está sendo criada |
2664| `task_subject` | Título da tarefa |2672| `task_subject` | Título da tarefa |
2665| `task_description` | Descrição detalhada da tarefa. Pode estar ausente |2673| `task_description` | Descrição detalhada da tarefa. Pode estar ausente |
2666| `teammate_name` | Nome do colega de equipe criando a tarefa. Pode estar ausente |2674| `teammate_name` | Nome do colega de equipe que está criando a tarefa. Pode estar ausente |
2667| `team_name` | Descontinuado. Nome de equipe derivado de sessão; será removido em uma versão futura |2675| `team_name` | Descontinuado. Nome da equipe derivado da sessão; será removido em uma versão futura |
2668 2676
2669<h4 id="taskcreated-decision-control">2677<h4 id="taskcreated-decision-control">
2670 Controle de decisão TaskCreated2678 Controle de decisão do TaskCreated
2671</h4>2679</h4>
2672 2680
2673Um hook TaskCreated pode bloquear a criação de duas maneiras. De qualquer forma, Claude Code exclui a tarefa e retorna sua mensagem ao Claude como o erro da ferramenta. Claude Code ignora `continue: false` deste evento e Claude continua trabalhando.2681Um hook TaskCreated pode bloquear a criação de duas formas. Em ambos os casos, o Claude Code exclui a tarefa e retorna sua mensagem ao Claude como o erro da ferramenta. O Claude Code ignora `continue: false` deste evento e o Claude continua trabalhando.
2674 2682
2675* **Código de saída 2**: Claude Code retorna o texto stderr como a mensagem.2683* **Código de saída 2**: o Claude Code retorna o texto do stderr como a mensagem.
2676* **JSON `{"decision": "block", "reason": "..."}`**: Claude Code retorna `reason` como a mensagem.2684* **JSON `{"decision": "block", "reason": "..."}`**: o Claude Code retorna `reason` como a mensagem.
2677 2685
2678Este exemplo bloqueia tarefas cujos assuntos não seguem o formato necessário:2686Este exemplo bloqueia tarefas cujos assuntos não seguem o formato exigido:
2679 2687
2680```bash theme={null}2688```bash theme={null}
2681#!/bin/bash2689#!/bin/bash
2694 TaskCompleted2702 TaskCompleted
2695</h3>2703</h3>
2696 2704
2697Executa 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 de equipe](/docs/pt/agent-teams) termina seu turno com tarefas em andamento. Use isso para impor critérios de conclusão como testes passando ou verificações de lint antes de uma tarefa poder fechar.2705É executado quando uma tarefa está sendo marcada como concluída. Isso é disparado em duas situações: quando qualquer agente marca explicitamente uma tarefa como concluída por meio da ferramenta TaskUpdate, ou quando um colega de uma [equipe de agentes](/docs/pt/agent-teams) termina seu turno com tarefas em andamento. Use-o para impor critérios de conclusão, como testes ou verificações de lint aprovados, antes que uma tarefa possa ser fechada.
2698 2706
2699Hooks TaskCompleted não suportam matchers e disparam em cada ocorrência.2707Os hooks TaskCompleted não suportam matchers e são disparados em todas as ocorrências.
2700 2708
2701<h4 id="taskcompleted-input">2709<h4 id="taskcompleted-input">
2702 Entrada TaskCompleted2710 Entrada do TaskCompleted
2703</h4>2711</h4>
2704 2712
2705Além dos [campos de entrada comuns](#common-input-fields), hooks TaskCompleted recebem `task_id`, `task_subject` e opcionalmente `task_description`, `teammate_name` e `team_name`.2713Além dos [campos de entrada comuns](#common-input-fields), os hooks TaskCompleted recebem `task_id`, `task_subject` e, opcionalmente, `task_description`, `teammate_name` e `team_name`.
2706 2714
2707```json theme={null}2715```json theme={null}
2708{2716{
2721 2729
2722| Campo | Descrição |2730| Campo | Descrição |
2723| :- | :- |2731| :- | :- |
2724| `task_id` | Identificador da tarefa sendo concluída |2732| `task_id` | Identificador da tarefa que está sendo concluída |
2725| `task_subject` | Título da tarefa |2733| `task_subject` | Título da tarefa |
2726| `task_description` | Descrição detalhada da tarefa. Pode estar ausente |2734| `task_description` | Descrição detalhada da tarefa. Pode estar ausente |
2727| `teammate_name` | Nome do colega de equipe concluindo a tarefa. Pode estar ausente |2735| `teammate_name` | Nome do colega de equipe que está concluindo a tarefa. Pode estar ausente |
2728| `team_name` | Descontinuado. Nome de equipe derivado de sessão; será removido em uma versão futura |2736| `team_name` | Descontinuado. Nome da equipe derivado da sessão; será removido em uma versão futura |
2729 2737
2730<h4 id="taskcompleted-decision-control">2738<h4 id="taskcompleted-decision-control">
2731 Controle de decisão TaskCompleted2739 Controle de decisão do TaskCompleted
2732</h4>2740</h4>
2733 2741
2734Hooks TaskCompleted suportam duas maneiras de controlar a conclusão da tarefa:2742Os hooks TaskCompleted suportam duas formas de controlar a conclusão de tarefas:
2735 2743
2736* **Código de saída 2**: a tarefa não é marcada como concluída e a mensagem stderr é retornada ao modelo como feedback.2744* **Código de saída 2**: a tarefa não é marcada como concluída e a mensagem de stderr é devolvida ao modelo como feedback.
2737* **JSON `{"continue": false, "stopReason": "..."}`**: quando um colega de equipe terminando seu turno disparou o evento, para o colega de equipe inteiramente, correspondendo ao comportamento do hook `Stop`. O `stopReason` é mostrado ao usuário. Quando a ferramenta `TaskUpdate` disparou o evento, Claude Code ignora `continue: false`; código de saída 2 ainda bloqueia a conclusão.2745* **JSON `{"continue": false, "stopReason": "..."}`**: quando um colega de equipe que termina seu turno acionou o evento, interrompe o colega completamente, correspondendo ao comportamento do hook `Stop`. O `stopReason` é mostrado ao usuário. Quando a ferramenta `TaskUpdate` acionou o evento, o Claude Code ignora `continue: false`; o código de saída 2 ainda bloqueia a conclusão.
2738 2746
2739Este exemplo executa testes e bloqueia a conclusão da tarefa se falharem:2747Este exemplo executa testes e bloqueia a conclusão da tarefa se eles falharem:
2740 2748
2741```bash theme={null}2749```bash theme={null}
2742#!/bin/bash2750#!/bin/bash
2756 Stop2764 Stop
2757</h3>2765</h3>
2758 2766
2759Executa quando o agente Claude Code principal terminou de responder. Não é executado se a parada ocorreu devido a uma interrupção do usuário. Erros de API disparam [StopFailure](#stopfailure) em vez disso.2767É executado quando o agente principal do Claude Code termina de responder. Não é executado se
2768a parada ocorreu devido a uma interrupção do usuário. Erros de API disparam
2769[StopFailure](#stopfailure) em vez disso.
2760 2770
2761<Tip>2771<Tip>
2762 O comando [`/goal`](/docs/pt/goal) é um atalho integrado para um hook Stop com escopo de sessão baseado em prompt. Use-o quando você quer que Claude continue trabalhando em direção a uma condição sem escrever configuração de hook.2772 O comando [`/goal`](/docs/pt/goal) é um atalho integrado para um hook Stop baseado em prompt com escopo de sessão. Use-o quando quiser que o Claude continue trabalhando em direção a uma condição sem escrever a configuração do hook.
2763</Tip>2773</Tip>
2764 2774
2765<h4 id="stop-input">2775<h4 id="stop-input">
2766 Entrada Stop2776 Entrada do Stop
2767</h4>2777</h4>
2768 2778
2769Além dos [campos de entrada comuns](#common-input-fields), hooks Stop recebem `stop_hook_active`, `last_assistant_message`, `background_tasks` e `session_crons`. O campo `stop_hook_active` é `true` quando Claude Code já está continuando como resultado de um hook stop. Verifique este valor ou processe a transcrição para evitar bloquear em uma condição que nunca será resolvida. Claude Code aplica um limite de 8 continuações consecutivas: após hooks stop terem continuado o turno oito vezes seguidas, Claude Code sobrescreve o próximo bloqueio e termina o turno. Para aumentar o limite, defina [`CLAUDE_CODE_STOP_HOOK_BLOCK_CAP`](/docs/pt/env-vars).2779Além dos [campos de entrada comuns](#common-input-fields), os hooks Stop recebem `stop_hook_active`, `last_assistant_message`, `background_tasks` e `session_crons`. O campo `stop_hook_active` é `true` quando o Claude Code já está continuando como resultado de um hook de parada. Verifique esse valor ou processe a transcrição para evitar bloquear com base em uma condição que nunca será resolvida. O Claude Code aplica um limite de 8 continuações consecutivas: depois que os hooks de parada continuaram o turno oito vezes seguidas, o Claude Code sobrescreve o próximo bloqueio e encerra o turno. Para aumentar o limite, defina [`CLAUDE_CODE_STOP_HOOK_BLOCK_CAP`](/docs/pt/env-vars).
2770 2780
2771O campo `last_assistant_message` contém o conteúdo de texto da resposta final do Claude, então hooks podem acessá-lo sem analisar o arquivo de transcrição. Para hooks que agem no turno recém-concluído, como hooks de leitura em voz alta ou notificação, use este campo em vez de ler `transcript_path`: o arquivo de transcrição não é garantido incluir a mensagem final no tempo de Stop em todas as versões.2781O campo `last_assistant_message` contém o conteúdo de texto da resposta final do Claude, para que os hooks possam acessá-lo sem analisar o arquivo de transcrição. Para hooks que atuam sobre o turno recém-concluído, como hooks de leitura em voz alta ou de notificação, use este campo em vez de ler `transcript_path`: não há garantia de que o arquivo de transcrição inclua a mensagem final no momento do Stop em todas as versões.
2772 2782
2773Os arrays `background_tasks` e `session_crons` deixam hooks distinguir "sessão está feita" de "sessão está pausada esperando que trabalho de fundo a acorde novamente". Ambos os arrays estão presentes quando o registro de tarefas é alcançável e estão vazios quando nada está em voo ou agendado.2783Os arrays `background_tasks` e `session_crons` permitem que os hooks distingam "a sessão terminou" de "a sessão está pausada aguardando que um trabalho em segundo plano a desperte novamente". Ambos os arrays estão presentes quando o registro de tarefas está acessível e ficam vazios quando não há nada em andamento ou agendado.
2774 2784
2775Cada entrada em `background_tasks` descreve uma tarefa em voo e usa esses campos:2785Cada entrada em `background_tasks` descreve uma tarefa em andamento e usa estes campos:
2776 2786
2777| Campo | Descrição |2787| Campo | Descrição |
2778| :- | :- |2788| :- | :- |
2779| `id` | Identificador de tarefa |2789| `id` | Identificador da tarefa |
2780| `type` | Rótulo de tipo de tarefa amigável como `shell`, `subagent`, `monitor`, `workflow`, `teammate`, `cloud session` ou `MCP task`. Cada rótulo identifica qual recurso Claude Code criou a tarefa. Volta para o discriminante bruto para tipos não reconhecidos |2790| `type` | Rótulo amigável do tipo de tarefa, como `shell`, `subagent`, `monitor`, `workflow`, `teammate`, `cloud session` ou `MCP task`. Cada rótulo identifica qual recurso do Claude Code criou a tarefa. Usa o discriminante bruto como alternativa para tipos não reconhecidos |
2781| `status` | Status atual da tarefa |2791| `status` | Status atual da tarefa |
2782| `description` | Descrição em texto livre, limitada a 1000 caracteres com um marcador `… [+N chars]` em string quando cortado |2792| `description` | Descrição em texto livre, limitada a 1000 caracteres com um marcador `… [+N chars]` na string quando cortada |
2783| `command` | Linha de comando de shell, limitada a 1000 caracteres. Presente apenas para tarefas `shell` |2793| `command` | Linha de comando do shell, limitada a 1000 caracteres. Presente somente para tarefas `shell` |
2784| `agent_type` | Nome de tipo de subagente. Presente apenas para tarefas `subagent` |2794| `agent_type` | Nome do tipo de subagente. Presente somente para tarefas `subagent` |
2785| `server` | Nome do servidor MCP. Presente apenas para tarefas `monitor` e `MCP task` |2795| `server` | Nome do servidor MCP. Presente somente para tarefas `monitor` e `MCP task` |
2786| `tool` | Nome da ferramenta MCP. Presente apenas para tarefas `monitor` e `MCP task` |2796| `tool` | Nome da ferramenta MCP. Presente somente para tarefas `monitor` e `MCP task` |
2787| `name` | Nome do workflow. Presente apenas para tarefas `workflow` |2797| `name` | Nome do workflow. Presente somente para tarefas `workflow` |
2788 2798
2789Cada entrada em `session_crons` descreve um despertar agendado com escopo de sessão, originário de `CronCreate`, `ScheduleWakeup` e `/loop`:2799Cada entrada em `session_crons` descreve um despertar agendado com escopo de sessão, originado de `CronCreate`, `ScheduleWakeup` e `/loop`:
2790 2800
2791| Campo | Descrição |2801| Campo | Descrição |
2792| :- | :- |2802| :- | :- |
2793| `id` | Identificador de tarefa cron |2803| `id` | Identificador da tarefa cron |
2794| `schedule` | Expressão cron, por exemplo `0 9 * * 1-5` |2804| `schedule` | Expressão cron, por exemplo `0 9 * * 1-5` |
2795| `recurring` | `false` para despertares únicos cuja programação codifica um tempo de disparo único, `true` para tarefas que disparam novamente em cada correspondência |2805| `recurring` | `false` para despertares únicos cujo agendamento codifica um único horário de disparo, `true` para tarefas que disparam novamente a cada correspondência |
2796| `prompt` | Prompt enviado quando o cron dispara, limitado a 1000 caracteres com o mesmo marcador `… [+N chars]` |2806| `prompt` | Prompt enviado quando o cron é disparado, limitado a 1000 caracteres com o mesmo marcador `… [+N chars]` |
2797 2807
2798Este exemplo mostra uma entrada Stop com uma tarefa de shell em voo e um cron recorrente:2808Este exemplo mostra uma entrada de Stop com uma tarefa de shell em andamento e um cron recorrente:
2799 2809
2800```json theme={null}2810```json theme={null}
2801{2811{
2827```2837```
2828 2838
2829<h4 id="stop-decision-control">2839<h4 id="stop-decision-control">
2830 Controle de decisão Stop2840 Controle de decisão do Stop
2831</h4>2841</h4>
2832 2842
2833Hooks `Stop` e `SubagentStop` podem controlar se Claude continua. Além dos [campos de saída JSON](#json-output) disponíveis para todos os hooks, seu script de hook pode retornar esses campos específicos do evento:2843Os hooks `Stop` e `SubagentStop` podem controlar se o Claude continua. Além dos [campos de saída JSON](#json-output) disponíveis para todos os hooks, seu script de hook pode retornar estes campos específicos do evento:
2834 2844
2835| Campo | Descrição |2845| Campo | Descrição |
2836| :- | :- |2846| :- | :- |
2837| `decision` | `"block"` impede que Claude pare. Omita para permitir que Claude pare |2847| `decision` | `"block"` impede que o Claude pare. Omita para permitir que o Claude pare |
2838| `reason` | Obrigatório quando `decision` é `"block"`. Diz ao Claude por que deve continuar |2848| `reason` | Obrigatório quando `decision` é `"block"`. Informa ao Claude por que ele deve continuar |
2839| `hookSpecificOutput.additionalContext` | Feedback sem erro para Claude. A conversa continua para que Claude possa agir sobre ele, mas ao contrário de `decision: "block"` é mostrado na transcrição como feedback de hook em vez de um erro de hook |2849| `hookSpecificOutput.additionalContext` | Feedback que não é de erro para o Claude. A conversa continua para que o Claude possa agir com base nele, mas, ao contrário de `decision: "block"`, ele é mostrado na transcrição como feedback do hook em vez de um erro do hook |
2840 2850
2841Um hook que bloqueia ao sair com 2 roteia da mesma forma que `reason`: Claude recebe a mensagem stderr como a explicação para por que deve continuar.2851Um hook que bloqueia saindo com código 2 é encaminhado da mesma forma que `reason`: o Claude recebe a mensagem de stderr como a explicação de por que deve continuar.
2842 2852
2843```json theme={null}2853```json theme={null}
2844{2854{
2847}2857}
2848```2858```
2849 2859
2850Use `additionalContext` quando o hook está funcionando como projetado e dando orientação ao Claude, como "execute a suite de testes antes de terminar". Mantém a conversa passando através das mesmas proteções de loop que `decision: "block"`, a saber a entrada `stop_hook_active` e o limite de 8 continuações consecutivas, mas a transcrição a rotula como `Stop hook feedback` e nenhuma notificação de erro de hook é mostrada:2860Use `additionalContext` quando o hook está funcionando conforme projetado e fornecendo orientação ao Claude, como "execute a suíte de testes antes de terminar". Ele mantém a conversa em andamento com as mesmas proteções contra loop de `decision: "block"`, ou seja, a entrada `stop_hook_active` e o limite de 8 continuações consecutivas, mas a transcrição o rotula como `Stop hook feedback` e nenhuma notificação de erro de hook é mostrada:
2851 2861
2852```json theme={null}2862```json theme={null}
2853{2863{
2862 StopFailure2872 StopFailure
2863</h3>2873</h3>
2864 2874
2865Executa em vez de [Stop](#stop) quando o turno termina devido a um erro de API. Claude Code ignora a saída e código de saída do hook, além de [`terminalSequence`](#emit-terminal-notifications). Use isso para registrar falhas, enviar alertas ou tomar ações de recuperação quando Claude não pode completar uma resposta devido a limites de taxa, problemas de autenticação ou outros erros de API.2875É executado em vez de [Stop](#stop) quando o turno termina devido a um erro de API. O Claude Code ignora a saída e o código de saída do hook, exceto [`terminalSequence`](#emit-terminal-notifications). Use-o para registrar falhas em log, enviar alertas ou tomar ações de recuperação quando o Claude não consegue concluir uma resposta devido a rate limits, problemas de autenticação ou outros erros de API.
2866 2876
2867<h4 id="stopfailure-input">2877<h4 id="stopfailure-input">
2868 Entrada StopFailure2878 Entrada do StopFailure
2869</h4>2879</h4>
2870 2880
2871Além dos [campos de entrada comuns](#common-input-fields), hooks StopFailure recebem `error`, `error_details` opcional e `last_assistant_message` opcional. O campo `error` identifica o tipo de erro e é usado para filtragem de matcher.2881Além dos [campos de entrada comuns](#common-input-fields), os hooks StopFailure recebem `error`, `error_details` opcional e `last_assistant_message` opcional. O campo `error` identifica o tipo de erro e é usado para a filtragem do matcher.
2872 2882
2873| Campo | Descrição |2883| Campo | Descrição |
2874| :- | :- |2884| :- | :- |
2875| `error` | Tipo de erro: `rate_limit`, `overloaded`, `authentication_failed`, `oauth_org_not_allowed`, `account_on_hold`, `billing_error`, `invalid_request`, `model_not_found`, `server_error`, `max_output_tokens`, `cloud_credential_error` ou `unknown` |2885| `error` | Tipo de erro: `rate_limit`, `overloaded`, `authentication_failed`, `oauth_org_not_allowed`, `account_on_hold`, `billing_error`, `invalid_request`, `model_not_found`, `server_error`, `max_output_tokens`, `cloud_credential_error` ou `unknown` |
2876| `error_details` | Detalhes adicionais sobre o erro, quando disponível |2886| `error_details` | Detalhes adicionais sobre o erro, quando disponíveis |
2877| `last_assistant_message` | O texto de erro renderizado mostrado na conversa. Ao contrário de `Stop` e `SubagentStop`, onde este campo contém a saída conversacional do Claude, para `StopFailure` ele contém a string de erro da API em si, como `"API Error: Rate limit reached"` |2887| `last_assistant_message` | O texto de erro renderizado mostrado na conversa. Ao contrário de `Stop` e `SubagentStop`, em que este campo contém a saída conversacional do Claude, para `StopFailure` ele contém a própria string de erro da API, como `"API Error: Rate limit reached"` |
2878 2888
2879```json theme={null}2889```json theme={null}
2880{2890{
2888}2898}
2889```2899```
2890 2900
2891Hooks StopFailure não têm controle de decisão. Eles são executados apenas para fins de notificação e logging.2901Os hooks StopFailure não têm controle de decisão. Eles são executados apenas para fins de notificação e log.
2892 2902
2893<h3 id="teammateidle">2903<h3 id="teammateidle">
2894 TeammateIdle2904 TeammateIdle
2895</h3>2905</h3>
2896 2906
2897Executa quando um colega de equipe de [agente de equipe](/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 de equipe parar de trabalhar, como exigir verificações de lint passando ou verificar que arquivos de saída existem.2907É executado quando um colega de uma [equipe de agentes](/docs/pt/agent-teams) está prestes a ficar ocioso após terminar seu turno. Use-o para impor critérios de qualidade antes que um colega pare de trabalhar, como exigir verificações de lint aprovadas ou verificar se os arquivos de saída existem.
2898 2908
2899Hooks TeammateIdle não suportam matchers e disparam em cada ocorrência.2909Os hooks TeammateIdle não suportam matchers e são disparados em todas as ocorrências.
2900 2910
2901<h4 id="teammateidle-input">2911<h4 id="teammateidle-input">
2902 Entrada TeammateIdle2912 Entrada do TeammateIdle
2903</h4>2913</h4>
2904 2914
2905Além dos [campos de entrada comuns](#common-input-fields), hooks TeammateIdle recebem `teammate_name` e `team_name`.2915Além dos [campos de entrada comuns](#common-input-fields), os hooks TeammateIdle recebem `teammate_name` e `team_name`.
2906 2916
2907```json theme={null}2917```json theme={null}
2908{2918{
2919| Campo | Descrição |2929| Campo | Descrição |
2920| :- | :- |2930| :- | :- |
2921| `teammate_name` | Nome do colega de equipe que está prestes a ficar ocioso |2931| `teammate_name` | Nome do colega de equipe que está prestes a ficar ocioso |
2922| `team_name` | Descontinuado. Nome de equipe derivado de sessão; será removido em uma versão futura |2932| `team_name` | Descontinuado. Nome da equipe derivado da sessão; será removido em uma versão futura |
2923 2933
2924<h4 id="teammateidle-decision-control">2934<h4 id="teammateidle-decision-control">
2925 Controle de decisão TeammateIdle2935 Controle de decisão do TeammateIdle
2926</h4>2936</h4>
2927 2937
2928Hooks TeammateIdle suportam duas maneiras de controlar o comportamento do colega de equipe:2938Os hooks TeammateIdle suportam duas formas de controlar o comportamento do colega de equipe:
2929 2939
2930* **Código de saída 2**: o colega de equipe recebe a mensagem stderr como feedback e continua trabalhando em vez de ficar ocioso.2940* **Código de saída 2**: o colega recebe a mensagem de stderr como feedback e continua trabalhando em vez de ficar ocioso.
2931* **JSON `{"continue": false, "stopReason": "..."}`**: para o colega de equipe inteiramente, correspondendo ao comportamento do hook `Stop`. O `stopReason` é mostrado ao usuário.2941* **JSON `{"continue": false, "stopReason": "..."}`**: interrompe o colega completamente, correspondendo ao comportamento do hook `Stop`. O `stopReason` é mostrado ao usuário.
2932 2942
2933Este exemplo verifica se um artefato de compilação existe antes de permitir que um colega de equipe fique ocioso:2943Este exemplo verifica se um artefato de build existe antes de permitir que um colega fique ocioso:
2934 2944
2935```bash theme={null}2945```bash theme={null}
2936#!/bin/bash2946#!/bin/bash
2947 ConfigChange2957 ConfigChange
2948</h3>2958</h3>
2949 2959
2950Executa quando um arquivo de configuração muda durante uma sessão. Use isso para auditar mudanças de configurações, impor políticas de segurança ou bloquear modificações não autorizadas em arquivos de configuração.2960É executado quando um arquivo de configuração muda durante uma sessão. Use-o para auditar alterações de configurações, impor políticas de segurança ou bloquear modificações não autorizadas em arquivos de configuração.
2951 2961
2952Claude Code executa hooks ConfigChange quando um arquivo de configurações, um arquivo de política gerenciada ou um arquivo de skill muda. Para política gerenciada, ele os executa apenas quando `managed-settings.json` ou um arquivo em `managed-settings.d/` muda. Ele aplica [configurações gerenciadas pelo servidor](/docs/pt/server-managed-settings) e mudanças em preferências gerenciadas macOS ou política de registro Windows sem executá-los. Em WSL com [`wslInheritsWindowsSettings`](/docs/pt/settings-reference#wslinheritswindowssettings), ele também aplica um arquivo de configurações gerenciadas do lado Windows alterado em sua pesquisa de política sem executá-los.2962O Claude Code executa hooks ConfigChange quando um arquivo de configurações, um arquivo de política gerenciada ou um arquivo de skill muda. Para política gerenciada, ele os executa somente quando `managed-settings.json` ou um arquivo em `managed-settings.d/` muda. Ele aplica [configurações gerenciadas pelo servidor](/docs/pt/server-managed-settings) e alterações nas preferências gerenciadas do macOS ou na política do registro do Windows sem executá-los. No WSL com [`wslInheritsWindowsSettings`](/docs/pt/settings-reference#wslinheritswindowssettings), ele também aplica um arquivo de configurações gerenciadas alterado do lado do Windows em sua verificação periódica de política sem executá-los.
2953 2963
2954O matcher filtra na fonte de configuração:2964O matcher filtra pela origem da configuração:
2955 2965
2956| Matcher | Quando é disparado |2966| Matcher | Quando é disparado |
2957| :- | :- |2967| :- | :- |
2961| `policy_settings` | `managed-settings.json` ou um arquivo em `managed-settings.d/` muda |2971| `policy_settings` | `managed-settings.json` ou um arquivo em `managed-settings.d/` muda |
2962| `skills` | Um arquivo de skill em `.claude/skills/` muda |2972| `skills` | Um arquivo de skill em `.claude/skills/` muda |
2963 2973
2964Este exemplo registra todas as mudanças de configuração para auditoria de segurança:2974Este exemplo registra em log todas as alterações de configuração para auditoria de segurança:
2965 2975
2966```json theme={null}2976```json theme={null}
2967{2977{
2982```2992```
2983 2993
2984<h4 id="configchange-input">2994<h4 id="configchange-input">
2985 Entrada ConfigChange2995 Entrada do ConfigChange
2986</h4>2996</h4>
2987 2997
2988Além dos [campos de entrada comuns](#common-input-fields), hooks ConfigChange recebem `source` e opcionalmente `file_path`. O campo `source` indica qual tipo de configuração mudou, e `file_path` fornece o caminho para o arquivo específico que foi modificado.2998Além dos [campos de entrada comuns](#common-input-fields), os hooks ConfigChange recebem `source` e, opcionalmente, `file_path`. O campo `source` indica qual tipo de configuração mudou, e `file_path` fornece o caminho do arquivo específico que foi modificado.
2989 2999
2990```json theme={null}3000```json theme={null}
2991{3001{
2999```3009```
3000 3010
3001<h4 id="configchange-decision-control">3011<h4 id="configchange-decision-control">
3002 Controle de decisão ConfigChange3012 Controle de decisão do ConfigChange
3003</h4>3013</h4>
3004 3014
3005Hooks ConfigChange podem bloquear mudanças de configuração de entrarem em vigor. Use código de saída 2 ou um JSON `decision` para impedir a mudança. Quando bloqueado, as novas configurações não são aplicadas à sessão em execução.3015Os hooks ConfigChange podem impedir que alterações de configuração entrem em vigor. Use o código de saída 2 ou um `decision` em JSON para impedir a alteração. Quando bloqueadas, as novas configurações não são aplicadas à sessão em execução.
3006 3016
3007| Campo | Descrição |3017| Campo | Descrição |
3008| :- | :- |3018| :- | :- |
3009| `decision` | `"block"` impede que a mudança de configuração seja aplicada. Omita para permitir a mudança |3019| `decision` | `"block"` impede que a alteração de configuração seja aplicada. Omita para permitir a alteração |
3010| `reason` | Aceito mas nunca mostrado |3020| `reason` | Aceito, mas nunca exibido |
3011 3021
3012```json theme={null}3022```json theme={null}
3013{3023{
3016}3026}
3017```3027```
3018 3028
3019Mudanças `policy_settings` não podem ser bloqueadas. Hooks ainda disparam para fontes `policy_settings` quando um arquivo de configurações gerenciadas na máquina muda, então você pode usá-los para registrar essas edições, mas qualquer decisão de bloqueio é ignorada. Isso garante que configurações gerenciadas pela empresa sempre entrem em vigor. Claude Code não executa hooks `ConfigChange` quando [configurações gerenciadas pelo servidor](/docs/pt/server-managed-settings) chegam ou são atualizadas.3029As alterações de `policy_settings` não podem ser bloqueadas. Os hooks ainda são disparados para origens `policy_settings` quando um arquivo de configurações gerenciadas na máquina muda, então você pode usá-los para registrar essas edições em log, mas qualquer decisão de bloqueio é ignorada. Isso garante que as configurações gerenciadas pela empresa sempre entrem em vigor. O Claude Code não executa hooks `ConfigChange` quando [configurações gerenciadas pelo servidor](/docs/pt/server-managed-settings) chegam ou são atualizadas.
3020 3030
3021Claude Code age na decisão de bloqueio da saída JSON de um hook ConfigChange e descarta `systemMessage` e `continue`. Uma mudança bloqueada não exibe nenhuma mensagem para você ou para Claude, independentemente de você bloquear com `reason` ou com stderr ao sair com 2. Claude Code apenas escreve uma linha no log de depuração.3031O Claude Code age com base na decisão de bloqueio da saída JSON de um hook ConfigChange e descarta `systemMessage` e `continue`. Uma alteração bloqueada não exibe nenhuma mensagem para você nem para o Claude, seja o bloqueio feito com `reason` ou com stderr no código de saída 2. O Claude Code apenas grava uma linha no log de depuração.
3022 3032
3023<h3 id="cwdchanged">3033<h3 id="cwdchanged">
3024 CwdChanged3034 CwdChanged
3025</h3>3035</h3>
3026 3036
3027Executa quando um comando de shell na conversa principal muda o diretório de trabalho, por exemplo quando Claude executa um comando `cd`. Use isso para reagir a mudanças de diretório: recarregar variáveis de ambiente, ativar toolchains específicas do projeto ou executar scripts de configuração automaticamente. Emparelha com [FileChanged](#filechanged) para ferramentas como [direnv](https://direnv.net/) que gerenciam ambiente por diretório.3037É executado quando um comando de shell na conversa principal altera o diretório de trabalho, por exemplo quando o Claude executa um comando `cd`. Use-o para reagir a mudanças de diretório: recarregar variáveis de ambiente, ativar toolchains específicas do projeto ou executar scripts de configuração automaticamente. Funciona em conjunto com [FileChanged](#filechanged) para ferramentas como [direnv](https://direnv.net/) que gerenciam o ambiente por diretório.
3028 3038
3029Hooks CwdChanged têm acesso a [`CLAUDE_ENV_FILE`](#persist-environment-variables). Variáveis escritas nesse arquivo persistem em comandos Bash subsequentes até o próximo evento CwdChanged, quando Claude Code as limpa.3039Os hooks CwdChanged têm acesso a [`CLAUDE_ENV_FILE`](#persist-environment-variables). As variáveis gravadas nesse arquivo persistem nos comandos Bash subsequentes até o próximo evento CwdChanged, quando o Claude Code as limpa.
3030 3040
3031CwdChanged não suporta matchers e dispara em cada ocorrência.3041O CwdChanged não suporta matchers e é disparado em todas as ocorrências.
3032 3042
3033<h4 id="cwdchanged-input">3043<h4 id="cwdchanged-input">
3034 Entrada CwdChanged3044 Entrada do CwdChanged
3035</h4>3045</h4>
3036 3046
3037Além dos [campos de entrada comuns](#common-input-fields), hooks CwdChanged recebem `old_cwd` e `new_cwd`.3047Além dos [campos de entrada comuns](#common-input-fields), os hooks CwdChanged recebem `old_cwd` e `new_cwd`.
3038 3048
3039```json theme={null}3049```json theme={null}
3040{3050{
3048```3058```
3049 3059
3050<h4 id="cwdchanged-output">3060<h4 id="cwdchanged-output">
3051 Saída CwdChanged3061 Saída do CwdChanged
3052</h4>3062</h4>
3053 3063
3054Além dos [campos de saída JSON](#json-output) disponíveis para todos os hooks, hooks CwdChanged podem retornar `watchPaths` para definir dinamicamente quais caminhos de arquivo [FileChanged](#filechanged) observa:3064Além dos [campos de saída JSON](#json-output) disponíveis para todos os hooks, os hooks CwdChanged podem retornar `watchPaths` para definir dinamicamente quais caminhos de arquivo o [FileChanged](#filechanged) monitora:
3055 3065
3056| Campo | Descrição |3066| Campo | Descrição |
3057| :- | :- |3067| :- | :- |
3058| `watchPaths` | Array de caminhos absolutos. Substitui a lista de observação dinâmica atual. Caminhos de sua configuração `matcher` são sempre observados. Retornar um array vazio limpa a lista dinâmica, que é típico ao entrar em um novo diretório |3068| `watchPaths` | Array de caminhos absolutos. Substitui a lista de monitoramento dinâmica atual. Os caminhos da sua configuração de `matcher` são sempre monitorados. Retornar um array vazio limpa a lista dinâmica, o que é comum ao entrar em um novo diretório |
3059 3069
3060Hooks CwdChanged não têm controle de decisão. Eles não podem bloquear a mudança de diretório.3070Os hooks CwdChanged não têm controle de decisão. Eles não podem bloquear a mudança de diretório.
3061 3071
3062Claude Code lê `watchPaths` e `systemMessage` de sua saída JSON e descarta `continue`. Em sessões interativas, mostra o `systemMessage` como uma notificação de terminal breve. A mensagem não chega ao fluxo de mensagens do SDK.3072O Claude Code lê `watchPaths` e `systemMessage` da saída JSON deles e descarta `continue`. Em sessões interativas, ele mostra o `systemMessage` como uma breve notificação no terminal. A mensagem não chega ao fluxo de mensagens do SDK.
3063 3073
3064<h3 id="directoryadded">3074<h3 id="directoryadded">
3065 DirectoryAdded3075 DirectoryAdded
3066</h3>3076</h3>
3067 3077
3068Executa após você adicionar um diretório de trabalho no meio da sessão com o comando `/add-dir`, ou após um cliente SDK adicionar um com a solicitação de controle `register_repo_root`. Use isso para preparar um repositório recém-adicionado, por exemplo instalando suas dependências.3078É executado depois que você adiciona um diretório de trabalho no meio da sessão com o comando `/add-dir`, ou depois que um cliente SDK adiciona um com a requisição de controle `register_repo_root`. Use-o para preparar um repositório recém-adicionado, por exemplo instalando suas dependências.
3069 3079
3070Claude Code não dispara este evento quando:3080O Claude Code não dispara este evento quando:
3071 3081
3072* Você passa um diretório com a flag de startup `--add-dir`; [SessionStart](#sessionstart) cobre esses diretórios3082* Você passa um diretório com a flag de inicialização `--add-dir`; [SessionStart](#sessionstart) cobre esses diretórios
3073* Você adiciona um diretório na aba Workspace `/permissions`3083* Você adiciona um diretório na aba Workspace de `/permissions`
3074* Você adiciona um diretório que já é um diretório de trabalho ou está dentro de um3084* Você adiciona um diretório que já é um diretório de trabalho ou está dentro de um
3075 3085
3076Claude Code dispara DirectoryAdded após atualizar estado de sandbox e permissão, então ferramentas em sandbox já veem o novo diretório quando seu hook é executado. Comandos de hook em si são executados sem sandbox.3086O Claude Code dispara o DirectoryAdded depois de atualizar o estado do sandbox e das permissões, então as ferramentas em sandbox já veem o novo diretório quando seu hook é executado. Os próprios comandos de hook são executados fora do sandbox.
3077 3087
3078Claude Code não espera pelo hook: a adição é concluída imediatamente, e o hook é executado em segundo plano com o tempo limite padrão de 600 segundos.3088O Claude Code não espera pelo hook: a adição é concluída imediatamente, e o hook é executado em segundo plano com o timeout padrão de 600 segundos.
3079 3089
3080O matcher filtra em como o diretório foi adicionado:3090O matcher filtra pela forma como o diretório foi adicionado:
3081 3091
3082| Matcher | Quando é disparado |3092| Matcher | Quando é disparado |
3083| :- | :- |3093| :- | :- |
3084| `slash_command` | Você adiciona um diretório com `/add-dir` |3094| `slash_command` | Você adiciona um diretório com `/add-dir` |
3085| `register_repo_root` | Um cliente SDK adiciona um diretório com a solicitação de controle `register_repo_root` |3095| `register_repo_root` | Um cliente SDK adiciona um diretório com a requisição de controle `register_repo_root` |
3086 3096
3087<h4 id="directoryadded-input">3097<h4 id="directoryadded-input">
3088 Entrada DirectoryAdded3098 Entrada do DirectoryAdded
3089</h4>3099</h4>
3090 3100
3091Além dos [campos de entrada comuns](#common-input-fields), hooks DirectoryAdded recebem `directory` e `source`.3101Além dos [campos de entrada comuns](#common-input-fields), os hooks DirectoryAdded recebem `directory` e `source`.
3092 3102
3093| Campo | Descrição |3103| Campo | Descrição |
3094| :- | :- |3104| :- | :- |
3095| `directory` | Caminho absoluto do diretório que foi adicionado |3105| `directory` | Caminho absoluto do diretório que foi adicionado |
3096| `source` | Como o diretório foi adicionado, `"slash_command"` para `/add-dir` ou `"register_repo_root"` para a solicitação de controle do SDK |3106| `source` | Como o diretório foi adicionado, `"slash_command"` para `/add-dir` ou `"register_repo_root"` para a requisição de controle do SDK |
3097 3107
3098```json theme={null}3108```json theme={null}
3099{3109{
3106}3116}
3107```3117```
3108 3118
3109Hooks DirectoryAdded não têm controle de decisão. Eles não podem bloquear a adição, que já foi concluída quando o hook é executado. Claude Code descarta o campo `continue` de sua saída JSON e exibe o resto diferentemente por fonte:3119Os hooks DirectoryAdded não têm controle de decisão. Eles não podem bloquear a adição, que já foi concluída quando o hook é executado. O Claude Code descarta o campo `continue` da saída JSON deles e apresenta o restante de forma diferente conforme a origem:
3110 3120
3111* `slash_command`: Claude Code entrega o `systemMessage` do hook ao Claude como contexto no próximo turno de conversa, em vez de mostrar a você. Uma contagem de hooks falhados aparece na transcrição. Saída de falha completa vai para o log de depuração3121* `slash_command`: o Claude Code entrega o `systemMessage` do hook ao Claude como contexto no próximo turno da conversa, em vez de mostrá-lo a você. Uma contagem de hooks com falha aparece na transcrição. A saída completa das falhas vai para o log de depuração
3112* `register_repo_root`: Claude Code escreve saída `systemMessage` e saída de falha apenas no log de depuração3122* `register_repo_root`: o Claude Code grava a saída de `systemMessage` e a saída de falhas somente no log de depuração
3113 3123
3114<h3 id="filechanged">3124<h3 id="filechanged">
3115 FileChanged3125 FileChanged
3116</h3>3126</h3>
3117 3127
3118Executa quando um arquivo observado muda no disco. Claude Code detecta mudanças com um observador de sistema de arquivos, não inspecionando chamadas de ferramenta, então executa o hook não importa o que mudou o arquivo: uma chamada de ferramenta `Edit` ou `Write`, um script que Claude executa com `Bash`, ou um processo fora de Claude Code inteiramente. Um uso comum é recarregar variáveis de ambiente quando arquivos de configuração do projeto mudam.3128É executado quando um arquivo monitorado muda no disco. O Claude Code detecta alterações com um monitor do sistema de arquivos, não inspecionando chamadas de ferramenta, portanto executa o hook independentemente do que alterou o arquivo: uma chamada de ferramenta `Edit` ou `Write`, um script que o Claude executa com `Bash` ou um processo totalmente fora do Claude Code. Um uso comum é recarregar variáveis de ambiente quando arquivos de configuração do projeto mudam.
3119 3129
3120O `matcher` para este evento serve dois papéis:3130O `matcher` deste evento tem duas funções:
3121 3131
3122* **Construir a lista de observação**: o valor é dividido em `|` e cada segmento é registrado como um nome de arquivo literal no diretório de trabalho, então `".envrc|.env"` observa exatamente esses dois arquivos. Padrões regex não são úteis aqui: um valor como `^\.env` observaria um arquivo literalmente nomeado `^\.env`.3132* **Construir a lista de monitoramento**: o valor é dividido em `|` e cada segmento é registrado como um nome de arquivo literal no diretório de trabalho, então `".envrc|.env"` monitora exatamente esses dois arquivos. Padrões regex não são úteis aqui: um valor como `^\.env` monitoraria um arquivo literalmente chamado `^\.env`.
3123* **Filtrar quais hooks são executados**: quando um arquivo observado muda, o mesmo valor filtra quais grupos de hook são executados usando as [regras de matcher](#matcher-patterns) padrão contra o nome base do arquivo alterado.3133* **Filtrar quais hooks são executados**: quando um arquivo monitorado muda, o mesmo valor filtra quais grupos de hooks são executados usando as [regras de matcher](#matcher-patterns) padrão em relação ao nome base do arquivo alterado.
3124 3134
3125Este exemplo normaliza terminações de linha em `data.csv` após qualquer mudança, incluindo um comando `Bash` ou um script externo reescrevendo o arquivo:3135Este exemplo normaliza as terminações de linha em `data.csv` após qualquer alteração, incluindo um comando `Bash` ou um script externo que reescreve o arquivo:
3126 3136
3127```json theme={null}3137```json theme={null}
3128{3138{
3142}3152}
3143```3153```
3144 3154
3145O hook lê o caminho absoluto do arquivo alterado do campo `file_path` da [entrada JSON](#filechanged-input) em stdin. Sua guarda `grep` testa a mesma coisa que `perl` remove, um CR no final de uma linha, então a execução após uma normalização sai sem tocar no arquivo. Uma guarda mais solta faz um loop infinito, porque `perl -i` reescreve o arquivo mesmo quando não substitui nada e Claude Code executa o hook novamente após cada reescrita. Salve este script em `/path/to/normalize-line-endings.sh` e torne-o executável:3155O hook lê o caminho absoluto do arquivo alterado do campo `file_path` da [entrada JSON](#filechanged-input) no stdin. Sua proteção com `grep` testa a mesma coisa que o `perl` remove, um CR no final de uma linha, portanto a execução após uma normalização termina sem tocar no arquivo. Uma proteção menos rigorosa entra em loop para sempre, porque `perl -i` reescreve o arquivo mesmo quando não substitui nada, e o Claude Code executa o hook novamente após cada reescrita. Salve este script em `/path/to/normalize-line-endings.sh` e torne-o executável:
3146 3156
3147```bash theme={null}3157```bash theme={null}
3148#!/bin/bash3158#!/bin/bash
3152fi3162fi
3153```3163```
3154 3164
3155Para confirmar que o hook funciona, peça ao Claude para anexar uma linha CRLF a `data.csv` com um comando `Bash`. Claude Code executa o hook e o arquivo termina com terminações LF.3165Para confirmar que o hook funciona, peça ao Claude para acrescentar uma linha CRLF a `data.csv` com um comando `Bash`. O Claude Code executa o hook e o arquivo fica com terminações LF.
3156 3166
3157Para observar arquivos que você não pode nomear antecipadamente, retorne [`watchPaths`](#filechanged-output) de um hook para atualizar a lista de observação dinamicamente. Claude Code inicia o observador apenas quando algo nomeia um arquivo para observar, então semeie a lista com um grupo FileChanged cujo matcher nomeia pelo menos um arquivo, ou com um hook [SessionStart](#sessionstart-decision-control) ou [CwdChanged](#cwdchanged) que retorna `watchPaths`. O matcher ainda filtra quais grupos de hook são executados quando um arquivo observado muda, então dê ao grupo que lida com caminhos dinâmicos um matcher omitido, que corresponde a cada arquivo observado e não adiciona nada à lista de observação. Um matcher `"*"` também corresponde a cada arquivo, mas Claude Code o registra na lista de observação como qualquer outro valor, como um arquivo literal nomeado `*`.3167Para monitorar arquivos que você não pode nomear de antemão, retorne [`watchPaths`](#filechanged-output) de um hook para atualizar a lista de monitoramento dinamicamente. O Claude Code inicia o monitor somente quando algo nomeia um arquivo a ser monitorado, então inicialize a lista com um grupo FileChanged cujo matcher nomeie pelo menos um arquivo, ou com um hook [SessionStart](#sessionstart-decision-control) ou [CwdChanged](#cwdchanged) que retorne `watchPaths`. O matcher ainda filtra quais grupos de hooks são executados quando um arquivo monitorado muda, então dê ao grupo que lida com caminhos dinâmicos um matcher omitido, que corresponde a todos os arquivos monitorados e não adiciona nada à lista de monitoramento. Um matcher `"*"` também corresponde a todos os arquivos, mas o Claude Code o registra na lista de monitoramento como qualquer outro valor, como um arquivo literal chamado `*`.
3158 3168
3159Hooks FileChanged têm acesso a [`CLAUDE_ENV_FILE`](#persist-environment-variables). Variáveis escritas nesse arquivo persistem em comandos Bash subsequentes até o próximo evento [CwdChanged](#cwdchanged), quando Claude Code as limpa.3169Os hooks FileChanged têm acesso a [`CLAUDE_ENV_FILE`](#persist-environment-variables). As variáveis gravadas nesse arquivo persistem nos comandos Bash subsequentes até o próximo evento [CwdChanged](#cwdchanged), quando o Claude Code as limpa.
3160 3170
3161<h4 id="filechanged-input">3171<h4 id="filechanged-input">
3162 Entrada FileChanged3172 Entrada do FileChanged
3163</h4>3173</h4>
3164 3174
3165Além dos [campos de entrada comuns](#common-input-fields), hooks FileChanged recebem `file_path` e `event`.3175Além dos [campos de entrada comuns](#common-input-fields), os hooks FileChanged recebem `file_path` e `event`.
3166 3176
3167| Campo | Descrição |3177| Campo | Descrição |
3168| :- | :- |3178| :- | :- |
3169| `file_path` | Caminho absoluto para o arquivo que mudou |3179| `file_path` | Caminho absoluto do arquivo que mudou |
3170| `event` | O que aconteceu: `"change"` para um arquivo modificado, `"add"` para um arquivo criado ou `"unlink"` para um arquivo excluído |3180| `event` | O que aconteceu: `"change"` para um arquivo modificado, `"add"` para um arquivo criado ou `"unlink"` para um arquivo excluído |
3171 3181
3172```json theme={null}3182```json theme={null}
3181```3191```
3182 3192
3183<h4 id="filechanged-output">3193<h4 id="filechanged-output">
3184 Saída FileChanged3194 Saída do FileChanged
3185</h4>3195</h4>
3186 3196
3187Além dos [campos de saída JSON](#json-output) disponíveis para todos os hooks, hooks FileChanged podem retornar `watchPaths` para atualizar dinamicamente quais caminhos de arquivo são observados:3197Além dos [campos de saída JSON](#json-output) disponíveis para todos os hooks, os hooks FileChanged podem retornar `watchPaths` para atualizar dinamicamente quais caminhos de arquivo são monitorados:
3188 3198
3189| Campo | Descrição |3199| Campo | Descrição |
3190| :- | :- |3200| :- | :- |
3191| `watchPaths` | Array de caminhos absolutos. Substitui a lista de observação dinâmica atual. Caminhos de sua configuração `matcher` são sempre observados. Use isso quando seu script de hook descobre arquivos adicionais para observar com base no arquivo alterado |3201| `watchPaths` | Array de caminhos absolutos. Substitui a lista de monitoramento dinâmica atual. Os caminhos da sua configuração de `matcher` são sempre monitorados. Use isto quando seu script de hook descobrir arquivos adicionais a monitorar com base no arquivo alterado |
3192 3202
3193Hooks FileChanged não têm controle de decisão. Eles não podem bloquear a mudança de arquivo de ocorrer.3203Os hooks FileChanged não têm controle de decisão. Eles não podem impedir que a alteração do arquivo ocorra.
3194 3204
3195Claude Code lê `watchPaths` e `systemMessage` de sua saída JSON e descarta `continue`. Em sessões interativas, mostra o `systemMessage` como uma notificação de terminal breve. A mensagem não chega ao fluxo de mensagens do SDK.3205O Claude Code lê `watchPaths` e `systemMessage` da saída JSON deles e descarta `continue`. Em sessões interativas, ele mostra o `systemMessage` como uma breve notificação no terminal. A mensagem não chega ao fluxo de mensagens do SDK.
3196 3206
3197<h3 id="worktreecreate">3207<h3 id="worktreecreate">
3198 WorktreeCreate3208 WorktreeCreate
3199</h3>3209</h3>
3200 3210
3201Executa quando uma worktree está sendo criada, seja de `claude --worktree`, de um [subagente usando `isolation: "worktree"`](/docs/pt/sub-agents#choose-the-subagent-scope), ou para uma [sessão de fundo](/docs/pt/agent-view#how-file-edits-are-isolated) que Claude Code isola em sua própria worktree. 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.3211É executado quando um worktree está sendo criado, seja a partir de `claude --worktree`, de um [subagente usando `isolation: "worktree"`](/docs/pt/sub-agents#choose-the-subagent-scope) ou para uma [sessão em segundo plano](/docs/pt/agent-view#how-file-edits-are-isolated) que o Claude Code isola em seu próprio worktree. Por padrão, o Claude Code cria a cópia de trabalho isolada com `git worktree`. Configurar um hook WorktreeCreate substitui esse comportamento padrão do git, permitindo que você use um sistema de controle de versão diferente, como SVN, Perforce ou Mercurial.
3202 3212
3203Como 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 a nova worktree, faça-o dentro de seu script de hook.3213Como o hook substitui o comportamento padrão por completo, [`.worktreeinclude`](/docs/pt/worktrees#copy-gitignored-files-into-worktrees) não é processado. Se você precisar copiar arquivos de configuração locais como `.env` para o novo worktree, faça isso dentro do seu script de hook.
3204 3214
3205O hook deve retornar o caminho para o diretório de worktree criado. Claude Code usa este caminho como o diretório de trabalho para a sessão isolada. Veja [saída WorktreeCreate](#worktreecreate-output) para como cada tipo de hook retorna o caminho.3215O hook deve retornar o caminho do diretório do worktree criado. O Claude Code usa esse caminho como o diretório de trabalho da sessão isolada. Consulte [Saída do WorktreeCreate](#worktreecreate-output) para ver como cada tipo de hook retorna o caminho.
3206 3216
3207Claude Code age no sucesso do hook e no caminho retornado, e descarta `systemMessage` e `continue`.3217O Claude Code age com base no sucesso do hook e no caminho retornado, e descarta `systemMessage` e `continue`.
3208 3218
3209Este exemplo cria uma cópia de trabalho SVN e imprime o caminho para Claude Code usar. Substitua a URL do repositório pela sua própria:3219Este exemplo cria uma cópia de trabalho SVN e imprime o caminho para o Claude Code usar. Substitua a URL do repositório pela sua:
3210 3220
3211```json theme={null}3221```json theme={null}
3212{3222{
3225}3235}
3226```3236```
3227 3237
3228O hook lê o `name` da worktree da entrada JSON em stdin, faz checkout de uma cópia fresca em um novo diretório e imprime o caminho do diretório. O `echo` na última linha é o que Claude Code lê como o caminho da worktree. Redirecione qualquer outra saída para stderr para que não interfira com o caminho.3238O hook lê o `name` do worktree da entrada JSON no stdin, faz checkout de uma cópia nova em um novo diretório e imprime o caminho do diretório. O `echo` na última linha é o que o Claude Code lê como o caminho do worktree. Redirecione qualquer outra saída para o stderr para que ela não interfira no caminho.
3229 3239
3230<h4 id="worktreecreate-input">3240<h4 id="worktreecreate-input">
3231 Entrada WorktreeCreate3241 Entrada do WorktreeCreate
3232</h4>3242</h4>
3233 3243
3234Além dos [campos de entrada comuns](#common-input-fields), hooks WorktreeCreate recebem o campo `name`. Este é um identificador slug para a nova worktree, especificado pelo usuário ou auto-gerado, por exemplo `bold-oak-a3f2`.3244Além dos [campos de entrada comuns](#common-input-fields), os hooks WorktreeCreate recebem o campo `name`. Ele é um identificador slug para o novo worktree, especificado pelo usuário ou gerado automaticamente, por exemplo `bold-oak-a3f2`.
3235 3245
3236```json theme={null}3246```json theme={null}
3237{3247{
3244```3254```
3245 3255
3246<h4 id="worktreecreate-output">3256<h4 id="worktreecreate-output">
3247 Saída WorktreeCreate3257 Saída do WorktreeCreate
3248</h4>3258</h4>
3249 3259
3250Hooks WorktreeCreate não usam o modelo de decisão permitir/bloquear padrão. Em vez disso, o sucesso ou falha do hook determina o resultado. O hook deve retornar o caminho para o diretório de worktree criado:3260Os hooks WorktreeCreate não usam o modelo padrão de decisão de permitir/bloquear. Em vez disso, o sucesso ou a falha do hook determina o resultado. O hook deve retornar o caminho para o diretório do worktree criado:
3251 3261
3252* **Hooks de comando** (`type: "command"`): imprima o caminho como a última linha não vazia de stdout. Claude Code remove códigos de escape ANSI antes de ler essa linha, então banners de startup de shell impressos antes de seu `echo` são ignorados. Redirecione qualquer outra saída de hook para stderr.3262* **Hooks de comando** (`type: "command"`): imprima o caminho como a última linha não vazia do stdout. O Claude Code remove os códigos de escape ANSI antes de ler essa linha, então os banners de inicialização do shell impressos antes do seu `echo` são ignorados. Redirecione qualquer outra saída do hook para o stderr.
3253* **Hooks HTTP** (`type: "http"`): retorne `{ "hookSpecificOutput": { "hookEventName": "WorktreeCreate", "worktreePath": "/absolute/path" } }` no corpo da resposta.3263* **Hooks HTTP** (`type: "http"`): retorne `{ "hookSpecificOutput": { "hookEventName": "WorktreeCreate", "worktreePath": "/absolute/path" } }` no corpo da resposta.
3254 3264
3255Se o hook falhar ou não produzir um caminho, a criação de worktree falha com um erro.3265Se o hook falhar ou não produzir nenhum caminho, a criação do worktree falha com um erro.
3256 3266
3257Claude Code resolve um caminho relativo contra o diretório em que o hook foi executado, colapsando quaisquer segmentos `.` ou `..` nele. Se o caminho resultante não for um diretório que Claude Code possa entrar, a sessão imprime um erro nomeando o caminho e sai com código 1.3267O Claude Code resolve um caminho relativo em relação ao diretório em que o hook foi executado, eliminando quaisquer segmentos `.` ou `..` nele. Se o caminho resultante não for um diretório em que o Claude Code possa entrar, a sessão imprime um erro com o nome do caminho e encerra com o código 1.
3258 3268
3259Claude Code recusa um caminho absoluto que contém segmentos `.` ou `..`, e qualquer caminho que passa através de um symlink abaixo da raiz do repositório, porque um symlink comprometido no repositório poderia redirecionar a worktree para fora dele. O erro nomeia o componente rejeitado. Retorne um caminho normalizado que não passa através de um symlink dentro do repositório. Antes da v2.1.216, a criação de worktree seguia o caminho do hook sem essa triagem.3269O Claude Code recusa um caminho absoluto que contenha segmentos `.` ou `..`, e qualquer caminho que passe por um link simbólico abaixo da raiz do repositório, porque um link simbólico commitado no repositório poderia redirecionar o worktree para fora dele. O erro indica o componente rejeitado. Retorne um caminho normalizado que não passe por um link simbólico dentro do repositório. Antes da v2.1.216, a criação do worktree seguia o caminho do hook sem essa verificação.
3260 3270
3261<h3 id="worktreeremove">3271<h3 id="worktreeremove">
3262 WorktreeRemove3272 WorktreeRemove
3263</h3>3273</h3>
3264 3274
3265Executa quando uma worktree está sendo removida. Este é o equivalente de limpeza para [WorktreeCreate](#worktreecreate). O evento dispara quando:3275É executado quando um worktree está sendo removido. Este é o equivalente de limpeza do [WorktreeCreate](#worktreecreate). O evento é disparado quando:
3266 3276
3267* você sai de uma sessão `--worktree` e escolhe removê-la3277* você sai de uma sessão `--worktree` e escolhe removê-lo
3268* um subagente com `isolation: "worktree"` termina3278* um subagente com `isolation: "worktree"` termina
3269* você exclui uma [sessão de fundo](/docs/pt/agent-view#what-deleting-a-session-removes) cuja worktree o hook criou3279* você exclui uma [sessão em segundo plano](/docs/pt/agent-view#what-deleting-a-session-removes) cujo worktree foi criado pelo hook
3270 3280
3271Para worktrees baseadas em git, Claude Code lida com limpeza automaticamente com `git worktree remove`. Se você configurou um hook WorktreeCreate, emparelhe-o com um hook WorktreeRemove para controlar a limpeza das worktrees que ele cria:3281Para worktrees baseados em git, o Claude Code lida com a limpeza automaticamente com `git worktree remove`. Se você configurou um hook WorktreeCreate, combine-o com um hook WorktreeRemove para controlar a limpeza dos worktrees que ele cria:
3272 3282
3273* **Sem hook WorktreeRemove**: quando você sai de uma sessão `--worktree` e escolhe remoção, Claude Code volta para `git worktree remove --force` no caminho que seu hook WorktreeCreate retornou, então uma worktree que git reconhece é removida. Uma worktree que git não reconhece, por exemplo uma que seu hook criou com um sistema de controle de versão não-git, fica no disco. Para o que excluir uma [sessão de fundo](/docs/pt/agent-view#what-deleting-a-session-removes) faz com uma worktree criada por hook, veja as regras de exclusão da visualização de agente.3283* **Sem hook WorktreeRemove**: quando você sai de uma sessão `--worktree` e escolhe a remoção, o Claude Code recorre a `git worktree remove --force` no caminho que seu hook WorktreeCreate retornou, de modo que um worktree que o git reconhece é removido. Um worktree que o git não reconhece, por exemplo, um que seu hook criou com um sistema de controle de versão que não seja git, permanece no disco. Para saber o que a exclusão de uma [sessão em segundo plano](/docs/pt/agent-view#what-deleting-a-session-removes) faz com um worktree criado por hook, consulte as regras de exclusão da visualização de agentes.
3274* **Hook sai com 0**: a worktree é contada como removida. Claude Code não lê nada mais do hook, então certifique-se de que seu hook excluiu o diretório.3284* **O hook encerra com 0**: o worktree é considerado removido. O Claude Code não lê mais nada do hook, então certifique-se de que seu hook excluiu o diretório.
3275* **Hook sai com código não-zero**: a remoção falha se o diretório em `worktree_path` ainda existir depois, e a worktree fica no disco sem fallback git. Um hook que excluiu o diretório antes de sair com código não-zero é contado como removido. Para como a falha é relatada, veja [entrada WorktreeRemove](#worktreeremove-input).3285* **O hook encerra com código diferente de zero**: a remoção falha se o diretório em `worktree_path` ainda existir depois, e o worktree permanece no disco sem fallback do git. Um hook que excluiu o diretório antes de encerrar com código diferente de zero é considerado como tendo removido o worktree. Para saber como a falha é relatada, consulte [Entrada do WorktreeRemove](#worktreeremove-input).
3276 3286
3277Claude Code nunca exclui um branch pertencente a uma worktree criada por hook, porque ele só conhece o caminho que seu hook WorktreeCreate retornou. Se seu hook WorktreeCreate cria um branch, exclua-o em seu hook WorktreeRemove.3287O Claude Code nunca exclui um branch pertencente a um worktree criado por hook, porque ele conhece apenas o caminho que seu hook WorktreeCreate retornou. Se seu hook WorktreeCreate criar um branch, exclua-o no seu hook WorktreeRemove.
3278 3288
3279Claude Code descarta [campos de saída JSON](#json-output) de um hook WorktreeRemove, como `systemMessage` e `continue`.3289O Claude Code descarta os [campos de saída JSON](#json-output) de um hook WorktreeRemove, como `systemMessage` e `continue`.
3280 3290
3281Para uma exclusão de sessão de fundo, Claude Code verifica o caminho de worktree armazenado antes de executar o hook e recusa um caminho que é um symlink ou passa através de um abaixo da raiz do repositório. O hook é executado para uma worktree que ainda contém arquivos apenas quando você confirma a exclusão em [visualização de agente](/docs/pt/agent-view#what-deleting-a-session-removes); para tal worktree, [`claude rm`](/docs/pt/agent-view#manage-sessions-from-the-shell) mantém a sessão e worktree em vez disso. Antes da v2.1.216, o hook era executado no caminho armazenado sem essas verificações.3291Para a exclusão de uma sessão em segundo plano, o Claude Code verifica o caminho do worktree armazenado antes de executar o hook e recusa um caminho que seja um link simbólico ou que passe por um abaixo da raiz do repositório. O hook é executado para um worktree que ainda contém arquivos somente quando você confirma a exclusão na [visualização de agentes](/docs/pt/agent-view#what-deleting-a-session-removes); para um worktree assim, [`claude rm`](/docs/pt/agent-view#manage-sessions-from-the-shell) mantém a sessão e o worktree. Antes da v2.1.216, o hook era executado no caminho armazenado sem essas verificações.
3282 3292
3283Claude Code passa o caminho retornado por WorktreeCreate como `worktree_path` na entrada do hook. Este exemplo lê esse caminho e remove o diretório:3293O Claude Code passa o caminho retornado pelo WorktreeCreate como `worktree_path` na entrada do hook. Este exemplo lê esse caminho e remove o diretório:
3284 3294
3285```json theme={null}3295```json theme={null}
3286{3296{
3300```3310```
3301 3311
3302<h4 id="worktreeremove-input">3312<h4 id="worktreeremove-input">
3303 Entrada WorktreeRemove3313 Entrada do WorktreeRemove
3304</h4>3314</h4>
3305 3315
3306Além dos [campos de entrada comuns](#common-input-fields), hooks WorktreeRemove recebem o campo `worktree_path`, que é o caminho absoluto para a worktree sendo removida.3316Além dos [campos de entrada comuns](#common-input-fields), os hooks WorktreeRemove recebem o campo `worktree_path`, que é o caminho absoluto para o worktree que está sendo removido.
3307 3317
3308```json theme={null}3318```json theme={null}
3309{3319{
3315}3325}
3316```3326```
3317 3327
3318O código de saída de um hook WorktreeRemove decide o resultado. Quando um hook sai com código não-zero e o diretório em `worktree_path` ainda existe depois, a remoção falha:3328O código de saída de um hook WorktreeRemove decide o resultado. Quando um hook encerra com código diferente de zero e o diretório em `worktree_path` ainda existe depois, a remoção falha:
3319 3329
3320* A worktree fica no disco, e o comando do hook e stderr vão para o [log de depuração](#debug-hooks).3330* O worktree permanece no disco, e o comando e o stderr do hook vão para o [log de depuração](#debug-hooks).
3321* Se você estava excluindo uma sessão de fundo, a sessão também fica. A mensagem de recusa em [visualização de agente](/docs/pt/agent-view#what-deleting-a-session-removes) relata como o hook terminou, como `exited 1`, cita o início de seu stderr e diz se excluir a sessão novamente remove o diretório de qualquer forma.3331* Se você estava excluindo uma sessão em segundo plano, a sessão também permanece. A mensagem de recusa na [visualização de agentes](/docs/pt/agent-view#what-deleting-a-session-removes) informa como o hook terminou, como `exited 1`, cita o início do seu stderr e diz se excluir a sessão novamente remove o diretório mesmo assim.
3322 3332
3323<h3 id="precompact">3333<h3 id="precompact">
3324 PreCompact3334 PreCompact
3325</h3>3335</h3>
3326 3336
3327Executa antes de Claude Code estar prestes a executar uma operação de compactação.3337É executado antes de o Claude Code executar uma operação de compactação.
3328 3338
3329O valor do matcher indica se a compactação foi disparada manualmente ou automaticamente:3339O valor do matcher indica se a compactação foi acionada manual ou automaticamente:
3330 3340
3331| Matcher | Quando é disparado |3341| Matcher | Quando é disparado |
3332| :- | :- |3342| :- | :- |
3333| `manual` | `/compact` |3343| `manual` | `/compact` |
3334| `auto` | Compactação automática quando a conversa atinge a [janela de compactação automática](/docs/pt/model-config#set-the-auto-compact-window) |3344| `auto` | Compactação automática quando a conversa atinge a [janela de compactação automática](/docs/pt/model-config#set-the-auto-compact-window) |
3335 3345
3336Saia com código 2 para bloquear a compactação. Para um `/compact` manual, a mensagem stderr é mostrada ao usuário. Você também pode bloquear retornando JSON com `"decision": "block"`.3346Encerre com o código 2 para bloquear a compactação. Para um `/compact` manual, a mensagem do stderr é mostrada ao usuário. Você também pode bloquear retornando JSON com `"decision": "block"`.
3337 3347
3338Bloquear compactação automática tem efeitos diferentes dependendo de quando dispara. Se a compactação foi disparada proativamente antes do limite de contexto, Claude Code a pula e a conversa continua não compactada. Se a compactação foi disparada para recuperar de um erro de limite de contexto já retornado pela API, o erro subjacente aparece e a solicitação atual falha.3348Bloquear a compactação automática tem efeitos diferentes dependendo de quando ela é disparada. Se a compactação foi acionada proativamente antes do limite de contexto, o Claude Code a ignora e a conversa continua sem compactação. Se a compactação foi acionada para se recuperar de um erro de limite de contexto já retornado pela API, o erro subjacente aparece e a requisição atual falha.
3339 3349
3340Claude Code descarta campos `systemMessage` e `continue` de um hook PreCompact.3350O Claude Code descarta os campos `systemMessage` e `continue` de um hook PreCompact.
3341 3351
3342<h4 id="precompact-input">3352<h4 id="precompact-input">
3343 Entrada PreCompact3353 Entrada do PreCompact
3344</h4>3354</h4>
3345 3355
3346Além dos [campos de entrada comuns](#common-input-fields), hooks PreCompact recebem `trigger` e `custom_instructions`. Para `manual`, `custom_instructions` contém o que o usuário passa para `/compact` e é `null` quando ele não passa nada. Para `auto`, `custom_instructions` é `null`.3356Além dos [campos de entrada comuns](#common-input-fields), os hooks PreCompact recebem `trigger` e `custom_instructions`. Para `manual`, `custom_instructions` contém o que o usuário passa para `/compact` e é `null` quando ele não passa nada. Para `auto`, `custom_instructions` é `null`.
3347 3357
3348```json theme={null}3358```json theme={null}
3349{3359{
3360 PostCompact3370 PostCompact
3361</h3>3371</h3>
3362 3372
3363Executa após Claude Code completar uma operação de compactação. Use este evento para reagir ao novo estado compactado, por exemplo para registrar o resumo gerado ou atualizar estado externo. Claude Code descarta campos `systemMessage` e `continue` de um hook PostCompact.3373É executado depois que o Claude Code conclui uma operação de compactação. Use este evento para reagir ao novo estado compactado, por exemplo, para registrar em log o resumo gerado ou atualizar um estado externo. O Claude Code descarta os campos `systemMessage` e `continue` de um hook PostCompact.
3364 3374
3365Os mesmos valores de matcher se aplicam como para `PreCompact`:3375Os mesmos valores de matcher do `PreCompact` se aplicam:
3366 3376
3367| Matcher | Quando é disparado |3377| Matcher | Quando é disparado |
3368| :- | :- |3378| :- | :- |
3369| `manual` | Após `/compact` |3379| `manual` | Após `/compact` |
3370| `auto` | Após compactação automática quando a conversa atinge a [janela de compactação automática](/docs/pt/model-config#set-the-auto-compact-window) |3380| `auto` | Após a compactação automática quando a conversa atinge a [janela de compactação automática](/docs/pt/model-config#set-the-auto-compact-window) |
3371 3381
3372<h4 id="postcompact-input">3382<h4 id="postcompact-input">
3373 Entrada PostCompact3383 Entrada do PostCompact
3374</h4>3384</h4>
3375 3385
3376Além dos [campos de entrada comuns](#common-input-fields), hooks PostCompact recebem `trigger` e `compact_summary`. O campo `compact_summary` contém o resumo de conversa gerado pela operação de compactação.3386Além dos [campos de entrada comuns](#common-input-fields), os hooks PostCompact recebem `trigger` e `compact_summary`. O campo `compact_summary` contém o resumo da conversa gerado pela operação de compactação.
3377 3387
3378```json theme={null}3388```json theme={null}
3379{3389{
3386}3396}
3387```3397```
3388 3398
3389Hooks PostCompact não têm controle de decisão. Eles não podem afetar o resultado da compactação mas podem executar tarefas de acompanhamento.3399Os hooks PostCompact não têm controle de decisão. Eles não podem afetar o resultado da compactação, mas podem executar tarefas de acompanhamento.
3390 3400
3391<h3 id="premodelswitch">3401<h3 id="premodelswitch">
3392 PreModelSwitch3402 PreModelSwitch
3393</h3>3403</h3>
3394 3404
3395Executa antes de Claude Code aplicar uma mudança de modelo que você ou um cliente solicitou. Use-o para bloquear uma mudança, exigir confirmação ou mostrar qual será o custo da mudança antes de acontecer.3405É executado antes de o Claude Code aplicar uma troca de modelo que você ou um cliente solicitou. Use-o para bloquear uma troca, exigir confirmação ou mostrar quanto a troca vai custar antes que ela aconteça.
3396 3406
3397PreModelSwitch requer Claude Code v2.1.251 ou posterior. Claude Code o executa para essas solicitações:3407O PreModelSwitch requer o Claude Code v2.1.251 ou posterior. O Claude Code o executa para estas solicitações:
3398 3408
3399* `/model <name>` e o seletor `/model`3409* `/model <name>` e o seletor do `/model`
3400* O seletor de modelo `Option+P` ou `Alt+P`3410* O seletor de modelo `Option+P` ou `Alt+P`
3401* A configuração Model em `/config`3411* A configuração Model em `/config`
3402* Ativar [modo rápido](/docs/pt/fast-mode) quando isso muda o modelo da sessão3412* Ativar o [modo rápido](/docs/pt/fast-mode) quando isso altera o modelo da sessão
3403* Uma solicitação `set_model`, ou uma mudança de modelo em uma solicitação `apply_flag_settings`, de um host [Agent SDK](/docs/pt/agent-sdk/typescript#query-object) ou [Remote Control](/docs/pt/remote-control)3413* Uma requisição `set_model`, ou uma mudança de modelo em uma requisição `apply_flag_settings`, de um host do [Agent SDK](/docs/pt/agent-sdk/typescript#query-object) ou do [Remote Control](/docs/pt/remote-control)
3404 3414
3405Claude Code não executa hooks PreModelSwitch para mudanças que faz por conta própria, como um [fallback de modelo automático](/docs/pt/model-config#automatic-model-fallback) ou restaurar o modelo quando você retoma uma sessão. Essas mudanças chegam a [PostModelSwitch](#postmodelswitch) apenas.3415O Claude Code não executa hooks PreModelSwitch para trocas que ele faz por conta própria, como um [fallback automático de modelo](/docs/pt/model-config#automatic-model-fallback) ou a restauração do modelo quando você retoma uma sessão. Essas mudanças chegam apenas ao [PostModelSwitch](#postmodelswitch).
3406 3416
3407Claude Code compara o matcher contra o nome canônico do modelo para o qual a sessão está mudando, ignorando qualquer sufixo `[1m]`. Um alias como `opus`, um ID de modelo datado e um ID específico do provedor como um ID de modelo Amazon Bedrock todos correspondem ao um nome canônico que resolvem, então `claude-opus-5` cobre cada ortografia de Opus 5.3417O Claude Code compara o matcher com o nome canônico do modelo para o qual a sessão está trocando, ignorando qualquer sufixo `[1m]`. Um alias como `opus`, um ID de modelo com data e um ID específico de provedor, como um ID de modelo do Amazon Bedrock, correspondem todos ao único nome canônico para o qual são resolvidos, então `claude-opus-5` abrange todas as grafias do Opus 5.
3408 3418
3409Quando Claude Code não pode determinar um nome canônico para o alvo, por exemplo um ID de modelo personalizado que apenas seu [gateway LLM](/docs/pt/llm-gateway) conhece, ele executa cada hook PreModelSwitch independentemente do matcher. Um hook que bloqueia deve portanto verificar `to_model` de sua entrada em vez de confiar apenas no matcher.3419Quando o Claude Code não consegue determinar um nome canônico para o destino, por exemplo, um ID de modelo personalizado que somente o seu [gateway de LLM](/docs/pt/llm-gateway) conhece, ele executa todos os hooks PreModelSwitch independentemente do matcher. Portanto, um hook que bloqueia deve verificar `to_model` em sua entrada em vez de depender apenas do matcher.
3410 3420
3411Escreva o matcher como um nome exato, uma lista separada por `|` como `claude-opus-4-6|claude-opus-5`, ou uma expressão regular como `.*opus.*`. Este exemplo usa um matcher de nome exato e também verifica `to_model` da entrada do hook, então recusa uma mudança para Opus 4.6 ao sair com código 2 e deixa qualquer outro alvo passar:3421Escreva o matcher como um nome exato, uma lista separada por `|` como `claude-opus-4-6|claude-opus-5`, ou uma expressão regular como `.*opus.*`. Este exemplo usa um matcher de nome exato e também verifica `to_model` na entrada do hook, de modo que recusa uma troca para o Opus 4.6 encerrando com o código 2 e permite qualquer outro destino:
3412 3422
3413<Tabs>3423<Tabs>
3414 <Tab title="macOS/Linux">3424 <Tab title="macOS/Linux">
3434 </Tab>3444 </Tab>
3435 3445
3436 <Tab title="Windows (PowerShell)">3446 <Tab title="Windows (PowerShell)">
3437 Registre um hook de comando que executa um script através do PowerShell:3447 Registre um hook de comando que executa um script pelo PowerShell:
3438 3448
3439 ```json theme={null}3449 ```json theme={null}
3440 {3450 {
3461 }3471 }
3462 ```3472 ```
3463 3473
3464 Salve este script em `.claude/hooks/block-opus-46.ps1` em seu projeto:3474 Salve este script em `.claude/hooks/block-opus-46.ps1` no seu projeto:
3465 3475
3466 ```powershell theme={null}3476 ```powershell theme={null}
3467 $hookInput = [Console]::In.ReadToEnd() | ConvertFrom-Json3477 $hookInput = [Console]::In.ReadToEnd() | ConvertFrom-Json
3474 </Tab>3484 </Tab>
3475</Tabs>3485</Tabs>
3476 3486
3477Para confirmar que o hook funciona, execute `/model claude-opus-4-6` de uma sessão executando um modelo diferente. Claude Code mantém o modelo atual e relata que um hook PreModelSwitch bloqueou a mudança, com sua mensagem como o motivo.3487Para confirmar que o hook funciona, execute `/model claude-opus-4-6` em uma sessão que esteja usando um modelo diferente. O Claude Code mantém o modelo atual e informa que um hook PreModelSwitch bloqueou a troca, com a sua mensagem como motivo.
3478 3488
3479<h4 id="premodelswitch-input">3489<h4 id="premodelswitch-input">
3480 Entrada PreModelSwitch3490 Entrada do PreModelSwitch
3481</h4>3491</h4>
3482 3492
3483Além dos [campos de entrada comuns](#common-input-fields), hooks PreModelSwitch recebem os campos nesta tabela. Os últimos cinco descrevem qual é o custo de reenviar a conversa para o novo modelo, então um hook pode mostrar essa figura antes da mudança acontecer.3493Além dos [campos de entrada comuns](#common-input-fields), os hooks PreModelSwitch recebem os campos desta tabela. Os cinco últimos descrevem quanto custa reenviar a conversa para o novo modelo, para que um hook possa mostrar esse valor antes que a troca aconteça.
3484 3494
3485| Campo | Tipo | Descrição |3495| Campo | Tipo | Descrição |
3486| :- | :- | :- |3496| :- | :- | :- |
3487| `from_model` | string | ID de modelo da mudança de |3497| `from_model` | string | ID do modelo de origem da troca |
3488| `to_model` | string | ID de modelo da mudança para. O matcher compara contra o nome canônico deste modelo |3498| `to_model` | string | ID do modelo de destino da troca. O matcher é comparado com o nome canônico desse modelo |
3489| `requested_model` | string ou `null` | O modelo que a solicitação nomeou: um alias como `opus`, um ID de modelo completo, ou `null` quando a solicitação foi para o modelo padrão |3499| `requested_model` | string ou `null` | O modelo indicado na solicitação: um alias como `opus`, um ID de modelo completo, ou `null` quando a solicitação foi para o modelo padrão |
3490| `source` | string | De onde a solicitação veio: `"command"` para `/model <name>`, a configuração Model em `/config` ou ativar modo rápido; `"picker"` para um seletor de modelo; `"sdk"` para uma solicitação `set_model`, ou uma mudança de modelo em uma solicitação `apply_flag_settings`, de um host Agent SDK ou Remote Control |3500| `source` | string | De onde veio a solicitação: `"command"` para `/model <name>`, a configuração Model em `/config` ou a ativação do modo rápido; `"picker"` para um seletor de modelo; `"sdk"` para uma requisição `set_model`, ou uma mudança de modelo em uma requisição `apply_flag_settings`, de um host do Agent SDK ou do Remote Control |
3491| `context_tokens` | number | Tokens que a próxima solicitação reenvia como seu prompt: os tokens de entrada, leitura de cache, criação de cache e saída da última resposta na conversa principal, combinados. `0` antes da primeira resposta |3501| `context_tokens` | number | Tokens que a próxima requisição reenvia como seu prompt: os tokens de entrada, de leitura de cache, de criação de cache e de saída da última resposta na conversa principal, somados. `0` antes da primeira resposta |
3492| `prompt_cache_warm` | boolean | Se o cache de prompt do modelo atual provavelmente ainda está quente, significando que a mudança o perde |3502| `prompt_cache_warm` | boolean | Se o cache de prompt do modelo atual provavelmente ainda está aquecido, o que significa que a troca o perde |
3493| `cache_ttl` | string | [Tempo de vida do cache de prompt](/docs/pt/prompt-caching#cache-lifetime) que Claude Code solicita para esta sessão: `"5m"` ou `"1h"` |3503| `cache_ttl` | string | [Tempo de vida do cache de prompt](/docs/pt/prompt-caching#cache-lifetime) que o Claude Code solicita para esta sessão: `"5m"` ou `"1h"` |
3494| `estimated_cache_write_usd` | number | Custo estimado em dólares americanos de escrever `context_tokens` no cache de prompt em `to_model` na taxa `cache_ttl`, excluindo a próxima resposta. O servidor pode não precisar re-cachear todo o contexto, então trate-o como uma estimativa |3504| `estimated_cache_write_usd` | number | Custo estimado em dólares americanos de gravar `context_tokens` no cache de prompt em `to_model` à taxa de `cache_ttl`, excluindo a próxima resposta. O servidor pode não precisar refazer o cache de todo o contexto, então trate-o como uma estimativa |
3495| `pricing` | string | Como Claude Code precificou `estimated_cache_write_usd`: `"configured"` em suas próprias taxas da organização quando as configurou, `"catalog"` ao preço de lista, ou `"default"` quando `to_model` não tem preço conhecido e Claude Code assumiu uma taxa padrão |3505| `pricing` | string | Como o Claude Code precificou `estimated_cache_write_usd`: `"configured"` pelas taxas próprias da sua organização quando ela as configurou, `"catalog"` pelo preço de tabela, ou `"default"` quando `to_model` não tem preço conhecido e o Claude Code assumiu uma taxa padrão |
3496 3506
3497Este exemplo mostra a entrada para `/model opus` em uma sessão executando Sonnet 5:3507Este exemplo mostra a entrada para `/model opus` em uma sessão usando o Sonnet 5:
3498 3508
3499```json theme={null}3509```json theme={null}
3500{3510{
3515```3525```
3516 3526
3517<h4 id="premodelswitch-decision-control">3527<h4 id="premodelswitch-decision-control">
3518 Controle de decisão PreModelSwitch3528 Controle de decisão do PreModelSwitch
3519</h4>3529</h4>
3520 3530
3521Hooks `PreModelSwitch` podem cancelar a mudança, pedir ao usuário para confirmar ou deixar prosseguir. Código de saída 2 ou `decision: "block"` de nível superior cancela a mudança.3531Os hooks `PreModelSwitch` podem cancelar a troca, pedir ao usuário que a confirme ou deixá-la prosseguir. O código de saída 2 ou um `decision: "block"` no nível superior cancela a troca.
3522 3532
3523Para controle mais fino, retorne `permissionDecision` e `permissionDecisionReason` em um objeto `hookSpecificOutput`, como em [PreToolUse](#pretooluse-decision-control). `PreModelSwitch` aceita `"allow"`, `"deny"` e `"ask"`. Não aceita `"defer"`, `updatedInput` ou `additionalContext`. A tabela abaixo descreve ambos os campos:3533Para um controle mais refinado, retorne `permissionDecision` e `permissionDecisionReason` em um objeto `hookSpecificOutput`, como no [PreToolUse](#pretooluse-decision-control). O `PreModelSwitch` aceita `"allow"`, `"deny"` e `"ask"`. Ele não aceita `"defer"`, `updatedInput` nem `additionalContext`. A tabela abaixo descreve ambos os campos:
3524 3534
3525| Campo | Descrição |3535| Campo | Descrição |
3526| :- | :- |3536| :- | :- |
3527| `permissionDecision` | `"allow"` prossegue e pula a [confirmação que Claude Code mostra enquanto o cache de prompt está quente](/docs/pt/prompt-caching#switching-models). `"deny"` cancela a mudança. `"ask"` solicita ao usuário para confirmar |3537| `permissionDecision` | `"allow"` prossegue e pula a [confirmação que o Claude Code mostra enquanto o cache de prompt está aquecido](/docs/pt/prompt-caching#switching-models). `"deny"` cancela a troca. `"ask"` pede ao usuário que a confirme |
3528| `permissionDecisionReason` | Para `"deny"`, mostrado ao usuário como o motivo pelo qual a mudança foi bloqueada, ou retornado como o erro para uma solicitação `set_model`. Para `"ask"`, mostrado no prompt de confirmação. Ignorado para `"allow"` |3538| `permissionDecisionReason` | Para `"deny"`, mostrado ao usuário como o motivo pelo qual a troca foi bloqueada, ou retornado como erro para uma requisição `set_model`. Para `"ask"`, mostrado no prompt de confirmação. Ignorado para `"allow"` |
3529 3539
3530Apenas `/model` em uma sessão interativa pode mostrar o prompt `"ask"`. Em todas as outras superfícies, incluindo modo não interativo com a flag `-p`, `/config` e solicitações `set_model`, Claude Code trata `"ask"` como uma recusa.3540Somente o `/model` em uma sessão interativa pode mostrar o prompt de `"ask"`. Em todas as outras superfícies, incluindo o modo não interativo com a flag `-p`, `/config` e requisições `set_model`, o Claude Code trata `"ask"` como uma recusa.
3531 3541
3532Este exemplo pede ao usuário para confirmar e cita a contagem de tokens de `context_tokens`:3542Este exemplo pede ao usuário que confirme e cita a contagem de tokens de `context_tokens`:
3533 3543
3534```json theme={null}3544```json theme={null}
3535{3545{
3543 3553
3544Quando vários hooks PreModelSwitch retornam decisões diferentes, a precedência é `deny` > `ask` > `allow`.3554Quando vários hooks PreModelSwitch retornam decisões diferentes, a precedência é `deny` > `ask` > `allow`.
3545 3555
3546Claude Code mostra ao usuário qualquer `systemMessage` que seu hook retorna independentemente da decisão, então um hook de relatório de custo pode retornar `{"systemMessage": "..."}` e sair com 0.3556O Claude Code mostra ao usuário qualquer `systemMessage` que seu hook retornar, independentemente da decisão, então um hook de relatório de custo pode retornar `{"systemMessage": "..."}` e encerrar com 0.
3547 3557
3548Um hook PreModelSwitch que não responde antes de seu tempo limite bloqueia a mudança. Em [PreToolUse](#timeouts), por contraste, um hook de comando que atingiu tempo limite deixa a chamada de ferramenta continuar. O tempo limite padrão para este evento é 30 segundos. `PreModelSwitch` executa apenas hooks `command`, `http` e `mcp_tool`, então os padrões `prompt` e `agent` não se aplicam.3558Um hook PreModelSwitch que não responde antes do seu timeout bloqueia a troca. No [PreToolUse](#timeouts), por outro lado, um hook de comando que atingiu o timeout deixa a chamada de ferramenta continuar. O timeout padrão para este evento é de 30 segundos. O `PreModelSwitch` executa apenas hooks `command`, `http` e `mcp_tool`, então os padrões de `prompt` e `agent` não se aplicam.
3549 3559
3550Um hook que sai com um código diferente de 0 ou 2 e não imprime nenhuma decisão JSON não bloqueia: Claude Code mostra seu stderr e aplica a mudança, conforme descrito em [Outros códigos de saída](#other-exit-codes).3560Um hook que encerra com um código diferente de 0 ou 2 e não imprime nenhuma decisão JSON não bloqueia: o Claude Code mostra seu stderr e aplica a troca, conforme descrito em [Outros códigos de saída](#other-exit-codes).
3551 3561
3552<h3 id="postmodelswitch">3562<h3 id="postmodelswitch">
3553 PostModelSwitch3563 PostModelSwitch
3554</h3>3564</h3>
3555 3565
3556Executa após o modelo da sessão mudar. Use-o para dar orientação específica do modelo ao Claude sem editar cada CLAUDE.md, por exemplo uma instrução em toda a organização que se aplica em certos modelos.3566É executado depois que o modelo da sessão muda. Use-o para dar ao Claude orientações específicas do modelo sem editar cada CLAUDE.md, por exemplo, uma instrução para toda a organização que se aplica a determinados modelos.
3557 3567
3558PostModelSwitch requer Claude Code v2.1.251 ou posterior. Não pode bloquear, porque o modelo já mudou. Claude Code executa hooks PostModelSwitch após qualquer uma dessas mudanças:3568O PostModelSwitch requer o Claude Code v2.1.251 ou posterior. Ele não pode bloquear, porque o modelo já mudou. O Claude Code executa hooks PostModelSwitch após qualquer uma destas mudanças:
3559 3569
3560* Uma mudança que você ou um cliente solicitou3570* Uma troca que você ou um cliente solicitou
3561* Um [fallback de modelo automático](/docs/pt/model-config#automatic-model-fallback), que muda o modelo da sessão3571* Um [fallback automático de modelo](/docs/pt/model-config#automatic-model-fallback), que altera o modelo da sessão
3562* Uma configuração como [`opusplan`](/docs/pt/model-config#opusplan-model-setting) entrando ou saindo do modo de plano3572* Uma configuração como [`opusplan`](/docs/pt/model-config#opusplan-model-setting) entrando ou saindo do modo de planejamento
3563* Claude Code restaurando o modelo quando você retoma uma sessão3573* O Claude Code restaurando o modelo quando você retoma uma sessão
3564 3574
3565Claude Code não executa hooks PostModelSwitch quando um modelo de uma [cadeia de modelo fallback](/docs/pt/model-config#fallback-model-chains) serve um turno, porque essa substituição dura um turno e deixa o modelo da sessão inalterado.3575O Claude Code não executa hooks PostModelSwitch quando um modelo de uma [cadeia de modelos de fallback](/docs/pt/model-config#fallback-model-chains) atende a um turno, porque essa substituição dura um turno e mantém o modelo da sessão inalterado.
3566 3576
3567O matcher segue as mesmas regras que [PreModelSwitch](#premodelswitch): Claude Code compara contra o nome canônico do modelo para o qual a sessão mudou.3577O matcher segue as mesmas regras do [PreModelSwitch](#premodelswitch): o Claude Code o compara com o nome canônico do modelo para o qual a sessão trocou.
3568 3578
3569Este exemplo adiciona orientação sempre que o modelo da sessão muda para qualquer modelo Opus:3579Este exemplo adiciona orientações sempre que o modelo da sessão muda para qualquer modelo Opus:
3570 3580
3571```json theme={null}3581```json theme={null}
3572{3582{
3586}3596}
3587```3597```
3588 3598
3589Para confirmar que o hook funciona, mude para um modelo Opus de uma sessão executando um modelo diferente, por exemplo execute `/model opus` de uma sessão Sonnet, depois pergunte ao Claude qual orientação ele tem sobre o modelo atual.3599Para confirmar que o hook funciona, troque para um modelo Opus a partir de uma sessão que esteja usando um modelo diferente, por exemplo, execute `/model opus` em uma sessão do Sonnet, e depois pergunte ao Claude quais orientações ele tem sobre o modelo atual.
3590 3600
3591<h4 id="postmodelswitch-input">3601<h4 id="postmodelswitch-input">
3592 Entrada PostModelSwitch3602 Entrada do PostModelSwitch
3593</h4>3603</h4>
3594 3604
3595Hooks PostModelSwitch recebem os mesmos campos que [PreModelSwitch](#premodelswitch-input), com `hook_event_name` definido como `"PostModelSwitch"` e dois valores `source` mais: `"auto"` para um fallback automático ou outra mudança que Claude Code fez por conta própria, e `"resume"` para o modelo restaurado quando você retoma uma sessão.3605Os hooks PostModelSwitch recebem os mesmos campos do [PreModelSwitch](#premodelswitch-input), com `hook_event_name` definido como `"PostModelSwitch"` e mais dois valores de `source`: `"auto"` para um fallback automático ou outra mudança que o Claude Code fez por conta própria, e `"resume"` para o modelo restaurado quando você retoma uma sessão.
3596 3606
3597`requested_model` é `null` quando `source` é `"auto"`. Quando `source` é `"resume"`, é a configuração de modelo salva que Claude Code restaurou.3607`requested_model` é `null` quando `source` é `"auto"`. Quando `source` é `"resume"`, é a configuração de modelo salva que o Claude Code restaurou.
3598 3608
3599<h4 id="postmodelswitch-decision-control">3609<h4 id="postmodelswitch-decision-control">
3600 Controle de decisão PostModelSwitch3610 Controle de decisão do PostModelSwitch
3601</h4>3611</h4>
3602 3612
3603Claude Code pega seu [stdout de texto simples](#exit-code-0) de hook ao sair com 0, ou `additionalContext` de saída JSON, e o entrega ao Claude com a próxima solicitação após a mudança. Além dos [campos de saída JSON](#json-output) disponíveis para todos os hooks, você pode retornar:3613O Claude Code pega o [stdout em texto simples](#exit-code-0) do seu hook ao encerrar com 0, ou o `additionalContext` da saída JSON, e o entrega ao Claude com a próxima requisição após a troca. Além dos [campos de saída JSON](#json-output) disponíveis para todos os hooks, você pode retornar:
3604 3614
3605| Campo | Descrição |3615| Campo | Descrição |
3606| :- | :- |3616| :- | :- |
3607| `additionalContext` | String adicionada ao contexto do Claude com a próxima solicitação. Veja [Adicionar contexto para Claude](#add-context-for-claude) |3617| `additionalContext` | String adicionada ao contexto do Claude com a próxima requisição. Consulte [Adicionar contexto para o Claude](#add-context-for-claude) |
3608 3618
3609Se o hook não terminar dentro de cinco segundos após você enviar a próxima solicitação, Claude Code envia essa solicitação sem a saída e a anexa à solicitação seguinte em vez disso. Se o modelo mudar várias vezes antes da próxima solicitação, Claude Code entrega apenas a saída para a mudança de alvo do último modelo.3619Se o hook não tiver terminado dentro de cinco segundos depois que você enviar o próximo prompt, o Claude Code envia essa requisição sem a saída e a anexa à requisição seguinte. Se o modelo mudar várias vezes antes da próxima requisição, o Claude Code entrega apenas a saída referente ao modelo de destino da última troca.
3610 3620
3611<h3 id="sessionend">3621<h3 id="sessionend">
3612 SessionEnd3622 SessionEnd
3613</h3>3623</h3>
3614 3624
3615Executa quando uma sessão Claude Code termina. Útil para tarefas de limpeza, registrar estatísticas de sessão ou salvar estado de sessão. Suporta matchers para filtrar por motivo de saída.3625É executado quando uma sessão do Claude Code termina. Útil para tarefas de limpeza, registro em log de estatísticas
3626da sessão ou salvamento do estado da sessão. Suporta matchers para filtrar pelo motivo de saída.
3616 3627
3617O campo `reason` na entrada do hook indica por que a sessão terminou:3628O campo `reason` na entrada do hook indica por que a sessão terminou:
3618 3629
3619| Motivo | Descrição |3630| Motivo | Descrição |
3620| :- | :- |3631| :- | :- |
3621| `clear` | Sessão limpa com comando `/clear` |3632| `clear` | Sessão limpa com o comando `/clear` |
3622| `resume` | Sessão mudada via `/resume` interativo |3633| `resume` | Sessão trocada via `/resume` interativo |
3623| `logout` | Usuário fez logout |3634| `logout` | O usuário fez logout |
3624| `prompt_input_exit` | Usuário saiu enquanto entrada de prompt estava visível |3635| `prompt_input_exit` | O usuário saiu enquanto a entrada do prompt estava visível |
3625| `other` | Outros motivos de saída |3636| `other` | Outros motivos de saída |
3626| `bypass_permissions_disabled` | Removido na v2.1.234; Claude Code não o envia. Remova-o de seus matchers `SessionEnd` |3637| `bypass_permissions_disabled` | Removido na v2.1.234; o Claude Code não o envia. Remova-o dos seus matchers de `SessionEnd` |
3627 3638
3628<h4 id="sessionend-input">3639<h4 id="sessionend-input">
3629 Entrada SessionEnd3640 Entrada do SessionEnd
3630</h4>3641</h4>
3631 3642
3632Além dos [campos de entrada comuns](#common-input-fields), hooks SessionEnd recebem um campo `reason` indicando por que a sessão terminou. Veja a [tabela de motivos](#sessionend) acima para todos os valores.3643Além dos [campos de entrada comuns](#common-input-fields), os hooks SessionEnd recebem um campo `reason` indicando por que a sessão terminou. Consulte a [tabela de motivos](#sessionend) acima para ver todos os valores.
3633 3644
3634```json theme={null}3645```json theme={null}
3635{3646{
3641}3652}
3642```3653```
3643 3654
3644Hooks SessionEnd não têm controle de decisão. Eles não podem bloquear o término da sessão mas podem executar tarefas de limpeza. Claude Code descarta seus [campos de saída JSON](#json-output), como `systemMessage`.3655Os hooks SessionEnd não têm controle de decisão. Eles não podem bloquear o encerramento da sessão, mas podem executar tarefas de limpeza. O Claude Code descarta seus [campos de saída JSON](#json-output), como `systemMessage`.
3645 3656
3646Hooks SessionEnd têm um tempo limite padrão de 1,5 segundos. Aplica-se quando você sai, executa `/clear` ou muda de sessões com `/resume` interativo. Você pode dar a um hook mais tempo de duas maneiras:3657Os hooks SessionEnd têm um timeout padrão de 1,5 segundo. Ele se aplica quando você sai, executa `/clear` ou troca de sessão com o `/resume` interativo. Você pode dar mais tempo a um hook de duas maneiras:
3647 3658
3648* **`timeout` por hook**: defina `timeout` na configuração daquele hook. O orçamento geral sobe automaticamente para corresponder ao `timeout` por hook mais alto em seus arquivos de configurações, até 60 segundos. Se você aumentar o orçamento dessa forma, um hook sem seu próprio `timeout` ainda mantém o padrão. Tempos limite definidos em hooks fornecidos por plugin não aumentam o orçamento.3659* **`timeout` por hook**: defina `timeout` na configuração desse hook. O orçamento geral aumenta automaticamente para corresponder ao maior `timeout` por hook nos seus arquivos de configuração, até 60 segundos. Se você aumentar o orçamento dessa forma, um hook sem seu próprio `timeout` ainda mantém o padrão. Timeouts definidos em hooks fornecidos por plugins não aumentam o orçamento.
3649* **`CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS`**: defina esta variável de ambiente em milissegundos para sobrescrever o orçamento explicitamente. O valor que você define também se torna o tempo limite para cada hook sem seu próprio `timeout`.3660* **`CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS`**: defina esta variável de ambiente em milissegundos para sobrescrever o orçamento explicitamente. O valor que você define também se torna o timeout de cada hook sem seu próprio `timeout`.
3650 3661
3651Este exemplo define o orçamento para 5 segundos:3662Este exemplo define o orçamento como 5 segundos:
3652 3663
3653```bash theme={null}3664```bash theme={null}
3654CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS=5000 claude3665CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS=5000 claude
3655```3666```
3656 3667
3657Antes da v2.1.268, `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` aumentava apenas o orçamento geral, e um hook sem seu próprio `timeout` ainda era cancelado após 1,5 segundos.3668Antes da v2.1.268, `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` aumentava apenas o orçamento geral, e um hook sem seu próprio `timeout` ainda era cancelado após 1,5 segundo.
3658 3669
3659<h3 id="elicitation">3670<h3 id="elicitation">
3660 Elicitation3671 Elicitation
3661</h3>3672</h3>
3662 3673
3663Executa quando um servidor MCP solicita entrada do usuário no meio da tarefa. Por padrão, Claude Code mostra um diálogo interativo para o usuário responder. Hooks podem interceptar esta solicitação e responder programaticamente, pulando o diálogo inteiramente.3674É executado quando um servidor MCP solicita entrada do usuário no meio de uma tarefa. Por padrão, o Claude Code mostra uma caixa de diálogo interativa para o usuário responder. Os hooks podem interceptar essa solicitação e responder programaticamente, pulando totalmente a caixa de diálogo.
3664 3675
3665O campo matcher corresponde ao nome do servidor MCP.3676O campo matcher é comparado com o nome do servidor MCP.
3666 3677
3667<h4 id="elicitation-input">3678<h4 id="elicitation-input">
3668 Entrada Elicitation3679 Entrada do Elicitation
3669</h4>3680</h4>
3670 3681
3671Além dos [campos de entrada comuns](#common-input-fields), hooks Elicitation recebem `mcp_server_name`, `message` e campos opcionais `mode`, `url`, `elicitation_id` e `requested_schema`.3682Além dos [campos de entrada comuns](#common-input-fields), os hooks Elicitation recebem `mcp_server_name`, `message` e os campos opcionais `mode`, `url`, `elicitation_id` e `requested_schema`.
3672 3683
3673Para elicitação de modo de formulário, o caso mais comum:3684Para elicitação no modo de formulário, o caso mais comum:
3674 3685
3675```json theme={null}3686```json theme={null}
3676{3687{
3690}3701}
3691```3702```
3692 3703
3693Para elicitação de modo URL, usada para autenticação baseada em navegador:3704Para elicitação no modo URL, usada para autenticação baseada em navegador:
3694 3705
3695```json theme={null}3706```json theme={null}
3696{3707{
3706```3717```
3707 3718
3708<h4 id="elicitation-output">3719<h4 id="elicitation-output">
3709 Saída Elicitation3720 Saída do Elicitation
3710</h4>3721</h4>
3711 3722
3712Para responder programaticamente sem mostrar o diálogo, retorne um objeto JSON com `hookSpecificOutput`:3723Para responder programaticamente sem mostrar a caixa de diálogo, retorne um objeto JSON com `hookSpecificOutput`:
3713 3724
3714```json theme={null}3725```json theme={null}
3715{3726{
3726| Campo | Valores | Descrição |3737| Campo | Valores | Descrição |
3727| :- | :- | :- |3738| :- | :- | :- |
3728| `action` | `accept`, `decline`, `cancel` | Se deve aceitar, recusar ou cancelar a solicitação |3739| `action` | `accept`, `decline`, `cancel` | Se deve aceitar, recusar ou cancelar a solicitação |
3729| `content` | object | Valores de campo de formulário a enviar. Usado apenas quando `action` é `accept` |3740| `content` | object | Valores dos campos do formulário a serem enviados. Usado somente quando `action` é `accept` |
3730 3741
3731Código de saída 2 nega a elicitação. Claude Code não mostra sua mensagem stderr em lugar algum.3742O código de saída 2 nega a elicitação. O Claude Code não mostra sua mensagem de stderr em lugar nenhum.
3732 3743
3733Claude Code age em `hookSpecificOutput` de uma saída JSON de hook Elicitation e descarta `systemMessage` e `continue`.3744O Claude Code age com base no `hookSpecificOutput` da saída JSON de um hook Elicitation e descarta `systemMessage` e `continue`.
3734 3745
3735<h3 id="elicitationresult">3746<h3 id="elicitationresult">
3736 ElicitationResult3747 ElicitationResult
3737</h3>3748</h3>
3738 3749
3739Executa após um usuário responder a uma elicitação MCP. Hooks podem observar, modificar ou bloquear a resposta antes de ser enviada de volta para o servidor MCP.3750É executado depois que um usuário responde a uma elicitação MCP. Os hooks podem observar, modificar ou bloquear a resposta antes que ela seja enviada de volta ao servidor MCP.
3740 3751
3741O campo matcher corresponde ao nome do servidor MCP.3752O campo matcher é comparado com o nome do servidor MCP.
3742 3753
3743<h4 id="elicitationresult-input">3754<h4 id="elicitationresult-input">
3744 Entrada ElicitationResult3755 Entrada do ElicitationResult
3745</h4>3756</h4>
3746 3757
3747Além dos [campos de entrada comuns](#common-input-fields), hooks ElicitationResult recebem `mcp_server_name`, `action` e campos opcionais `mode`, `elicitation_id` e `content`.3758Além dos [campos de entrada comuns](#common-input-fields), os hooks ElicitationResult recebem `mcp_server_name`, `action` e os campos opcionais `mode`, `elicitation_id` e `content`.
3748 3759
3749```json theme={null}3760```json theme={null}
3750{3761{
3761```3772```
3762 3773
3763<h4 id="elicitationresult-output">3774<h4 id="elicitationresult-output">
3764 Saída ElicitationResult3775 Saída do ElicitationResult
3765</h4>3776</h4>
3766 3777
3767Para sobrescrever a resposta do usuário, retorne um objeto JSON com `hookSpecificOutput`:3778Para sobrescrever a resposta do usuário, retorne um objeto JSON com `hookSpecificOutput`:
3779| Campo | Valores | Descrição |3790| Campo | Valores | Descrição |
3780| :- | :- | :- |3791| :- | :- | :- |
3781| `action` | `accept`, `decline`, `cancel` | Sobrescreve a ação do usuário |3792| `action` | `accept`, `decline`, `cancel` | Sobrescreve a ação do usuário |
3782| `content` | object | Sobrescreve valores de campo de formulário. Significativo apenas quando `action` é `accept` |3793| `content` | object | Sobrescreve os valores dos campos do formulário. Significativo somente quando `action` é `accept` |
3783 3794
3784Código de saída 2 bloqueia a resposta, mudando a ação efetiva para `decline`. Claude Code não mostra sua mensagem stderr em lugar algum.3795O código de saída 2 bloqueia a resposta, alterando a ação efetiva para `decline`. O Claude Code não mostra sua mensagem de stderr em lugar nenhum.
3785 3796
3786Claude Code age em `hookSpecificOutput` de uma saída JSON de hook ElicitationResult e descarta `systemMessage` e `continue`.3797O Claude Code age com base no `hookSpecificOutput` da saída JSON de um hook ElicitationResult e descarta `systemMessage` e `continue`.
3787 3798
3788<h2 id="prompt-based-hooks">3799<h2 id="prompt-based-hooks">
3789 Hooks baseados em prompt3800 Hooks baseados em prompt
