827 827
828O código de saída do seu hook diz ao Claude Code se deve continuar com a ação que disparou o hook, como uma chamada de ferramenta ou um prompt. Uma execução que termina tem um de três resultados:828O código de saída do seu hook diz ao Claude Code se deve continuar com a ação que disparou o hook, como uma chamada de ferramenta ou um prompt. Uma execução que termina tem um de três resultados:
829 829
830* **Sucesso**: seu hook sai com 0. Claude Code aplica quaisquer campos de [saída JSON](#json-output) que seu hook imprimiu, e a ação prossegue, a menos que esses campos a bloqueiem ou neguem.830* **Sucesso**: seu hook sai com 0. Claude Code aplica quaisquer campos de [saída JSON](#json-output) que seu hook imprimiu, e a ação prossegue, a menos que esses campos a bloqueiem ou neguem. [Hooks que iniciam um processo em segundo plano](#hooks-that-start-a-background-process) cobre a exceção.
831* **Erro bloqueador**: seu hook sai com 2. Em [eventos que podem bloquear](#exit-code-2-behavior-per-event), Claude Code interrompe a ação.831* **Erro bloqueador**: seu hook sai com 2. Em [eventos que podem bloquear](#exit-code-2-behavior-per-event), Claude Code interrompe a ação.
832* **Erro não-bloqueador**: seu hook sai com qualquer outro código, ou falha de alguma outra forma, como não iniciar ou imprimir JSON inválido. A ação prossegue, e em eventos como `PreToolUse` você vê um aviso `<hook name> hook error` na transcrição. Se você quiser que um hook com falha bloqueie a ação, defina [`onFailure: "block"`](#block-the-action-when-a-hook-fails).832* **Erro não-bloqueador**: seu hook sai com qualquer outro código, ou falha de alguma outra forma, como não iniciar ou imprimir JSON inválido. A ação prossegue, e em eventos como `PreToolUse` você vê um aviso `<hook name> hook error` na transcrição. Se você quiser que um hook com falha bloqueie a ação, defina [`onFailure: "block"`](#block-the-action-when-a-hook-fails).
833 833
932* Um hook `command`, `http` ou `mcp_tool` expirado não bloqueia a chamada da ferramenta. A chamada continua através do [fluxo de permissão](/docs/pt/permissions) normal, portanto não conte com um hook travado para agir como um portão. Para bloquear a chamada quando um hook `command` ou `http` atinge o timeout, defina [`onFailure: "block"`](#block-the-action-when-a-hook-fails).932* Um hook `command`, `http` ou `mcp_tool` expirado não bloqueia a chamada da ferramenta. A chamada continua através do [fluxo de permissão](/docs/pt/permissions) normal, portanto não conte com um hook travado para agir como um portão. Para bloquear a chamada quando um hook `command` ou `http` atinge o timeout, defina [`onFailure: "block"`](#block-the-action-when-a-hook-fails).
933* Um hook de callback [Agent SDK](/docs/pt/agent-sdk/hooks) que excede seu timeout [bloqueia a chamada da ferramenta](#pretooluse).933* Um hook de callback [Agent SDK](/docs/pt/agent-sdk/hooks) que excede seu timeout [bloqueia a chamada da ferramenta](#pretooluse).
934 934
935<h4 id="hooks-that-start-a-background-process">
936 Hooks que iniciam um processo em segundo plano
937</h4>
938
939Se seu hook de comando toma sua decisão em um processo em segundo plano e sai, uma negação que esse processo imprime depois que Claude Code parou de ler não bloqueia a chamada de ferramenta. Para um hook que não é [async](#run-hooks-in-the-background), Claude Code termina de ler a saída do hook logo após o próprio processo do hook sair.
940
941Imprima a decisão antes de iniciar um processo em segundo plano, e redirecione o stdout e o stderr desse processo. Se seu script imprime um allow e depois inicia um processo em segundo plano sem redirecionar o stdout e o stderr desse processo, Claude Code bloqueia a chamada de ferramenta. O erro do hook inclui `refusing to honor the suspect capture`.
942
943Este script de hook `PreToolUse` imprime a decisão com `policy-check.sh` e depois envia métricas em segundo plano:
944
945```bash theme={null}
946#!/bin/bash
947"$CLAUDE_PROJECT_DIR"/.claude/hooks/policy-check.sh || exit $?
948"$CLAUDE_PROJECT_DIR"/.claude/hooks/upload-metrics.sh >/dev/null 2>&1 &
949```
950
951O restante do script faz o seguinte:
952
953* **`|| exit $?`**: torna o código de saída da verificação o código do próprio hook, para que uma verificação que sai com 2 para negar ainda bloqueie. Caso contrário, o hook sai com o código da última linha, que é 0.
954* **`>/dev/null 2>&1 &`**: executa `upload-metrics.sh` em segundo plano com sua saída redirecionada, para que ele não mantenha a saída do hook aberta.
955
956Para testar o script, faça `policy-check.sh` sair com 2 e então dispare uma chamada de ferramenta correspondida pelo hook. A chamada de ferramenta é bloqueada.
957
935<h4 id="block-the-action-when-a-hook-fails">958<h4 id="block-the-action-when-a-hook-fails">
936 Bloquear a ação quando um hook falha959 Bloquear a ação quando um hook falha
937</h4>960</h4>
1245 Eventos de hook1268 Eventos de hook
1246</h2>1269</h2>
1247 1270
1248Cada evento corresponde a um ponto no ciclo de vida do Claude Code em que 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.1271Cada evento corresponde a um ponto no ciclo de vida do Claude Code em que 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 recebe e como controlar o comportamento por meio da saída.
1249 1272
1250<h3 id="sessionstart">1273<h3 id="sessionstart">
1251 SessionStart1274 SessionStart
1252</h3>1275</h3>
1253 1276
1254É 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 [CLAUDE.md](/docs/pt/memory) em vez disso.1277É 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 requer um script, use o [CLAUDE.md](/docs/pt/memory).
1255 1278
1256O SessionStart é executado em todas as sessões, portanto mantenha esses hooks rápidos. Apenas hooks `type: "command"` e `type: "mcp_tool"` são suportados. Consulte [campos de hook de ferramenta MCP](#mcp-tool-hook-fields) para saber quando hooks `mcp_tool` são executados.1279O SessionStart é executado em todas as sessões, portanto 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 hooks `mcp_tool` são executados.
1257 1280
1258O valor do matcher corresponde a como a sessão foi iniciada:1281O valor do matcher corresponde a como a sessão foi iniciada:
1259 1282
1263| `resume` | `--resume`, `--continue` ou `/resume` |1286| `resume` | `--resume`, `--continue` ou `/resume` |
1264| `clear` | `/clear` |1287| `clear` | `/clear` |
1265| `compact` | Compactação automática ou manual |1288| `compact` | Compactação automática ou manual |
1266| `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) |1289| `fork` | Uma nova sessão bifurcada de uma existente: `--fork-session` com `--resume` ou `--continue`, a cópia em segundo plano do `/fork`, `/branch` ou uma conversa que você [move para o segundo plano](/docs/pt/agent-view#from-inside-a-session) |
1267 1290
1268Antes da v2.1.214, sessões bifurcadas informavam a origem `"resume"`.1291Antes da v2.1.214, sessões bifurcadas informavam a origem `"resume"`.
1269 1292
1283 1306
1284| Campo | Descrição |1307| Campo | Descrição |
1285| :- | :- |1308| :- | :- |
1286| `source` | Como a sessão foi iniciada: `"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 |1309| `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 |
1287| `model` | O identificador do modelo ativo. Pode ser omitido, por exemplo após `/clear` ou quando uma sessão é restaurada por meio da recuperação de conversa, portanto verifique se o campo existe antes de lê-lo |1310| `model` | O identificador do modelo ativo. Ele pode ser omitido, por exemplo após `/clear` ou quando uma sessão é restaurada por meio da recuperação de conversa, portanto verifique se o campo existe antes de lê-lo |
1288| `agent_type` | O nome do agente, presente quando você inicia o Claude Code com `claude --agent <name>` |1311| `agent_type` | O nome do agente, presente quando você inicia o Claude Code com `claude --agent <name>` |
1289| `session_title` | O título personalizado da sessão, presente quando um estiver definido, por exemplo com `--name`, `/rename`, a saída `sessionTitle` de um hook ou o `renameSession()` do Agent SDK. Um hook que emite `sessionTitle` pode verificar este campo primeiro para evitar sobrescrever um título personalizado existente |1312| `session_title` | O título personalizado da sessão, presente quando um é definido, por exemplo com `--name`, `/rename`, a saída `sessionTitle` de um hook ou o `renameSession()` do Agent SDK. Um hook que emite `sessionTitle` pode verificar esse campo primeiro para evitar sobrescrever um título personalizado existente |
1290 1313
1291Uma 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`.1314Uma 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`.
1292 1315
1293Quando `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.1316Quando `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 requerem o Claude Code v2.1.251 ou posterior.
1294 1317
1295| Campo | Descrição |1318| Campo | Descrição |
1296| :- | :- |1319| :- | :- |
1325| Campo | Descrição |1348| Campo | Descrição |
1326| :- | :- |1349| :- | :- |
1327| `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 |1350| `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 |
1328| `initialUserMessage` | String usada como a primeira mensagem do usuário da sessão, no [modo não interativo](/docs/pt/headless) com a flag `-p`. Ela se torna o primeiro turno mesmo que você não passe nenhum prompt. Um prompt que você passar vem em seguida como o próximo turno |1351| `initialUserMessage` | String usada como a primeira mensagem do usuário da sessão, no [modo não interativo](/docs/pt/headless) com a flag `-p`. Ela se torna o primeiro turno mesmo que você não passe nenhum prompt. Um prompt que você passe vem em seguida, como o próximo turno |
1329| `sessionTitle` | Define o título da sessão, com o mesmo efeito de `/rename`. Aplica-se quando `source` é `"startup"`, `"resume"` ou `"fork"` |1352| `sessionTitle` | Define o título da sessão, com o mesmo efeito de `/rename`. Aplica-se quando `source` é `"startup"`, `"resume"` ou `"fork"` |
1330| `watchPaths` | Array de caminhos absolutos a observar para eventos [FileChanged](#filechanged) durante esta sessão |1353| `watchPaths` | Array de caminhos absolutos a serem observados para eventos [FileChanged](#filechanged) durante esta sessão |
1331| `reloadSkills` | Booleano. Quando `true`, o Claude Code verifica novamente os diretórios de [skills](/docs/pt/skills) e comandos após a conclusão dos hooks SessionStart. Consulte [Recarregar skills que um hook instala](#reload-skills-that-a-hook-installs) |1354| `reloadSkills` | Booleano. Quando `true`, o Claude Code verifica novamente os diretórios de [skills](/docs/pt/skills) e de comandos após a conclusão dos hooks SessionStart. Consulte [Recarregar skills que um hook instala](#reload-skills-that-a-hook-installs) |
1332 1355
1333Esta saída adiciona contexto e nomeia a sessão:1356Esta saída adiciona contexto e nomeia a sessão:
1334 1357
1342}1365}
1343```1366```
1344 1367
1345Um hook que apenas adiciona contexto pode imprimi-lo sem construir JSON, porque o Claude Code adiciona o [stdout em texto simples](#exit-code-0) de um hook SessionStart ao contexto do Claude.1368Um hook que apenas adiciona contexto pode imprimi-lo sem montar JSON, porque o Claude Code adiciona o [stdout em texto simples](#exit-code-0) de um hook SessionStart ao contexto do Claude.
1346 1369
1347Se o hook SessionStart do seu plugin fornecer `initialUserMessage` ou `sessionTitle`, instale o plugin antes de a sessão começar. O Claude Code ignora ambos os campos de um plugin cuja instalação termina depois que os hooks SessionStart já foram executados.1370Se o hook SessionStart do seu plugin fornece `initialUserMessage` ou `sessionTitle`, instale o plugin antes do início da sessão. O Claude Code ignora ambos os campos de um plugin cuja instalação termina depois que os hooks SessionStart foram executados.
1348 1371
1349<h4 id="reload-skills-that-a-hook-installs">1372<h4 id="reload-skills-that-a-hook-installs">
1350 Recarregar skills que um hook instala1373 Recarregar skills que um hook instala
1351</h4>1374</h4>
1352 1375
1353Para disponibilizar na mesma sessão as skills que um hook SessionStart instala, retorne `reloadSkills`. A descoberta de skills normalmente é executada antes de os hooks SessionStart terminarem, então, sem isso, arquivos que um hook grava em `~/.claude/skills/` ou `.claude/skills/` podem estar ausentes quando o primeiro prompt for executado.1376Para disponibilizar na mesma sessão as skills que um hook SessionStart instala, retorne `reloadSkills`. A descoberta de skills normalmente é executada antes de os hooks SessionStart terminarem; portanto, sem isso, arquivos que um hook grava em `~/.claude/skills/` ou `.claude/skills/` podem estar ausentes quando o primeiro prompt for executado.
1354 1377
1355Este exemplo sincroniza um repositório compartilhado de skills e solicita a nova verificação:1378Este exemplo sincroniza um repositório compartilhado de skills e solicita a nova verificação:
1356 1379
1363echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "reloadSkills": true}}'1386echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "reloadSkills": true}}'
1364```1387```
1365 1388
1366A URL do repositório é um espaço reservado. Substitua-a pelo seu próprio repositório de skills.1389A URL do repositório é um marcador de exemplo. Substitua-a pelo seu próprio repositório de skills.
1367 1390
1368<h4 id="persist-environment-variables">1391<h4 id="persist-environment-variables">
1369 Persistir variáveis de ambiente1392 Persistir variáveis de ambiente
1370</h4>1393</h4>
1371 1394
1372Os hooks SessionStart têm acesso à variável de ambiente `CLAUDE_ENV_FILE`, que fornece um caminho de arquivo onde você pode persistir variáveis de ambiente para os comandos de shell que o Claude executa mais tarde na sessão.1395Os hooks SessionStart têm acesso à variável de ambiente `CLAUDE_ENV_FILE`, que fornece um caminho de arquivo onde você pode persistir variáveis de ambiente para os comandos de shell que o Claude executa mais adiante na sessão.
1373 1396
1374Para definir variáveis de ambiente individuais, escreva instruções `export` em `CLAUDE_ENV_FILE`. Use anexação (`>>`) para preservar variáveis definidas por outros hooks:1397Para definir variáveis de ambiente individuais, escreva instruções `export` em `CLAUDE_ENV_FILE`. Use anexação (`>>`) para preservar variáveis definidas por outros hooks:
1375 1398
1385exit 01408exit 0
1386```1409```
1387 1410
1388Para capturar todas as alterações de ambiente de comandos de configuração, compare as variáveis exportadas antes e depois:1411Para capturar todas as alterações de ambiente dos comandos de configuração, compare as variáveis exportadas antes e depois:
1389 1412
1390```bash theme={null}1413```bash theme={null}
1391#!/bin/bash1414#!/bin/bash
1404exit 01427exit 0
1405```1428```
1406 1429
1407Cada comando Bash executa o conteúdo do arquivo como código de shell antes do próprio comando, portanto uma linha ali pode usar qualquer coisa que o Bash avalie, como a referência `$PATH` em `export PATH="$PATH:./node_modules/.bin"`.1430Cada comando Bash executa o conteúdo do arquivo como código de shell antes do próprio comando, portanto uma linha ali pode usar qualquer coisa que o Bash avalia, como a referência `$PATH` em `export PATH="$PATH:./node_modules/.bin"`.
1408 1431
1409<a id="persisted-variables-in-powershell-commands" />1432<a id="persisted-variables-in-powershell-commands" />
1410 1433
1412 Variáveis persistidas em comandos PowerShell1435 Variáveis persistidas em comandos PowerShell
1413</h5>1436</h5>
1414 1437
1415Os comandos [PowerShell](/docs/pt/tools-reference#powershell-tool) também recebem as variáveis de `CLAUDE_ENV_FILE`, no Claude Code v2.1.296 ou posterior, mas o PowerShell nunca executa o arquivo. Em vez disso, o Claude Code lê as atribuições do arquivo e as copia para o ambiente do comando PowerShell. Ele faz isso somente quando cada linha é uma das seguintes, considerando o que todos os hooks desta sessão gravaram e qualquer script para o qual você [definiu `CLAUDE_ENV_FILE`](/docs/pt/env-vars) antes da inicialização:1438Comandos [PowerShell](/docs/pt/tools-reference#powershell-tool) também recebem as variáveis de `CLAUDE_ENV_FILE`, no Claude Code v2.1.296 ou posterior, mas o PowerShell nunca executa o arquivo. Em vez disso, o Claude Code lê as atribuições do arquivo e as copia para o ambiente do comando PowerShell. Ele faz isso somente quando cada linha é de um dos tipos a seguir, considerando tudo o que cada hook nesta sessão gravou e qualquer script para o qual você [definiu `CLAUDE_ENV_FILE`](/docs/pt/env-vars) antes da inicialização:
1416 1439
1417* Uma linha em branco ou um comentário `#`1440* Uma linha em branco ou um comentário `#`
1418* Uma atribuição no início da linha, escrita como `export NAME=value`, `declare -x NAME=value` ou `NAME=value`, com um valor que o Bash usaria exatamente como escrito, composto por qualquer combinação destas partes: texto sem aspas que usa apenas letras, dígitos e os caracteres `_ @ % + = : , . / -`, texto entre aspas simples e texto entre aspas duplas em que qualquer `$`, crase ou `"` interno esteja escapado com uma barra invertida1441* Uma atribuição no início da linha, escrita como `export NAME=value`, `declare -x NAME=value` ou `NAME=value`, com um valor que o Bash usaria exatamente como escrito, composto por qualquer combinação destas partes: texto sem aspas que use apenas letras, dígitos e os caracteres `_ @ % + = : , . / -`, texto entre aspas simples e texto entre aspas duplas em que qualquer `$`, acento grave ou `"` interno esteja escapado com uma barra invertida
1419 1442
1420Se qualquer linha for de outro tipo, como `export PATH="$PATH:./node_modules/.bin"` com seu `$PATH` não escapado, um comando `source` ou as strings `$'...'` que `direnv export bash` imprime, os comandos PowerShell não recebem nenhuma das variáveis, e `claude --debug` registra `Session environment is not all plain assignments`. Os comandos Bash ainda recebem todas elas. No Windows, os comandos PowerShell também não recebem uma variável cujo valor contenha `/` ou `\`, porque o Git Bash e o Windows escrevem caminhos de forma diferente. Um comando PowerShell em [sandbox](/docs/pt/sandboxing) não recebe nenhuma das variáveis.1443Se qualquer linha for de outro tipo, como `export PATH="$PATH:./node_modules/.bin"` com seu `$PATH` sem escape, um comando `source` ou as strings `$'...'` que `direnv export bash` imprime, os comandos PowerShell não recebem nenhuma das variáveis, e `claude --debug` registra `Session environment is not all plain assignments`. Os comandos Bash ainda recebem todas elas. No Windows, os comandos PowerShell também não recebem uma variável cujo valor contenha `/` ou `\`, porque o Git Bash e o Windows escrevem caminhos de forma diferente. Um comando PowerShell em [sandbox](/docs/pt/sandboxing) não recebe nenhuma das variáveis.
1421 1444
1422<Note>1445<Note>
1423 `CLAUDE_ENV_FILE` está disponível para os hooks SessionStart, [Setup](#setup), [CwdChanged](#cwdchanged) e [FileChanged](#filechanged). Outros eventos de hook não têm acesso a esta variável, nem um hook que é executado no PowerShell, seja por meio de [`"shell": "powershell"`](#command-hook-fields) ou por padrão no Windows sem Git Bash.1446 `CLAUDE_ENV_FILE` está disponível para hooks SessionStart, [Setup](#setup), [CwdChanged](#cwdchanged) e [FileChanged](#filechanged). Outros eventos de hook não têm acesso a essa variável, nem um hook executado no PowerShell, seja por meio de [`"shell": "powershell"`](#command-hook-fields) ou por padrão no Windows sem Git Bash.
1424</Note>1447</Note>
1425 1448
1426<h3 id="setup">1449<h3 id="setup">
1427 Setup1450 Setup
1428</h3>1451</h3>
1429 1452
1430É disparado apenas 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`. 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 [SessionStart](#sessionstart) em vez disso.1453É 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).
1431 1454
1432O valor do matcher corresponde à flag da CLI que acionou o hook:1455O valor do matcher corresponde à flag da CLI que acionou o hook:
1433 1456
1438 1461
1439Quando 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.1462Quando 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.
1440 1463
1441Quando 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).1464Quando você inicia ou continua uma conversa com `-p`, também precisa fornecer um prompt, como argumento ou via 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).
1442 1465
1443Em 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>` pelo local de um arquivo de log, e verifique no log as entradas dos hooks Setup e SessionStart.1466Em 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.
1444 1467
1445Como o Setup não é disparado em toda 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 a existência de `${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) quando armazena o plugin em cache.1468Como o Setup não é disparado em toda 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 caso esteja 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 as 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) quando armazena o plugin em cache.
1446 1469
1447<h4 id="setup-input">1470<h4 id="setup-input">
1448 Entrada do Setup1471 Entrada do Setup
1464 Controle de decisão do Setup1487 Controle de decisão do Setup
1465</h4>1488</h4>
1466 1489
1467Os hooks Setup não podem bloquear; a execução continua com qualquer código de saída. Em todos os códigos de saída, o Claude Code descarta os [campos de saída JSON](#json-output) de um hook Setup, como `systemMessage`, `continue` e `hookSpecificOutput.additionalContext`. Com `-p`, o stdout, o stderr e o código de saída de um hook Setup aparecem na saída da execução apenas como [eventos `hook_response`](/docs/pt/headless#read-session-metadata) quando você inicia com `--output-format stream-json --verbose`.1490Os hooks Setup não podem bloquear; a execução continua com qualquer código de saída. Em todos os códigos de saída, o Claude Code descarta os [campos de saída JSON](#json-output) de um hook Setup, como `systemMessage`, `continue` e `hookSpecificOutput.additionalContext`. Com `-p`, o stdout, o stderr e o código de saída de um hook Setup aparecem na saída da execução somente como [eventos `hook_response`](/docs/pt/headless#read-session-metadata) quando você inicia com `--output-format stream-json --verbose`.
1468 1491
1469Os hooks Setup têm acesso a `CLAUDE_ENV_FILE`. Variáveis gravadas nesse arquivo persistem nos comandos Bash subsequentes da sessão, como nos [hooks SessionStart](#persist-environment-variables). Apenas hooks `type: "command"` são executados no `Setup`. Um hook `type: "mcp_tool"` no `Setup` é sempre ignorado, conforme descrito em [campos de hook de ferramenta MCP](#mcp-tool-hook-fields).1492Os hooks Setup têm acesso a `CLAUDE_ENV_FILE`. As variáveis gravadas nesse arquivo persistem nos comandos Bash subsequentes da sessão, como nos [hooks SessionStart](#persist-environment-variables). Somente hooks `type: "command"` são executados no `Setup`. Um hook `type: "mcp_tool"` no `Setup` é sempre ignorado, conforme descrito em [Campos de hook de ferramenta MCP](#mcp-tool-hook-fields).
1470 1493
1471<h3 id="instructionsloaded">1494<h3 id="instructionsloaded">
1472 InstructionsLoaded1495 InstructionsLoaded
1473</h3>1496</h3>
1474 1497
1475É 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 antecipadamente e novamente mais tarde quando arquivos são carregados de forma preguiçosa, 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.1498É disparado quando um arquivo `CLAUDE.md` ou `.claude/rules/*.md` é carregado no contexto. Esse evento é disparado no início da sessão para arquivos carregados antecipadamente e novamente mais tarde quando arquivos são carregados sob demanda, 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.
1476 1499
1477Este 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`.1500Esse evento não é disparado quando o Claude [lê o `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 o `CLAUDE.md` é um link simbólico para ele, como um carregamento normal de `CLAUDE.md`.
1478 1501
1479O matcher é avaliado 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.1502O matcher é aplicado a `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 sob demanda.
1480 1503
1481<h4 id="instructionsloaded-input">1504<h4 id="instructionsloaded-input">
1482 Entrada do InstructionsLoaded1505 Entrada do InstructionsLoaded
1489| `file_path` | Caminho absoluto para o arquivo de instruções que foi carregado |1512| `file_path` | Caminho absoluto para o arquivo de instruções que foi carregado |
1490| `memory_type` | Escopo do arquivo: `"User"`, `"Project"`, `"Local"` ou `"Managed"` |1513| `memory_type` | Escopo do arquivo: `"User"`, `"Project"`, `"Local"` ou `"Managed"` |
1491| `load_reason` | Por que o arquivo foi carregado: `"session_start"`, `"nested_traversal"`, `"path_glob_match"`, `"include"` ou `"compact"`. O valor `"compact"` é disparado quando arquivos de instruções são recarregados após um evento de compactação |1514| `load_reason` | Por que o arquivo foi carregado: `"session_start"`, `"nested_traversal"`, `"path_glob_match"`, `"include"` ou `"compact"`. O valor `"compact"` é disparado quando arquivos de instruções são recarregados após um evento de compactação |
1492| `globs` | Padrões glob de caminho do frontmatter `paths:` do arquivo, se houver. Presente apenas para carregamentos `path_glob_match` |1515| `globs` | Padrões glob de caminho do frontmatter `paths:` do arquivo, se houver. Presente somente para carregamentos `path_glob_match` |
1493| `trigger_file_path` | Caminho para o arquivo cujo acesso acionou este carregamento, para carregamentos preguiçosos |1516| `trigger_file_path` | Caminho para o arquivo cujo acesso acionou esse carregamento, para carregamentos sob demanda |
1494| `parent_file_path` | Caminho para o arquivo de instruções pai que incluiu este, para carregamentos `include` |1517| `parent_file_path` | Caminho para o arquivo de instruções pai que incluiu este, para carregamentos `include` |
1495 1518
1496```json theme={null}1519```json theme={null}
1509 Controle de decisão do InstructionsLoaded1532 Controle de decisão do InstructionsLoaded
1510</h4>1533</h4>
1511 1534
1512Os 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.1535Os 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 esse evento para logs de auditoria, rastreamento de conformidade ou observabilidade.
1513 1536
1514<h3 id="userpromptsubmit">1537<h3 id="userpromptsubmit">
1515 UserPromptSubmit1538 UserPromptSubmit
1516</h3>1539</h3>
1517 1540
1518É executado quando um prompt é enviado, antes de o Claude processá-lo. Isso permite1541É executado quando um prompt é enviado, antes que o Claude o processe. Isso permite
1519adicionar contexto extra com base no prompt/conversa, validar prompts ou1542adicionar contexto extra com base no prompt/conversa, validar prompts ou
1520bloquear certos tipos de prompts.1543bloquear certos tipos de prompts.
1521 1544
1525* Um [subagente em segundo plano](/docs/pt/sub-agents#run-subagents-in-foreground-or-background) reporta de volta à sessão que o iniciou1548* Um [subagente em segundo plano](/docs/pt/sub-agents#run-subagents-in-foreground-or-background) reporta de volta à sessão que o iniciou
1526* Uma [mensagem que outra sessão envia](/docs/pt/cross-session-messaging) chega à sua conversa principal1549* Uma [mensagem que outra sessão envia](/docs/pt/cross-session-messaging) chega à sua conversa principal
1527 1550
1528Os 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é terminar, um hook travado paralisa a sessão. Se seu hook precisar de mais tempo, defina o campo `timeout` na entrada do hook.1551Os 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 para esses tipos na maioria dos outros eventos. Como esse hook é executado antes de cada prompt e bloqueia o processamento do modelo até terminar, um hook travado paralisa a sessão. Se o seu hook precisar de mais tempo, defina o campo `timeout` na entrada do hook.
1529 1552
1530Com exceção de 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. Para bloquear o prompt em vez disso, defina [`onFailure: "block"`](#block-the-action-when-a-hook-fails) em um hook de comando ou HTTP. A transcrição mostra um aviso nomeando o hook, o timeout que foi atingido e que a saída foi descartada.1553Exceto por um hook de comando que você executa com [`async: true`](#run-hooks-in-the-background), um hook de comando, HTTP ou de ferramenta MCP em `UserPromptSubmit` que atinge seu timeout é cancelado, e sua saída, incluindo qualquer `additionalContext`, é descartada. O prompt ainda chega ao Claude sem esse contexto. Para bloquear o prompt em vez disso, defina [`onFailure: "block"`](#block-the-action-when-a-hook-fails) em um hook de comando ou HTTP. A transcrição mostra um aviso nomeando o hook, o timeout que foi atingido e que a saída foi descartada.
1531 1554
1532Um [hook de callback do Agent SDK](/docs/pt/agent-sdk/hooks) em `UserPromptSubmit` que atinge seu timeout bloqueia o prompt com uma mensagem que nomeia 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 permissiva. A sessão continua. Antes da v2.1.208, um timeout de callback nesse evento encerrava o turno com um erro de execução.1555Um [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 ali pode estar atuando como uma barreira de política que não deve falhar de forma permissiva. A sessão continua. Antes da v2.1.208, um timeout de callback nesse evento encerrava o turno com um erro de execução.
1533 1556
1534<h4 id="userpromptsubmit-input">1557<h4 id="userpromptsubmit-input">
1535 Entrada do UserPromptSubmit1558 Entrada do UserPromptSubmit
1536</h4>1559</h4>
1537 1560
1538Alé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="…">`, portanto leve essas linhas em conta se seu hook analisar o prompt.1561Além dos [campos de entrada comuns](#common-input-fields), os hooks UserPromptSubmit recebem o campo `prompt` contendo o texto enviado. Conteúdo colado que foi recolhido em um marcador `[Pasted text #N]` chega expandido no lugar. Em sessões em que o Claude Code [marca texto colado para o Claude](/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="…">`, portanto leve essas linhas em conta se o seu hook analisar o prompt.
1539 1562
1540Os 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).1563Os 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).
1541 1564
1573| `sessionTitle` | Define o título da sessão. Use para nomear sessões automaticamente com base no conteúdo do prompt |1596| `sessionTitle` | Define o título da sessão. Use para nomear sessões automaticamente com base no conteúdo do prompt |
1574| `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) |1597| `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) |
1575 1598
1576Um hook que bloqueia saindo com 2 é tratado da mesma forma que `reason`: a mensagem de bloqueio mostra o texto do stderr ao usuário, e ele não é adicionado ao contexto.1599Um 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.
1577 1600
1578```json theme={null}1601```json theme={null}
1579{1602{
1592 O que um prompt bloqueado deixa para trás1615 O que um prompt bloqueado deixa para trás
1593</h4>1616</h4>
1594 1617
1595Um 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 quando o hook bloqueia com `decision: "block"` quanto saindo com 2.1618Um 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.
1596 1619
1597`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, portanto 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).1620`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, portanto um hook de bloqueio não é uma maneira 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).
1598 1621
1599<h3 id="userpromptexpansion">1622<h3 id="userpromptexpansion">
1600 UserPromptExpansion1623 UserPromptExpansion
1601</h3>1624</h3>
1602 1625
1603É executado quando um comando digitado pelo usuário é expandido em um prompt antes de chegar ao Claude. Use-o 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`.1626É executado quando um comando digitado pelo usuário se expande em um prompt antes de chegar ao Claude. Use-o para impedir a invocação direta de comandos específicos, injetar contexto para uma skill específica ou registrar 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`.
1604 1627
1605Este evento cobre o caminho que o `PreToolUse` não cobre: um hook `PreToolUse` que corresponde à ferramenta `Skill` é disparado apenas quando o Claude chama a ferramenta, mas digitar `/skillname` diretamente contorna o `PreToolUse`. O `UserPromptExpansion` é disparado nesse caminho direto.1628Esse 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 ignora o `PreToolUse`. O `UserPromptExpansion` é disparado nesse caminho direto.
1606 1629
1607Faz a correspondência com `command_name`. Deixe o matcher vazio para disparar em todo comando do tipo prompt.1630Faz a correspondência em `command_name`. Deixe o matcher vazio para disparar em todo comando do tipo prompt.
1608 1631
1609<h4 id="userpromptexpansion-input">1632<h4 id="userpromptexpansion-input">
1610 Entrada do UserPromptExpansion1633 Entrada do UserPromptExpansion
1635 1658
1636| Campo | Descrição |1659| Campo | Descrição |
1637| :- | :- |1660| :- | :- |
1638| `decision` | `"block"` impede que o comando seja expandido. Omita para permitir que ele prossiga |1661| `decision` | `"block"` impede que o comando se expanda. Omita para permitir que ele prossiga |
1639| `reason` | Mostrado ao usuário quando `decision` é `"block"` |1662| `reason` | Mostrado ao usuário quando `decision` é `"block"` |
1640| `additionalContext` | String adicionada ao contexto do Claude junto com o prompt expandido. Consulte [Adicionar contexto para o Claude](#add-context-for-claude) |1663| `additionalContext` | String adicionada ao contexto do Claude junto com o prompt expandido. Consulte [Adicionar contexto para o Claude](#add-context-for-claude) |
1641 1664
1642Um hook que bloqueia saindo com 2 é tratado da mesma forma que `reason`: a mensagem de bloqueio mostra o texto do stderr ao usuário.1665Um hook que bloqueia saindo com 2 é encaminhado da mesma forma que `reason`: a mensagem de bloqueio mostra o texto do stderr ao usuário.
1643 1666
1644```json theme={null}1667```json theme={null}
1645{1668{
1656 MessageDisplay1679 MessageDisplay
1657</h3>1680</h3>
1658 1681
1659É 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 ser renderizado, 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.1682É 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 ser renderizado, 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.
1660 1683
1661Use o MessageDisplay para:1684Use o MessageDisplay para:
1662 1685
1663* remover markdown para uma exibição minimalista1686* remover markdown para uma exibição minimalista
1664* transformar o texto que uma aplicação do Agent SDK mostra aos seus usuários1687* transformar o texto que um aplicativo do Agent SDK mostra aos seus usuários
1665* ocultar chaves de API ou nomes de host internos das respostas do Claude1688* ocultar chaves de API ou nomes de host internos das respostas do Claude
1666 1689
1667O Claude Code retém cada lote até que seu hook retorne, portanto 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 seu hook precisar de mais tempo, defina o campo `timeout` na entrada do hook.1690O Claude Code retém cada lote até que seu hook retorne, portanto 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 esse evento é de 10 segundos; se o seu hook precisar de mais tempo, defina o campo `timeout` na entrada do hook.
1668 1691
1669O MessageDisplay é apenas de 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 verboso mostra o original. O hook recebe apenas o texto das mensagens do assistente, portanto resultados de ferramentas e o texto que você digita são renderizados sem alterações.1692O 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, portanto o Claude nunca vê a substituição, e o modo verbose mostra o original. O hook recebe apenas o texto das mensagens do assistente, portanto resultados de ferramentas e o texto que você digita são renderizados sem alteração.
1670 1693
1671O 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.1694O 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.
1672 1695
1673Em 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` para cada mensagem recebe o mesmo texto total em ambos os modos.1696Em 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 após a conclusão da mensagem 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.
1674 1697
1675<h4 id="messagedisplay-input">1698<h4 id="messagedisplay-input">
1676 Entrada do MessageDisplay1699 Entrada do MessageDisplay
1677</h4>1700</h4>
1678 1701
1679Alé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, portanto use `index` e `final` para acompanhar o progresso em uma mensagem, em vez de esperar que as linhas sejam agrupadas de uma forma específica.1702Além dos [campos de entrada comuns](#common-input-fields), os hooks MessageDisplay recebem identificadores do turno e da mensagem, a posição dessa chamada dentro da mensagem e o novo texto em `delta`. Os limites dos lotes dependem de como o texto é transmitido, portanto use `index` e `final` para acompanhar o progresso pela mensagem, em vez de esperar que as linhas sejam agrupadas de uma forma específica.
1680 1703
1681| Campo | Descrição |1704| Campo | Descrição |
1682| :- | :- |1705| :- | :- |
1683| `turn_id` | UUID do turno atual |1706| `turn_id` | UUID do turno atual |
1684| `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, portanto não pode ser correlacionado com os ids de mensagem da transcrição |1707| `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, portanto não pode ser correlacionado com os ids de mensagem da transcrição |
1685| `index` | Índice baseado em zero deste lote dentro da mensagem |1708| `index` | Índice, começando em zero, deste lote dentro da mensagem |
1686| `final` | `true` no último lote da mensagem. Cada mensagem tem exatamente um lote final |1709| `final` | `true` no último lote da mensagem. Cada mensagem tem exatamente um lote final |
1687| `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, portanto trate `final`, e não um delta não vazio, como o sinal de fim de mensagem. Em execuções do Agent SDK e `claude -p`, a chamada única carrega a mensagem inteira |1710| `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, portanto 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 |
1688 1711
1689```json theme={null}1712```json theme={null}
1690{1713{
1710| :- | :- |1733| :- | :- |
1711| `displayContent` | Texto exibido no lugar do delta. Omita-o para exibir o original |1734| `displayContent` | Texto exibido no lugar do delta. Omita-o para exibir o original |
1712 1735
1713Os 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`.1736Os 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 sobre o `displayContent` da saída JSON deles e descarta `systemMessage` e `continue`.
1714 1737
1715Este 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 as crases de código inline de `delta` e retorna o resultado como `displayContent`.1738Este 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`.
1716 1739
1717<Tabs>1740<Tabs>
1718 <Tab title="macOS/Linux">1741 <Tab title="macOS/Linux">
1771 }1794 }
1772 ```1795 ```
1773 1796
1774 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.1797 A flag `-NoProfile` evita 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.
1775 1798
1776 Salve este script em `.claude/hooks/plain-display.ps1` no seu projeto:1799 Salve este script em `.claude/hooks/plain-display.ps1` no seu projeto:
1777 1800
1788 </Tab>1811 </Tab>
1789</Tabs>1812</Tabs>
1790 1813
1791Lotes sem markdown passam sem alterações. Se o script falhar, por exemplo porque o `jq` não está instalado, o Claude Code exibe o texto original e registra a falha apenas na [saída de depuração](#debug-hooks), não na sessão.1814Lotes 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 apenas na [saída de depuração](#debug-hooks), não na sessão.
1792 1815
1793<h3 id="pretooluse">1816<h3 id="pretooluse">
1794 PreToolUse1817 PreToolUse
1795</h3>1818</h3>
1796 1819
1797É executado depois que o Claude cria os parâmetros da ferramenta e antes de processar a chamada de ferramenta. Faz 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).1820É 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).
1798 1821
1799Para executar um hook quando um arquivo específico muda no disco, independentemente de quem o gravou, use [FileChanged](#filechanged) em vez de corresponder às ferramentas de edição de arquivos pelo nome. Ao contrário do PreToolUse, o Claude Code executa os hooks FileChanged depois da alteração, e eles não têm controle de decisão, portanto não podem bloquear a gravação.1822Para 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, portanto não podem bloquear a gravação.
1800 1823
1801<Warning>1824<Warning>
1802 O PreToolUse é executado apenas quando o Claude chama uma ferramenta. 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, portanto nenhum hook PreToolUse é disparado para eles, incluindo hooks que correspondem a `Read`. Para bloquear caminhos específicos de referências `@`, use uma [regra de negação de `Read`](/docs/pt/permissions#read-and-edit) em vez disso.1825 O PreToolUse é executado somente quando o Claude chama uma ferramenta. Por padrão, 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 enquanto monta o prompt, portanto nenhum hook PreToolUse é disparado para eles, incluindo hooks que correspondem a `Read`. O PreToolUse também não é disparado para [`EndConversation`](/docs/pt/tools-reference#endconversation-tool-behavior).
1826
1827 Você pode bloquear caminhos específicos de referências `@` ou desativar a inserção:
1803 1828
1804 O PreToolUse também não é disparado para [`EndConversation`](/docs/pt/tools-reference#endconversation-tool-behavior).1829 * **Bloquear caminhos específicos**: adicione uma [regra de negação de `Read`](/docs/pt/permissions#read-and-edit) para eles
1830 * **Desativar a inserção**: defina [`CLAUDE_CODE_DISABLE_FILE_MENTIONS=1`](/docs/pt/env-vars#variables) no seu shell, nas configurações de usuário ou nas configurações gerenciadas. O Claude então recebe os caminhos mencionados com uma nota para lê-los usando suas ferramentas de arquivo. Se ele fizer isso, seus hooks PreToolUse correspondentes serão executados. A variável requer o Claude Code v2.1.299 ou posterior, e o Claude Code a ignora nas configurações de projeto e locais.
1805</Warning>1831</Warning>
1806 1832
1807Use o [controle de decisão do PreToolUse](#pretooluse-decision-control) para permitir, negar, pedir confirmação ou adiar a chamada de ferramenta.1833Use o [controle de decisão do PreToolUse](#pretooluse-decision-control) para permitir, negar, perguntar ou adiar a chamada de ferramenta.
1808 1834
1809Um [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 que nomeia o timeout. Uma negação explícita retornada por outro hook ainda tem precedência.1835Um [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.
1810 1836
1811<h4 id="pretooluse-input">1837<h4 id="pretooluse-input">
1812 Entrada do PreToolUse1838 Entrada do PreToolUse
1814 1840
1815Além dos [campos de entrada comuns](#common-input-fields), os hooks PreToolUse recebem `tool_name`, `tool_input` e `tool_use_id`.1841Além dos [campos de entrada comuns](#common-input-fields), os hooks PreToolUse recebem `tool_name`, `tool_input` e `tool_use_id`.
1816 1842
1817Para uma [ferramenta MCP](#match-mcp-tools), a entrada também carrega `mcp_server`, um objeto com o `name` do servidor e um `source` que indica 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 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.1843Para uma [ferramenta MCP](#match-mcp-tools), a entrada também carrega `mcp_server`, um objeto com o `name` do servidor e um `source` que indica 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 reconheça. Baseie 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` requer o Claude Code v2.1.274 ou posterior.
1818 1844
1819Para as ferramentas de arquivo `Write`, `Edit` e `Read`, `tool_input.file_path` é sempre absoluto:1845Para as ferramentas de arquivo `Write`, `Edit` e `Read`, `tool_input.file_path` é sempre absoluto:
1820 1846
1821* O Claude Code expande `~` e caminhos relativos antes de os hooks serem executados, portanto um hook que faz correspondência por caminhos não pode ser contornado via `~` ou por uma grafia relativa do mesmo caminho1847* O Claude Code expande `~` e caminhos relativos antes de os hooks serem executados, portanto um hook que faz a correspondência de caminhos não pode ser contornado por meio de `~` ou de uma grafia relativa do mesmo caminho
1822* 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`1848* 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`
1823* 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 bloquear1849* 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
1824* 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 com um segmento de caminho como `/src/` em vez de ancorar com `^`, já que o caminho é absoluto1850* 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
1825 1851
1826Uma chamada `Write` no Windows entrega:1852Uma chamada `Write` no Windows entrega:
1827 1853
1854| `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 |1880| `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 |
1855| `run_in_background` | boolean | `false` | Se o comando deve ser executado em segundo plano |1881| `run_in_background` | boolean | `false` | Se o comando deve ser executado em segundo plano |
1856 1882
1857Quando 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 indica quais arquivos podem defini-la. Caso contrário, ele as registra apenas 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.1883Quando 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 indica 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.
1858 1884
1859Seu [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.1885Seu [hook PostToolUse](#posttooluse) então recebe os arquivos alterados em `tool_response.bashEditDiff`. A lista abrange 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. Requer o Claude Code v2.1.269 ou posterior.
1860 1886
1861<Note>1887<Note>
1862 A lista é de melhor esforço e está em beta público. O Claude Code pode deixar passar 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 descobrir o que revisar, não para impor uma política.1888 A lista é de melhor esforço e está em beta público. O Claude Code pode deixar de capturar 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.
1863</Note>1889</Note>
1864 1890
1865`changedFiles` e `files` listam o que o comando alterou; os demais campos indicam quão completa e quão confiável essa lista é.1891`changedFiles` e `files` listam o que o comando alterou; os campos restantes indicam quão completa e quão confiável é essa lista.
1866 1892
1867| Campo | Tipo | Exemplo | Descrição |1893| Campo | Tipo | Exemplo | Descrição |
1868| :- | :- | :- | :- |1894| :- | :- | :- | :- |
1869| `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 |1895| `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 |
1870| `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 |1896| `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 |
1871| `moreFiles` | number | `2` | Contagem de arquivos alterados sem diff em `files` |1897| `moreFiles` | number | `2` | Quantidade de arquivos alterados sem diff em `files` |
1872| `unavailable` | boolean | `true` | Definido quando o diff está incompleto ou não pôde ser obtido |1898| `unavailable` | boolean | `true` | Definido quando o diff está incompleto ou não pôde ser obtido |
1873| `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 |1899| `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 nenhum diff |
1874| `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 |1900| `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 |
1875 1901
1876<a id="powershell" />1902<a id="powershell" />
1879 PowerShell1905 PowerShell
1880</h5>1906</h5>
1881 1907
1882Executa comandos do PowerShell. Consulte a [ferramenta PowerShell](/docs/pt/tools-reference#powershell-tool) para ver a disponibilidade por plataforma.1908Executa comandos PowerShell. Consulte a [ferramenta PowerShell](/docs/pt/tools-reference#powershell-tool) para ver a disponibilidade por plataforma.
1883 1909
1884Os campos correspondem aos da ferramenta Bash, com a string do comando em `command`:1910Os campos correspondem aos da ferramenta Bash, com a string do comando em `command`:
1885 1911
1886| Campo | Tipo | Exemplo | Descrição |1912| Campo | Tipo | Exemplo | Descrição |
1887| :- | :- | :- | :- |1913| :- | :- | :- | :- |
1888| `command` | string | `"Get-ChildItem -Recurse"` | O comando do PowerShell a ser executado |1914| `command` | string | `"Get-ChildItem -Recurse"` | O comando PowerShell a ser executado |
1889| `description` | string | `"List files recursively"` | Descrição opcional do que o comando faz |1915| `description` | string | `"List files recursively"` | Descrição opcional do que o comando faz |
1890| `timeout` | number | `120000` | Timeout opcional em milissegundos |1916| `timeout` | number | `120000` | Timeout opcional em milissegundos |
1891| `run_in_background` | boolean | `false` | Se o comando deve ser executado em segundo plano |1917| `run_in_background` | boolean | `false` | Se o comando deve ser executado em segundo plano |
1892 1918
1893Use `Bash|PowerShell` como matcher em hooks que inspecionam comandos de shell, para que eles cubram ambas as ferramentas:1919Use `Bash|PowerShell` como matcher em hooks que inspecionam comandos de shell, para que cubram ambas as ferramentas:
1894 1920
1895* No Windows, sempre que a ferramenta PowerShell estiver habilitada, o Claude trata o PowerShell como o shell principal e encaminha os comandos de shell por ele.1921* 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.
1896* No Windows sem Git Bash, a ferramenta é habilitada automaticamente e o Claude Code não registra a ferramenta Bash.1922* No Windows sem Git Bash, a ferramenta é habilitada automaticamente e o Claude Code não registra a ferramenta Bash.
1897* Um hook que corresponde apenas a `Bash` nunca é disparado nesse caso.1923* Um hook que corresponde apenas a `Bash` nunca é disparado nesse caso.
1898 1924
1940 1966
1941| Campo | Tipo | Exemplo | Descrição |1967| Campo | Tipo | Exemplo | Descrição |
1942| :- | :- | :- | :- |1968| :- | :- | :- | :- |
1943| `pattern` | string | `"**/*.ts"` | Padrão glob com o qual os arquivos serão comparados |1969| `pattern` | string | `"**/*.ts"` | Padrão glob com o qual comparar os arquivos |
1944| `path` | string | `"/path/to/dir"` | Diretório opcional onde pesquisar. O padrão é o diretório de trabalho atual |1970| `path` | string | `"/path/to/dir"` | Diretório opcional no qual pesquisar. O padrão é o diretório de trabalho atual |
1945 1971
1946<h5 id="grep">1972<h5 id="grep">
1947 Grep1973 Grep
1952| Campo | Tipo | Exemplo | Descrição |1978| Campo | Tipo | Exemplo | Descrição |
1953| :- | :- | :- | :- |1979| :- | :- | :- | :- |
1954| `pattern` | string | `"TODO.*fix"` | Padrão de expressão regular a ser pesquisado |1980| `pattern` | string | `"TODO.*fix"` | Padrão de expressão regular a ser pesquisado |
1955| `path` | string | `"/path/to/dir"` | Arquivo ou diretório opcional onde pesquisar |1981| `path` | string | `"/path/to/dir"` | Arquivo ou diretório opcional no qual pesquisar |
1956| `glob` | string | `"*.ts"` | Padrão glob opcional para filtrar arquivos |1982| `glob` | string | `"*.ts"` | Padrão glob opcional para filtrar arquivos |
1957| `output_mode` | string | `"content"` | `"content"`, `"files_with_matches"` ou `"count"`. O padrão é `"files_with_matches"` |1983| `output_mode` | string | `"content"` | `"content"`, `"files_with_matches"` ou `"count"`. O padrão é `"files_with_matches"` |
1958| `-i` | boolean | `true` | Pesquisa sem diferenciar maiúsculas de minúsculas |1984| `-i` | boolean | `true` | Pesquisa sem diferenciar maiúsculas de minúsculas |
1959| `multiline` | boolean | `false` | Habilita correspondência em várias linhas |1985| `multiline` | boolean | `false` | Habilita a correspondência em várias linhas |
1960 1986
1961<h5 id="webfetch">1987<h5 id="webfetch">
1962 WebFetch1988 WebFetch
1966 1992
1967| Campo | Tipo | Exemplo | Descrição |1993| Campo | Tipo | Exemplo | Descrição |
1968| :- | :- | :- | :- |1994| :- | :- | :- | :- |
1969| `url` | string | `"https://example.com/api"` | URL de onde buscar o conteúdo |1995| `url` | string | `"https://example.com/api"` | URL da qual buscar o conteúdo |
1970| `prompt` | string | `"Extract the API endpoints"` | Prompt a ser executado sobre o conteúdo buscado |1996| `prompt` | string | `"Extract the API endpoints"` | Prompt a ser executado no conteúdo buscado |
1971| `offset` | number | `100000` | Número opcional de caracteres a pular a partir do início da página. O Claude o define para continuar lendo uma página longa. Exige o Claude Code v2.1.290 ou posterior |1997| `offset` | number | `100000` | Número opcional de caracteres a pular a partir do início da página. O Claude o define para continuar lendo uma página longa. Requer o Claude Code v2.1.290 ou posterior |
1972 1998
1973<h5 id="websearch">1999<h5 id="websearch">
1974 WebSearch2000 WebSearch
1999 2025
2000| Campo | Tipo | Exemplo | Descrição |2026| Campo | Tipo | Exemplo | Descrição |
2001| :- | :- | :- | :- |2027| :- | :- | :- | :- |
2002| `status` | string | `"completed"` | `"completed"` para subagentes em primeiro plano, `"async_launched"` para subagentes em segundo plano. Subagentes são executados em segundo plano por padrão, portanto uma chamada Agent que omite `run_in_background` também produz `"async_launched"` |2028| `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, portanto uma chamada Agent que omite `run_in_background` também produz `"async_launched"` |
2003| `agentId` | string | `"a4d2c8f1e0b3a297"` | Identificador da execução do subagente |2029| `agentId` | string | `"a4d2c8f1e0b3a297"` | Identificador da execução do subagente |
2004| `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 |2030| `content` | array | `[{"type": "text", "text": "Found 12 endpoints..."}]` | Os blocos de texto finais do subagente ou, para um subagente cujo relatório passa pelo `SubagentHandback`, uma nota curta sobre essa entrega no lugar deles |
2005| `resolvedModel` | string | `"claude-sonnet-4-5"` | Modelo com o qual o subagente começou, que pode ser diferente do modelo solicitado |2031| `resolvedModel` | string | `"claude-sonnet-4-5"` | Modelo com o qual o subagente começou, que pode ser diferente do modelo solicitado |
2006| `modelsUsed` | array | `["claude-sonnet-4-5", "claude-haiku-4-5"]` | Modelos usados em ordem, com repetições consecutivas condensadas; definido apenas quando o modelo foi trocado no meio da execução. Exige o Claude Code v2.1.212 ou posterior |2032| `modelsUsed` | array | `["claude-sonnet-4-5", "claude-haiku-4-5"]` | Modelos usados em ordem, com repetições consecutivas agrupadas; definido somente quando o modelo foi trocado no meio da execução. Requer o Claude Code v2.1.212 ou posterior |
2007| `totalTokens` | number | `12450` | Contagem de tokens da requisição final à API do subagente: tokens de entrada, saída e cache combinados. Isso não é um total de toda a execução |2033| `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 |
2008| `totalDurationMs` | number | `48211` | Duração em tempo real da execução do subagente |2034| `totalDurationMs` | number | `48211` | Duração em tempo real da execução do subagente |
2009| `totalToolUseCount` | number | `7` | Contagem de chamadas de ferramenta que o subagente fez |2035| `totalToolUseCount` | number | `7` | Quantidade de chamadas de ferramenta que o subagente fez |
2010| `usage` | object | `{"input_tokens": 8320, ...}` | Detalhamento de tokens por tipo da requisição final à API: `input_tokens`, `output_tokens`, `cache_creation_input_tokens`, `cache_read_input_tokens` |2036| `usage` | object | `{"input_tokens": 8320, ...}` | Detalhamento por tipo dos tokens da requisição final de API: `input_tokens`, `output_tokens`, `cache_creation_input_tokens`, `cache_read_input_tokens` |
2011 2037
2012No Claude Code v2.1.271 ou posterior, um subagente 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, configure um hook `PreToolUse` ou `PostToolUse` com matcher em `SubagentHandback` e leia `tool_input.message`.2038No Claude Code v2.1.271 ou posterior, um subagente 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` de 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` com `SubagentHandback` e leia `tool_input.message`.
2013 2039
2014Para subagentes em segundo plano, a ferramenta retorna quando a tarefa passa para o segundo plano, portanto `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`.2040Para subagentes em segundo plano, a ferramenta retorna quando a tarefa passa para o segundo plano, portanto `tool_response` não carrega campos de uso: um lançamento 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. Ele tem `status: "async_launched"`, `agentId`, `description`, `prompt`, `outputFile` e `resolvedModel`.
2015 2041
2016Em 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 ocorrida antes disso é refletida ali. `modelsUsed` e o comportamento de `resolvedModel` no momento da passagem para segundo plano exigem o Claude Code v2.1.212 ou posterior.2042Em uma resposta `completed`, `resolvedModel` indica 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` indica o modelo em uso quando o agente passou para o segundo plano, de modo que uma troca ocorrida antes disso é refletida ali. `modelsUsed` e o comportamento de `resolvedModel` no momento da passagem para o segundo plano requerem o Claude Code v2.1.212 ou posterior.
2017 2043
2018<a id="askuserquestion" />2044<a id="askuserquestion" />
2019 2045
2025 2051
2026| Campo | Tipo | Exemplo | Descrição |2052| Campo | Tipo | Exemplo | Descrição |
2027| :- | :- | :- | :- |2053| :- | :- | :- | :- |
2028| `questions` | array | `[{"question": "Which framework?", "header": "Framework", "options": [{"label": "React", "description": "Component library"}, {"label": "Vue", "description": "Progressive framework"}], "multiSelect": false}]` | Perguntas a apresentar, cada uma com uma string `question`, um `header` curto, um array `options` e uma flag `multiSelect` opcional |2054| `questions` | array | `[{"question": "Which framework?", "header": "Framework", "options": [{"label": "React", "description": "Component library"}, {"label": "Vue", "description": "Progressive framework"}], "multiSelect": false}]` | Perguntas a serem apresentadas, cada uma com uma string `question`, um `header` curto, um array `options` e uma flag `multiSelect` opcional |
2029| `answers` | object | `{"Which framework?": "React"}` | Opcional. Mapeia o texto da pergunta para o rótulo da opção selecionada. Respostas de múltipla seleção unem os rótulos com vírgulas. O Claude não define este campo; forneça-o via `updatedInput` para responder programaticamente |2055| `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 esse campo; forneça-o via `updatedInput` para responder programaticamente |
2030 2056
2031<h5 id="exitplanmode">2057<h5 id="exitplanmode">
2032 ExitPlanMode2058 ExitPlanMode
2033</h5>2059</h5>
2034 2060
2035Apresenta um plano e pede ao usuário que o aprove antes de o Claude sair 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, portanto 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 para os hooks.2061Apresenta um plano e pede ao usuário que o aprove antes de o Claude sair 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, portanto o `tool_input` literal do modelo normalmente está vazio. O Claude Code injeta o conteúdo do plano e o caminho do arquivo antes de passar a entrada para os hooks.
2036 2062
2037| Campo | Tipo | Exemplo | Descrição |2063| Campo | Tipo | Exemplo | Descrição |
2038| :- | :- | :- | :- |2064| :- | :- | :- | :- |
2039| `plan` | string | `"## Refactor auth\n1. Extract..."` | Conteúdo do plano em Markdown. Injetado a partir do arquivo de plano no disco |2065| `plan` | string | `"## Refactor auth\n1. Extract..."` | Conteúdo do plano em Markdown. Injetado a partir do arquivo do plano no disco |
2040| `planFilePath` | string | `"/Users/.../plans/refactor-auth.md"` | Caminho para o arquivo de plano. Injetado |2066| `planFilePath` | string | `"/Users/.../plans/refactor-auth.md"` | Caminho para o arquivo do plano. Injetado |
2041| `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 |2067| `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 |
2042 2068
2043No `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 do disco novamente.2069No `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 novamente o arquivo do disco.
2044 2070
2045<h4 id="pretooluse-decision-control">2071<h4 id="pretooluse-decision-control">
2046 Controle de decisão do PreToolUse2072 Controle de decisão do PreToolUse
2047</h4>2073</h4>
2048 2074
2049Os hooks `PreToolUse` podem controlar se uma chamada de ferramenta prossegue. Ao contrário 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 (permitir, negar, pedir confirmação ou adiar) e a capacidade de modificar a entrada da ferramenta antes da execução.2075Os 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.
2050 2076
2051| Campo | Descrição |2077| Campo | Descrição |
2052| :- | :- |2078| :- | :- |
2053| `permissionDecision` | `"allow"` ignora o prompt de permissão, exceto para as [ações que nenhum modo aprova automaticamente](/docs/pt/permission-modes#actions-no-mode-auto-approves), para [leituras de caminhos de rede](/docs/pt/permissions#network-paths) e para `AskUserQuestion` e `ExitPlanMode`, que precisam de [`updatedInput` combinado com ele](#allow-with-updatedinput). `"deny"` impede a chamada de ferramenta. `"ask"` pede ao usuário que confirme. `"defer"` sai de forma controlada para que a ferramenta possa ser retomada mais tarde. As [regras de negação e de confirmação](/docs/pt/permissions#manage-permissions) ainda são avaliadas independentemente do que o hook retorne |2079| `permissionDecision` | `"allow"` ignora o prompt de permissão, exceto para as [ações que nenhum modo aprova automaticamente](/docs/pt/permission-modes#actions-no-mode-auto-approves), para [leituras de caminhos de rede](/docs/pt/permissions#network-paths) e para `AskUserQuestion` e `ExitPlanMode`, que precisam de [`updatedInput` associado a ele](#allow-with-updatedinput). `"deny"` impede a chamada de ferramenta. `"ask"` pede ao usuário que confirme. `"defer"` sai de forma controlada para que a ferramenta possa ser retomada mais tarde. As [regras de negação e de pergunta](/docs/pt/permissions#manage-permissions) ainda são avaliadas independentemente do que o hook retorna |
2054| `permissionDecisionReason` | Para `"ask"`, mostrado ao usuário no prompt de permissão. Quando o Claude Code [nega a chamada](/docs/pt/headless#turn-off-permission-prompts-in-unattended-runs) em uma execução `-p` em que ninguém pode responder a esse prompt, o Claude lê o motivo no resultado da ferramenta. Para `"deny"`, mostrado ao Claude. Para `"allow"` e `"defer"`, gravado apenas no [log de depuração](#debug-hooks) |2080| `permissionDecisionReason` | Para `"ask"`, mostrado ao usuário no prompt de permissão. Quando o Claude Code [nega a chamada](/docs/pt/headless#turn-off-permission-prompts-in-unattended-runs) em uma execução `-p` em que ninguém pode responder a esse prompt, o Claude lê o motivo no resultado da ferramenta. Para `"deny"`, mostrado ao Claude. Para `"allow"` e `"defer"`, gravado apenas no [log de depuração](#debug-hooks) |
2055| `updatedInput` | Modifica os parâmetros de entrada da ferramenta antes da execução. Substitui todo o objeto de entrada, portanto inclua os campos inalterados junto com os modificados. O Claude Code avalia as regras de permissão e a [elegibilidade para segundo plano automático](/docs/pt/tools-reference#foreground-commands-that-move-to-the-background) de um comando Bash com base na entrada que seu hook retorna, não na entrada que o Claude enviou. Combine com `"allow"` para aprovar automaticamente, ou com `"ask"` para mostrar a entrada modificada ao usuário. Para `"defer"`, é ignorado |2081| `updatedInput` | Modifica os parâmetros de entrada da ferramenta antes da execução. Substitui o objeto de entrada inteiro, portanto inclua os campos inalterados junto com os modificados. O Claude Code avalia as regras de permissão e a [elegibilidade para segundo plano automático](/docs/pt/tools-reference#foreground-commands-that-move-to-the-background) de um comando Bash com base na entrada que seu hook retorna, 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 |
2056| `additionalContext` | String adicionada ao contexto do Claude junto com o resultado da ferramenta. Ignorada quando `permissionDecision` é `"defer"`. Consulte [Adicionar contexto para o Claude](#add-context-for-claude) |2082| `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) |
2057 2083
2058Quando vários hooks PreToolUse retornam decisões diferentes, a precedência é `deny` > `defer` > `ask` > `allow`.2084Quando vários hooks PreToolUse retornam decisões diferentes, a precedência é `deny` > `defer` > `ask` > `allow`.
2059 2085
2060Um hook que bloqueia saindo com 2 é tratado da mesma forma que `"deny"`: o Claude vê a mensagem do stderr como o motivo da negação.2086Um 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.
2061 2087
2062Quando 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.2088Quando um hook retorna `"ask"`, o prompt de permissão exibido ao usuário inclui um rótulo que identifica de onde o hook veio: `[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.
2063 2089
2064Um `"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 que o hook solicitou; o classificador ainda aplicava suas próprias regras de segurança a esse comando, e um `"deny"` de hook sempre era respeitado.2090O `"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 que o hook solicitou; o classificador ainda aplicava suas próprias regras de segurança a esse comando, e um `"deny"` de hook sempre era respeitado.
2065 2091
2066```json theme={null}2092```json theme={null}
2067{2093{
2078```2104```
2079 2105
2080<Note>2106<Note>
2081 O PreToolUse usava anteriormente os campos `decision` e `reason` de nível superior, mas eles estão descontinuados para este evento. Use `hookSpecificOutput.permissionDecision` e `hookSpecificOutput.permissionDecisionReason` em vez disso. Os valores descontinuados `"approve"` e `"block"` são mapeados para `"allow"` e `"deny"`, respectivamente. Outros eventos, como PostToolUse e Stop, continuam usando `decision` e `reason` de nível superior como seu formato atual.2107 O PreToolUse usava anteriormente os campos de nível superior `decision` e `reason`, mas eles estão descontinuados para esse 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 a usar `decision` e `reason` de nível superior como seu formato atual.
2082</Note>2108</Note>
2083 2109
2084<h4 id="allow-with-updatedinput">2110<h4 id="allow-with-updatedinput">
2085 Ferramentas que exigem interação do usuário2111 Ferramentas que exigem interação do usuário
2086</h4>2112</h4>
2087 2113
2088`AskUserQuestion` e `ExitPlanMode` exigem interação do usuário. No [modo não interativo](/docs/pt/headless) com a flag `-p`, o Claude Code as oferece 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.2114`AskUserQuestion` e `ExitPlanMode` exigem interação do usuário. No [modo não interativo](/docs/pt/headless) com a flag `-p`, o Claude Code as oferece 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.
2089 2115
2090Um hook `PreToolUse` satisfaz esse requisito quando faz o seguinte:2116Um hook `PreToolUse` satisfaz esse requisito quando faz o seguinte:
2091 2117
20921. Lê a entrada da ferramenta do stdin21181. Lê a entrada da ferramenta do stdin
20932. Coleta a resposta por meio da sua própria interface21192. Coleta a resposta por meio da sua própria interface
20943. Retorna `permissionDecision: "allow"` junto com `updatedInput` contendo a resposta, para que a ferramenta seja executada sem solicitar confirmação21203. Retorna `permissionDecision: "allow"` junto com um `updatedInput` que contém a resposta, para que a ferramenta seja executada sem solicitar confirmação
2095 2121
2096Retornar apenas `"allow"` não é suficiente para essas ferramentas.2122Retornar apenas `"allow"` não é suficiente para essas ferramentas.
2097 2123
2117}2143}
2118```2144```
2119 2145
2120Uma 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 pode confirmar que o hook coletou a interação de que a ferramenta precisa.2146Uma ferramenta MCP que seu servidor marca com [`_meta["anthropic/requiresUserInteraction"]`](/docs/pt/mcp#require-approval-for-a-specific-tool) é mais restrita: um hook não pode ignorar seu prompt de aprovação com `"allow"`, com ou sem `updatedInput`, porque o Claude Code não pode confirmar que o hook coletou a interação de que a ferramenta precisa.
2121 2147
2122<h4 id="defer-a-tool-call-for-later">2148<h4 id="defer-a-tool-call-for-later">
2123 Adiar uma chamada de ferramenta para depois2149 Adiar uma chamada de ferramenta para mais tarde
2124</h4>2150</h4>
2125 2151
2126`"defer"` é para integrações que executam `claude -p` como subprocesso e leem sua saída JSON, como um app do Agent SDK ou uma interface 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 de sua própria interface e retome de onde parou. O Claude Code respeita esse valor apenas 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.2152`"defer"` destina-se a integrações que executam `claude -p` como subprocesso e leem sua saída JSON, como um aplicativo do Agent SDK ou uma interface 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 de sua própria interface e retome de onde parou. O Claude Code respeita esse valor somente no [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.
2127 2153
2128A 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` 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`, portanto inicie a execução com um. O ciclo completo funciona assim:2154A 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`, portanto inicie a execução com um. O ciclo funciona assim:
2129 2155
21301. O Claude chama `AskUserQuestion`. O hook `PreToolUse` é disparado.21561. O Claude chama `AskUserQuestion`. O hook `PreToolUse` é disparado.
21312. 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.21572. 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.
21323. O processo chamador lê `deferred_tool_use` do resultado do SDK, apresenta a pergunta em sua própria interface e aguarda uma resposta.21583. O processo chamador lê `deferred_tool_use` do resultado do SDK, exibe a pergunta em sua própria interface e aguarda uma resposta.
21334. 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.21594. 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.
21345. O hook retorna `permissionDecision: "allow"` com a resposta em `updatedInput`. A ferramenta é executada e o Claude continua.21605. O hook retorna `permissionDecision: "allow"` com a resposta em `updatedInput`. A ferramenta é executada e o Claude continua.
2135 2161
2149}2175}
2150```2176```
2151 2177
2152Não há timeout nem limite de novas 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 da 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 chamador controla quando interromper o loop, retornando eventualmente `"allow"` ou `"deny"` a partir do hook.2178Não há timeout nem limite de novas tentativas. A sessão permanece no disco até você retomá-la, sujeita à limpeza de retenção de [`cleanupPeriodDays`](/docs/pt/settings-reference#cleanupperioddays), que exclui arquivos de sessão após 30 dias por padrão, seguindo as [regras da 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 ciclo, retornando eventualmente `"allow"` ou `"deny"` do hook.
2153 2179
2154`"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ão. A restrição existe porque a retomada só pode reexecutar uma ferramenta: não há como adiar uma chamada de um lote sem deixar as outras sem resolução.2180`"defer"` só funciona quando o Claude faz uma única chamada de ferramenta no turno. Se o Claude fizer várias chamadas de ferramenta ao mesmo tempo, `"defer"` é ignorado com um aviso e a ferramenta prossegue pelo fluxo normal de permissão. 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.
2155 2181
2156Se a ferramenta adiada não estiver mais disponível quando você retomar, o processo sai com `stop_reason: "tool_deferred_unavailable"` e `is_error: true` antes de o hook ser disparado. Isso acontece quando um servidor MCP que fornecia a ferramenta não está conectado na sessão retomada. O payload `deferred_tool_use` ainda é incluído para que você possa identificar qual ferramenta ficou indisponível.2182Se a ferramenta adiada não estiver mais disponível quando você retomar, o processo sai com `stop_reason: "tool_deferred_unavailable"` e `is_error: true` antes de o hook ser disparado. Isso acontece quando um servidor MCP que fornecia a ferramenta não está conectado na sessão retomada. O payload `deferred_tool_use` ainda é incluído para que você possa identificar qual ferramenta ficou indisponível.
2157 2183
2158<Note>2184<Note>
2159 Para retomar uma sessão adiada no modo de planejamento, passe [`--permission-prompt-tool`](/docs/pt/cli-reference#cli-flags) junto com `--resume` para que o Claude Code possa apresentar o plano para aprovação. Para as demais condições, consulte [Retomar no modo de planejamento com `-p`](/docs/pt/sessions#resume-in-plan-mode-with-p). Requer o Claude Code v2.1.246 ou posterior.2185 Para retomar uma sessão adiada no modo de planejamento, passe [`--permission-prompt-tool`](/docs/pt/cli-reference#cli-flags) junto com `--resume` para que o Claude Code possa apresentar o plano para aprovação. Para as demais condições, consulte [Retomar no modo de planejamento com `-p`](/docs/pt/sessions#resume-in-plan-mode-with-p). Requer o Claude Code v2.1.246 ou posterior.
2160 2186
2161 Quando você retoma com `-p`, o Claude Code não restaura nenhum outro modo de permissão armazenado. Ele inicia a execução no modo de permissão em que uma nova execução `claude -p` iniciaria, portanto passe `--permission-mode` ou `--dangerously-skip-permissions` novamente se a sessão adiada usava um deles. Quando você retoma com `claude --resume <session-id>` sem `-p`, o Claude Code restaura o modo de permissão armazenado, com as exceções listadas em [modo de permissão na retomada](/docs/pt/sessions#permission-mode-on-resume).2187 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` começaria, portanto passe `--permission-mode` ou `--dangerously-skip-permissions` novamente se a sessão adiada usava um deles. Quando você retoma com `claude --resume <session-id>` sem `-p`, o Claude Code restaura o modo de permissão armazenado, com as exceções listadas em [modo de permissão na retomada](/docs/pt/sessions#permission-mode-on-resume).
2162</Note>2188</Note>
2163 2189
2164<h3 id="permissionrequest">2190<h3 id="permissionrequest">
2165 PermissionRequest2191 PermissionRequest
2166</h3>2192</h3>
2167 2193
2168É 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, 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 seu host, e vale a decisão de quem decidir primeiro.2194É 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, 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 vale a decisão de quem decidir primeiro.
2169Use o [controle de decisão do PermissionRequest](#permissionrequest-decision-control) para permitir ou negar em nome do usuário.2195Use o [controle de decisão do PermissionRequest](#permissionrequest-decision-control) para permitir ou negar em nome do usuário.
2170 2196
2171Use 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 aguardou cerca de seis segundos.2197Use esse 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 fica aguardando por cerca de seis segundos.
2172 2198
2173O 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`.2199O 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`.
2174 2200
2175Faz correspondência com o nome da ferramenta, com os mesmos valores do PreToolUse.2201Faz a correspondência com o nome da ferramenta, com os mesmos valores do PreToolUse.
2176 2202
2177<h4 id="permissionrequest-input">2203<h4 id="permissionrequest-input">
2178 Entrada do PermissionRequest2204 Entrada do PermissionRequest
2179</h4>2205</h4>
2180 2206
2181Os 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 de permissão ou alterar o modo de permissão.2207Os 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 essa requisição, como adicionar uma regra de permissão allow ou alterar o modo de permissão.
2182 2208
2183O 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ção de arquivos, não leem o array e derivam suas opções da própria solicitação. Um diálogo que o lê ainda pode ocultar 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.2209O array `permission_suggestions` não é uma lista exata das opções que você vê, porque cada diálogo de permissão monta as próprias opções. Alguns diálogos, como o de edições de arquivo, não leem o array e derivam suas opções da própria requisiçã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 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.
2184 2210
2185Os hooks PreToolUse são executados antes de toda chamada de ferramenta, precise ela de permissão ou não. Os hooks PermissionRequest são executados apenas quando o Claude Code está prestes a pedir sua permissão, ou quando ele negaria automaticamente uma chamada que não pode solicitar confirmação. Nenhum dos dois eventos é disparado para [`EndConversation`](/docs/pt/tools-reference#endconversation-tool-behavior).2211Os 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 apenas quando o Claude Code está prestes a pedir sua permissão, ou quando, de outra forma, negaria automaticamente uma chamada que não pode solicitar confirmação. Nenhum dos dois eventos é disparado para [`EndConversation`](/docs/pt/tools-reference#endconversation-tool-behavior).
2186 2212
2187```json theme={null}2213```json theme={null}
2188{2214{
2211 Controle de decisão do PermissionRequest2237 Controle de decisão do PermissionRequest
2212</h4>2238</h4>
2213 2239
2214Os 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:2240Os hooks `PermissionRequest` podem permitir ou negar requisiçõ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:
2215 2241
2216| Campo | Descrição |2242| Campo | Descrição |
2217| :- | :- |2243| :- | :- |
2218| `behavior` | `"allow"` concede a permissão, `"deny"` a nega. [Regras de negação e de confirmação](/docs/pt/permissions#manage-permissions) ainda são avaliadas, portanto um hook que retorna `"allow"` não sobrescreve uma regra de negação correspondente |2244| `behavior` | `"allow"` concede a permissão, `"deny"` a nega. [Regras deny e ask](/docs/pt/permissions#manage-permissions) ainda são avaliadas, portanto um hook que retorna `"allow"` não sobrescreve uma regra deny correspondente |
2219| `updatedInput` | Apenas para `"allow"`: modifica os parâmetros de entrada da ferramenta antes da execução. Substitui todo o objeto de entrada, portanto inclua os campos inalterados junto com os modificados. A entrada modificada é reavaliada com base nas regras de negação e de confirmação |2245| `updatedInput` | Apenas para `"allow"`: modifica os parâmetros de entrada da ferramenta antes da execução. Substitui o objeto de entrada inteiro, então inclua os campos inalterados junto com os modificados. A entrada modificada é reavaliada em relação às regras deny e ask |
2220| `updatedPermissions` | Apenas para `"allow"`: array de [entradas de atualização de permissão](#permission-update-entries) a aplicar, como adicionar uma regra de permissão ou alterar o modo de permissão da sessão |2246| `updatedPermissions` | Apenas para `"allow"`: array de [entradas de atualização de permissão](#permission-update-entries) a aplicar, como adicionar uma regra allow ou alterar o modo de permissão da sessão |
2221| `message` | Apenas para `"deny"`: informa ao Claude por que a permissão foi negada |2247| `message` | Apenas para `"deny"`: informa ao Claude por que a permissão foi negada |
2222| `interrupt` | Apenas para `"deny"`: se `true`, interrompe o Claude |2248| `interrupt` | Apenas para `"deny"`: se `true`, interrompe o Claude |
2223 2249
2224Um hook que sai com código 2 sem um objeto `decision` deixa o fluxo de permissão inalterado, e seu stderr é descartado. Para conceder ou negar a solicitação, retorne o objeto `decision`.2250Um hook que sai com código 2 sem um objeto `decision` deixa o fluxo de permissão inalterado, e seu stderr é descartado. Para conceder ou negar a requisição, retorne o objeto `decision`.
2225 2251
2226```json theme={null}2252```json theme={null}
2227{2253{
2241 Entradas de atualização de permissão2267 Entradas de atualização de permissão
2242</h4>2268</h4>
2243 2269
2244O 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.2270O 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.
2245 2271
2246| `type` | Campos | Efeito |2272| `type` | Campos | Efeito |
2247| :- | :- | :- |2273| :- | :- | :- |
2248| `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"` |2274| `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"` |
2249| `replaceRules` | `rules`, `behavior`, `destination` | Substitui todas as regras do `behavior` informado no `destination` pelas `rules` fornecidas |2275| `replaceRules` | `rules`, `behavior`, `destination` | Substitui todas as regras do `behavior` informado no `destination` pelas `rules` fornecidas |
2250| `removeRules` | `rules`, `behavior`, `destination` | Remove as regras correspondentes do `behavior` informado |2276| `removeRules` | `rules`, `behavior`, `destination` | Remove as regras correspondentes do `behavior` informado |
2251| `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` |2277| `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 para `default` |
2252| `addDirectories` | `directories`, `destination` | Adiciona diretórios de trabalho. `directories` é um array de strings de caminho |2278| `addDirectories` | `directories`, `destination` | Adiciona diretórios de trabalho. `directories` é um array de strings de caminho |
2253| `removeDirectories` | `directories`, `destination` | Remove diretórios de trabalho |2279| `removeDirectories` | `directories`, `destination` | Remove diretórios de trabalho |
2254 2280
2275 2301
2276É executado imediatamente após uma ferramenta ser concluída com sucesso.2302É executado imediatamente após uma ferramenta ser concluída com sucesso.
2277 2303
2278Faz correspondência pelo nome da ferramenta, com os mesmos valores de PreToolUse.2304Corresponde ao nome da ferramenta, com os mesmos valores do PreToolUse.
2279 2305
2280Faça uma correspondência mais ampla quando o nome da ferramenta não for o filtro certo:2306Use uma correspondência mais ampla quando o nome da ferramenta não for o filtro certo:
2281 2307
2282* 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` deixa passar. Para chamadas de ferramenta que falham, adicione o mesmo hook em [PostToolUseFailure](#posttoolusefailure).2308* Para executar um hook depois que qualquer ferramenta for 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 `git diff` não mostra. Para chamadas de ferramenta que falham, adicione o mesmo hook em [PostToolUseFailure](#posttoolusefailure).
2283* Para executar um hook quando um arquivo específico mudar no disco, independentemente do que 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.2309* 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` com matcher `Edit|Write` quando um comando `Bash` ou um processo fora do Claude Code reescreve o mesmo arquivo.
2284 2310
2285<h4 id="posttooluse-input">2311<h4 id="posttooluse-input">
2286 Entrada de PostToolUse2312 Entrada do PostToolUse
2287</h4>2313</h4>
2288 2314
2289Os 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` das ferramentas de arquivo chegam no mesmo formato que em [PreToolUse](#pretooluse-input): sempre absolutos, com os separadores nativos da plataforma, ou seja, barras invertidas no Windows. Para uma ferramenta MCP, a entrada também traz o objeto [`mcp_server`](#pretooluse-input).2315Os 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 no [PreToolUse](#pretooluse-input): sempre absolutos, com os separadores nativos da plataforma, ou seja, barras invertidas no Windows. Para uma ferramenta MCP, a entrada também traz o objeto [`mcp_server`](#pretooluse-input).
2290 2316
2291```json theme={null}2317```json theme={null}
2292{2318{
2314| `duration_ms` | Opcional. Tempo de execução da ferramenta em milissegundos. Exclui o tempo gasto em prompts de permissão e em hooks PreToolUse |2340| `duration_ms` | Opcional. Tempo de execução da ferramenta em milissegundos. Exclui o tempo gasto em prompts de permissão e em hooks PreToolUse |
2315 2341
2316<h4 id="posttooluse-decision-control">2342<h4 id="posttooluse-decision-control">
2317 Controle de decisão de PostToolUse2343 Controle de decisão do PostToolUse
2318</h4>2344</h4>
2319 2345
2320Os 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:2346Os 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:
2346```2372```
2347 2373
2348<Warning>2374<Warning>
2349 `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á tiveram efeito. A telemetria, como spans de ferramenta do OpenTelemetry e eventos de analytics, também captura a saída original antes de o hook ser executado. Para impedir ou modificar uma chamada de ferramenta antes que ela seja executada, use um hook [PreToolUse](#pretooluse).2375 `updatedToolOutput` altera apenas o que o Claude vê. A ferramenta já foi executada quando o hook é disparado, então quaisquer arquivos gravados, comandos executados ou requisições de rede enviadas já surtiram efeito. A telemetria, como spans de ferramenta do OpenTelemetry e eventos de analytics, também captura a saída original antes de o hook ser executado. Para impedir ou modificar uma chamada de ferramenta antes que ela seja executada, use um hook [PreToolUse](#pretooluse).
2350 2376
2351 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 corresponda 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 fazer com que ele prossiga com base em uma suposição falsa.2377 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 fazer com que ele prossiga com base em uma suposição falsa.
2352</Warning>2378</Warning>
2353 2379
2354<h4 id="annotate-a-result-for-the-auto-mode-classifier">2380<h4 id="annotate-a-result-for-the-auto-mode-classifier">
2355 Anotar um resultado para o classificador do modo auto2381 Anotar um resultado para o classificador do modo auto
2356</h4>2382</h4>
2357 2383
2358Retorne `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 informar algo sobre o que uma chamada retornou antes que ele revise ações posteriores. O campo requer Claude Code v2.1.236 ou posterior.2384Retorne `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 informar algo sobre o que uma chamada retornou antes que ele revise as ações seguintes. O campo requer Claude Code v2.1.236 ou posterior.
2359 2385
2360O exemplo abaixo informa ao classificador de onde veio a saída de uma consulta:2386O exemplo abaixo informa ao classificador de onde veio a saída de uma consulta:
2361 2387
2370 2396
2371O peso que o classificador dá à nota depende de onde você configurou o hook:2397O peso que o classificador dá à nota depende de onde você configurou o hook:
2372 2398
2373* **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 em relação às suas próprias mensagens na conversa2399* **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 confere essa afirmação com suas próprias mensagens na conversa
2374* **Callbacks do Agent SDK em processo**: quando uma aplicação que incorpora o Claude Code registra o hook como um [callback do SDK em TypeScript](/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. Essa declaração pode satisfazer um requisito de consentimento que o classificador aceitaria de uma mensagem enviada por você, mas nunca suspende um bloqueio que sua própria mensagem também não conseguiria suspender. 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 verificada2400* **Callbacks do Agent SDK em processo**: 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 transmitida na nota como intenção do usuário. Essa declaração pode satisfazer um requisito de consentimento que o classificador aceitaria de uma mensagem enviada por você, mas nunca suspende um bloqueio que sua própria mensagem também não conseguiria suspender. Depois que uma sessão é retomada, o Claude Code trata as notas restauradas como contexto não verificado. Quando hooks dos dois grupos anotam a mesma chamada, o classificador trata a nota combinada como não verificada
2375 2401
2376O Claude Code aplica estes limites ao entregar a nota:2402O Claude Code aplica estes limites ao entregar a nota:
2377 2403
2378* **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 chamada2404* **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
2379* **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 ferramenta2405* **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
2380* **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 chamadas2406* **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
2381* **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ída2407* **Interação com reescritas**: quando a nota descreve uma saída que você está substituindo com `updatedToolOutput`, retorne os dois 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
2382 2408
2383<Warning>2409<Warning>
2384 O classificador lê o conteúdo que você coloca em `classifierContext` como informação da aplicação que hospeda a sessão, então não copie saídas de ferramentas não confiáveis nem textos de terceiros para ele. Limite a nota a uma afirmação curta sobre esta única 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.2410 O classificador lê o conteúdo que você coloca em `classifierContext` como informação vinda da aplicação que hospeda a sessão, portanto não copie saída de ferramenta não confiável nem texto de terceiros para ele. Mantenha a nota como uma afirmação curta sobre esta única 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.
2385</Warning>2411</Warning>
2386 2412
2387<h3 id="posttoolusefailure">2413<h3 id="posttoolusefailure">
2388 PostToolUseFailure2414 PostToolUseFailure
2389</h3>2415</h3>
2390 2416
2391É 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.2417É 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.
2392 2418
2393Faz correspondência pelo nome da ferramenta, com os mesmos valores de PreToolUse.2419Corresponde ao nome da ferramenta, com os mesmos valores do PreToolUse.
2394 2420
2395<Note>2421<Note>
2396 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 na validação 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 acontecem antes de os hooks serem executados, portanto não disparam nem `PreToolUse` nem `PostToolUseFailure`. As negações de permissão disparam `PreToolUse`, mas não este evento; consulte [PermissionDenied](#permissiondenied).2422 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 na validação 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 acontecem 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).
2397</Note>2423</Note>
2398 2424
2399<h4 id="posttoolusefailure-input">2425<h4 id="posttoolusefailure-input">
2400 Entrada de PostToolUseFailure2426 Entrada do PostToolUseFailure
2401</h4>2427</h4>
2402 2428
2403Os hooks 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` com falha poderia entregar:2429Os 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` que falhou pode entregar:
2404 2430
2405```json theme={null}2431```json theme={null}
2406{2432{
2424| Campo | Descrição |2450| Campo | Descrição |
2425| :- | :- |2451| :- | :- |
2426| `error` | String que descreve o que deu errado. O formato depende da ferramenta que falhou |2452| `error` | String que descreve o que deu errado. O formato depende da ferramenta que falhou |
2427| `is_interrupt` | Booleano opcional. Verdadeiro quando a falha chegou ao Claude Code como um aborto, 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 traz a mensagem de interrupção |2453| `is_interrupt` | Booleano opcional. Verdadeiro quando a falha chegou ao Claude Code como uma interrupção (abort), 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 traz a mensagem de interrupção |
2428| `duration_ms` | Opcional. Tempo de execução da ferramenta em milissegundos. Exclui o tempo gasto em prompts de permissão e em hooks PreToolUse |2454| `duration_ms` | Opcional. Tempo de execução da ferramenta em milissegundos. Exclui o tempo gasto em prompts de permissão e em hooks PreToolUse |
2429 2455
2430A string `error` geralmente é o mesmo texto que o Claude recebe como resultado da ferramenta com falha. 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.2456A 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, e não como um formato estável.
2431 2457
2432* 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 tenha produzido como um único bloco com stdout e stderr intercalados2458* 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
2433* Um payload também pode trazer apenas uma mensagem de falha sem linha de código de saída, quando o Claude Code não conseguiu iniciar o próprio processo do shell2459* Um payload também pode trazer uma mensagem de falha simples, sem a linha de código de saída, quando o Claude Code não conseguiu iniciar o próprio processo do shell
2434* 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`2460* 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`
2435 2461
2436<h4 id="posttoolusefailure-decision-control">2462<h4 id="posttoolusefailure-decision-control">
2437 Controle de decisão de PostToolUseFailure2463 Controle de decisão do PostToolUseFailure
2438</h4>2464</h4>
2439 2465
2440Os 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:2466Os hooks `PostToolUseFailure` podem fornecer contexto ao Claude após a falha de uma 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:
2441 2467
2442| Campo | Descrição |2468| Campo | Descrição |
2443| :- | :- |2469| :- | :- |
2456 PostToolBatch2482 PostToolBatch
2457</h3>2483</h3>
2458 2484
2459É executado uma vez depois que todas as chamadas de ferramenta de um lote foram resolvidas, antes que o Claude Code envie a próxima requisição ao modelo. `PostToolUse` é disparado uma vez por ferramenta, o que significa que é disparado de forma concorrente quando o Claude faz chamadas de ferramenta paralelas. `PostToolBatch` é disparado exatamente uma vez com o lote completo, então é 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.2485É 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 de forma concorrente quando o Claude faz chamadas de ferramenta em paralelo. `PostToolBatch` é disparado exatamente uma vez com o lote completo, então é o lugar certo para injetar contexto que depende do conjunto de ferramentas executadas, e não de uma ferramenta isolada. Não há matcher para este evento.
2460 2486
2461<h4 id="posttoolbatch-input">2487<h4 id="posttoolbatch-input">
2462 Entrada de PostToolBatch2488 Entrada do PostToolBatch
2463</h4>2489</h4>
2464 2490
2465Além dos [campos de entrada comuns](#common-input-fields), os hooks PostToolBatch recebem `tool_calls`, um array que descreve cada chamada de ferramenta do lote:2491Além dos [campos de entrada comuns](#common-input-fields), os hooks PostToolBatch recebem `tool_calls`, um array que descreve cada chamada de ferramenta do lote:
2491`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, e não o conteúdo bruto do arquivo. As respostas podem ser grandes, então analise apenas os campos de que você precisa.2517`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, e não o conteúdo bruto do arquivo. As respostas podem ser grandes, então analise apenas os campos de que você precisa.
2492 2518
2493<Note>2519<Note>
2494 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ê.2520 O formato de `tool_response` difere do de `PostToolUse`. `PostToolUse` repassa o objeto `Output` estruturado da ferramenta, como `{filePath: "...", type: "create"}` para `Write`; `PostToolBatch` repassa o conteúdo serializado de `tool_result` que o modelo vê.
2495</Note>2521</Note>
2496 2522
2497<h4 id="posttoolbatch-decision-control">2523<h4 id="posttoolbatch-decision-control">
2498 Controle de decisão de PostToolBatch2524 Controle de decisão do PostToolBatch
2499</h4>2525</h4>
2500 2526
2501Os 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:2527Os 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:
2502 2528
2503| Campo | Descrição |2529| Campo | Descrição |
2504| :- | :- |2530| :- | :- |
2505| `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 colocar nela e como as sessões retomadas lidam com valores anteriores |2531| `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 |
2506 2532
2507```json theme={null}2533```json theme={null}
2508{2534{
2513}2539}
2514```2540```
2515 2541
2516Retornar `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 do `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.2542Retornar `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 na saída com código 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.
2517 2543
2518<h3 id="permissiondenied">2544<h3 id="permissiondenied">
2519 PermissionDenied2545 PermissionDenied
2520</h3>2546</h3>
2521 2547
2522É 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 sua resposta 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.2548É 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 sua resposta não pôde ser analisada. Este hook só é disparado no modo auto: ele 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 em log, ajustar a configuração ou informar ao modelo que ele pode tentar novamente a chamada de ferramenta.
2523 2549
2524Faz correspondência pelo nome da ferramenta, com os mesmos valores de PreToolUse.2550Corresponde ao nome da ferramenta, com os mesmos valores do PreToolUse.
2525 2551
2526<h4 id="permissiondenied-input">2552<h4 id="permissiondenied-input">
2527 Entrada de PermissionDenied2553 Entrada do PermissionDenied
2528</h4>2554</h4>
2529 2555
2530Alé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).2556Alé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).
2551| `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 do classificador estava indisponível, é o texto fixo `Classifier unavailable` |2577| `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 do classificador estava indisponível, é o texto fixo `Classifier unavailable` |
2552 2578
2553<h4 id="permissiondenied-decision-control">2579<h4 id="permissiondenied-decision-control">
2554 Controle de decisão de PermissionDenied2580 Controle de decisão do PermissionDenied
2555</h4>2581</h4>
2556 2582
2557Os 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`:2583Os 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`:
2565}2591}
2566```2592```
2567 2593
2568Quando `retry` é `true`, o Claude Code adiciona uma mensagem à conversa informando ao modelo que ele pode tentar novamente a chamada de ferramenta. O Claude Code não reverte a negação em si. Se o seu hook não retornar JSON, ou retornar `retry: false`, a negação permanece e o modelo recebe a mensagem de rejeição original.2594Quando `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.
2569 2595
2570O 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.2596O 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 adiante.
2571 2597
2572<h3 id="notification">2598<h3 id="notification">
2573 Notification2599 Notification
2574</h3>2600</h3>
2575 2601
2576É 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.2602É executado quando o Claude Code envia notificações. Corresponde ao tipo de notificação. Omita o matcher para executar hooks para todos os tipos de notificação.
2577 2603
2578Você 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.2604Você 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, e não se o seu hook é executado.
2579 2605
2580| Matcher | Quando é disparado |2606| Matcher | Quando é disparado |
2581| :- | :- |2607| :- | :- |
2582| `permission_prompt` | O Claude precisa que você aprove o uso de uma ferramenta ou a [requisição de rede](/docs/pt/sandboxing#network-isolation) de um comando em sandbox, e o prompt está aguardando há cerca de seis segundos |2608| `permission_prompt` | O Claude precisa que você aprove um uso de ferramenta ou a [requisição de rede](/docs/pt/sandboxing#network-isolation) de um comando em sandbox, e o prompt está aguardando há cerca de seis segundos |
2583| `idle_prompt` | O Claude terminou de responder há cerca de 60 segundos e você não digitou nada desde então |2609| `idle_prompt` | O Claude terminou de responder há cerca de 60 segundos e você não digitou nada desde então |
2584| `auth_success` | A autenticação é concluída |2610| `auth_success` | A autenticação é concluída |
2585| `elicitation_dialog` | Um servidor MCP abre um formulário de elicitação e você não digita há cerca de seis segundos |2611| `elicitation_dialog` | Um servidor MCP abre um formulário de elicitação e você não digitou nada por cerca de seis segundos |
2586| `elicitation_url_dialog` | Um servidor MCP pede que você abra uma URL no navegador e você não digita há cerca de seis segundos |2612| `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 |
2587| `elicitation_complete` | Um servidor MCP informa que uma [elicitação no modo URL](#elicitation-input) foi concluída |2613| `elicitation_complete` | Um servidor MCP informa que uma [elicitação em modo URL](#elicitation-input) foi concluída |
2588| `elicitation_response` | Uma resposta de elicitação MCP é enviada de volta ao servidor |2614| `elicitation_response` | Uma resposta de elicitação MCP é enviada de volta ao servidor |
2589| `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 uma equipe de agentes](/docs/pt/agent-teams#choose-a-display-mode) ou o aviso do modo auto sobre [cobranças de requisições do classificador](/docs/pt/auto-mode-classifier-billing) e você não digita há cerca de seis segundos |2615| `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 do 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 de requisições do classificador](/docs/pt/auto-mode-classifier-billing) e você não digitou nada por cerca de seis segundos |
2590| `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 |2616| `agent_completed` | Uma sessão em segundo plano termina ou falha. É disparado apenas enquanto a [visualização de agentes](/docs/pt/agent-view) está aberta em um terminal |
2591| `quota_auto_resume_fired` | O Claude Code continua sua tarefa depois que um limite de uso do claude.ai a pausou: no momento da redefinição, ou antes disso 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) |2617| `quota_auto_resume_fired` | O Claude Code continua sua tarefa depois que um limite de uso do claude.ai a pausou: no momento da 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) |
2592| `quota_auto_resume_stale` | Um limite de uso do claude.ai foi redefinido enquanto seu computador ficou em suspensão por mais de cerca de 30 minutos. O Claude Code aguarda que você pressione `Enter` em vez de continuar. Após uma suspensão mais curta, ele continua e dispara `quota_auto_resume_fired` em vez disso |2618| `quota_auto_resume_stale` | Um limite de uso do claude.ai foi redefinido enquanto seu computador ficou 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` |
2593| `quota_auto_resume_disabled` | O Claude Code encerra a 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 foi adiada para mais de 24 horas 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** |2619| `quota_auto_resume_disabled` | O Claude Code encerra a 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 de distância 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** |
2594 2620
2595Os tipos `quota_auto_resume_fired`, `quota_auto_resume_stale` e `quota_auto_resume_disabled` requerem Claude Code v2.1.234 ou posterior.2621Os tipos `quota_auto_resume_fired`, `quota_auto_resume_stale` e `quota_auto_resume_disabled` requerem Claude Code v2.1.234 ou posterior.
2596 2622
2597Em 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.2623Em 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.
2598 2624
2599`agent_needs_input` para a pergunta de configuração de terminal de um colega requer Claude Code v2.1.248 ou posterior.2625`agent_needs_input` para a pergunta de configuração do terminal de um colega de equipe requer Claude Code v2.1.248 ou posterior.
2600 2626
2601<Note>2627<Note>
2602 Os tipos `permission_prompt`, `idle_prompt`, `elicitation_dialog` e `elicitation_url_dialog` compartilham o tempo com as notificações da área de trabalho, então, em sessões de terminal, você só os vê quando parece estar longe do terminal:2628 Os tipos `permission_prompt`, `idle_prompt`, `elicitation_dialog` e `elicitation_url_dialog` compartilham o mesmo timing das notificações da área de trabalho, então, em sessões de terminal, você só os vê quando parece estar longe do terminal:
2603 2629
2604 * Espere `permission_prompt` quando você não digitar 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 pedir permissão para usar uma ferramenta, use [PermissionRequest](#permissionrequest) em vez disso.2630 * Espere `permission_prompt` depois que você ficar cerca de seis segundos sem digitar. O cronômetro começa quando o prompt de permissão aparece, e cada tecla pressionada o adia. Para executar um hook imediatamente quando o Claude pedir permissão para usar uma ferramenta, use [PermissionRequest](#permissionrequest).
2605 * Espere `idle_prompt` cerca de 60 segundos depois que o Claude terminar de responder, e somente se você não tiver digitado 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 em vez disso.2631 * Espere `idle_prompt` cerca de 60 segundos depois que o Claude terminar de responder, e apenas 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 em seu lugar.
2606 * Espere `elicitation_dialog` para um formulário de elicitação, ou `elicitation_url_dialog` para uma solicitação de URL no navegador, quando você não digitar por cerca de seis segundos. Ambos compartilham o mesmo limite de seis segundos que `permission_prompt`: o temporizador começa quando a caixa de diálogo aparece, e cada tecla pressionada o adia.2632 * Espere `elicitation_dialog` para um formulário de elicitação, ou `elicitation_url_dialog` para uma requisição de URL no navegador, depois que você ficar cerca de seis segundos sem digitar. Ambos compartilham o mesmo limite de seis segundos do `permission_prompt`: o cronômetro começa quando o diálogo aparece, e cada tecla pressionada o adia.
2607 2633
2608 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.2634 Uma requisição de permissão ou elicitação que chega enquanto outro diálogo está na tela mantém o mesmo limite de seis segundos, contado a partir do momento em que a requisição chega. Sua notificação pode chegar a você enquanto a requisição ainda aguarda atrás do diálogo aberto.
2609</Note>2635</Note>
2610 2636
2611O Claude Code temporiza `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:2637O Claude Code calcula o timing de `permission_prompt` de forma diferente em sessões em que envia requisiçõ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:
2612 2638
2613* Espere `permission_prompt` cerca de seis segundos depois que o Claude pedir permissão. O Claude Code não o adia enquanto você digita.2639* Espere `permission_prompt` cerca de seis segundos depois que o Claude pedir permissão. O Claude Code não o adia enquanto você digita.
2614* Se você ou um hook [PermissionRequest](#permissionrequest) responder antes, o Claude Code não executa `permission_prompt`.2640* Se você ou um hook [PermissionRequest](#permissionrequest) responderem antes, o Claude Code não executa `permission_prompt`.
2615* Defina [`CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS`](/docs/pt/env-vars) como `1` para desativar `permission_prompt` nessas sessões.2641* Defina [`CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS`](/docs/pt/env-vars) como `1` para desativar `permission_prompt` nessas sessões.
2616 2642
2617Antes da v2.1.233, `permission_prompt` não era disparado nessas sessões.2643Antes da v2.1.233, `permission_prompt` não era disparado nessas sessões.
2646```2672```
2647 2673
2648<h4 id="notification-input">2674<h4 id="notification-input">
2649 Entrada de Notification2675 Entrada do Notification
2650</h4>2676</h4>
2651 2677
2652Alé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`, que indica qual tipo foi disparado.2678Alé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`, que indica qual tipo foi disparado.
2663}2689}
2664```2690```
2665 2691
2666Os 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 recurso em que o exemplo de notificação da área de trabalho se baseia. Os hooks Notification destinam-se a efeitos colaterais, como encaminhar a notificação a um serviço externo.2692Os 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 é do que o exemplo de notificação da área de trabalho depende. Os hooks Notification são destinados a efeitos colaterais, como encaminhar a notificação para um serviço externo.
2667 2693
2668<h3 id="subagentstart">2694<h3 id="subagentstart">
2669 SubagentStart2695 SubagentStart
2670</h3>2696</h3>
2671 2697
2672É 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 em processo de uma [equipe de agentes](/docs/pt/agent-teams) processa uma nova mensagem. Oferece suporte a 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.2698É executado quando o Claude inicia um subagente com a ferramenta Agent, quando o Claude [retoma um subagente](/docs/pt/sub-agents#resume-subagents) e cada vez que um colega de uma [equipe de agentes](/docs/pt/agent-teams) em processo lida com 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, e não o nome do arquivo.
2673 2699
2674Para subagentes distribuídos por um [plugin](/docs/pt/plugins/overview), o tipo de agente é o identificador com escopo de plugin, como `my-plugin:reviewer`, e não o nome simples do frontmatter. Os dois-pontos colocam um nome com escopo de plugin no caminho de expressão regular, então ancore o matcher com `^` e `$` para uma correspondência exata: `^my-plugin:reviewer$`.2700Para subagentes fornecidos por um [plugin](/docs/pt/plugins/overview), o tipo de agente é o identificador com escopo de plugin, como `my-plugin:reviewer`, e não o nome simples do frontmatter. Os dois-pontos colocam um nome com escopo de plugin no caminho de expressão regular, então ancore o matcher com `^` e `$` para uma correspondência exata: `^my-plugin:reviewer$`.
2675 2701
2676<h4 id="subagentstart-input">2702<h4 id="subagentstart-input">
2677 Entrada de SubagentStart2703 Entrada do SubagentStart
2678</h4>2704</h4>
2679 2705
2680Além dos [campos de entrada comuns](#common-input-fields), os hooks SubagentStart recebem `agent_id` com o identificador exclusivo do subagente e `agent_type` com o nome do agente pelo qual o matcher filtra.2706Alé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 usado pelo filtro do matcher.
2681 2707
2682```json theme={null}2708```json theme={null}
2683{2709{
2694 2720
2695| Campo | Descrição |2721| Campo | Descrição |
2696| :- | :- |2722| :- | :- |
2697| `additionalContext` | String adicionada ao contexto do subagente no início de sua conversa, antes do seu primeiro prompt. Consulte [Adicionar contexto para o Claude](#add-context-for-claude) |2723| `additionalContext` | String adicionada ao contexto do subagente no início da conversa, antes do primeiro prompt. Consulte [Adicionar contexto para o Claude](#add-context-for-claude) |
2698 2724
2699```json theme={null}2725```json theme={null}
2700{2726{
2705}2731}
2706```2732```
2707 2733
2708Quando 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 execução seguinte.2734Quando o hook é executado novamente para o mesmo subagente, o Claude Code injeta o contexto retornado apenas 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.
2709 2735
2710<h3 id="subagentstop">2736<h3 id="subagentstop">
2711 SubagentStop2737 SubagentStop
2712</h3>2738</h3>
2713 2739
2714É executado quando um subagente do Claude Code termina de responder. Faz correspondência pelo tipo de agente, com os mesmos valores de SubagentStart.2740É executado quando um subagente do Claude Code termina de responder. Corresponde ao tipo de agente, com os mesmos valores do SubagentStart.
2715 2741
2716<h4 id="subagentstop-input">2742<h4 id="subagentstop-input">
2717 Entrada de SubagentStop2743 Entrada do SubagentStop
2718</h4>2744</h4>
2719 2745
2720Alé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.2746Alé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.
2721 2747
2722Nem 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 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.2748Nem todo evento SubagentStop vem de um subagente iniciado 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 que 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.
2723 2749
2724Um `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.2750Um `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.
2725 2751
2726No Claude Code v2.1.271 ou posterior, um subagente que é 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` então contém 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`.2752No Claude Code v2.1.271 ou posterior, um subagente que é 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` então contém 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 matcher em `SubagentHandback` recebe como `tool_input.message`.
2727 2753
2728Os hooks SubagentStop também recebem os arrays `background_tasks` e `session_crons` descritos em [Entrada de Stop](#stop-input). Ambos os arrays têm escopo na sessão pai, não no subagente.2754Os hooks SubagentStop também recebem os arrays `background_tasks` e `session_crons` descritos em [Entrada do Stop](#stop-input). Ambos os arrays têm como escopo a sessão pai, e não o subagente.
2729 2755
2730```json theme={null}2756```json theme={null}
2731{2757{
2744}2770}
2745```2771```
2746 2772
2747Os hooks SubagentStop usam o mesmo formato de controle de decisão que os [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 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`.2773Os 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 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 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`.
2748 2774
2749<h3 id="taskcreated">2775<h3 id="taskcreated">
2750 TaskCreated2776 TaskCreated
2751</h3>2777</h3>
2752 2778
2753É 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.2779É 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 certas tarefas sejam criadas. Em uma [sessão sem as ferramentas Task](/docs/pt/tools-reference#task-tool-availability), este evento não é disparado.
2754 2780
2755Os hooks TaskCreated não oferecem suporte a matchers e são disparados em todas as ocorrências.2781Os hooks TaskCreated não suportam matchers e são disparados em todas as ocorrências.
2756 2782
2757<h4 id="taskcreated-input">2783<h4 id="taskcreated-input">
2758 Entrada de TaskCreated2784 Entrada do TaskCreated
2759</h4>2785</h4>
2760 2786
2761Alé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`.2787Alé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`.
2779| `task_id` | Identificador da tarefa que está sendo criada |2805| `task_id` | Identificador da tarefa que está sendo criada |
2780| `task_subject` | Título da tarefa |2806| `task_subject` | Título da tarefa |
2781| `task_description` | Descrição detalhada da tarefa. Pode estar ausente |2807| `task_description` | Descrição detalhada da tarefa. Pode estar ausente |
2782| `teammate_name` | Nome do colega que está criando a tarefa. Pode estar ausente |2808| `teammate_name` | Nome do colega de equipe que está criando a tarefa. Pode estar ausente |
2783| `team_name` | Descontinuado. Nome da equipe derivado da sessão; será removido em uma versão futura |2809| `team_name` | Descontinuado. Nome da equipe derivado da sessão; será removido em uma versão futura |
2784| `agent_id` | Neste evento, o [campo de entrada comum](#common-input-fields) identifica o subagente ou o [colega em processo](/docs/pt/agent-teams#choose-a-display-mode) que está criando a tarefa. Pode estar ausente. Requer Claude Code v2.1.290 ou posterior |2810| `agent_id` | Neste evento, o [campo de entrada comum](#common-input-fields) identifica o subagente ou o [colega de equipe em processo](/docs/pt/agent-teams#choose-a-display-mode) que está criando a tarefa. Pode estar ausente. Requer Claude Code v2.1.290 ou posterior |
2785 2811
2786<h4 id="taskcreated-decision-control">2812<h4 id="taskcreated-decision-control">
2787 Controle de decisão de TaskCreated2813 Controle de decisão do TaskCreated
2788</h4>2814</h4>
2789 2815
2790Um hook TaskCreated pode bloquear a criação com o código de saída 2 ou com uma decisão JSON. De qualquer forma, 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.2816Um hook TaskCreated pode bloquear a criação com o código de saída 2 ou com uma decisão JSON. 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.
2791 2817
2792* **Código de saída 2**: o Claude Code retorna o texto do stderr como a mensagem.2818* **Código de saída 2**: o Claude Code retorna o texto do stderr como a mensagem.
2793* **JSON `{"decision": "block", "reason": "..."}`**: o Claude Code retorna `reason` como a mensagem.2819* **JSON `{"decision": "block", "reason": "..."}`**: o Claude Code retorna `reason` como a mensagem.
2811 TaskCompleted2837 TaskCompleted
2812</h3>2838</h3>
2813 2839
2814É 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 aprovados ou verificações de lint, antes que uma tarefa possa ser fechada.2840É 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 aprovados ou verificações de lint, antes que uma tarefa possa ser encerrada.
2815 2841
2816Os hooks TaskCompleted não oferecem suporte a matchers e são disparados em todas as ocorrências.2842Os hooks TaskCompleted não suportam matchers e são disparados em todas as ocorrências.
2817 2843
2818<h4 id="taskcompleted-input">2844<h4 id="taskcompleted-input">
2819 Entrada de TaskCompleted2845 Entrada do TaskCompleted
2820</h4>2846</h4>
2821 2847
2822Alé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`.2848Alé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`.
2841| `task_id` | Identificador da tarefa que está sendo concluída |2867| `task_id` | Identificador da tarefa que está sendo concluída |
2842| `task_subject` | Título da tarefa |2868| `task_subject` | Título da tarefa |
2843| `task_description` | Descrição detalhada da tarefa. Pode estar ausente |2869| `task_description` | Descrição detalhada da tarefa. Pode estar ausente |
2844| `teammate_name` | Nome do colega que está concluindo a tarefa. Pode estar ausente |2870| `teammate_name` | Nome do colega de equipe que está concluindo a tarefa. Pode estar ausente |
2845| `team_name` | Descontinuado. Nome da equipe derivado da sessão; será removido em uma versão futura |2871| `team_name` | Descontinuado. Nome da equipe derivado da sessão; será removido em uma versão futura |
2846| `agent_id` | Neste evento, o [campo de entrada comum](#common-input-fields) identifica o subagente ou o [colega em processo](/docs/pt/agent-teams#choose-a-display-mode) que está concluindo a tarefa. Pode estar ausente. Requer Claude Code v2.1.290 ou posterior |2872| `agent_id` | Neste evento, o [campo de entrada comum](#common-input-fields) identifica o subagente ou o [colega de equipe em processo](/docs/pt/agent-teams#choose-a-display-mode) que está concluindo a tarefa. Pode estar ausente. Requer Claude Code v2.1.290 ou posterior |
2847 2873
2848<h4 id="taskcompleted-decision-control">2874<h4 id="taskcompleted-decision-control">
2849 Controle de decisão de TaskCompleted2875 Controle de decisão do TaskCompleted
2850</h4>2876</h4>
2851 2877
2852Os hooks TaskCompleted oferecem duas formas de controlar a conclusão de tarefas:2878Os hooks TaskCompleted suportam duas formas de controlar a conclusão de tarefas:
2853 2879
2854* **Código de saída 2**: a tarefa não é marcada como concluída e a mensagem do stderr é enviada de volta ao modelo como feedback.2880* **Código de saída 2**: a tarefa não é marcada como concluída e a mensagem do stderr é enviada de volta ao modelo como feedback.
2855* **JSON `{"continue": false, "stopReason": "..."}`**: quando um colega terminando 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.2881* **JSON `{"continue": false, "stopReason": "..."}`**: quando um colega de equipe terminando seu turno acionou o evento, interrompe o colega de equipe por completo, 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.
2856 2882
2857Este exemplo executa testes e bloqueia a conclusão da tarefa se eles falharem:2883Este exemplo executa testes e bloqueia a conclusão da tarefa se eles falharem:
2858 2884
2876 2902
2877É executado quando o agente principal do Claude Code termina de responder. Não é executado se2903É executado quando o agente principal do Claude Code termina de responder. Não é executado se
2878a parada ocorreu devido a uma interrupção do usuário. Erros de API disparam2904a parada ocorreu devido a uma interrupção do usuário. Erros de API disparam
2879[StopFailure](#stopfailure) em vez disso.2905[StopFailure](#stopfailure) em seu lugar.
2880 2906
2881<Tip>2907<Tip>
2882 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 uma configuração de hook.2908 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 configuração de hook.
2883</Tip>2909</Tip>
2884 2910
2885<h4 id="stop-input">2911<h4 id="stop-input">
2886 Entrada de Stop2912 Entrada do Stop
2887</h4>2913</h4>
2888 2914
2889Alé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.2915Alé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 Stop. Verifique esse valor ou processe a transcrição para evitar bloquear em uma condição que nunca será resolvida.
2890 2916
2891O Claude Code aplica um limite de 8 continuações consecutivas: depois que os hooks de parada continuarem o turno oito vezes seguidas, o Claude Code sobrescreve o próximo bloqueio e encerra o turno. A contagem de continuações consecutivas é redefinida sempre que o Claude chama uma ferramenta. Para aumentar o limite, defina [`CLAUDE_CODE_STOP_HOOK_BLOCK_CAP`](/docs/pt/env-vars).2917O Claude Code aplica um limite de 8 continuações consecutivas: depois que os hooks Stop continuaram o turno oito vezes seguidas, o Claude Code sobrescreve o próximo bloqueio e encerra o turno. A contagem de continuações consecutivas é redefinida cada vez que o Claude chama uma ferramenta. Para aumentar o limite, defina [`CLAUDE_CODE_STOP_HOOK_BLOCK_CAP`](/docs/pt/env-vars).
2892 2918
2893O 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.2919O 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.
2894 2920
2895Os arrays `background_tasks` e `session_crons` permitem que os hooks distingam entre "a sessão terminou" e "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 nada está em andamento ou agendado.2921Os arrays `background_tasks` e `session_crons` permitem que os hooks diferenciem "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 nada está em andamento ou agendado.
2896 2922
2897Cada entrada em `background_tasks` descreve uma tarefa em andamento e usa estes campos:2923Cada entrada em `background_tasks` descreve uma tarefa em andamento e usa estes campos:
2898 2924
2899| Campo | Descrição |2925| Campo | Descrição |
2900| :- | :- |2926| :- | :- |
2901| `id` | Identificador da tarefa |2927| `id` | Identificador da tarefa |
2902| `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 |2928| `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. Recorre ao discriminante bruto para tipos não reconhecidos |
2903| `status` | Status atual da tarefa |2929| `status` | Status atual da tarefa |
2904| `description` | Descrição em texto livre, limitada a 1000 caracteres, com um marcador `… [+N chars]` na própria string quando cortada |2930| `description` | Descrição em texto livre, limitada a 1000 caracteres com um marcador `… [+N chars]` na própria string quando cortada |
2905| `command` | Linha de comando do shell, limitada a 1000 caracteres. Presente somente para tarefas `shell` |2931| `command` | Linha de comando do shell, limitada a 1000 caracteres. Presente apenas para tarefas `shell` |
2906| `agent_type` | Nome do tipo de subagente. Presente somente para tarefas `subagent` |2932| `agent_type` | Nome do tipo de subagente. Presente apenas para tarefas `subagent` |
2907| `server` | Nome do servidor MCP. Presente somente para tarefas `monitor` e `MCP task` |2933| `server` | Nome do servidor MCP. Presente apenas para tarefas `monitor` e `MCP task` |
2908| `tool` | Nome da ferramenta MCP. Presente somente para tarefas `monitor` e `MCP task` |2934| `tool` | Nome da ferramenta MCP. Presente apenas para tarefas `monitor` e `MCP task` |
2909| `name` | Nome do workflow. Presente somente para tarefas `workflow` |2935| `name` | Nome do workflow. Presente apenas para tarefas `workflow` |
2910 2936
2911Cada entrada em `session_crons` descreve um despertar agendado com escopo de sessão, originado de `CronCreate`, `ScheduleWakeup` e `/loop`:2937Cada entrada em `session_crons` descreve um despertar agendado com escopo de sessão, proveniente de `CronCreate`, `ScheduleWakeup` e `/loop`:
2912 2938
2913| Campo | Descrição |2939| Campo | Descrição |
2914| :- | :- |2940| :- | :- |
2915| `id` | Identificador da tarefa cron |2941| `id` | Identificador da tarefa cron |
2916| `schedule` | Expressão cron, por exemplo `0 9 * * 1-5` |2942| `schedule` | Expressão cron, por exemplo `0 9 * * 1-5` |
2917| `recurring` | `false` para despertares únicos cujo agendamento codifica um único horário de disparo, `true` para tarefas que disparam novamente a cada correspondência |2943| `recurring` | `false` para despertares únicos cujo agendamento codifica um único horário de disparo, `true` para tarefas que são disparadas novamente a cada correspondência |
2918| `prompt` | Prompt enviado quando o cron é disparado, limitado a 1000 caracteres com o mesmo marcador `… [+N chars]` |2944| `prompt` | Prompt enviado quando o cron é disparado, limitado a 1000 caracteres com o mesmo marcador `… [+N chars]` |
2919 2945
2920Este exemplo mostra uma entrada de Stop com uma tarefa shell em andamento e um cron recorrente:2946Este exemplo mostra uma entrada do Stop com uma tarefa de shell em andamento e um cron recorrente:
2921 2947
2922```json theme={null}2948```json theme={null}
2923{2949{
2949```2975```
2950 2976
2951<h4 id="stop-decision-control">2977<h4 id="stop-decision-control">
2952 Controle de decisão de Stop2978 Controle de decisão do Stop
2953</h4>2979</h4>
2954 2980
2955Os 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:2981Os 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:
2958| :- | :- |2984| :- | :- |
2959| `decision` | `"block"` impede que o Claude pare. Omita para permitir que o Claude pare |2985| `decision` | `"block"` impede que o Claude pare. Omita para permitir que o Claude pare |
2960| `reason` | Obrigatório quando `decision` é `"block"`. Informa ao Claude por que ele deve continuar |2986| `reason` | Obrigatório quando `decision` é `"block"`. Informa ao Claude por que ele deve continuar |
2961| `hookSpecificOutput.additionalContext` | Feedback sem erro para o Claude. A conversa continua para que o Claude possa agir sobre ele, mas, diferentemente de `decision: "block"`, ele é mostrado na transcrição como feedback de hook, e não como erro de hook |2987| `hookSpecificOutput.additionalContext` | Feedback sem 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, e não como um erro de hook |
2962 2988
2963Um hook que bloqueia saindo com código 2 é encaminhado da mesma forma que `reason`: o Claude recebe a mensagem do stderr como a explicação de por que deve continuar.2989Um hook que bloqueia saindo com código 2 é encaminhado da mesma forma que `reason`: o Claude recebe a mensagem do stderr como a explicação de por que deve continuar.
2964 2990
2969}2995}
2970```2996```
2971 2997
2972Use `additionalContext` quando o hook estiver funcionando conforme projetado e dando orientações ao Claude, como "execute o conjunto de testes antes de terminar". Ele mantém a conversa em andamento com as mesmas proteções contra loop que `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:2998Use `additionalContext` quando o hook estiver funcionando como projetado e dando 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"`, a saber, 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 é exibida:
2973 2999
2974```json theme={null}3000```json theme={null}
2975{3001{
2984 StopFailure3010 StopFailure
2985</h3>3011</h3>
2986 3012
2987É 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, com exceção de [`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.3013É executado em vez do [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.
2988 3014
2989<h4 id="stopfailure-input">3015<h4 id="stopfailure-input">
2990 Entrada de StopFailure3016 Entrada do StopFailure
2991</h4>3017</h4>
2992 3018
2993Alé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.3019Alé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.
2996| :- | :- |3022| :- | :- |
2997| `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` |3023| `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` |
2998| `error_details` | Detalhes adicionais sobre o erro, quando disponíveis |3024| `error_details` | Detalhes adicionais sobre o erro, quando disponíveis |
2999| `last_assistant_message` | O texto de erro renderizado mostrado na conversa. Diferentemente 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 do erro de API, como `"API Error: Rate limit reached"` |3025| `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"` |
3000 3026
3001```json theme={null}3027```json theme={null}
3002{3028{
3010}3036}
3011```3037```
3012 3038
3013Os hooks StopFailure não têm controle de decisão. Eles são executados apenas para fins de notificação e registro em log.3039Os hooks StopFailure não têm controle de decisão. Eles são executados apenas para fins de notificação e log.
3014 3040
3015<h3 id="teammateidle">3041<h3 id="teammateidle">
3016 TeammateIdle3042 TeammateIdle
3017</h3>3043</h3>
3018 3044
3019É 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.3045É executado quando um colega de uma [equipe de agentes](/docs/pt/agent-teams) está prestes a ficar ocioso depois de terminar seu turno. Use-o para impor critérios de qualidade antes que um colega de equipe pare de trabalhar, como exigir que as verificações de lint passem ou verificar se os arquivos de saída existem.
3020 3046
3021Os hooks TeammateIdle não oferecem suporte a matchers e são disparados em todas as ocorrências.3047Os hooks TeammateIdle não suportam matchers e são disparados em todas as ocorrências.
3022 3048
3023<h4 id="teammateidle-input">3049<h4 id="teammateidle-input">
3024 Entrada de TeammateIdle3050 Entrada do TeammateIdle
3025</h4>3051</h4>
3026 3052
3027Além dos [campos de entrada comuns](#common-input-fields), os hooks TeammateIdle recebem `teammate_name` e `team_name`.3053Além dos [campos de entrada comuns](#common-input-fields), os hooks TeammateIdle recebem `teammate_name` e `team_name`.
3040 3066
3041| Campo | Descrição |3067| Campo | Descrição |
3042| :- | :- |3068| :- | :- |
3043| `teammate_name` | Nome do colega que está prestes a ficar ocioso |3069| `teammate_name` | Nome do colega de equipe que está prestes a ficar ocioso |
3044| `team_name` | Descontinuado. Nome da equipe derivado da sessão; será removido em uma versão futura |3070| `team_name` | Descontinuado. Nome da equipe derivado da sessão; será removido em uma versão futura |
3045| `agent_id` | Neste evento, o [campo de entrada comum](#common-input-fields) identifica o [colega em processo](/docs/pt/agent-teams#choose-a-display-mode) que está prestes a ficar ocioso. Pode estar ausente. Requer Claude Code v2.1.290 ou posterior |3071| `agent_id` | Neste evento, o [campo de entrada comum](#common-input-fields) identifica o [colega de equipe em processo](/docs/pt/agent-teams#choose-a-display-mode) que está prestes a ficar ocioso. Pode estar ausente. Requer Claude Code v2.1.290 ou posterior |
3046 3072
3047<h4 id="teammateidle-decision-control">3073<h4 id="teammateidle-decision-control">
3048 Controle de decisão de TeammateIdle3074 Controle de decisão do TeammateIdle
3049</h4>3075</h4>
3050 3076
3051Os hooks TeammateIdle oferecem duas formas de controlar o comportamento do colega:3077Os hooks TeammateIdle suportam duas formas de controlar o comportamento do colega de equipe:
3052 3078
3053* **Código de saída 2**: o colega recebe a mensagem do stderr como feedback e continua trabalhando em vez de ficar ocioso.3079* **Código de saída 2**: o colega de equipe recebe a mensagem do stderr como feedback e continua trabalhando em vez de ficar ocioso.
3054* **JSON `{"continue": false, "stopReason": "..."}`**: interrompe o colega completamente, correspondendo ao comportamento do hook `Stop`. O `stopReason` é mostrado ao usuário.3080* **JSON `{"continue": false, "stopReason": "..."}`**: interrompe o colega de equipe por completo, correspondendo ao comportamento do hook `Stop`. O `stopReason` é mostrado ao usuário.
3055 3081
3056Este exemplo verifica se um artefato de build existe antes de permitir que um colega fique ocioso:3082Este exemplo verifica se um artefato de build existe antes de permitir que um colega de equipe fique ocioso:
3057 3083
3058```bash theme={null}3084```bash theme={null}
3059#!/bin/bash3085#!/bin/bash
3072 3098
3073É 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.3099É 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.
3074 3100
3075O 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.3101O 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 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 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 do lado do Windows alterado na sua verificação periódica de política sem executá-los.
3076 3102
3077O matcher filtra pela origem da configuração:3103O matcher filtra pela origem da configuração:
3078 3104
3105```3131```
3106 3132
3107<h4 id="configchange-input">3133<h4 id="configchange-input">
3108 Entrada de ConfigChange3134 Entrada do ConfigChange
3109</h4>3135</h4>
3110 3136
3111Alé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 para o arquivo específico que foi modificado.3137Alé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.
3112 3138
3113```json theme={null}3139```json theme={null}
3114{3140{
3122```3148```
3123 3149
3124<h4 id="configchange-decision-control">3150<h4 id="configchange-decision-control">
3125 Controle de decisão de ConfigChange3151 Controle de decisão do ConfigChange
3126</h4>3152</h4>
3127 3153
3128Os hooks ConfigChange podem impedir que alterações de configuração entrem em vigor. Use o código de saída 2 ou uma `decision` em JSON para impedir a alteração. Quando bloqueadas, as novas configurações não são aplicadas à sessão em execução.3154Os hooks ConfigChange podem impedir que alterações de configuração entrem em vigor. Use o código de saída 2 ou uma `decision` JSON para impedir a alteração. Quando bloqueadas, as novas configurações não são aplicadas à sessão em execução.
3129 3155
3130| Campo | Descrição |3156| Campo | Descrição |
3131| :- | :- |3157| :- | :- |
3132| `decision` | `"block"` impede que a alteração de configuração seja aplicada. Omita para permitir a alteração |3158| `decision` | `"block"` impede que a alteração de configuração seja aplicada. Omita para permitir a alteração |
3133| `reason` | Aceito, mas nunca mostrado |3159| `reason` | Aceito, mas nunca exibido |
3134 3160
3135```json theme={null}3161```json theme={null}
3136{3162{
3141 3167
3142Alteraçõ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.3168Alteraçõ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.
3143 3169
3144O Claude Code age sobre a 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 bloqueando com `reason` ou com stderr no código de saída 2. O Claude Code apenas grava uma linha no log de depuração.3170O 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, quer você bloqueie com `reason` ou com stderr na saída com código 2. O Claude Code apenas grava uma linha no log de depuração.
3145 3171
3146<h3 id="cwdchanged">3172<h3 id="cwdchanged">
3147 CwdChanged3173 CwdChanged
3148</h3>3174</h3>
3149 3175
3150É 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íficos do projeto ou executar scripts de configuração automaticamente. Funciona em conjunto com [FileChanged](#filechanged) para ferramentas como o [direnv](https://direnv.net/), que gerenciam o ambiente por diretório.3176É executado quando um comando de shell na conversa principal altera o diretório de trabalho, por exemplo quando o Claude executa um comando `cd`. Use-o para reagir a mudanças de diretório: recarregar variáveis de ambiente, ativar toolchains específicas do projeto ou executar scripts de configuração automaticamente. Combina com [FileChanged](#filechanged) para ferramentas como o [direnv](https://direnv.net/), que gerenciam o ambiente por diretório.
3151 3177
3152Os 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.3178Os 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.
3153 3179
3154CwdChanged não oferece suporte a matchers e é disparado em todas as ocorrências.3180O CwdChanged não suporta matchers e é disparado em todas as ocorrências.
3155 3181
3156<h4 id="cwdchanged-input">3182<h4 id="cwdchanged-input">
3157 Entrada de CwdChanged3183 Entrada do CwdChanged
3158</h4>3184</h4>
3159 3185
3160Além dos [campos de entrada comuns](#common-input-fields), os hooks CwdChanged recebem `old_cwd` e `new_cwd`.3186Além dos [campos de entrada comuns](#common-input-fields), os hooks CwdChanged recebem `old_cwd` e `new_cwd`.
3171```3197```
3172 3198
3173<h4 id="cwdchanged-output">3199<h4 id="cwdchanged-output">
3174 Saída de CwdChanged3200 Saída do CwdChanged
3175</h4>3201</h4>
3176 3202
3177Alé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) observa:3203Alé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) observa:
3182 3208
3183Os hooks CwdChanged não têm controle de decisão. Eles não podem bloquear a mudança de diretório.3209Os hooks CwdChanged não têm controle de decisão. Eles não podem bloquear a mudança de diretório.
3184 3210
3185O Claude Code lê `watchPaths` e `systemMessage` da saída JSON desses hooks 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.3211O 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.
3186 3212
3187<h3 id="directoryadded">3213<h3 id="directoryadded">
3188 DirectoryAdded3214 DirectoryAdded
3189</h3>3215</h3>
3190 3216
3191É 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 do 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.3217É 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.
3192 3218
3193O Claude Code não dispara este evento quando:3219O Claude Code não dispara este evento quando:
3194 3220
3195* Você passa um diretório com a flag de inicialização `--add-dir`; [SessionStart](#sessionstart) cobre esses diretórios3221* Você passa um diretório com a flag de inicialização `--add-dir`; o [SessionStart](#sessionstart) cobre esses diretórios
3196* Você adiciona um diretório na aba Workspace de `/permissions`3222* Você adiciona um diretório na aba Workspace de `/permissions`
3197* Você adiciona um diretório que já é um diretório de trabalho ou que está dentro de um3223* Você adiciona um diretório que já é um diretório de trabalho ou está dentro de um
3198 3224
3199O Claude Code dispara 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 do hook são executados fora do sandbox.3225O 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.
3200 3226
3201O 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.3227O 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.
3202 3228
3205| Matcher | Quando é disparado |3231| Matcher | Quando é disparado |
3206| :- | :- |3232| :- | :- |
3207| `slash_command` | Você adiciona um diretório com `/add-dir` |3233| `slash_command` | Você adiciona um diretório com `/add-dir` |
3208| `register_repo_root` | Um cliente do SDK adiciona um diretório com a requisição de controle `register_repo_root` |3234| `register_repo_root` | Um cliente SDK adiciona um diretório com a requisição de controle `register_repo_root` |
3209 3235
3210<h4 id="directoryadded-input">3236<h4 id="directoryadded-input">
3211 Entrada de DirectoryAdded3237 Entrada do DirectoryAdded
3212</h4>3238</h4>
3213 3239
3214Além dos [campos de entrada comuns](#common-input-fields), os hooks DirectoryAdded recebem `directory` e `source`.3240Além dos [campos de entrada comuns](#common-input-fields), os hooks DirectoryAdded recebem `directory` e `source`.
3216| Campo | Descrição |3242| Campo | Descrição |
3217| :- | :- |3243| :- | :- |
3218| `directory` | Caminho absoluto do diretório que foi adicionado |3244| `directory` | Caminho absoluto do diretório que foi adicionado |
3219| `source` | Como o diretório foi adicionado: `"slash_command"` para `/add-dir` ou `"register_repo_root"` para a requisição de controle do SDK |3245| `source` | Como o diretório foi adicionado, `"slash_command"` para `/add-dir` ou `"register_repo_root"` para a requisição de controle do SDK |
3220 3246
3221```json theme={null}3247```json theme={null}
3222{3248{
3229}3255}
3230```3256```
3231 3257
3232Os 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 desses hooks e exibe o restante de forma diferente conforme a origem:3258Os 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 trata o restante de forma diferente conforme a origem:
3233 3259
3234* `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 da falha vai para o log de depuração3260* `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
3235* `register_repo_root`: o Claude Code grava a saída de `systemMessage` e a saída de falhas somente no log de depuração3261* `register_repo_root`: o Claude Code grava a saída de `systemMessage` e a saída das falhas apenas no log de depuração
3236 3262
3237<h3 id="filechanged">3263<h3 id="filechanged">
3238 FileChanged3264 FileChanged
3239</h3>3265</h3>
3240 3266
3241É executado quando um arquivo observado muda no disco. O Claude Code detecta mudanças com um observador do sistema de arquivos, e não inspecionando chamadas de ferramenta, então 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.3267É 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, então ele 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.
3242 3268
3243O `matcher` deste evento tem duas funções:3269O `matcher` deste evento tem duas funções:
3244 3270
3245* **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 chamado `^\.env`.3271* **Montar 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 chamado literalmente `^\.env`.
3246* **Filtrar quais hooks são executados**: quando um arquivo observado 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.3272* **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.
3247 3273
3248Este exemplo normaliza as terminações de linha em `data.csv` após qualquer alteração, incluindo um comando `Bash` ou um script externo que reescreva o arquivo:3274Este exemplo normaliza as quebras de linha em `data.csv` após qualquer alteração, incluindo um comando `Bash` ou um script externo reescrevendo o arquivo:
3249 3275
3250```json theme={null}3276```json theme={null}
3251{3277{
3265}3291}
3266```3292```
3267 3293
3268O hook lê o caminho absoluto do arquivo alterado do campo `file_path` da [entrada JSON](#filechanged-input) no stdin. Sua verificação com `grep` testa exatamente o que o `perl` remove, um CR no final de uma linha, então a execução após uma normalização termina sem tocar no arquivo. Uma verificação mais frouxa entra em loop infinito, 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:3294O hook lê o caminho absoluto do arquivo alterado no campo `file_path` da [entrada JSON](#filechanged-input) em stdin. Sua verificação com `grep` testa a mesma coisa que o `perl` remove, um CR no final de uma linha, então a execução após uma normalização termina sem tocar no arquivo. Uma verificação mais permissiva entra em loop infinito, 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:
3269 3295
3270```bash theme={null}3296```bash theme={null}
3271#!/bin/bash3297#!/bin/bash
3275fi3301fi
3276```3302```
3277 3303
3278Para 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 termina com terminações LF.3304Para 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 termina com quebras de linha LF.
3279 3305
3280Para observar arquivos que você não consegue nomear de antemão, retorne [`watchPaths`](#filechanged-output) de um hook para atualizar a lista de observação dinamicamente. O Claude Code inicia o observador somente quando algo nomeia um arquivo a ser observado, 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 observado muda, então deixe o matcher omitido no grupo que lida com caminhos dinâmicos, o que corresponde a todo arquivo observado e não adiciona nada à lista de observação. Um matcher `"*"` também corresponde a todos os arquivos, mas o Claude Code o registra na lista de observação como qualquer outro valor, como um arquivo literal chamado `*`.3306Para 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 deixe sem matcher o grupo que lida com caminhos dinâmicos, o 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 `*`.
3281 3307
3282Os 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.3308Os 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.
3283 3309
3284<h4 id="filechanged-input">3310<h4 id="filechanged-input">
3285 Entrada de FileChanged3311 Entrada do FileChanged
3286</h4>3312</h4>
3287 3313
3288Além dos [campos de entrada comuns](#common-input-fields), os hooks FileChanged recebem `file_path` e `event`.3314Além dos [campos de entrada comuns](#common-input-fields), os hooks FileChanged recebem `file_path` e `event`.
3289 3315
3290| Campo | Descrição |3316| Campo | Descrição |
3291| :- | :- |3317| :- | :- |
3292| `file_path` | Caminho absoluto para o arquivo que mudou |3318| `file_path` | Caminho absoluto do arquivo que mudou |
3293| `event` | O que aconteceu: `"change"` para um arquivo modificado, `"add"` para um arquivo criado ou `"unlink"` para um arquivo excluído |3319| `event` | O que aconteceu: `"change"` para um arquivo modificado, `"add"` para um arquivo criado ou `"unlink"` para um arquivo excluído |
3294 3320
3295```json theme={null}3321```json theme={null}
3304```3330```
3305 3331
3306<h4 id="filechanged-output">3332<h4 id="filechanged-output">
3307 Saída de FileChanged3333 Saída do FileChanged
3308</h4>3334</h4>
3309 3335
3310Alé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 observados:3336Alé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:
3311 3337
3312| Campo | Descrição |3338| Campo | Descrição |
3313| :- | :- |3339| :- | :- |
3314| `watchPaths` | Array de caminhos absolutos. Substitui a lista dinâmica de observação atual. Os caminhos da sua configuração de `matcher` são sempre observados. Use isto quando seu script de hook descobrir arquivos adicionais a serem observados com base no arquivo alterado |3340| `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 o seu script de hook descobrir arquivos adicionais a serem monitorados com base no arquivo alterado |
3315 3341
3316Os hooks FileChanged não têm controle de decisão. Eles não podem impedir que a alteração do arquivo ocorra.3342Os hooks FileChanged não têm controle de decisão. Eles não podem impedir que a alteração do arquivo ocorra.
3317 3343
3318O Claude Code lê `watchPaths` e `systemMessage` da saída JSON desses hooks 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.3344O Claude Code lê `watchPaths` e `systemMessage` da saída JSON deles e descarta `continue`. Em sessões interativas, ele mostra a `systemMessage` como uma breve notificação no terminal. A mensagem não chega ao fluxo de mensagens do SDK.
3319 3345
3320<h3 id="worktreecreate">3346<h3 id="worktreecreate">
3321 WorktreeCreate3347 WorktreeCreate
3330* O Claude Code isola uma [sessão em segundo plano](/docs/pt/agent-view#how-file-edits-are-isolated) em seu próprio worktree3356* O Claude Code isola uma [sessão em segundo plano](/docs/pt/agent-view#how-file-edits-are-isolated) em seu próprio worktree
3331* [`claude remote-control`](/docs/pt/remote-control#start-a-remote-control-session) no modo `worktree` inicia uma sessão em seu próprio worktree3357* [`claude remote-control`](/docs/pt/remote-control#start-a-remote-control-session) no modo `worktree` inicia uma sessão em seu próprio worktree
3332 3358
3333Quando o Claude executa `git worktree add` por meio da ferramenta Bash em vez de chamar `EnterWorktree`, seu hook WorktreeCreate não é executado. Para inspecionar ou bloquear esse comando, adicione um hook [`PreToolUse`](#pretooluse) com o matcher `Bash`.3359Quando o Claude executa `git worktree add` por meio da ferramenta Bash em vez de chamar `EnterWorktree`, o seu hook WorktreeCreate não é executado. Para inspecionar ou bloquear esse comando, adicione um hook [`PreToolUse`](#pretooluse) com o matcher `Bash`.
3334 3360
3335Por 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.3361Por 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.
3336 3362
3337Como o hook substitui totalmente o comportamento padrão, o [`.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.3363Como o hook substitui totalmente o comportamento padrão, [`.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.
3338 3364
3339O hook deve retornar o caminho para o diretório do worktree criado. O Claude Code usa esse caminho como diretório de trabalho para a sessão isolada. Consulte [Saída de WorktreeCreate](#worktreecreate-output) para ver como cada tipo de hook retorna o caminho.3365O hook deve retornar o caminho para o diretório do worktree criado. O Claude Code usa esse caminho como diretório de trabalho para a sessão isolada. Consulte [Saída do WorktreeCreate](#worktreecreate-output) para saber como cada tipo de hook retorna o caminho.
3340 3366
3341O Claude Code age com base no sucesso do hook e no caminho retornado, e descarta `systemMessage` e `continue`.3367O Claude Code age com base no sucesso do hook e no caminho retornado, e descarta `systemMessage` e `continue`.
3342 3368
3359}3385}
3360```3386```
3361 3387
3362O hook lê o `name` do worktree a partir 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.3388O hook lê o `name` do worktree da entrada JSON em 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 caminho do worktree. Redirecione qualquer outra saída para stderr para que ela não interfira no caminho.
3363 3389
3364<h4 id="worktreecreate-input">3390<h4 id="worktreecreate-input">
3365 Entrada de WorktreeCreate3391 Entrada do WorktreeCreate
3366</h4>3392</h4>
3367 3393
3368Além dos [campos de entrada comuns](#common-input-fields), os hooks WorktreeCreate recebem o campo `name`. Este é um identificador slug para o novo worktree, especificado pelo usuário ou gerado automaticamente, por exemplo `bold-oak-a3f2`.3394Além dos [campos de entrada comuns](#common-input-fields), os hooks WorktreeCreate recebem o campo `name`. Este é um identificador slug para o novo worktree, especificado pelo usuário ou gerado automaticamente, por exemplo `bold-oak-a3f2`.
3378```3404```
3379 3405
3380<h4 id="worktreecreate-output">3406<h4 id="worktreecreate-output">
3381 Saída de WorktreeCreate3407 Saída do WorktreeCreate
3382</h4>3408</h4>
3383 3409
3384Os 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:3410Os hooks WorktreeCreate não usam o modelo padrão de decisão 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:
3385 3411
3386* **Hooks de comando** (`type: "command"`): imprima o caminho como a última linha não vazia do stdout. O Claude Code remove códigos de escape ANSI antes de ler essa linha, então banners de inicialização do shell impressos antes do seu `echo` são ignorados. Redirecione qualquer outra saída do hook para o stderr.3412* **Hooks de comando** (`type: "command"`): imprima o caminho como a última linha não vazia de stdout. O Claude Code remove códigos de escape ANSI antes de ler essa linha, então banners de inicialização do shell impressos antes do seu `echo` são ignorados. Redirecione qualquer outra saída do hook para stderr.
3387* **Hooks HTTP** (`type: "http"`): retorne `{ "hookSpecificOutput": { "hookEventName": "WorktreeCreate", "worktreePath": "/absolute/path" } }` no corpo da resposta.3413* **Hooks HTTP** (`type: "http"`): retorne `{ "hookSpecificOutput": { "hookEventName": "WorktreeCreate", "worktreePath": "/absolute/path" } }` no corpo da resposta.
3388 3414
3389Se o hook falhar ou não produzir nenhum caminho, a criação do worktree falha com um erro.3415Se o hook falhar ou não produzir um caminho, a criação do worktree falha com um erro.
3390 3416
3391O 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 indicando o caminho e encerra com o código 1.3417O Claude Code resolve um caminho relativo em relação ao diretório em que o hook foi executado, resolvendo 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 indicando o caminho e termina com código 1.
3392 3418
3393O 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.3419O 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 incluído em um commit do 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.
3394 3420
3395<h3 id="worktreeremove">3421<h3 id="worktreeremove">
3396 WorktreeRemove3422 WorktreeRemove
3398 3424
3399É executado quando o Claude Code limpa um worktree que o seu hook [`WorktreeCreate`](#worktreecreate) criou. O evento é disparado quando:3425É executado quando o Claude Code limpa um worktree que o seu hook [`WorktreeCreate`](#worktreecreate) criou. O evento é disparado quando:
3400 3426
3401* Você sai de uma [sessão de worktree](/docs/pt/worktrees#start-claude-in-a-worktree) interativa e opta por remover o worktree quando o Claude Code pergunta3427* Você sai de uma [sessão de worktree](/docs/pt/worktrees#start-claude-in-a-worktree) interativa e escolhe remover o worktree quando o Claude Code solicita
3402* Você sai de uma sessão de worktree interativa que não [nomeou](/docs/pt/sessions#name-your-sessions), o Claude Code não encontra arquivos alterados ou não rastreados, e remove o worktree sem perguntar3428* Você sai de uma sessão de worktree interativa que não [nomeou](/docs/pt/sessions#name-your-sessions), o Claude Code não encontra arquivos alterados ou não rastreados e remove o worktree sem solicitar confirmação
3403* Você exclui uma [sessão em segundo plano](/docs/pt/agent-view#what-deleting-a-session-removes) que é executada no worktree3429* Você exclui uma [sessão em segundo plano](/docs/pt/agent-view#what-deleting-a-session-removes) que é executada no worktree
3404* Você pede ao Claude para sair e remover o worktree durante uma sessão, e o Claude o remove com a ferramenta [`ExitWorktree`](/docs/pt/tools-reference)3430* Você pede ao Claude para sair e remover o worktree durante uma sessão, e o Claude o remove com a ferramenta [`ExitWorktree`](/docs/pt/tools-reference)
3405* Uma sessão que [`claude remote-control`](/docs/pt/remote-control#start-a-remote-control-session) iniciou no modo `worktree` termina sem travar, e o Claude Code não encontra arquivos alterados ou não rastreados nem novos commits em seu worktree3431* Uma sessão que [`claude remote-control`](/docs/pt/remote-control#start-a-remote-control-session) iniciou no modo `worktree` termina sem falhar, e o Claude Code não encontra arquivos alterados ou não rastreados nem novos commits em seu worktree
3406* Você para o `claude remote-control` enquanto sessões que ele iniciou no modo `worktree` ainda estão em execução, e o Claude Code não encontra arquivos alterados ou não rastreados nem novos commits em seus worktrees3432* Você interrompe `claude remote-control` enquanto sessões que ele iniciou no modo `worktree` ainda estão em execução, e o Claude Code não encontra arquivos alterados ou não rastreados nem novos commits em seus worktrees
3407 3433
3408Quando um subagente ou um agente de fluxo de trabalho termina, o Claude Code mantém o worktree que seu hook WorktreeCreate criou para ele e não executa seu hook WorktreeRemove. Remova esses worktrees você mesmo quando o trabalho estiver concluído.3434Quando um subagente ou um agente de fluxo de trabalho termina, o Claude Code mantém o worktree que o seu hook WorktreeCreate criou para ele e não executa o seu hook WorktreeRemove. Remova esses worktrees você mesmo quando o trabalho estiver concluído.
3409 3435
3410O Claude Code não pede confirmação antes de seu hook ser executado para uma chamada `ExitWorktree` ou uma limpeza do `claude remote-control`. `ExitWorktree` se recusa a remover um worktree criado por hook, a menos que a chamada passe [`discard_changes: true`](/docs/pt/agent-sdk/typescript#exitworktree), o que torna seu hook a última verificação nesse caminho.3436O Claude Code não solicita confirmação antes de o seu hook ser executado para uma chamada `ExitWorktree` ou uma limpeza do `claude remote-control`. `ExitWorktree` se recusa a remover um worktree criado por hook, a menos que a chamada passe [`discard_changes: true`](/docs/pt/agent-sdk/typescript#exitworktree), o que torna o seu hook a última verificação nesse caminho.
3411 3437
3412O Claude Code usa o git para procurar arquivos alterados ou não rastreados, então não encontra nenhum em um worktree que não seja um checkout git nem esteja dentro de um, mesmo quando o diretório contém trabalho não commitado. Verifique esse trabalho no seu hook WorktreeRemove antes que ele exclua qualquer coisa.3438O Claude Code usa o git para procurar arquivos alterados ou não rastreados, então não encontra nenhum em um worktree que não seja um checkout git nem esteja dentro de um, mesmo quando o diretório contém trabalho sem commit. Verifique esse trabalho no seu hook WorktreeRemove antes que ele exclua qualquer coisa.
3413 3439
3414Para worktrees baseados em git, o Claude Code faz a limpeza automaticamente com `git worktree remove`. Se você configurou um hook WorktreeCreate, combine-o com um hook WorktreeRemove para controlar a limpeza:3440Para 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:
3415 3441
3416* **Sem hook WorktreeRemove**: o Claude Code recorre ao git para uma remoção na saída ou por meio de `ExitWorktree`, e mantém o worktree quando o `claude remote-control` faz a limpeza:3442* **Sem hook WorktreeRemove**: o Claude Code recorre ao git para uma remoção ao sair ou por meio de `ExitWorktree`, e mantém o worktree quando o `claude remote-control` faz a limpeza:
3417 * **Você sai de uma sessão de worktree, ou o Claude chama `ExitWorktree`**: o Claude Code remove o caminho que seu hook WorktreeCreate retornou como `git worktree remove --force` faria, 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.3443 * **Você sai de uma sessão de worktree, ou o Claude chama `ExitWorktree`**: o Claude Code remove o caminho que o seu hook WorktreeCreate retornou como `git worktree remove --force` faria, então um worktree que o git reconhece é removido. Um worktree que o git não reconhece, por exemplo um que o seu hook criou com um sistema de controle de versão que não seja git, permanece no disco.
3418 * **O `claude remote-control` limpa o worktree de uma sessão**: o worktree permanece no disco, e o terminal que executa `claude remote-control` mostra `worktree removal failed, kept: <path>`.3444 * **`claude remote-control` limpa o worktree de uma sessão**: o worktree permanece no disco, e o terminal que executa `claude remote-control` mostra `worktree removal failed, kept: <path>`.
3419 * **Você exclui uma sessão em segundo plano**: consulte [O que a exclusão de uma sessão remove](/docs/pt/agent-view#what-deleting-a-session-removes).3445 * **Você exclui uma sessão em segundo plano**: consulte [O que a exclusão de uma sessão remove](/docs/pt/agent-view#what-deleting-a-session-removes).
3420* **O hook sai com 0**: o worktree conta como removido. O Claude Code não lê mais nada do hook, então certifique-se de que seu hook excluiu o diretório.3446* **O hook termina com 0**: o worktree conta como removido. O Claude Code não lê mais nada do hook, então certifique-se de que o seu hook excluiu o diretório.
3421* **O hook sai 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 para o git. Um hook que excluiu o diretório antes de sair com código diferente de zero conta como removido. Para saber como a falha é relatada, consulte [Entrada de WorktreeRemove](#worktreeremove-input).3447* **O hook termina 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 para o git. Um hook que excluiu o diretório antes de terminar com código diferente de zero conta como removido. Para saber como a falha é relatada, consulte [Entrada do WorktreeRemove](#worktreeremove-input).
3422 3448
3423O Claude Code nunca exclui um branch pertencente a um worktree criado por hook, porque ele só conhece o caminho que seu hook WorktreeCreate retornou. Se o seu hook WorktreeCreate cria um branch, exclua-o no seu hook WorktreeRemove.3449O Claude Code nunca exclui um branch pertencente a um worktree criado por hook, porque ele só conhece o caminho que o seu hook WorktreeCreate retornou. Se o seu hook WorktreeCreate criar um branch, exclua-o no seu hook WorktreeRemove.
3424 3450
3425O Claude Code descarta os [campos de saída JSON](#json-output) de um hook WorktreeRemove, como `systemMessage` e `continue`.3451O Claude Code descarta os [campos de saída JSON](#json-output) de um hook WorktreeRemove, como `systemMessage` e `continue`.
3426 3452
3427Para 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 passe por um abaixo da raiz do repositório. Nesse caminho, 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 esse worktree, [`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.3453Para 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 passe por um abaixo da raiz do repositório. Nesse caminho, 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 esse worktree, [`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.
3428 3454
3429O Claude Code passa o caminho retornado por WorktreeCreate como `worktree_path` na entrada do hook. Este exemplo lê esse caminho e remove o diretório:3455O 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:
3430 3456
3431```json theme={null}3457```json theme={null}
3432{3458{
3446```3472```
3447 3473
3448<h4 id="worktreeremove-input">3474<h4 id="worktreeremove-input">
3449 Entrada de WorktreeRemove3475 Entrada do WorktreeRemove
3450</h4>3476</h4>
3451 3477
3452Alé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.3478Além dos [campos de entrada comuns](#common-input-fields), os hooks WorktreeRemove recebem o campo `worktree_path`, que é o caminho absoluto para o worktree sendo removido.
3453 3479
3454```json theme={null}3480```json theme={null}
3455{3481{
3461}3487}
3462```3488```
3463 3489
3464O código de saída de um hook WorktreeRemove decide o resultado. Quando um hook sai com código diferente de zero e o diretório em `worktree_path` ainda existe depois, a remoção falha:3490O código de saída de um hook WorktreeRemove decide o resultado. Quando um hook termina com código diferente de zero e o diretório em `worktree_path` ainda existe depois, a remoção falha:
3465 3491
3466* O worktree permanece no disco, e o comando do hook e o stderr vão para o [log de depuração](#debug-hooks).3492* O worktree permanece no disco, e o comando e o stderr do hook vão para o [log de depuração](#debug-hooks).
3467* Se você estava excluindo uma sessão em segundo plano, a sessão também permanece. A mensagem de recusa no [agent view](/docs/pt/agent-view#what-deleting-a-session-removes) informa como o hook terminou, como `exited 1`, cita o início do stderr e diz se excluir a sessão novamente remove o diretório mesmo assim.3493* 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.
3468* Se o `claude remote-control` estava limpando o worktree de uma sessão, o terminal que o executa mostra `worktree removal failed, kept: <path>`.3494* Se o `claude remote-control` estava limpando o worktree de uma sessão, o terminal que o executa mostra `worktree removal failed, kept: <path>`.
3469 3495
3470<h3 id="precompact">3496<h3 id="precompact">
3478| Matcher | Quando é disparado |3504| Matcher | Quando é disparado |
3479| :- | :- |3505| :- | :- |
3480| `manual` | `/compact` |3506| `manual` | `/compact` |
3481| `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) |3507| `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), e [compactação por inatividade](/docs/pt/settings-reference#idlecompaction) |
3482 3508
3483Saia 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"`.3509Termine com código 2 para bloquear a compactação. Para um `/compact` manual, a mensagem de stderr é mostrada ao usuário. Você também pode bloquear retornando JSON com `"decision": "block"`.
3484 3510
3485Bloquear 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.3511Bloquear 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.
3486 3512
3487O Claude Code descarta os campos `systemMessage` e `continue` de um hook PreCompact.3513O Claude Code descarta os campos `systemMessage` e `continue` de um hook PreCompact.
3488 3514
3489<h4 id="precompact-input">3515<h4 id="precompact-input">
3490 Entrada de PreCompact3516 Entrada do PreCompact
3491</h4>3517</h4>
3492 3518
3493Alé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`.3519Alé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`.
3507 PostCompact3533 PostCompact
3508</h3>3534</h3>
3509 3535
3510É executado após o Claude Code concluir 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.3536É 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.
3511 3537
3512Os mesmos valores de matcher se aplicam como para `PreCompact`:3538Os mesmos valores de matcher se aplicam como no `PreCompact`:
3513 3539
3514| Matcher | Quando é disparado |3540| Matcher | Quando é disparado |
3515| :- | :- |3541| :- | :- |
3516| `manual` | Após `/compact` |3542| `manual` | Após `/compact` |
3517| `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) |3543| `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), e após a [compactação por inatividade](/docs/pt/settings-reference#idlecompaction) |
3518 3544
3519<h4 id="postcompact-input">3545<h4 id="postcompact-input">
3520 Entrada de PostCompact3546 Entrada do PostCompact
3521</h4>3547</h4>
3522 3548
3523Alé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.3549Alé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.
3541 3567
3542É 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 custará antes que ela aconteça.3568É 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 custará antes que ela aconteça.
3543 3569
3544O PreModelSwitch requer o Claude Code v2.1.251 ou posterior. O Claude Code o executa para estas requisições:3570O PreModelSwitch requer o Claude Code v2.1.251 ou posterior. O Claude Code o executa para estas solicitações:
3545 3571
3546* `/model <name>` e o seletor do `/model`3572* `/model <name>` e o seletor do `/model`
3547* O seletor de modelo `Option+P` ou `Alt+P`3573* O seletor de modelo `Option+P` ou `Alt+P`
3551 3577
3552O 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 alterações chegam apenas ao [PostModelSwitch](#postmodelswitch).3578O 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 alterações chegam apenas ao [PostModelSwitch](#postmodelswitch).
3553 3579
3554O 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` cobre todas as grafias do Opus 5.3580O Claude Code compara o matcher com 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 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` cobre todas as grafias do Opus 5.
3555 3581
3556Quando o Claude Code não consegue determinar um nome canônico para o destino, por exemplo um ID de modelo personalizado que só o seu [gateway de LLM](/docs/pt/llm-gateway) conhece, ele executa todos os hooks PreModelSwitch independentemente do matcher. Um hook que bloqueia deve, portanto, verificar `to_model` na sua entrada em vez de depender apenas do matcher.3582Quando o Claude Code não consegue determinar um nome canônico para o destino, por exemplo um ID de modelo personalizado que só o seu [gateway de LLM](/docs/pt/llm-gateway) conhece, ele executa todos os hooks PreModelSwitch independentemente do matcher. Um hook que bloqueia deve, portanto, verificar `to_model` na sua entrada em vez de confiar apenas no matcher.
3557 3583
3558Escreva 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 saindo com o código 2 e deixa passar qualquer outro destino:3584Escreva 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, então recusa uma troca para o Opus 4.6 terminando com código 2 e deixa passar qualquer outro destino:
3559 3585
3560<Tabs>3586<Tabs>
3561 <Tab title="macOS/Linux">3587 <Tab title="macOS/Linux">
3621 </Tab>3647 </Tab>
3622</Tabs>3648</Tabs>
3623 3649
3624Para confirmar que o hook funciona, execute `/model claude-opus-4-6` a partir de 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.3650Para confirmar que o hook funciona, execute `/model claude-opus-4-6` a partir de uma sessão que esteja executando 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.
3625 3651
3626<h4 id="premodelswitch-input">3652<h4 id="premodelswitch-input">
3627 Entrada de PreModelSwitch3653 Entrada do PreModelSwitch
3628</h4>3654</h4>
3629 3655
3630Além dos [campos de entrada comuns](#common-input-fields), os hooks PreModelSwitch recebem os campos desta tabela. Os últimos cinco descrevem quanto custa reenviar a conversa para o novo modelo, para que um hook possa mostrar esse valor antes que a troca aconteça.3656Além dos [campos de entrada comuns](#common-input-fields), os hooks PreModelSwitch recebem os campos desta tabela. Os últimos cinco descrevem quanto custa reenviar a conversa para o novo modelo, para que um hook possa mostrar esse valor antes que a troca aconteça.
3632| Campo | Tipo | Descrição |3658| Campo | Tipo | Descrição |
3633| :- | :- | :- |3659| :- | :- | :- |
3634| `from_model` | string | ID do modelo do qual a troca parte |3660| `from_model` | string | ID do modelo do qual a troca parte |
3635| `to_model` | string | ID do modelo para o qual a troca muda. O matcher é comparado com o nome canônico deste modelo |3661| `to_model` | string | ID do modelo para o qual a troca vai. O matcher compara com o nome canônico deste modelo |
3636| `requested_model` | string ou `null` | O modelo indicado na requisição: um alias como `opus`, um ID de modelo completo, ou `null` quando a requisição foi para o modelo padrão |3662| `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 era para o modelo padrão |
3637| `source` | string | De onde veio a requisiçã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 alteração de modelo em uma requisição `apply_flag_settings`, de um host do Agent SDK ou do Remote Control |3663| `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 alteração de modelo em uma requisição `apply_flag_settings`, de um host do Agent SDK ou do Remote Control |
3638| `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 |3664| `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 |
3639| `prompt_cache_warm` | boolean | Se o cache de prompt do modelo atual provavelmente ainda está aquecido, o que significa que a troca o perde |3665| `prompt_cache_warm` | boolean | Se o cache de prompt do modelo atual provavelmente ainda está aquecido, o que significa que a troca o perde |
3640| `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"` |3666| `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"` |
3641| `estimated_cache_write_usd` | number | Custo estimado em dólares americanos de gravar `context_tokens` no cache de prompt em `to_model` na tarifa de `cache_ttl`, excluindo a próxima resposta. O servidor pode não precisar armazenar em cache todo o contexto novamente, então trate-o como uma estimativa |3667| `estimated_cache_write_usd` | number | Custo estimado em dólares americanos de gravar `context_tokens` no cache de prompt em `to_model` na taxa de `cache_ttl`, excluindo a próxima resposta. O servidor pode não precisar armazenar em cache novamente todo o contexto, então trate-o como uma estimativa |
3642| `pricing` | string | Como o Claude Code precificou `estimated_cache_write_usd`: `"configured"` nas tarifas próprias da sua organização quando ela as configurou, `"catalog"` no preço de tabela, ou `"default"` quando `to_model` não tem preço conhecido e o Claude Code assumiu uma tarifa padrão |3668| `pricing` | string | Como o Claude Code precificou `estimated_cache_write_usd`: `"configured"` nas taxas da sua organização quando ela as configurou, `"catalog"` no preço de tabela ou `"default"` quando `to_model` não tem preço conhecido e o Claude Code assumiu uma taxa padrão |
3643 3669
3644Este exemplo mostra a entrada para `/model opus` em uma sessão que está usando o Sonnet 5:3670Este exemplo mostra a entrada para `/model opus` em uma sessão que executa o Sonnet 5:
3645 3671
3646```json theme={null}3672```json theme={null}
3647{3673{
3662```3688```
3663 3689
3664<h4 id="premodelswitch-decision-control">3690<h4 id="premodelswitch-decision-control">
3665 Controle de decisão de PreModelSwitch3691 Controle de decisão do PreModelSwitch
3666</h4>3692</h4>
3667 3693
3668Os 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"` de nível superior cancela a troca.3694Os 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"` de nível superior cancela a troca.
3671 3697
3672| Campo | Descrição |3698| Campo | Descrição |
3673| :- | :- |3699| :- | :- |
3674| `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"` solicita ao usuário que a confirme |3700| `permissionDecision` | `"allow"` prossegue e ignora 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 |
3675| `permissionDecisionReason` | Para `"deny"`, mostrado ao usuário como o motivo pelo qual a troca foi bloqueada, ou retornado como o erro de uma requisição `set_model`. Para `"ask"`, mostrado no prompt de confirmação. Ignorado para `"allow"` |3701| `permissionDecisionReason` | Para `"deny"`, mostrado ao usuário como o motivo pelo qual a troca foi bloqueada, ou retornado como o erro de uma requisição `set_model`. Para `"ask"`, mostrado no prompt de confirmação. Ignorado para `"allow"` |
3676 3702
3677Somente 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.3703Somente 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.
3690 3716
3691Quando vários hooks PreModelSwitch retornam decisões diferentes, a precedência é `deny` > `ask` > `allow`.3717Quando vários hooks PreModelSwitch retornam decisões diferentes, a precedência é `deny` > `ask` > `allow`.
3692 3718
3693O Claude Code mostra ao usuário qualquer `systemMessage` que o seu hook retorne, independentemente da decisão, então um hook de relatório de custo pode retornar `{"systemMessage": "..."}` e sair com 0.3719O Claude Code mostra ao usuário qualquer `systemMessage` que o seu hook retorne, independentemente da decisão, então um hook de relatório de custos pode retornar `{"systemMessage": "..."}` e terminar com 0.
3694 3720
3695Um hook PreModelSwitch que não responde antes do seu timeout bloqueia a troca. Para saber o que um timeout faz em outros eventos, consulte [Timeouts](#timeouts). O timeout padrão para este evento é de 30 segundos. O `PreModelSwitch` executa apenas hooks `command`, `http` e `mcp_tool`, portanto os padrões de `prompt` e `agent` não se aplicam.3721Um hook PreModelSwitch que não responde antes do seu timeout bloqueia a troca. Para saber o que um timeout faz em outros eventos, consulte [Timeouts](#timeouts). 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.
3696 3722
3697Um hook que sai com um código diferente de 0 ou 2 e não imprime nenhuma decisão JSON é um erro não bloqueante, conforme descrito em [Outros códigos de saída](#other-exit-codes).3723Um hook que termina com um código diferente de 0 ou 2 e não imprime nenhuma decisão JSON é um erro não bloqueante, conforme descrito em [Outros códigos de saída](#other-exit-codes).
3698 3724
3699<h3 id="postmodelswitch">3725<h3 id="postmodelswitch">
3700 PostModelSwitch3726 PostModelSwitch
3701</h3>3727</h3>
3702 3728
3703É executado após a alteração do modelo da sessão. Use-o para dar ao Claude orientações específicas do modelo sem editar cada CLAUDE.md, por exemplo uma instrução válida para toda a organização que se aplica a determinados modelos.3729É 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.
3704 3730
3705O PostModelSwitch requer o Claude Code v2.1.251 ou posterior. Ele não pode bloquear, porque o modelo já foi alterado. O Claude Code executa hooks PostModelSwitch após qualquer uma destas alterações:3731O 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 alterações:
3706 3732
3707* Uma troca que você ou um cliente solicitou3733* Uma troca que você ou um cliente solicitou
3708* Um [fallback automático de modelo](/docs/pt/model-config#automatic-model-fallback), que altera o modelo da sessão3734* Um [fallback automático de modelo](/docs/pt/model-config#automatic-model-fallback), que altera o modelo da sessão
3709* Uma configuração como [`opusplan`](/docs/pt/model-config#opusplan-model-setting) entrando ou saindo do modo de planejamento3735* Uma configuração como [`opusplan`](/docs/pt/model-config#opusplan-model-setting) entrando ou saindo do modo de planejamento
3710* O Claude Code restaurando o modelo quando você retoma uma sessão3736* O Claude Code restaurando o modelo quando você retoma uma sessão
3711 3737
3712O 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 deixa o modelo da sessão inalterado.3738O 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 um turno, porque essa substituição dura um turno e deixa o modelo da sessão inalterado.
3713 3739
3714O matcher segue as mesmas regras que o [PreModelSwitch](#premodelswitch): o Claude Code o compara com o nome canônico do modelo para o qual a sessão trocou.3740O 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 mudou.
3715 3741
3716Este exemplo adiciona orientações sempre que o modelo da sessão muda para qualquer modelo Opus:3742Este exemplo adiciona orientações sempre que o modelo da sessão muda para qualquer modelo Opus:
3717 3743
3733}3759}
3734```3760```
3735 3761
3736Para 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` a partir de uma sessão do Sonnet, e depois pergunte ao Claude que orientações ele tem sobre o modelo atual.3762Para confirmar que o hook funciona, mude para um modelo Opus a partir de uma sessão que esteja executando 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.
3737 3763
3738<h4 id="postmodelswitch-input">3764<h4 id="postmodelswitch-input">
3739 Entrada de PostModelSwitch3765 Entrada do PostModelSwitch
3740</h4>3766</h4>
3741 3767
3742Os hooks PostModelSwitch recebem os mesmos campos que o [PreModelSwitch](#premodelswitch-input), com `hook_event_name` definido como `"PostModelSwitch"` e mais dois valores de `source`: `"auto"` para um fallback automático ou outra alteração que o Claude Code fez por conta própria, e `"resume"` para o modelo restaurado quando você retoma uma sessão.3768Os hooks PostModelSwitch recebem os mesmos campos que o [PreModelSwitch](#premodelswitch-input), com `hook_event_name` definido como `"PostModelSwitch"` e mais dois valores de `source`: `"auto"` para um fallback automático ou outra alteração que o Claude Code fez por conta própria, e `"resume"` para o modelo restaurado quando você retoma uma sessão.
3743 3769
3744`requested_model` é `null` quando `source` é `"auto"`. Quando `source` é `"resume"`, ele é a configuração de modelo salva que o Claude Code restaurou.3770`requested_model` é `null` quando `source` é `"auto"`. Quando `source` é `"resume"`, é a configuração de modelo salva que o Claude Code restaurou.
3745 3771
3746<h4 id="postmodelswitch-decision-control">3772<h4 id="postmodelswitch-decision-control">
3747 Controle de decisão de PostModelSwitch3773 Controle de decisão do PostModelSwitch
3748</h4>3774</h4>
3749 3775
3750O Claude Code pega o [stdout em texto simples](#exit-code-0) do seu hook na saída 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:3776O Claude Code pega o [stdout em texto simples](#exit-code-0) do seu hook ao terminar com 0, ou `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:
3751 3777
3752| Campo | Descrição |3778| Campo | Descrição |
3753| :- | :- |3779| :- | :- |
3754| `additionalContext` | String adicionada ao contexto do Claude com a próxima requisição. Consulte [Adicionar contexto para o Claude](#add-context-for-claude) |3780| `additionalContext` | String adicionada ao contexto do Claude com a próxima requisição. Consulte [Adicionar contexto para o Claude](#add-context-for-claude) |
3755 3781
3756Se o hook não tiver terminado em até cinco segundos após 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 para o modelo de destino da última troca.3782Se o hook não tiver terminado dentro de cinco segundos após 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 correspondente ao modelo de destino da última troca.
3757 3783
3758<h3 id="sessionend">3784<h3 id="sessionend">
3759 SessionEnd3785 SessionEnd
3774| `bypass_permissions_disabled` | Removido na v2.1.234; o Claude Code não o envia. Remova-o dos seus matchers de `SessionEnd` |3800| `bypass_permissions_disabled` | Removido na v2.1.234; o Claude Code não o envia. Remova-o dos seus matchers de `SessionEnd` |
3775 3801
3776<h4 id="sessionend-input">3802<h4 id="sessionend-input">
3777 Entrada de SessionEnd3803 Entrada do SessionEnd
3778</h4>3804</h4>
3779 3805
3780Alé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.3806Alé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 todos os valores.
3781 3807
3782```json theme={null}3808```json theme={null}
3783{3809{
3789}3815}
3790```3816```
3791 3817
3792Os 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`.3818Os 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 os [campos de saída JSON](#json-output) deles, como `systemMessage`.
3793 3819
3794Os 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:3820Os 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:
3795 3821
3796* **`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.3822* **`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çõ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. Timeouts definidos em hooks fornecidos por plugins não aumentam o orçamento.
3797* **`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`.3823* **`CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS`**: defina esta variável de ambiente em milissegundos para sobrescrever o orçamento explicitamente. O valor que você definir também se torna o timeout de cada hook sem seu próprio `timeout`.
3798 3824
3799Este exemplo define o orçamento como 5 segundos:3825Este exemplo define o orçamento para 5 segundos:
3800 3826
3801```bash theme={null}3827```bash theme={null}
3802CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS=5000 claude3828CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS=5000 claude
3808 Elicitation3834 Elicitation
3809</h3>3835</h3>
3810 3836
3811É executado quando um servidor MCP solicita entrada do usuário no meio de uma tarefa. Por padrão, o Claude Code mostra um diálogo interativo para o usuário responder. Os hooks podem interceptar essa solicitação e responder programaticamente, pulando o diálogo completamente.3837É executado quando um servidor MCP solicita entrada do usuário no meio de uma tarefa. Por padrão, o Claude Code mostra um diálogo interativo para o usuário responder. Os hooks podem interceptar essa solicitação e responder programaticamente, ignorando totalmente o diálogo.
3812 3838
3813Para um hook completo com sua entrada de configuração e script, consulte [Responder a uma solicitação de formulário a partir de um script](#answer-a-form-request-from-a-script).3839Para um hook completo com sua entrada de configurações e script, consulte [Responder a uma solicitação de formulário a partir de um script](#answer-a-form-request-from-a-script).
3814 3840
3815O campo matcher é comparado com o nome do servidor MCP.3841O campo matcher corresponde ao nome do servidor MCP.
3816 3842
3817<h4 id="elicitation-input">3843<h4 id="elicitation-input">
3818 Entrada de Elicitation3844 Entrada do Elicitation
3819</h4>3845</h4>
3820 3846
3821Alé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`.3847Alé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`.
3822 3848
3823Para elicitation no modo formulário, o caso mais comum:3849Para elicitação no modo de formulário, o caso mais comum:
3824 3850
3825```json theme={null}3851```json theme={null}
3826{3852{
3840}3866}
3841```3867```
3842 3868
3843Para elicitation no modo URL, usado para autenticação baseada em navegador:3869Para elicitação no modo URL, usada para autenticação baseada em navegador:
3844 3870
3845```json theme={null}3871```json theme={null}
3846{3872{
3856```3882```
3857 3883
3858<h4 id="elicitation-output">3884<h4 id="elicitation-output">
3859 Saída de Elicitation3885 Saída do Elicitation
3860</h4>3886</h4>
3861 3887
3862Um hook Elicitation pode responder à solicitação pelo usuário, recusá-la ou cancelá-la, ou deixá-la para o diálogo. Para responder, recusar ou cancelar, saia com 0 e imprima um objeto `hookSpecificOutput` com uma `action`. O servidor recebe sua resposta e nenhum diálogo aparece. Cada linha desta tabela mostra o que retornar para um resultado e o que o servidor MCP recebe:3888Um hook Elicitation pode responder à solicitação pelo usuário, recusá-la ou cancelá-la, ou deixá-la para o diálogo. Para responder, recusar ou cancelar, termine com 0 e imprima um objeto `hookSpecificOutput` com uma `action`. O servidor recebe a sua resposta e nenhum diálogo aparece. Cada linha desta tabela mostra o que retornar para um resultado e o que o servidor MCP recebe:
3863 3889
3864| Para | Retorne | O servidor recebe |3890| Para | Retorne | O servidor recebe |
3865| :- | :- | :- |3891| :- | :- | :- |
3868| Cancelar a solicitação | `"action": "cancel"` | `cancel` |3894| Cancelar a solicitação | `"action": "cancel"` | `cancel` |
3869| Deixar a solicitação para o usuário | Nenhuma saída, com código de saída 0 | A resposta do usuário no [diálogo](/docs/pt/mcp#respond-to-mcp-elicitation-requests) |3895| Deixar a solicitação para o usuário | Nenhuma saída, com código de saída 0 | A resposta do usuário no [diálogo](/docs/pt/mcp#respond-to-mcp-elicitation-requests) |
3870 3896
3871Esta saída responde à solicitação no modo formulário mostrada em [Entrada de Elicitation](#elicitation-input). As chaves em `content` são os nomes das propriedades do `requested_schema` dessa solicitação:3897Esta saída responde à solicitação no modo de formulário mostrada em [Entrada do Elicitation](#elicitation-input). As chaves em `content` são os nomes de propriedades do `requested_schema` dessa solicitação:
3872 3898
3873```json theme={null}3899```json theme={null}
3874{3900{
3895 3921
3896No diálogo, selecionar **Decline** envia `decline` e pressionar `Esc` envia `cancel`, então retorne aquele que você quer que o servidor veja.3922No diálogo, selecionar **Decline** envia `decline` e pressionar `Esc` envia `cancel`, então retorne aquele que você quer que o servidor veja.
3897 3923
3898Para uma solicitação no modo URL, um hook que retorna `accept` pula o diálogo, então a URL nunca é aberta.3924Para uma solicitação no modo URL, um hook que retorna `accept` ignora o diálogo, então a URL nunca é aberta.
3899 3925
3900O Claude Code descarta `reason`, `systemMessage` e `continue` da saída JSON de um hook Elicitation, qualquer que seja a `action` que você retorne.3926O Claude Code descarta `reason`, `systemMessage` e `continue` da saída JSON de um hook Elicitation, seja qual for a `action` que você retornar.
3901 3927
3902<h4 id="other-ways-to-decline-an-elicitation">3928<h4 id="other-ways-to-decline-an-elicitation">
3903 Outras maneiras de recusar uma elicitation3929 Outras maneiras de recusar uma elicitação
3904</h4>3930</h4>
3905 3931
3906Seu hook também pode recusar destas maneiras. O servidor recebe o mesmo `decline` que para `"action": "decline"`:3932O seu hook também pode recusar destas maneiras. O servidor recebe o mesmo `decline` que para `"action": "decline"`:
3907 3933
3908* **Sai com o código 2**: o Claude Code ignora um `hookSpecificOutput` impresso pelo mesmo hook3934* **Termina com código 2**: o Claude Code ignora um `hookSpecificOutput` impresso pelo mesmo hook
3909* **Imprime um `"decision": "block"` de nível superior**: o bloqueio sobrescreve uma `action` na mesma saída3935* **Imprime um `"decision": "block"` de nível superior**: o bloqueio sobrescreve uma `action` na mesma saída
3910 3936
3911Quando vários hooks correspondem à mesma solicitação, uma recusa de um deles sobrescreve um `accept` ou `cancel` de outro.3937Quando vários hooks correspondem à mesma solicitação, uma recusa de um deles sobrescreve um `accept` ou `cancel` de outro.
3919fi3945fi
3920```3946```
3921 3947
3922Nem o usuário nem o servidor veem por que seu hook recusou, porque o Claude Code não mostra seu stderr nem seu `reason`.3948Nem o usuário nem o servidor veem por que o seu hook recusou, porque o Claude Code não mostra o seu stderr nem o seu `reason`.
3923 3949
3924O Claude Code ignorou um `decision` de nível superior de hooks `Elicitation` e `ElicitationResult` desde a v2.1.105 até a correção na v2.1.284.3950O Claude Code ignorou um `decision` de nível superior dos hooks `Elicitation` e `ElicitationResult` da v2.1.105 até a correção na v2.1.284.
3925 3951
3926<h4 id="answer-a-form-request-from-a-script">3952<h4 id="answer-a-form-request-from-a-script">
3927 Responder a uma solicitação de formulário a partir de um script3953 Responder a uma solicitação de formulário a partir de um script
3931 3957
3932<Tabs>3958<Tabs>
3933 <Tab title="macOS/Linux">3959 <Tab title="macOS/Linux">
3934 Registre um hook de comando para o evento no seu arquivo de configuração, com o nome do servidor como matcher:3960 Registre um hook de comando para o evento no seu arquivo de configurações, com o nome do servidor como matcher:
3935 3961
3936 ```json theme={null}3962 ```json theme={null}
3937 {3963 {
4018 ElicitationResult4044 ElicitationResult
4019</h3>4045</h3>
4020 4046
4021É executado depois que um usuário responde a uma elicitation MCP. Os hooks podem observar, modificar ou bloquear a resposta antes que ela seja enviada de volta ao servidor MCP.4047É 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.
4022 4048
4023Quando um hook [Elicitation](#elicitation) responde a uma solicitação, o Claude Code envia essa resposta ao servidor sem executar hooks ElicitationResult.4049Quando um hook [Elicitation](#elicitation) responde a uma solicitação, o Claude Code envia essa resposta ao servidor sem executar hooks ElicitationResult.
4024 4050
4025O campo matcher é comparado com o nome do servidor MCP.4051O campo matcher corresponde ao nome do servidor MCP.
4026 4052
4027<h4 id="elicitationresult-input">4053<h4 id="elicitationresult-input">
4028 Entrada de ElicitationResult4054 Entrada do ElicitationResult
4029</h4>4055</h4>
4030 4056
4031Alé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`.4057Alé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`.
4044```4070```
4045 4071
4046<h4 id="elicitationresult-output">4072<h4 id="elicitationresult-output">
4047 Saída de ElicitationResult4073 Saída do ElicitationResult
4048</h4>4074</h4>
4049 4075
4050Um hook ElicitationResult pode deixar a resposta do usuário passar, alterar seus valores ou bloqueá-la. Para alterar ou bloquear a resposta, saia com 0 e imprima um objeto `hookSpecificOutput` com uma `action`. Cada linha desta tabela mostra o que retornar para um resultado e o que o servidor MCP recebe:4076Um hook ElicitationResult pode deixar a resposta do usuário passar, alterar seus valores ou bloqueá-la. Para alterar ou bloquear a resposta, termine com 0 e imprima um objeto `hookSpecificOutput` com uma `action`. Cada linha desta tabela mostra o que retornar para um resultado e o que o servidor MCP recebe:
4051 4077
4052| Para | Retorne | O servidor recebe |4078| Para | Retorne | O servidor recebe |
4053| :- | :- | :- |4079| :- | :- | :- |
4056| Bloquear a resposta | `"action": "decline"` | `decline`, sem os valores do usuário |4082| Bloquear a resposta | `"action": "decline"` | `decline`, sem os valores do usuário |
4057| Cancelar a solicitação | `"action": "cancel"` | `cancel`, junto com os valores que o usuário enviou. Para retê-los, retorne `"decline"` |4083| Cancelar a solicitação | `"action": "cancel"` | `cancel`, junto com os valores que o usuário enviou. Para retê-los, retorne `"decline"` |
4058 4084
4059Esta saída altera a resposta mostrada em [Entrada de ElicitationResult](#elicitationresult-input), de modo que o servidor recebe `alice@example.com` onde o usuário enviou `alice`:4085Esta saída altera a resposta mostrada em [Entrada do ElicitationResult](#elicitationresult-input), então o servidor recebe `alice@example.com` onde o usuário enviou `alice`:
4060 4086
4061```json theme={null}4087```json theme={null}
4062{4088{
4070}4096}
4071```4097```
4072 4098
4073Seu `content` substitui todo o objeto `content` do usuário, então inclua os campos que você não está alterando. Retorne `action` junto com ele, porque o Claude Code ignora um `hookSpecificOutput` que não tenha `action`.4099O seu `content` substitui todo o objeto `content` do usuário, então inclua os campos que você não está alterando. Retorne `action` junto com ele, porque o Claude Code ignora um `hookSpecificOutput` que não tenha `action`.
4074 4100
4075Os hooks ElicitationResult também são executados quando o usuário recusa ou cancela, e sua `action` substitui a dele. Verifique se a `action` da entrada é `accept` antes de retornar `accept`, ou seu hook transformará uma solicitação recusada em uma aceita. Este script faz a mesma alteração quando o usuário aceitou, mantém os outros campos e não imprime nada caso contrário:4101Os hooks ElicitationResult também são executados quando o usuário recusa ou cancela, e a sua `action` substitui a dele. Verifique se a `action` da entrada é `accept` antes de retornar `accept`, ou o seu hook transformará uma solicitação recusada em uma aceita. Este script faz a mesma alteração quando o usuário aceitou, mantém os outros campos e não imprime nada caso contrário:
4076 4102
4077```bash theme={null}4103```bash theme={null}
4078#!/bin/bash4104#!/bin/bash
4094}4120}
4095```4121```
4096 4122
4097O código de saída 2 e um `"decision": "block"` de nível superior também bloqueiam a resposta. [Outras maneiras de recusar uma elicitation](#other-ways-to-decline-an-elicitation) explica qual deles tem efeito quando um hook os combina, o que o usuário vê e quais versões ignoravam `decision`.4123O código de saída 2 e um `"decision": "block"` de nível superior também bloqueiam a resposta. [Outras maneiras de recusar uma elicitação](#other-ways-to-decline-an-elicitation) aborda qual deles tem efeito quando um hook os combina, o que o usuário vê e quais versões ignoravam `decision`.
4098 4124
4099O Claude Code descarta `reason`, `systemMessage` e `continue` da saída JSON de um hook ElicitationResult, qualquer que seja a `action` que você retorne.4125O Claude Code descarta `reason`, `systemMessage` e `continue` da saída JSON de um hook ElicitationResult, seja qual for a `action` que você retornar.
4100 4126
4101<h2 id="prompt-based-hooks">4127<h2 id="prompt-based-hooks">
4102 Hooks baseados em prompt4128 Hooks baseados em prompt
4351* **Sozinha no stdout**: quando a resposta é o único texto no stdout, ela pode ocupar várias linhas, como a saída formatada do `jq`. Ocupar várias linhas requer Claude Code v2.1.295 ou posterior.4377* **Sozinha no stdout**: quando a resposta é o único texto no stdout, ela pode ocupar várias linhas, como a saída formatada do `jq`. Ocupar várias linhas requer Claude Code v2.1.295 ou posterior.
4352* **Em uma linha própria**: um hook assíncrono pode imprimir outro texto no stdout quando a resposta cabe sozinha em uma linha, por exemplo com `jq -c`.4378* **Em uma linha própria**: um hook assíncrono pode imprimir outro texto no stdout quando a resposta cabe sozinha em uma linha, por exemplo com `jq -c`.
4353 4379
4354Claude Code valida que a resposta JSON contra o mesmo [esquema de saída](#json-output) que hooks síncronos, e descarta qualquer campo cujo valor tenha o tipo errado, como um `systemMessage` que não seja uma string, em vez de entregá-lo. Execute com `--debug` para ver um aviso nomeando cada campo descartado. Antes da v2.1.202, saída JSON malformada de um hook assíncrono poderia travar a sessão, e a falha recorria cada vez que a sessão era retomada.4380Claude Code valida essa resposta JSON contra o mesmo [esquema de saída](#json-output) que hooks síncronos, e descarta qualquer campo cujo valor tenha o tipo errado, como um `systemMessage` que não seja uma string, em vez de entregá-lo. Execute com `--debug` para ver um aviso nomeando cada campo descartado.
4355 4381
4356Notificações de conclusão de hook assíncrono são suprimidas por padrão. Para vê-las, ative modo verbose com `Ctrl+O` ou inicie Claude Code com `--verbose`.4382Notificações de conclusão de hook assíncrono são suprimidas por padrão. Para vê-las, ative modo verbose com `Ctrl+O` ou inicie Claude Code com `--verbose`.
4357 4383
